Plans: the server-run design in the repo, what is left now, and the fork's files

- docs/plans/server-run.md: the server-run design, which lived only outside
  the repo, with a status at the top (T1 and T2 merged, T3, T4 and the
  integration waiting for the go; the four answers; the questions still
  open) and a section on what building T2 changed: a checkpoint needs more
  than route memory (rt carries pt, sl, ord and rk), who a worker exit
  counts against, the budgets now over, the contract additions, the open
  path-window question and what the shared calendar changes. The answers
  are marked where sections 0, 1 and 14 ask; probes are named, not pathed.
- docs/plans/next-session.md: rewritten to match main at 3e30621: what is
  built, the answers, the holds, the nine open questions, what is in
  progress and next, and only the limitations that still hold.
- docs/ARCHITECTURE.md: a table of the fork's own files (build standard,
  dark mode, IPv4, IPv6-only, express fiber, satellites, multiplayer,
  server-run play, the session server and the engine), kept apart from
  upstream's tables so merges stay clean.
- docs/MULTIPLAYER.md: server-run play is being built and not switched on.
This commit is contained in:
jvanvik 2026-11-09 22:47:43 +01:00
parent 3e30621684
commit 8068a45abd
4 changed files with 1578 additions and 63 deletions

View file

@ -93,6 +93,28 @@ Development runs on `npm run dev` (assembles the development page on every reque
| `scripts/weekly-scenario.js`, `scripts/lib/scenario-bot.js`, `site/scenarios/weekly/` | The weekly scenario generator, its reference player and its output (see below) | | `scripts/weekly-scenario.js`, `scripts/lib/scenario-bot.js`, `site/scenarios/weekly/` | The weekly scenario generator, its reference player and its output (see below) |
| `docs/adr/` | Decisions: GitHub Pages only (0001), one page assembled at build (0002), translations by label (0003), development-only code (0004) | | `docs/adr/` | Decisions: GitHub Pages only (0001), one page assembled at build (0002), translations by label (0003), development-only code (0004) |
## This fork's own files
This copy adds features upstream does not have. They follow the same rules as the rest of `src/`, and are listed here
apart so that upstream's tables above merge cleanly. The multiplayer server is for self-hosted copies only: a plain
build stays the static page described above.
| Path | What it is |
| --- | --- |
| `src/game/60-features/96-pop-standard.js` (grown from upstream's POP standard), `src/game/90-actions/88-build-standard.js`, `src/game/93-ui/59-build-standard.js` | The build standard: one target for every POP, port and fiber (`BSTD`, saved sparse in `S.popStd`), what is below it and what bringing it up costs (`bstdPlan()`, `bstdQuote()`), the sheet, "Bring everything up now" (`bstdApply`) and the intern's "Keep to the build standard" order (`std`, in `95-standing-orders.js`). The router model and the line system are picked here and nowhere else |
| `src/game/93-ui/15-theme.js`, `src/styles/05-theme.css`, `src/game/96-map/15-palette.js` | Dark mode (#80): Light, Dark or Auto per device (`sot-theme`), set on `<html data-theme>` before the first paint; the panels' dark colours as CSS custom properties; the map's colours per theme |
| `src/game/60-features/33-address-space.js`, `src/game/90-actions/54-address-space.js`, `src/game/94-dashboard/72-address-space.js` | IPv4 address space (#150): blocks held, bought, leased in and leased out (`S.ip4`), customers' blocks, CGNAT and its ratio; the bank's Address space section |
| `src/game/60-features/34-ipv6-only.js`, `src/game/90-actions/55-ipv6-only.js` | IPv6-only broadband: a city's home routers swapped for 464XLAT, and the NAT64 pool next to CGNAT |
| `src/game/80-simulation/65-express.js`, `src/game/90-actions/87-express.js`, `src/game/93-ui/72-express.js`, `src/game/96-map/51-express-geometry.js` | Express lightpaths (#58): a link of kind `xp` from A to C over a chain of ROADM fibers, passing the cities between as light; its rules, actions, panels, the link window's Express tab, and how the map draws it |
| `src/game/10-catalog/75-satellites.js`, `src/game/60-features/45-teleports.js`, `src/game/90-actions/87-teleports.js`, `src/game/93-ui/72-teleport-panels.js` | Satellites (#83): teleports at POPs (`p.tele`) and rented GEO and MEO circuits (links of kind `sat`): the birds and their reach, the rules and money, the actions and the panels |
| `src/game/60-features/89-multiplayer.js`, `src/game/95-modals/48-multiplayer.js`, `src/game/90-actions/92-multiplayer.js`, `src/styles/41-multiplayer.css` | Multiplayer, only in a copy built with `MP_API` ([MULTIPLAYER.md](MULTIPLAYER.md)): `S.mp`, saves and cards sent to the session server, the `#mp=` link; the title screen's door, the session panel and the HUD chip; `srvOn()`, false until server-run play is switched on |
| `src/game/98-server-play/`, `src/styles/43-server-play.css` | The page's side of server-run play (T4), only in a multiplayer build's page; a comment so far ([plans/server-run.md](plans/server-run.md)) |
| `scripts/mp-server.js`, `scripts/lib/mp.js` | The multiplayer session server: the command line and the built site, and the API with its storage. `npm run dev -- --mp` mounts the API in the development server |
| `scripts/lib/mp-sim-acts.js` | Server-run play's act tables (SEND, ASK, VOTE, LOCAL, CONFIRM, DRAFTS, TEXT, WINDOWS…) and the envelope check every request passes |
| `scripts/lib/mp-sim-engine.js`, `scripts/lib/mp-sim-worker.js`, `scripts/lib/mp-sim-realm.js` | The server-run engine (merged, not wired in yet): worker threads, each holding a vm realm per network that runs the plain page's game, behind the promise API the session host will use ([plans/server-run.md](plans/server-run.md)) |
| `tests/lib/mp-sim-*.js`, `tests/fixtures/mp-sim/` | Server-run play's contracts for the tests: the shape checker, the fake engine, the fixtures and their generator, the button crawl, and the player that plays a realm against a page |
| `docs/plans/next-session.md`, `server-run.md`, `multiplayer-phase2.md` | What is left and what waits for a decision; the server-run design and its status; the phase 2 design (on hold) |
## Globals ## Globals
- **`S`**: the whole saved game (one JSON object). Cash, day, POPs, links, transit, - **`S`**: the whole saved game (one JSON object). Cash, day, POPs, links, transit,

View file

@ -38,6 +38,14 @@ is switched on only when the build is told where the session server lives.
Not yet (phase 2): peering, transit and competition between players inside the simulation. The card already carries Not yet (phase 2): peering, transit and competition between players inside the simulation. The card already carries
what that will need (POPs, links, exchanges, transit, peering policy, reach). what that will need (POPs, links, exchanges, transit, peering policy, reach).
## Being built: the server runs the game
Work has started on server-run play. In a multiplayer build, the session server will run every network's days, so all
players of a session share one calendar and one speed, and the page will only show the network and send the player's
clicks. The engine that runs networks on the server is in the source (`scripts/lib/mp-sim-*.js`), but nothing uses it
yet and it is not switched on: sessions work exactly as this page describes, with each network simulated in its own
player's browser. The design and how far it has got are in [plans/server-run.md](plans/server-run.md).
## Build ## Build
```bash ```bash
@ -209,3 +217,6 @@ Cards are what each player's browser says: nothing on the server checks that a n
`src/game/95-modals/48-multiplayer.js` (door, sheets, panel, chip), `src/game/90-actions/92-multiplayer.js` `src/game/95-modals/48-multiplayer.js` (door, sheets, panel, chip), `src/game/90-actions/92-multiplayer.js`
(actions), `src/styles/41-multiplayer.css`. The build stamps `MP_API` into `src/game/00-core/20-analytics.js`. (actions), `src/styles/41-multiplayer.css`. The build stamps `MP_API` into `src/game/00-core/20-analytics.js`.
- Tests: `tests/mp-server.test.js`, `tests/multiplayer.test.js`. - Tests: `tests/mp-server.test.js`, `tests/multiplayer.test.js`.
- Server-run play (being built, not switched on): the act tables `scripts/lib/mp-sim-acts.js`, the engine
`scripts/lib/mp-sim-engine.js`, `mp-sim-worker.js` and `mp-sim-realm.js`, the page's side `src/game/98-server-play/`
(a comment so far), and the tests `tests/mp-sim-*.test.js` and `tests/server-sim-prereqs.test.js`.

View file

@ -1,75 +1,139 @@
# What is left (as of 2026-11-07) # What is left (as of 2026-11-09)
Work in this fork, pushed to the `vanvik` Forgejo remote (never to `origin`). Built so far: the build standard (the only Work in this fork, pushed to the `vanvik` Forgejo remote (never to `origin`). `main` is at 3e30621. Nothing below is
place for the router model and line system), multiplayer phase 1, dark mode (#80), IPv4 address space (#150) with switched on or built unless it says so.
IPv6-only broadband and NAT64, express fiber (#58) and satellite teleports (#83). Everything below is planned or known,
not built. Items 5 and 6 wait for the owner's go.
## Promised and not done yet ## Built so far
1. and 2. are built: the router model and the line system are picked in the Build standard sheet only (the `routers` and On top of upstream, merged up to 3.3.0 (61e31c5 "Merge upstream: Lambda Bazaar, traffic badges, moving customers and
`optup` orders read `bstd().g` / `bstd().sys`; sanitize moves an old setting into `S.popStd`), and `std` takes a fiber faster routing (3.3.0)"; earlier merges 032470f and 4b922ab):
dark on `optup`'s routing test (`opsDark()`), sharing its budget a night, with one owner per fiber a shift (`X.fib`). - **Build standard**: 2b48a6a "A build standard for the whole network, kept by the intern", and fbae6fc "The build
standard owns the router model and the line system; one owner per fiber" (the router model and line system are
picked in the sheet only; the `routers` and `optup` orders read them from there).
- **Multiplayer phase 1** for self-hosted copies: 95aa9b6 "Multiplayer for self-hosted copies: sessions, server-side
saves, a leaderboard" (`docs/MULTIPLAYER.md`).
- **Dark mode (#80)**: 2cd6b71 "Dark mode: Light, Dark or Auto under Settings › Theme".
- **IPv4 address space (#150)**: eac0604 "IPv4 address space: scarce, bought, leased, leased out; IPv6 is free", and
69328ce "IPv6-only broadband: 464XLAT city by city, a NAT64 pool next to CGNAT".
- **Express fiber (#58)**: 8e1f2d6 "Express fiber: light a wave through a city without its router".
- **Satellite teleports (#83)**: e1ae8e0 "Satellite teleports: GEO and MEO circuits for islands and remote towns".
- A fix after the 3.1.0 merge: e8808f6 "The connections list no longer breaks on a 400G fabric port".
- **Server-run play, parts 1 and 2** (merged, not switched on): T1 is d1e127d "Server-run play, part 1: game
prerequisites and shared contracts". T2 is 065c922 "Server-run play, part 2: the engine" with its fixes c5c7ea9,
72f31e8, 3b8c331, 9597d89, 77f4035 and 3e30621. The design, its status and what building T2 changed in it are in
`docs/plans/server-run.md`.
## Next features ## The user's answers (2026-11-09)
3. **The server runs every game of a multiplayer build** (decided 2026-11-07, being designed and built). In a page built The four questions of the server-run design:
with `MP_API`, each network's days run on the session server, not in the browser, so every player of a session is on 1. A player who joins an old session starts on the **session's date**: one shared calendar. The game's day-0 rules
the same day at the same speed. A single-player game in that build is a session of one and runs there too; old local then have to count from each network's own start (`server-run.md`, "What Q1 changes").
saves keep working in the browser, and the plain build stays exactly as it is (static, no server, no requests). 2. Single player in a multiplayer build runs **on the server** by default; "this device" stays an option.
- **Speed:** 1× by default (one day per `DAY_MS`, 2.5 s). Players vote for another speed, pause included; alone in a 3. An empty session that wakes runs at **1×**.
session your vote decides at once. The world pauses while no player is connected. 4. Phase-1 sessions **start fresh**: nothing is migrated.
- **Absent players:** while anyone plays, the networks of those away keep running on the server (their intern's
standing orders help), so nobody falls behind. ## On hold until the user says go
- **Why:** the same day for everyone, which phase 2's trades need, and less work for phones at higher speeds (at 1× the
day is about 10–15% of a phone's CPU on the big test network, at 8× about half; map and panels stay in the browser). - **#97 co-op companies** (several players run one network, with roles, budgets and approvals).
- **What stays in the browser:** map drawing and panels. The flow tables (`R.ef`/`R.fl`, about 3 MB per routing on the - **Multiplayer phase 2** (players as carriers in each other's simulations: transit, peering, PNIs, shared fiber):
big network) cannot be shipped every day, so what reads them (a selected link on the map, the link panel, PNI value, design in `docs/plans/multiplayer-phase2.md`. When it restarts, that design needs rework for the shared server clock:
puzzles) has to ask for them. it assumes each player's own clock, and tenders and notice timed in real minutes.
- **Phase 2 gets simpler:** with every world in one server process, its wall-clock timing (tenders that close after 10 - **#144 directional traffic**, last and on its own: keep the totals, split them by traffic profile, utilization is the
real minutes, `idle` ≥ 300 s, notice on each player's own clock) can move to game days. busier direction. It comes after #58 because both touch link capacity (express channels count too).
4. **IPv6-only broadband, the follow-up** (after the server-run game, or alongside it: it touches the build standard and
the intern, not the server). A build-standard row "Broadband: IPv6-only" (cities with broadband start the swap) and the ## Open questions waiting for the user
intern's `std` order rolling it out when there is money, busiest CGNAT cities first. `ip6Go`/`ip6Stop` and the city
panel are in `src/game/60-features/34-ipv6-only.js`; the row goes into `BSTD` and `bstdPlan` (96-pop-standard.js). Asked on 2026-11-09, not answered yet:
5. **Wave B: #97 co-op companies** (several players run one network with roles, budgets and approvals), host-authoritative 1. **Late joiners' prices and beginner grace.** With one calendar, a friend who joins an old session meets its economy
over the multiplayer server, and **multiplayer phase 2** (players as carriers in each other's simulations: transit, from day one: at day 1868, hardware about 18% dearer and customer prices about 34% lower, with the 180-day beginner
peering, PNIs, shared fiber): design in `docs/plans/multiplayer-phase2.md`. grace long over. Keep that, or give a grace or extra starting cash counted from the joiner's own start?
6. **Wave C: #144 directional traffic**, last and on its own: keep the totals, split them by traffic profile, utilization is 2. **Other players' POPs on the map.** Draw other players' POPs and links on your map (from their cards) as part of
the busier direction. It comes after #58 because both touch link capacity (express channels now count too). the server-run work, or wait for phase 2?
3. **The other modes in a multiplayer build.** Sandbox, scenarios, puzzles and the weekly keep running on the device.
Fine, or should sandbox (or all of them) also run on the server?
4. **Dark mode and the build standard upstream.** Upstream contributors have said they will open pull requests for a
dark mode (#80) and a bulk redundancy kit (#317), and a three-tier router standard sits on another contributor's
branch (#315). Offer the fork's dark mode and build standard upstream before those land, or keep them fork-only and
settle the clash at the next merge?
5. **#58 whole-fiber splicing.** Is the express lightpath enough, or should a whole fiber pair also splice through a
city (one dark fiber A–C through B, with no ROADM at B)? The issue asks for "waves and/or entire fibers".
6. **#83 WISP zones and a rented LEO tier.** Add island demand pools served remotely on top of the existing island
cities, and a tier between MEO and Pie in the Sky that rents LEO capacity from a partner network? Or are teleports
with GEO and MEO circuits enough?
7. **Investors' cut of IPv4 lease income.** Should investors on a revenue-share loan take their cut of the income from
leasing out IPv4 blocks too? Today they do not (dark fiber sold to customers is in their share).
8. **Founding an exchange on a basic router.** Founding your own exchange gives a 400G port even where the POP's router
only takes 100G, though the shop would not sell that port. Document it as a limitation, block founding until the
router takes 400G, or found at the router's largest port size? (`tests/server-sim-prereqs.test.js` asserts today's
behaviour.)
9. **The six old wip worktrees.** They hold nothing `main` lacks. Delete them and their branches?
## Next
- **In progress** (another builder is on these right now):
- the build standard's "Bring everything up now" and the intern follow one rule for fibers that carry sold alien or
managed waves (today the button can take such a fiber dark for a day, while the intern refuses any fiber with a
customer, leased pairs and IRUs included, which a line-system swap cannot hurt);
- dark mode: the capacity market's hot and cool tags, and red `--bad` text that is below AA contrast on dark cards;
- IPv4 notices in the notification log get their "Address space" button;
- the "no subsea cable lands here" hint (#321) mentions a satellite circuit where a teleport can reach the city;
- express fiber: a regen site added later charges for the express channels on its fiber, and loss incidents on a
fiber reach the expresses on it;
- selective peers react to peering that rides a GEO link;
- the intern's two small standing-orders fixes in `opsRun()` (the shift's log keeps an uncapped list of broken
orders, and the week's tally makes an empty list of places for a job that names none); `opsTidy()` stays after the
shift until `tests/canonical-state.test.js` passes without it;
- IPv6-only broadband in the build standard: a "Broadband: IPv6-only" row, with the intern's `std` order rolling it
out busiest CGNAT cities first (`ip6Go`/`ip6Stop` are in `src/game/90-actions/55-ipv6-only.js`, the panel and day
logic in `src/game/60-features/34-ipv6-only.js`; the row goes into `BSTD` and `bstdPlan` in
`src/game/60-features/96-pop-standard.js`).
- **After the user's go:** T3 (host and protocol), T4 (the browser client) and the integration of server-run play,
as `docs/plans/server-run.md` describes them, with the corrections at its top. That includes the Q1 work: the game's
`S.day0` and day-0 rules, a start day for a new network on the server, and `CLOCK.off` taken out of the contract.
## Known limitations of what shipped ## Known limitations of what shipped
- **Multiplayer:** other players' POPs are not drawn on the map (no clean hook yet); cards are what each browser reports, - **Multiplayer (phase 1):** each browser runs its own clock, so the players' worlds drift apart (server-run play fixes
the server does not verify them; a save over ~60 KB sends only the card when the tab closes; the HUD chip in phone this for new sessions only); other players' POPs are not drawn on the map (open question 2); cards are what each
landscape wider than 760 px was not measured. Behind a reverse proxy, run the server with `--trust-proxy`, or every browser reports, and the server does not check them; a save over ~60 KB sends only the card when the tab closes, and
player shares one address for the rate limits. the save goes with that device's next push; a session network still makes its save on the page, so it misses 3.3.0's
- **Build standard:** the game menu has 8 tiles in a multiplayer game (7 otherwise), so the last row is not full. The smoother saves in the worker; the capacity market and path moves are each player's own, with no market shared
sheet's quote and "Bring everything up now" still judge a line-system swap without routing (`bstdDarkOk()`: a quiet between players; the HUD chip in phone landscape wider than 760 px has not been checked by eye (worth doing when T4
fiber, under 10% of its capacity, or a parallel link with room; any express with traffic holds its fibers, changes the chip). Behind a reverse proxy, run the server with `--trust-proxy`, or every player shares one address's
`bstdXpBusy()`), so the quote is the bill; only the intern routes to test. A quiet fiber with no way around can still rate limits.
go dark from the button. An old save's `routers.model` moved into the standard (only from a running order with an - **Server-run engine (merged, not switched on):** a checkpoint is over its size budget, and so are a snapshot, a big
intern hired; a paused one's is dropped) also becomes what new POPs get. A model or line system in the standard is a realm's memory and a small network's day; a checkpoint written before c5c7ea9 restores close to exact, not exact; the
ceiling for the `routers` and `optup` orders (their next-one-up rule only applies with "keep"), as an order's own engine has no per-call deadline of its own; a worker of its own whose session's loads all fail stays idle until the
model was before; `optup` has no per-POP exceptions, so it moves fiber at POPs excepted from `std` too. next unload; the path window would read routes the page never gets (`server-run.md`, "Corrections from building
- **Dark mode (#80):** red error text on dark tinted cards is about 3.8–4.3:1 (bold, but below AA 4.5); the share card PNG T2").
and the web manifest stay light; the WebGL map was checked by tests only, not by eye in a real GPU browser. - **Build standard:** the game menu's last row of tiles is not full (7 tiles, or 8 in a multiplayer game, in rows of
- **IPv4 (#150):** the intern does not manage addresses (optional in the issue); transfers are instant; lease-out income 3). The sheet's quote and "Bring everything up now" judge a line-system swap without routing (`bstdDarkOk()`: a
is not in the investor revenue share; blocks granted to old saves can be sold after two years (a one-off windfall); quiet fiber, under 10% of its capacity, or a parallel link with room; any express with traffic holds its fibers,
CGNAT annoyance costs refunds but does not slow broadband growth; the NOC window's address-space button does nothing. `bstdXpBusy()`), so the quote is the bill; only the intern routes to test. A quiet fiber with no way around can
- **IPv6-only broadband:** no one-off grumble while a city's home routers are swapped; the swap and the NAT64 ratio are still go dark from the button for a day. An old save's `routers.model` moved into the standard (only from a running
not in the build standard or the intern's orders yet (item 4); a new home in an IPv6-only city pays its router even order with an intern hired; a paused one's is dropped) also becomes what new POPs get. A model or line system in the
when cash is short (a running cost, so a finished city never looks like a stopped swap). standard is a ceiling for the `routers` and `optup` orders (their next-one-up rule only applies with "keep"), as an
- **Express fiber (#58):** splicing a whole fiber pair through a city was left out on purpose (every fiber end is a POP; order's own model was before; `optup` has no per-POP exceptions, so it moves fiber at POPs excepted from `std` too.
expresses cover the need); loss and MTU incidents on a fiber do not reduce the expresses on it; the fiber panel's - **Dark mode (#80):** the share card PNG and the web manifest stay light; the WebGL map was checked by tests only, not
"n of max channels" line does not count express slots (the Express section does); regen sites added later do not charge by eye in a real GPU browser.
regen cards for express channels. - **IPv4 (#150):** the intern does not manage addresses (optional in the issue); transfers are instant (real ones take
- **Satellites (#83):** no WISP zones, no satellite incidents (rain fade, sun outage), no footprints on the map, no weeks); lease-out income is not in the investor revenue share (open question 7); blocks granted to old saves can be
satellite tab in the drag-to-link window (ordering is from the city panel); GEO/MEO losses and prices are design sold after two years (a one-off windfall); CGNAT annoyance costs refunds but does not slow broadband growth.
numbers; well-cabled islands (Wellington, Hobart) also count as "can be served"; MEO needs 5° elevation (10° would drop - **IPv6-only broadband:** no one-off grumble while a city's home routers are swapped; a new home in an IPv6-only city
416 pairs); Pitcairn's $120k satellite grant stays Pie-only. pays its router even when cash is short (a running cost, so a finished city never looks like a stopped swap).
- **Express fiber (#58):** a whole fiber pair does not splice through a city (every fiber end is a POP; expresses
cover the need; open question 5).
- **Satellites (#83):** no WISP zones and no rented LEO tier (open question 6); the rented GEO and MEO circuits never
fail (no rain fade or sun outage; Pie in the Sky has its own); no island volcano or Caribbean and Pacific hurricane
events; no "Island Hopper" scenario; no footprints on the map; no satellite tab in the drag-to-link window (ordering
is from the city panel); GEO/MEO losses and prices are design numbers; well-cabled islands (Wellington, Hobart) also
count as "can be served"; MEO needs 5° elevation (10° would drop 416 pairs); Pitcairn's $120k satellite grant stays
Pie-only.
## Housekeeping ## Housekeeping
- `npm run perf -- --browser` runs with `PERF_CHROME=/usr/bin/chromium`. - `npm run perf -- --browser` runs with `PERF_CHROME=/usr/bin/chromium`.
- The merged worktrees under `.claude/worktrees/` and their `worktree-wf_*` branches can be removed. - The phase-1 playtest on port 8090 runs from its own checkout outside the repo, with its data in
`mp-data/playtest`: leave it alone unless the user asks. Its one session can go once a server-run build replaces it
(answer 4).
- The six old wip worktrees under `.claude/worktrees/` wait for the user's answer (open question 9).

1418
docs/plans/server-run.md Normal file

File diff suppressed because it is too large Load diff