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
This commit is contained in:
jvanvik 2026-10-11 20:34:35 +02:00
parent 931f59e11e
commit cc0524de5e
8 changed files with 533 additions and 38 deletions

View file

@ -9,25 +9,30 @@ REST JSON under `/api/v1/`. The machine-readable contract is `docs/openapi.json`
and `DELETE /auth/tokens/:id` revoke). No cookies.
- Every response is an object with `serverTime` (integer ms since epoch, server clock). Clients compute countdowns from the offset.
- Errors: `{ serverTime, error: { code, message, details } }`. Clients switch on `code`. All codes: `x-error-codes` in openapi.json.
- Mutating POSTs accept `Idempotency-Key` (8-64 chars `A-Za-z0-9_.:-`); a replay returns the stored response with `Idempotent-Replay: true`;
- Mutating POSTs accept `Idempotency-Key` (8-64 chars `A-Za-z0-9_.:-`); a replay returns the stored response with `Idempotent-Replay: true` (keys are kept 24 h);
the same key with a different request is `idempotency_key_reuse`.
- Lists are cursor-paginated: `?after=<id>&limit=<n>`, response `next` is the cursor or `null`.
- Rate limits: per IP, per token, stricter on login/signup. `429 rate_limited` with `Retry-After`.
- Rate limits (token buckets, `server/http.js`): per client address 30 requests/s sustained, burst 90 (IPv6 clients share one bucket per /64); per
token 15/s, burst 45; login and signup per address about 1 per 10 s, burst 8, plus a per-username login throttle. `429 rate_limited` with
`Retry-After` / `details.retryAfter`. Request bodies are capped at 32 KB. Message and WebSocket limits are separate (below, PROTOCOL.md).
- The client never sends computed amounts, only intents. The server recomputes everything with `public/js/rules.js`.
## Resources (stage 0-2)
## Accounts, POPs, map (stage 0-2)
| Route | Purpose |
| ----- | ------- |
| `POST /auth/signup`, `POST /auth/login` | account + token (signup also founds the capital POP) |
| `POST /auth/signup {username, password, invite?, worldId?, device?}` | account + token (201); founds the capital POP; `invite` is required only when the server has `SIGNUP_CODE` set (`signup_closed` otherwise) |
| `POST /auth/login` | token for another device (`invalid_credentials`, `forbidden` when banned) |
| `GET /auth/tokens`, `DELETE /auth/tokens/:tokenId`, `POST /auth/logout` | list this account's active device tokens, revoke one, revoke the current one |
| `GET /me` | user, operators (per world), POPs |
| `GET /towns/:id` | full POP state: resources `{amount, rate, cap}` at `serverTime`, power, buildings with the server's build plan, queue |
| `POST /towns/:id/build {key}` | build/upgrade one level of a field (`f1..f18`) or an infrastructure building |
| `DELETE /towns/:id/queue/:eventId` | cancel a running build, 80% refund |
| `POST /towns/:id/rename {name}` | rename a POP (2-40 chars) |
| `GET /map?x&y&r` | rural areas, incumbent sites, POPs in the viewport |
| `GET /notifications?after&limit` | durable notification feed (build done, ...) |
| `GET /notifications?after&limit` | durable notification feed (build done, ...), pruned after 30 days |
## Social (stage 5, no marketplace/transport yet)
## Social (stage 5)
`worldId` is optional everywhere a caller's operator is needed (default: their oldest operator). Most commands are
idempotent where that makes sense and answer `{ changed: false }` when there was nothing to do (leaving twice, kicking someone
@ -91,8 +96,9 @@ Units are plain `{ unitId: count }` objects with the generic ids of `data.UNITS`
now carries `town.military`: units at home (`online` flag, `offlineSince`), reinforcements standing here and away, the training queue,
what can be trained (cost, time, missing requirements), research levels and queue, transport links, and this POP's outgoing/incoming
movements. Nothing resolves when you send it: combat, loot and arrival happen in the event queue at the arrival time, and reports and
notifications (`incoming`, `report`, `train_done`, `research_done`, `movement_returned`, `transport_arrived`, `units_offline`,
`units_decommissioned`, `town_lost`, `town_gained`) tell you afterwards.
notifications (`incoming`, `report`, `train_done`, `research_done`, `movement_returned`, `movement_lost`, `transport_arrived`,
`transport_delivered`, `reinforcements_sent_home`, `units_offline`, `units_decommissioned`, `town_lost`, `town_gained`; `build_done` for
buildings) tell you afterwards.
| Route | Purpose |
| ----- | ------- |
@ -131,7 +137,7 @@ offer you have (older ones follow). `status`: `open`, `accepted`, `completed`, `
| `GET /trade/offers?worldId&townId&give&want&after&limit` | open offers of others that one of your POPs (or `townId`) can take: within `min(maxDistance, 10 x exchange level)`. Each carries `acceptableFrom: [{townId, distance}]`; `exchangeLevels` lists your exchanges and their reach |
| `GET /trade/offers/mine?worldId&status&after&limit` | offers you posted or accepted, any status, with `role` |
| `GET /trade/offers/:id` | one offer: open ones to every operator of the world, closed ones to the two parties (`not_found` otherwise) |
| `DELETE /trade/offers/:id` | cancel your open offer; the escrow returns to the POP (`offer_closed` when it is not open) |
| `DELETE /trade/offers/:id` | cancel your open offer; the escrow returns to the POP, capped by its Rack hall (stock already above the cap stays; a refund never lifts it further, and the clipped part is lost without a notice: BALANCE.md S2). `offer_closed` when it is not open |
| `POST /trade/offers/:id/accept {townId}` | take it with one of your POPs (201): two transports leave at once (your payment, their goods); `own_offer`, `offer_closed`, `trade_out_of_range`, `no_transport_link`, `not_enough_resources`; all or nothing |
Notifications: `trade_accepted` (poster), `trade_completed` (both, when both transports arrived), `trade_expired`, `trade_void` (the POP

View file

@ -321,7 +321,7 @@ number to move.
**Server finding S2 (not fixed):** the escrow of an offer that expires or is cancelled after the POP's store filled up again is
refunded only up to the Rack hall cap (`trade.refund`, decision R1). The harness books it: 36 refunds per 30-day run (all three seeds) lose
12 to 15k Hardware and Capital in total (`arch-d30-s1`: 3.3k Hardware, 11.2k Capital in 36 events), invisibly to the player.
DESIGN.md says nothing is lost in trade. Fix options: credit the clipped part back as a transport that waits, or let escrow refunds
DESIGN.md used to say nothing is lost in trade (corrected to describe the cap). Fix options: credit the clipped part back as a transport that waits, or let escrow refunds
exceed the cap the way the existing "stock above a lowered cap is kept" rule does for stock.
### Power binds early and then recedes

View file

@ -32,7 +32,7 @@ committed file is stale, which satisfies "updated in the same commit as any rout
## D8 — Resource fields are slot-keyed
Buildings table key: `f1..f18` for resource fields (type fixed at founding, 4 per type + 2 wild), the building type for infrastructure.
Build "slots": 1 concurrent build, 2 from Core router 10 (queue = pending `buildDone` events).
Build "slots": 1 concurrent build, 2 from Core router 3 (was 10, changed by B1; queue = pending `buildDone` events).
## S5-1 — Alliance size cap is stored, only ever raised
DESIGN says the Peering office level sets the size you can found. The cap is stored at founding (`10 + 2 * best level`). A lost or
@ -111,7 +111,7 @@ arrival, before the POP changes hands. On transfer the old owner's pending train
the new owner's user, and that POP's units standing elsewhere are re-homed to the old owner's capital. A captured POP keeps its footprint.
## S3-6 — Transport links
`links` = Internet exchange level, each carries 500 (`D.TRANSPORT`). A link is busy while the transport is out and while its empty carriers
`links` = Internet exchange level, each carries 1000 (`D.TRANSPORT`; 500 until B2). A link is busy while the transport is out and while its empty carriers
drive back (a `return` movement with `extra.link`). Cargo above the receiver's Rack hall cap is lost (the notification says how much).
`transport` movements keep arbitrary `extra` and `movements.hooks.transportArrived` is called on delivery, so the trade stage needs no
change in the movement code.
@ -190,8 +190,8 @@ alliance can ship; nothing here is balanced.
## T1 — Trade: escrow, one link per side, reach by exchange level
- Offers are escrowed in `trade_offers` and hold one transport link of the poster's POP while open (`movements.activeLinks` counts open
offers), so accepting never fails for lack of a link on the poster's side and cannot exceed the exchange level.
- Each side of an offer must fit ONE transport (<= 500); larger deals are several offers. The ratio band is count-based 1:2.
- Escrow returns without the Rack hall cap (conservation beats the cap here); deliveries keep the existing cap rule (`cargoLost`).
- Each side of an offer must fit ONE transport (<= 1000, was 500 until B2); larger deals are several offers. The ratio band is count-based 1:2.
- Escrow returned WITHOUT the Rack hall cap at first (conservation beats the cap); review round 1 (R1) reversed that: refunds are capped like `cancelBuild` (stock already above the cap stays, the clipped part is lost silently, BALANCE.md S2). Deliveries keep the cap rule (`cargoLost`).
- Reach: `10 tiles x exchange level` of the taker's POP, and the offer's own `maxDistance`; the poster's level only matters for the number of
offers they can hold open.
- A POP changing hands voids its open offers (`combat.transferTown` calls `trade.onTownTransferred`); the escrow stays in the POP.
@ -221,7 +221,7 @@ no-referrer and a `connect-src` that allowed any `ws:`/`wss:` host (now `'self'`
cache per world); weaker town-name sanitiser (now `text.cleanText`); rejected 429s pinned into the idempotency store (no longer);
notifications never pruned (30 days); `units_offline` warning missing when units went offline through an arrival.
Accepted for now, written down so nobody is surprised:
- Escrowed trade stock is not lootable, so an unattractive offer is a hiding place for up to 250-500 of one resource per link (48 h
- Escrowed trade stock is not lootable, so an unattractive offer is a hiding place for up to 1000 (500 before B2) of one resource per link (48 h
offers, cancellable). Revisit if bots or players abuse it.
- Leaving/being kicked from an alliance drops pact protection at once (pacts bind alliances, not people). Revisit: track `left_at`.
- A battery above a lowered Battery bank cap is clamped immediately, while stock above a lowered Rack hall cap is kept. Intentional:

View file

@ -1,7 +1,7 @@
# Deploying UPSTREAM
UPSTREAM is one Node process: it serves the static client from `public/`, the REST API under `/api/v1/` and (stage 6)
a WebSocket at `/ws`. Unlike NETWALL it **keeps state**: one SQLite file, owned by that process. A restart loses
UPSTREAM is one Node process: it serves the static client from `public/`, the REST API under `/api/v1/` and a
WebSocket push channel at `/ws` (docs/PROTOCOL.md). Unlike NETWALL it **keeps state**: one SQLite file, owned by that process. A restart loses
nothing: overdue events are caught up in order before the server accepts traffic.
```
@ -17,6 +17,10 @@ layer. The differences are the Node version (`node:sqlite` needs 22.13+), a stat
* **Run:** `systemd-analyze verify` on the three unit files (syntax and directives only), the CLI `tools/admin.js`
and its tests on a dev machine (Node 24.21), a backup, verify and prune cycle, `sh -n` on `deploy/upstream-admin`.
Re-checked on 2026-10-11 with the code as it is now (Node 24.21, scratch directory, no systemd): first boot with `DB_PATH`/`PORT`/`HOST`
(migrations 001-004 applied, `created world 1`), `/healthz`, `/` headers, signup + build over the API, `admin.js` status / worlds / users /
operators / inspect-town / events / replay-events / backup / verify-backup / ban / unban / grant / end-world (refusal without `--yes`),
SIGTERM and restart (state, queue and password kept, no migrations re-applied; tokens revoked by `ban` stay revoked), SIGKILL then restart after a build fell due (`caught up 1 overdue event(s)`, the build level was applied), and a restore by copying a snapshot to a fresh `DB_PATH` and starting on it (section 7: it logged `caught up 1 overdue event(s)`).
* **Taken from NETWALL's docs, not re-run for UPSTREAM:** everything about nginx Proxy Manager (labels, header
behaviour, "Client addresses"). NETWALL's guide records what was observed against NPM v2.16.0.
* **Never run:** a Proxmox LXC, a started unit under systemd, the timer firing on its own, a Node install from the
@ -163,8 +167,8 @@ line, no `export`) or in a `systemctl edit upstream` override, then `systemctl r
| `DB_PATH` | `/var/lib/upstream/game.db` | SQLite file. The code default is `./data/game.db`; the unit overrides it. Its directory is created if missing, it must be writable by the service user. `-wal` and `-shm` files appear next to it: always copy via a snapshot (section 7), never with `cp` while running. |
| `TRUST_PROXY` | `auto` | `auto`: believe `X-Forwarded-For` / `X-Forwarded-Host` only from loopback / private-range peers. `1`: always (then firewall the port). `0`: never. Used for the per-IP rate limits and the log. |
| `TRUSTED_PROXIES` | empty | Extra IPs / CIDRs `auto` believes: needed when the proxy reaches the LXC from a global IPv6, Tailscale / CGNAT `100.64.0.0/10` or another routable address. |
| `ALLOWED_ORIGINS` | empty | Extra origins for the WebSocket origin check (stage 6), comma separated, with the port when it is not 80/443. The REST API uses bearer tokens (no cookies) and does not check origins. |
| `MAX_CONN_PER_IP` | `40` | Open connections per client address (WebSocket cap, stage 6). `0` disables. |
| `ALLOWED_ORIGINS` | empty | Extra origins for the WebSocket origin check, comma separated, with the port when it is not 80/443. The REST API uses bearer tokens (no cookies) and does not check origins. |
| `MAX_CONN_PER_IP` | `40` | Open WebSockets per client address (HTTP connections are not capped). `0` disables. |
| `WORLD_SPEED` | unset (1) | World speed multiplier, **first boot only**, when the database has no world yet. |
| `WORLD_RADIUS` | unset (50) | Map radius in tiles (coordinates `-R..R`, so 50 = 101 x 101), **first boot only**. |
| `WORLD_NAME` | unset (`World 1`) | Name of the first world, **first boot only**. |
@ -193,7 +197,7 @@ In NPM: **Hosts > Proxy Hosts > Add Proxy Host**.
| Details: Forward Port | `8080` |
| Details: Cache Assets | **off** (static files are `no-cache` and revalidated by ETag; the game must see new versions) |
| Details: Block Common Exploits | optional |
| Details: **Websockets Support** | **on.** The REST game works without it, but stage 6 adds `/ws` and it fails with HTTP 426 when this is off. Switch it on now so you do not forget. |
| Details: **Websockets Support** | **on.** The REST game works without it, but `/ws` (live push) fails with HTTP 426 when this is off. |
| Custom Locations | none needed |
| SSL | Request a new Let's Encrypt certificate, **Force SSL**, **HTTP/2** (HSTS optional) |
| Advanced (gear) | nothing required; optional gzip below |
@ -214,9 +218,9 @@ Notes carried over from NETWALL's setup (observed there against NPM v2.16.0, not
shares one rate-limit budget and the log shows the proxy's address. Fix: `TRUSTED_PROXIES=<its address or CIDR>`.
* Clients on your own LAN can pick their address through NPM's `real_ip` handling, so the per-IP limits protect against
public abuse, not against LAN users.
* **Heads-up for stage 6:** NPM's default `proxy_read_timeout` is 90 s. NETWALL never idles because it streams 20
snapshots a second; UPSTREAM's socket will be quiet for long stretches. The WebSocket server must send a ping
well under 90 s (NETWALL's pings every 25 s), or the proxy drops idle players.
* **Idle timeout:** nginx's `proxy_read_timeout` is 60 s by default (NETWALL's notes say 90 s for NPM; not re-checked). NETWALL never
idles because it streams 20 snapshots a second; UPSTREAM's socket is quiet for long stretches. `server/push.js` sends a protocol ping
every 30 s (`wsPingMs`), below either value, which is reasoning, not a measurement behind a real NPM.
Firewall and dual stack: identical to NETWALL (`docs/DEPLOY.md` there, section 6): only the proxy needs to reach port
8080. `curl -i http://127.0.0.1:8080/healthz` and `curl -gi 'http://[::1]:8080/healthz'` check both families.
@ -233,7 +237,7 @@ upstream-admin help
upstream-admin status # file, size, migrations, overdue events
upstream-admin worlds
upstream-admin create-world --name "Summer" --speed 2 --radius 60 --seed 1234 --end-in 90d
upstream-admin end-world 1 --yes
upstream-admin end-world 1 --yes # flag flip only, see below
upstream-admin users [--banned] # no hashes or tokens are ever printed
upstream-admin operators [--world 1]
upstream-admin ban mallory # sets banned, revokes all tokens: old tokens give 401, login 403
@ -259,6 +263,9 @@ Safety rules the CLI follows:
* Destructive or test-only commands refuse without a flag: `end-world` and `grant` need `--yes`; `reset-world`
needs `--yes-destroy` (without it, it prints what it would delete and exits 2). `ban`, `unban`, `revoke-tokens` are
reversible and need none.
* `end-world` just sets the world's status to `ended` (and `end_at` to now): signup and join stop and every game command answers
`world_ended`, but it writes no ranking snapshot (`GET /worlds/:id/results` stays `available: false`), cancels no pending event and
closes no trade offer. The natural end (a backbone winner, then the `worldEnd` event two world days later) does all of that.
* `reset-world` deletes the world's game rows (everything with a `world_id`, plus tables pointing at them: towns,
buildings, events, operators, alliances, messages, ... discovered from the schema, so tables added by later stages
are covered) and **keeps accounts and tokens**; players must join the world again. It resets `start_at`, clears
@ -394,4 +401,4 @@ A healthy server has **no overdue events** in `status`: the timer processes even
| `upstream-backup.service` failed | `journalctl -u upstream-backup`. Typical: disk full, or the integrity check of the new snapshot failed (then nothing was kept and nothing pruned; check the disk and the `game.db` itself). |
| Backups not appearing | `systemctl list-timers upstream-backup.timer`; the timer must be **enabled** (`systemctl enable --now upstream-backup.timer`), not just installed. |
| World reset by mistake | Restore the snapshot taken before (section 7), or the one `reset-world --backup` wrote. |
| (stage 6) WebSocket upgrade answered 426 / 403 / 429 | 426: **Websockets Support** off in NPM. 403: origin check, see `ALLOWED_ORIGINS` and the notes in section 5. 429: more than `MAX_CONN_PER_IP` sockets from one address. |
| WebSocket upgrade answered 426 / 403 / 429 | 426: **Websockets Support** off in NPM. 403: origin check, see `ALLOWED_ORIGINS` and the notes in section 5. 429: more than `MAX_CONN_PER_IP` sockets from one address. |

