Stage 3-5 server (military, expansion, social), web client for stages 1-2, ops/deploy

Built: units/research/training, movements (scan, raid, attack, takeover, reinforce, settle, transport), deterministic
combat resolved in the event queue, reports, power/offline units, founding + conquest + incumbent sites; alliances,
roles, diplomacy (24h pact cancel via events), messages, rankings; vanilla-JS phone-first client (auth, POP, map,
alerts, settings, en/nb); systemd units, backup timer, DEPLOY.md, tools/admin.js.
Tested: npm test 96/96 (fake clock, in-memory db, a few real-HTTP tests); client checked with headless Chromium
screenshots only. NOT done: marketplace/transport trade, client screens for military/social, WebSocket push,
bots/balance, e2e suite. All unit stats and costs are unbalanced first guesses.

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 18:32:36 +02:00
parent b56b13880e
commit 249818a7aa
111 changed files with 17472 additions and 13 deletions

View file

@ -33,3 +33,98 @@ 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).
## 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
downgraded building must never kick anyone, so the cap is monotonic: commands that depend on it (invite, accept, transfer) raise it if
the CURRENT leader's best office would give more; reads show `max(stored, formula)` without writing. The floor is therefore 10 even
for a leader without an office after a transfer. The office requirement (>= 1) is checked when founding and when accepting an invite,
not afterwards.
## S5-2 — Diplomacy move table is data, three kinds of change
`SOCIAL.diplomacyMoves` (data.js) says for each (from, to) whether it is `immediate`, a `proposal` or `delayed`. War from neutral is
immediate (no consent needed). Anything that leaves a pact (nap/confed -> neutral/war, confed -> nap) is `delayed`: 24 h / world speed
via a `diploChange` event, so you cannot betray a partner without warning. Pacts and peace need acceptance. While a delayed change is
pending the pair is locked (`diplomacy_pending`); only the starter can revoke. A pair at `neutral` with nothing pending has no row in
`alliance_relations`. Acceptance re-validates against the current state, because the relation may have moved since the proposal.
`war -> confed` is not allowed (go through a pact first).
## S5-3 — Membership lives in two tables, one writer
`operators.alliance_id` (from 001, cheap joins in /map, /me) and `alliance_members` (role, joined_at, one leader per alliance by a partial
unique index). `alliances.js` addMember/removeMember are the only writers. Alliance rows are hard-deleted on disband; messages keep a
`alliance_tag` snapshot and carry no foreign key to alliances so broadcasts survive.
## S5-4 — Last online comes from tokens
No new column: `lastOnline` = newest `tokens.last_used_at` of the member's user, which auth.js refreshes at most once a minute. So it
is accurate to about a minute and includes revoked tokens (a logout still counts as having been online).
## S5-5 — Message rate limit is DB-backed, not the in-memory Limiter
`server/http.js` Limiter keys on monotonic real time and forgets on restart; message limits are a product rule that should follow the
(fake) clock and survive restarts, so the sender's recent rows in `messages` are counted (`SOCIAL.messageLimits`, indexed by
`messages_sender`). The per-token/IP limiters still apply on top.
## S5-6 — Messages: per-recipient rows, sanitising on write
One `messages` row plus one `message_recipients` row per recipient (broadcast fan-out at send time: members who join later do not see
old broadcasts; members who leave keep what they received). Read/delete state is per recipient; the sender's copy is hidden with
`sender_deleted_at`; the row is purged when nobody has a copy. A blocked sender is silently not delivered to (no row), so blocking does
not leak. Text is sanitised once on write (`server/text.js`): C0/C1 controls, bidi overrides and isolates, zero-width and invisible
tag characters are stripped, NFC, `\r\n` -> `\n`; ZWJ/ZWNJ are kept for emoji. Clients render with `textContent` only.
## S5-7 — Rankings are computed per request, no cache
Footprint for a whole world comes from two queries (towns, buildings) and `rules.footprintAt`; fine for the expected 50-300 operators.
If it ever shows up in a profile, cache per (world, minute). Cursor is a rank offset because rankings are a computed snapshot, not rows.
## S5-8 — Route params and list order
`inviteId`, `noteId`, `proposalId`, `otherId`, `operatorId` were added to `INT_PARAMS` in http.js. Lists that are newest-first (messages)
use the last id as the `after` cursor and return older items; this is the one place `after` does not mean "newer than".
## S3-1 — Online/offline is computed lazily; `powerCheck` only does the side effects
Units are offline while the battery is empty and net power is negative. That is derived from the lazy battery value (`power.online`) at
the moment it matters (sending, combat, the town view), never from an event having run. The `powerCheck` event (one pending per POP,
re-armed by `power.reschedule` after anything that changes unit draw or building levels, including `buildDone`) only writes the
"units offline" notification and does the decommission after 24 h / world speed. Offline is all-or-nothing per POP (the contract of
`rules.unitsOnline`); the decommission then removes the most expensive units (home first, then reinforcements) until the draw fits the
output, not everything. Offline units are neither counted in defence nor hurt by a raid, but a full attack lost by the defender still
wipes them. Reinforcements draw from the host (`state.unitDraw` reads `stationed`); units in transit draw from nobody.
## S3-2 — Research is per POP, speed bonus per operator
`town_research(town_id, unit, stat, level)`; level n needs a Research lab of level n + 2, one research at a time per POP. An attack uses a
snapshot of the origin POP's research taken at departure (`movements.extra.research`); defenders use the research of the POP each group
belongs to. Incumbent sites: +10% research speed per distinct site taken (cap +50%), and a one-time +2500 Hardware per site and operator.
Taking a site does not remove it: it stays a static fortress for everybody else.
## S3-3 — One report row, many recipients; cleanup armed at the earliest expiry
A battle is one `reports` row shared through `report_recipients(report_id, user_id, role, read_at)`, so both sides see the same data (a
scan is two separate rows: intel for the scanner, "a scan happened" for the target, with the scanner's identity only if the target's
scanners won). `reportCleanup` is armed at the earliest `expires_at` (14 days, real time, not divided by world speed) and re-arms itself
only while reports remain: at most one pending cleanup per world, none on a quiet world.
## S3-4 — Arrival re-validates everything and bounces
A movement is validated when it is sent and again when it arrives (the target may have changed owner, got protection, joined a pact, the
tile may have been taken). If it no longer holds, the units turn around with the loot they carry and the sender gets a `movement_failed`
report. Return legs whose origin POP changed hands go to the operator's capital (or oldest POP).
## S3-5 — Takeover details
Only `takeover` movements (with an M&A team) can lower loyalty; one team per attack counts and is used up when it does. `takeoverBlock`:
a player's last POP wins over "capital" (refused at send); a capital with siblings is only dragged to loyalty 0. Loot is taken in the same
arrival, before the POP changes hands. On transfer the old owner's pending training/research is cancelled, pending builds are re-keyed to
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
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.
## S3-7 — Protection
Beginner protection blocks raid/attack/takeover in both directions. Sending one from a protected operator needs `confirmEndProtection`
and ends it at once; attacking an incumbent site does not end it; scans never do. The target's protection is compared with the ARRIVAL
time at send, and re-checked at arrival.
## S3-8 — Footprint gate counts the operator's total
`footprintNeeded(n)` with n = POPs owned now (second POP: n = 1). Founding and takeover both need `sum(footprint of own POPs) >= need`,
nothing is spent. New POPs start with every field at level 0, no infrastructure, 250 of each resource and loyalty 100.
## S3-9 — Moving units between your own POPs
`reinforce` to an own POP puts the units into `town_units` of the target (they live there now). Only units of OTHER operators are
`stationed` rows.