Upstream/docs/DECISIONS.md
jvanvik b56b13880e Stage 0-2 server spine: db, scheduler, REST, auth, economy, map
Built: SQLite (node:sqlite) via server/db.js with checksummed migrations, injectable clock, persistent event
scheduler with catch-up, tiny REST router (error envelope, idempotency keys, rate limits, bearer tokens with scrypt
passwords), lazy-resource economy in public/js/rules.js + data.js, build/cancel/rename commands, seeded map +
spawn ring, generated docs/openapi.json. NETWALL net.js/static.js reused.
Tested: manual smoke run only (signup, town view, build, map). No unit tests or e2e yet.
NOT done: military, expansion, social, client, push, deploy docs, bots/admin.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
2026-10-11 18:07:42 +02:00

2.3 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).