View file

@ -25,7 +25,7 @@ Mid game adds more POPs, alliances and trade. Late game is the backbone race.
## World
- Square tile map, default 301 x 301 (coordinates -150..150), one tile = one site. World config sets size,
- Square tile map, default 101 x 101 (radius 50, coordinates -50..50; `WORLD_DEFAULTS.mapRadius`, DECISIONS D6), one tile = one site. World config sets size,
speed (1x, 2x, 3x), start time and a planned end.
- Tile types: empty land, **rural area** (bonus tile), **incumbent site** (NPC), **backbone landing site**
(appears late, see End game), player POP.
@ -63,7 +63,7 @@ Current amount is always computed, never stored as "now": `amount = min(cap, sto
## Buildings
One build queue per POP. The **Core router** level shortens all build times. Level cap 20 for most buildings.
One build slot per POP, a second from Core router 3 (`FORMULAS.secondQueueCoreLevel`, BALANCE.md B1). The **Core router** level shortens all build times. Level cap 20 for most buildings.
| Building | Role |
| --------------- | --------------------------------------------------------------------------------------------- |
@ -166,7 +166,8 @@ pump-feeding. Accepting an offer spawns two transport movements. Direct transpor
an Internet exchange. Each side must fit ONE transport link (1..1000) and the two amounts differ by at most 1:2:
`give <= 2 x want` and `want <= 2 x give` (count-based, the resources are not weighted). The resources must differ.
- The offered amount is **escrowed**: it leaves the POP when the offer is posted. Cancelling or expiry (48 h / world speed) credits it back
to the POP without the Rack hall cap (an amount above the cap is kept, it only stops growing), so nothing is created or lost.
to the POP **capped by the Rack hall** (`trade.refund`, review fix R1: stock already above the cap stays, a refund never lifts it further). If
the POP's store filled up meanwhile, the clipped part is destroyed without a notice (BALANCE.md S2, open); otherwise nothing is created or lost.
- **Reach:** a POP sees and takes offers of other operators within `min(offer.maxDistance, 10 x Internet exchange level)` tiles. The poster
cannot take their own offer.
- **Links:** an open offer holds one transport link of the poster's POP in reserve (open offers + running transports + returning carriers
@ -260,4 +261,4 @@ computed from `serverTime`.
- Research as a tree or a flat list of upgrades?
- Should rural areas be contested (takeable from each other) or just held?
- Night protection and holiday mode.
- World size vs expected players (301² tiles is a lot for 50 players; shrink for the first world).
- World size vs expected players (the default is already 101², radius 50; is that right for 50 players? untested with real players).

View file

@ -2,6 +2,41 @@
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.
@ -22,8 +57,8 @@ Not done:
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 are not cached; battle rankings stay empty until the military stage writes `operator_stats`.
- Not run: Playwright, load, or any bot balance run; the social numbers in `SOCIAL` (limits, TTLs, role table) are first guesses.
- 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`,
@ -55,13 +90,13 @@ Built: `public/` vanilla JS, no build step, strict-CSP friendly (no inline scrip
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 reserved `push` event (no WebSocket client yet).
`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 push, no service worker, canvas has no inertia/fling, no light theme.
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
@ -162,7 +197,7 @@ Built (More group; strings in `strings/{trade,world,alerts}.js`, en + nb):
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 Playwright suite (`e2e/` is still empty), long lists (offers > 25 per
- 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.
@ -187,7 +222,7 @@ one tick are merged. Small edits outside the new files: `scheduler.js` (outbox,
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
(run after the push work, with the other agents' changes in the tree at that moment).
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.
@ -220,8 +255,8 @@ Not done / not claimed:
- 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); there is no admin "end world now" or
"reset" yet (stage 7 world lifecycle: the `worldEnd` event can be enqueued by hand); several winners are impossible by design.
- 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.
@ -243,5 +278,13 @@ reading the constant); trade escrow refunds are clipped at the Rack hall cap sil
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
- Everything else. See CLAUDE.md "Working in stages".
- 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.