Built: units/movements/reports/send/expansion screens, alliance/messages/rankings screens, ws client + server /ws push (docs/PROTOCOL.md), Internet exchange trade, backbone endgame + world end, shared reports, buildDone relative levels. Tested: npm test 175/175. Two adversarial reviews found issues (trade-leg recall exploit, __proto__ via validate.js, rankings DoS, static headers, ...): fixes follow in the next commit. NOT done: bots/balance, e2e suite, real-device checks. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
18 KiB
DECISIONS
Short log of non-obvious decisions and why. Newest at the bottom.
D1 — node:sqlite as the driver
Dev machine runs Node 24; the deploy target (Debian 13 LXC) ships Node 22+. node:sqlite is used through server/db.js only, so
better-sqlite3 is a one-file swap if it ever misbehaves. Parameters are always positional.
D2 — Scheduler processes ALL due events before any command or read
scheduler.runDue() runs every pending event with due_at <= now globally, in (due_at, id) order, not just the ones touching the
town in question. It is simpler and makes fairness trivial (nothing resolves out of order). Cost is nil in practice because the timer
processes events within milliseconds of their due time; it only matters after a restart (catch-up).
D3 — One towns.res_at for all lazily-grown values
Fiber, hardware, capital, power battery, footprint and loyalty are all settled together at res_at (state.settle). Any change that alters a
rate (building finished, unit trained or lost) settles first. rules.resourcesAt is therefore exact between settles.
D4 — Power battery uses the same lazy model
Battery = (amount, rate = net power x world speed, cap = Battery bank). Units are offline while battery = 0 and net < 0
(rules.unitsOnline). The 24 h decommission countdown is an event scheduled from rules.batteryEmptyAt.
D5 — Rural areas are held by proximity in v1
DESIGN.md leaves "contested or just held" open. v1: a POP within ruralReach (2) tiles of a rural tile gets its +25% (max 3, nearest first).
Computed from the seed, no state. Revisit after the first world.
D6 — First world is 101 x 101, not 301 x 301
DESIGN.md's own open question. mapRadius is world data (worlds.map_radius), default 50.
D7 — docs/openapi.json is generated
tools/gen-openapi.js builds it from the route table (schemas live in route meta + server/routes/schemas.js). npm test fails when the
committed file is stale, which satisfies "updated in the same commit as any route change" mechanically.
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.
S6-1 — Push hints leave only after the commit, through an outbox
scheduler.notify runs inside the transaction of the event or command, so pushing there would announce changes that may still roll
back. notify queues into scheduler.outbox (only when a listener is set); process() and commands.run flush it after COMMIT
(db.depth === 0) and truncate it to their mark on rollback. town hints use the existing scheduler.onEvent (post-commit already)
and a new commands.hooks.onCommand. push.js itself knows no game rules (it gets townOwner / tokenValid injected), the routing
lives in pushHooks.js. No new dependency (ws was already listed).
S6-2 — Revocation is polled, not pushed
Tokens are revoked by plain SQL in routes and the admin tool. Instead of hooking each place, the ping tick (30 s) re-checks
tokens.revoked_at and users.banned for every authenticated socket and closes with 4401. Worst case 30 s of hints after logout on
another device; hints carry no data, so nothing leaks. If that is ever not good enough, call a push.disconnectToken(id) from the routes.
S6-3 — Hints are merged per tick, town is not sent to the target at launch
Identical JSON hints produced in one tick (a catch-up) are deduplicated per socket via setImmediate. A launched movement tells the
target's owner incoming (town + ETA) and no plain town hint, so the type and origin of a launch cannot be inferred from extra traffic.
E1 — A landing site is a row of its own, not a POP
landing_sites(world_id, idx, x, y, holder_alliance_id, holder_operator_id, level, stockpile, build_*) (migration 004), positions from
rules.backboneSites(seed, radius). A town row of kind landing owned by the leader was considered and rejected: a "POP" that nobody plays
would have to be excluded from footprint rankings, the last-POP / capital / footprint-gate counts, homeTownFor, /me, spawn spacing and
the Rack hall cap (shipped resources would be thrown away at 250), and a leader change would have to re-own it. The holder is the
alliance (holder_alliance_id, FK ON DELETE SET NULL, the disband hook also clears it), holder_operator_id only records who took it.
Consequence, on purpose and to be revisited after the first world: no units can stand at a site, so there is no garrison and no
reinforcement. A site is defended by the static value incumbentDefence x 12 x (1 + 0.03 x level) only, i.e. exactly the "incumbent
with a backbone multiplier" of DESIGN.md; holders defend by growing the node (higher level = harder to take), attackers can scan the exact
number. Hooks into the military code are small: combat.arriveSite hands backbone tiles to military/landing.js,
arrivals.arriveTransport hands shipments (extra.siteId) to endgame.deliverShipment, sendMovement calls endgame.checkLandingTarget.
E2 — Site rows are created lazily, there is no timer event
ensureSites creates the 7 rows when something first touches a site (an attack/scan sent or arriving, a shipment, a build) once the world is
at day 100 / speed; that first call also writes a backbone_open notification for every operator. Reads (/worlds/:id/status, /map, tile
info) never write: untouched sites are shown as the incumbent's, level 0, id: null. A backboneOpen event at world creation was
dropped: a pending event 100 days ahead sits in every quiet world and breaks tooling that counts pending events (the admin CLI test).
Cost: nobody is pushed the moment the sites appear unless a first touch happens; clients see phase: backbone_open when they poll status.
E3 — The winner is fixed at level 100; the world is frozen when it ends
The holder of a node whose level completes at 100 wins (worlds.winner_*, once per world) and worldEnd is scheduled
graceDays x 24 h / speed later. Losing the node meanwhile does not change the winner (the race is over; the grace days are for the ranking
and the post-game). If a level-100 node is taken while nobody holds it (the holder disbanded mid-build) the new holder wins. worldEnd
writes the ranking snapshot, sets status = 'ended', closes open trade offers (expired, escrow back in its POP: every unit stays accounted
for) and CANCELS every other pending event of the world: nothing arrives, trains,
expires or builds after the snapshot, so the stored ranking stays the truth. Movements still out and queued builds stay as they were.
A running build of a site continues for whoever holds the site when it lands (the level belongs to the site; the cost was paid from the
stockpile at the start); the stockpile and the ledger stay with the site when it is taken.
E4 — world_ended is one gate in commands.run, found by probing the arguments
ownedTown, operatorOf and requireRole are shared with reads (rankings, map), so gating there would break "readable after the end".
commands.run calls endgame.guard(db, name, args): the world is args.worldId, else the world of townId/fromTownId/hostTownId,
allianceId, movementId, inviteId, proposalId, offerId, siteId, reportId, else the caller's oldest operator (the default every
command already uses). Allowed after the end: markReportRead, messageSend/Read/Delete, messageBlock/Unblock. New commands are gated
automatically as long as they carry one of those arguments.
E5 — Backbone cost curve is not the building curve
4000 x 1.28^99 is unreachable; the node has its own ENDGAME.costGrowth = 1.045 and timeGrowth = 1.025 (about 7.2 M of each resource and
about 36 world days of building in total, level 100 alone 312 k each and 23 h). Pure guesses until a bot run (stage 7) says how much an
alliance can ship; nothing here is balanced.
T1 — Trade: escrow, one link per side, reach by exchange level
- Offers are escrowed in
trade_offersand hold one transport link of the poster's POP while open (movements.activeLinkscounts 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). - Reach:
10 tiles x exchange levelof the taker's POP, and the offer's ownmaxDistance; the poster's level only matters for the number of offers they can hold open. - A POP changing hands voids its open offers (
combat.transferTowncallstrade.onTownTransferred); the escrow stays in the POP. transportArrivedhook:server/trade.jsregisters itself when required (bothcommands/index.jsandevents/index.jsload it), so the consumer exists in every test fixture that builds commands or events.- Offer expiry: one
tradeExpireevent per offer, cancelled on accept/cancel/void, idempotent (acts only whileopen).
T2 — Shared reports extend the report's life
Sharing sets expires_at = max(expires_at, now + 14 days) on the single shared reports row, so the folder is not emptied by a report that
was nearly due; the cascade report_shares.report_id ... ON DELETE CASCADE removes the share when the report is cleaned up.
G1 — buildDone adds one level to what the building is NOW
Each build event adds exactly one level to the current level (never lowers, never above the queued toLevel), so an upgrade in flight
cannot undo exploit-kit damage; a building knocked to 0 comes back at 1. The notification reports the real level.
G2 — Allied incoming is a separate list
GET /movements keeps incoming as "heading for YOUR POPs" and adds alliedIncoming for partners' POPs (own alliance + confederations),
each entry with ally: true and toOperator. Mixing them would make clients count allies' attacks as their own.