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

35 lines
2.3 KiB
Markdown

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