Phase 4: close loot/refund leaks, landing-site garrisons, speed-scaled shipping, update/offsite tooling, broad e2e

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

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

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
This commit is contained in:
jvanvik 2026-10-12 00:58:12 +02:00
parent 9104480463
commit 3c23c51902
92 changed files with 4887 additions and 300 deletions

23
docs/workflows/README.md Normal file
View file

@ -0,0 +1,23 @@
# Stage workflows
One short note per stage of CLAUDE.md "Working in stages": goal, done-when, what was actually built, what is open. They were
written after the fact (2026-10-11) from `docs/NEXT.md`, `docs/DECISIONS.md`, `docs/BALANCE.md` and the git history, so they
describe what happened, not what was once planned. The authoritative status is `docs/NEXT.md`; if a note here disagrees, NEXT wins
and the note is stale.
A stage is done when `npm test` passes, the smoke e2e passes, the docs (API, PROTOCOL, DESIGN, NEXT) match the code and the commit
message says honestly what was built, tested and NOT tested (CLAUDE.md).
| Stage | Note | Commits |
|---|---|---|
| 0 Skeleton | [stage-0-skeleton.md](stage-0-skeleton.md) | b56b138 |
| 1 Economy | [stage-1-economy.md](stage-1-economy.md) | b56b138, 249818a (client) |
| 2 World | [stage-2-world.md](stage-2-world.md) | b56b138, 249818a (client) |
| 3 Military | [stage-3-military.md](stage-3-military.md) | 249818a, b18645d |
| 4 Expansion | [stage-4-expansion.md](stage-4-expansion.md) | 249818a, b18645d |
| 5 Social | [stage-5-social.md](stage-5-social.md) | 249818a, b18645d, 931f59e, d84b0c9 |
| 6 Push and polish | [stage-6-push-polish.md](stage-6-push-polish.md) | b18645d, 931f59e, cc0524d |
| 7 Ops and balance | [stage-7-ops-balance.md](stage-7-ops-balance.md) | 931f59e, cc0524d, bf7af06, 9104480 and later |
Note: the work did not follow the stage order exactly. Stages 0-2 went in one commit, 3-5 in the next, and the end game and trade
(planned inside stage 5 / 7) arrived with the client work. The notes list the real commits.

View file

@ -0,0 +1,22 @@
# Stage 0: skeleton
**Goal:** a server that boots, stores state in SQLite, runs a persistent event queue and answers a documented REST API, before any
game rule exists.
**Done when:** repo layout in place; `server/db.js` (driver wrapper, transactions, checksummed migrations) and `server/clock.js`
(the only place that reads time); `scheduler.js` with catch-up after restart; router, error envelope, auth with hashed bearer
tokens, `/healthz`; `docs/openapi.json` generated and checked against the route table; systemd unit, backup timer, DEPLOY.md.
## Built (b56b138)
- `node:sqlite` behind `server/db.js` (D1); migrations `NNN_name.sql` applied in a transaction each and refused if edited later.
- `Scheduler`: events processed strictly in `(due_at, id)` order, one transaction per event, a throwing handler marks the event
`failed` and the queue moves on; `catchUp()` before the listener opens; outbox so push only leaves after commit (stage 6).
- Router with `Idempotency-Key`, per-IP/per-token rate limits (login/signup stricter), 32 KB bodies, scrypt passwords, opaque
tokens stored hashed, strict CSP static server (NETWALL's `net.js`/`static.js`).
- `tools/gen-openapi.js` + a test that fails when a route and `openapi.json` disagree (D7).
- Deploy files, DEPLOY.md and the admin CLI were added at stage 7 (see there).
## Open
- First commit had a manual smoke run only; unit tests arrived with each later stage.
- Never run: a unit under systemd, the backup timer firing on its own, Debian 13 with a real Node 22.13 (only 24.21 was used).
- Tokens never expire and there is no change-password route; revocation reaches an open socket at the next 30 s ping.

View file

@ -0,0 +1,21 @@
# Stage 1: economy
**Goal:** one POP per operator with lazily evaluated resources, buildings with levels, a build queue and storage caps; a minimal
client (POP view, build menu, countdowns).
**Done when:** `rules.resourcesAt(town, now)` is the only way to read a stock; every quantity that grows is `(amount, rate,
updatedAt)` (D3: one `towns.res_at`); build/cancel/rename commands validate and apply in one transaction; `buildDone` is an event.
## Built
- Four resources (Fiber, Hardware, Capital, Power as a battery, D4), resource fields by slot (D8), infrastructure (Core router,
Rack hall, Battery bank, ...), build queue with a second slot unlocked by Core router level (B1: level 3, was 10), cancel.
- `public/js/data.js` holds all numbers; `rules.js` all formulas and loads in browser and Node.
- Client (249818a): login/signup, POP screen with live resource bar ticked from the server clock, build sheet with live
affordability, countdowns, power panel, en + nb, PWA manifest and icons.
- Later balance (BALANCE.md): B4 early-level build discount (levels 1-3 take x0.5/x0.67/x0.83), B5 start stock 1000.
- Fix G1: `buildDone` adds one level to what the building is *now* (test written first, failed before).
## Open
- Nothing is balanced (bots only, 2 seeds for B4/B5); the first hour is limited by the start stock, not build time (B4/B5).
- The capital runs out of things to build long before the backbone opens (BALANCE section 5).
- No service worker, so no offline mode; no light theme.

View file

@ -0,0 +1,18 @@
# Stage 2: world
**Goal:** a seeded map, spawn placement, neutral land, a viewport query and a canvas map.
**Done when:** `rules.tileAt(seed, radius, x, y)` is deterministic; new operators land on a spawn ring; `GET /map?x&y&r` returns
a window; the client map pans, pinches and culls tiles; every game row carries `world_id` (multi-world from day one).
## Built
- First world is 101 x 101 (radius 50, D6), seed random at first boot; `worlds` is data, `create-world` makes more (stage 7).
- Rural areas are held by proximity in v1 (D5), not by a separate tile ownership model.
- `GET /map/tile`, chunked `GET /map` cache on the client, tile info sheet, `js/render.js` canvas (pan, pinch, wheel, keyboard).
- Seven landing sites are derived from the seed (`rules.backboneSites`) and excluded from spawn and settling from day 0.
- `POST /me/join` (9104480) lets an account without a POP found one in a running world after `reset-world`.
## Open
- Map canvas has no inertia/fling.
- `/me` exposes the world seed, which the client ignores.
- Joining a second world was only tested on the default-world path.

View file

@ -0,0 +1,22 @@
# Stage 3: military
**Goal:** training queues, movements (attack, raid, reinforce, scout, return), combat at arrival, loot, reports, incoming warnings.
**Done when:** every future thing is an `events` row; combat resolves only inside the event queue in `(due_at, id)` order; the
client sees incoming attacks without reload; a determinism test replays a fight identically.
## Built (249818a server, b18645d client)
- 10 unit types and research in `data.js`/`rules.js`; `trainDone` per batch, sequential per building; `researchDone`.
- Movements: scan, raid, attack, takeover, reinforce, settle, transport; latency = distance / slowest unit; recall for 90 s; return
legs with loot; arrival re-validates everything and bounces (S3-4).
- Combat: firewall vs DDoS rigs, exploit kits on a chosen building, Rack hall cache, losses; reports are one row with many
recipients, 14-day cleanup (S3-3); beginner protection both directions (S3-7); power: offline units, decommission after 24 h (S3-1).
- Client: Units, Moves, Reports screens, the send dialog, incoming banner and badge, map movement lines.
- Review round 1 (d84b0c9, DECISIONS R1): proto smuggling in `validate.js`, trade-leg recall, escrow cap, rate limits, rankings DoS.
## Open
- Training cannot be cancelled; no sitters, no night protection; units in transit draw no power.
- Nothing balanced: unit stats, costs and research curves are first guesses (BALANCE section 4: raiding profitable per raid but not
a winning strategy at equal attention; takeover expensive enough).
- No garrisons at landing sites (E1): after the opening days nobody can contest a built-up site.
- Takeover/capture flows and the confederation `alliedIncoming` view have no browser run.

View file

@ -0,0 +1,19 @@
# Stage 4: expansion
**Goal:** found new POPs, conquer others, multi-POP UI.
**Done when:** a Rollout crew founds a POP on a chosen wild slot; a hostile takeover moves loyalty to zero and flips owner with the
capital and last-POP protections; the UI switches between POPs.
## Built (249818a server, b18645d client)
- Settle command with wild-slot choice; footprint gate counts the operator's total (S3-8); takeover with loyalty (S3-5);
incumbent (legacy telco) sites with static defence growing with world age and a one-time Hardware bonus; +10% research speed
per incumbent site held.
- Moving units between your own POPs (S3-9); transport links (S3-6).
- Client: POP switcher in the resource bar, expansion card on the POP screen, settle through the send dialog, red ring on POPs that
something is heading for, `refreshTowns` after a settle/takeover.
## Open
- No command to choose a new capital; a captured POP keeps its footprint.
- The Hostile takeover button stays enabled on a capital/last POP (the client cannot know; the server refuses and the UI shows it).
- Settle and takeover resolution were exercised by fast-forwarding movement times in the DB, not by waiting in a browser.

View file

@ -0,0 +1,21 @@
# Stage 5: social
**Goal:** alliances, roles, messaging, diplomacy, marketplace and resource transport.
**Done when:** an alliance can be founded, grown, governed and dissolved; diplomacy states change through events; messages and
rankings work; trade moves resources between POPs and players without creating or losing any.
## Built
- Migration 003: alliances with roles and a stored size cap (S5-1), diplomacy (war, neutral, NAP, confederation; 24 h / speed pact
cancel via the `diploChange` event, S5-2), membership in two tables with one writer (S5-3), messages with per-recipient rows,
DB-backed rate limit and sanitising (S5-5/6), rankings computed per request with a 5 s footprint cache (S5-7/R1).
- Migration 004 (b18645d): Internet exchange trade (T1): offers with escrow, one link per side, 1:2 ratio band, accept = two
transports in one transaction, conservation asserted in tests; shared report folder (T2); `alliedIncoming` (G2).
- Client (b18645d, 931f59e): alliance, messages, rankings, trade (Exchange) screens, `SocUI`, all player text via `textContent`.
## Open
- Alliance rename/description and note editing have no UI; no operator profile page; no sitter accounts; no message retention job
beyond the report/notification pruning.
- Trade: no order book, price history, counter-offers, multi-link deals, or "new offer in reach" notification; escrow refunds are
clipped at the Rack hall cap without a notice (S2); the escrow of a taken-over POP goes to the conqueror.
- The `SOCIAL` numbers (limits, TTLs, role table) are first guesses.

View file

@ -0,0 +1,21 @@
# Stage 6: push and polish
**Goal:** WebSocket push, a notifications table, PWA, layout matrix, i18n nb/en.
**Done when:** the game is fully playable with push disconnected; hints leave only after the transaction that caused them
committed; the layout holds on phone portrait/landscape and desktop; every notification type and error code has en + nb text.
## Built
- `/ws` (b18645d): auth as the first message, Origin check, per-IP cap, 1 KB frames, token bucket, ping/pong with token re-check,
graceful 1001 on shutdown; hints `town`, `incoming`, `notification`, `report`, `message` (docs/PROTOCOL.md). Post-commit outbox (S6-1);
revocation polled, not pushed (S6-2); hints merged per tick (S6-3).
- Client `ws.js`: backoff 1..60 s, close-code handling, refetch after every `ready`; poll fallback (45 s down, 3 min up). Measured in
headless Chromium: incoming banner 214 ms after launch; fallback about 52 s.
- i18n en + nb with parity tests over every error `CODE` and every notification type (`test/client-alerts.test.js`).
- Smoke e2e (cc0524d): `e2e/run.js`, playwright-core, 61 checks, desktop, phone touch, layout matrix on 5 viewports.
## Open
- No service worker (no offline mode), no light theme, no sound or system notifications, no APNs/FCM sender.
- Never run behind nginx Proxy Manager (upgrade headers, idle timeouts, real client IPs); real devices and Safari never run.
- Hint gaps: no `incoming` for confederates, no `town` hint for reinforcing owners, no `backbone_open` push (E2).
- Unread-badge state partly in localStorage; ended-world locking is a DOM sweep, not per-button wiring.

View file

@ -0,0 +1,24 @@
# Stage 7: ops and balance
**Goal:** bot-driven balance passes, an admin CLI, a world lifecycle (start, end, reset), load test with bots, full e2e.
**Done when (CLAUDE.md):** `tools/bot.js` runs N bots for X simulated days in seconds and balance claims cite a run; `tools/admin.js`
creates, ends and resets worlds; the deploy runs on the real target; a human has played a world.
## Built
- `tools/bot.js` + `tools/bot/*` (931f59e): 50 bots x 14 days in about 3 s, 170 days in about 140 s, real server in-process with a
fake clock; exact resource and unit conservation, exit 1 when an invariant breaks. `docs/BALANCE.md` holds method and every run.
- Tuned with before/after runs: B1 second build slot at Core router 3, B2 transport 1000 per link, B4 early-level build discount,
B5 start stock 1000 (bf7af06). Server fix found by the harness: bounced shipments reported no overflow (B3).
- Admin CLI (status, migrate, worlds, create/end/reset-world, users, ban, inspect, events, replay-events, backup/verify-backup,
grant), deploy units, backup timer, DEPLOY.md. `end-world` now runs the real `worldEnd` handler (final ranking, escrow back,
events cancelled); quiet on a closed stdout pipe.
- Ops scripts: `deploy/update.sh` (backup, fast-forward, health check, rollback), `deploy/upstream-offsite.{service,timer}`
(off-box copy of the newest verified snapshot). Tests with stubs: `test/deploy-update.test.js`, `test/deploy-offsite.test.js`.
## Open
- **Not balanced.** Bots are not humans. A 3x world's end game is as long as a 1x world's; raid loot splits evenly and is destroyed
on overflow; no fight for a built-up landing site (E1); the capital runs out of builds before the backbone opens.
- No load test over HTTP/WebSocket with many real sockets; the full e2e suite beyond the smoke run; no scheduled "create next world".
- Never run: Node 22.13 (the stated minimum), the update script or the off-site copy against real systemd/ssh, the backup timer on
its own, nginx Proxy Manager, a restore on the real box.