Plans: multiplayer phase 2 design, and what is left after this round
Some checks failed
CI / test 1/4 (push) Waiting to run
CI / test 2/4 (push) Waiting to run
CI / test 3/4 (push) Waiting to run
CI / test 4/4 (push) Waiting to run
CI / build (push) Waiting to run
CI / test (push) Blocked by required conditions
CI / translations (push) Waiting to run
Container image / test (push) Waiting to run
Container image / publish (push) Blocked by required conditions
Auto-release / release (push) Has been cancelled

This commit is contained in:
jvanvik 2026-11-07 01:12:23 +01:00
parent e1ae8e0164
commit b533f3baa8
2 changed files with 459 additions and 0 deletions

View file

@ -0,0 +1,404 @@
# Multiplayer phase 2: players inside each other's simulations
Status: design only, not built. Phase 1 (sessions, server-side saves, leaderboard) is in `docs/MULTIPLAYER.md`.
**Conventions:**
- Line numbers are `main` at `1e7638c`.
- Phase 1 (multiplayer sessions, merged on `main`) provides `S.mp`, `MP`, `mpCard`/`mpCardOk`, and `cleanCard` in `scripts/lib/mp.js`.
- Everything runs only when `MP_API` is stamped and `S.mpx` is not null. The plain GitHub Pages build is unchanged (`pages.test.js`, `build.test.js`).
## 1. Starting point and grafts
**Base: "contracts".** It had the best totals in two of the three scorings, and the best feasibility and risk.
- Players are pseudo carriers `mp:<pid>`, registered only in `NET` with single-entry `CONE`/`CONE_S`/`DOWN`/`ANC`.
- `NETS`, `NET_IDS`, `NSH`, `t1Need()`, seen/grace and the gameplay-rules tests never see a player.
- No catalog id contains `:`, and nothing iterates `NET`.
**I checked this on big-network** (a throwaway probe, not committed): a buyer row on `mp:p1` in `S.transit` plus a player PNI, through `compute`, 5 day ticks, the intern, every panel and tab, traceroute, `t1Why`/`isTier1` and a `migrate` round trip.
Results:
- No errors anywhere.
- The rows were kept while registered and dropped once unregistered.
- Warm compute went from 32.3 to 33.2 ms (median of 25 alternating runs).
- `R.sessions` rose by 1. That confirms the exploit fixed below.
**How each fatal flaw the judges found is removed:**
| Judged flaw | Fix |
|---|---|
| The seller's `S.biz` row is exposed to dropBiz, decommission, ddosTargets, Pie moods and the mood loop | The seller side is a deal entry read in exactly two places, demand and money (nets) |
| Peering is cosmetic, yet player PNIs count toward `isTier2`/`t1Club` | Player traffic ships with peering (§2.3). Player sessions never enter `R.sessions` |
| Health is all or nothing, and bought transit reaches every network | A capacity factor (`t.mpf`) and a `miss` id list, from day one |
| A↔B transit loops | The server refuses with 409; clients drop loop links in a fixed pid order (nets) |
| A stale or alt buyer keeps paying the commit forever | The seller earns, and carries load, only while the buyer's clock runs. Prices are capped against the catalog |
| A bought wave can be upgraded past its agreed price | `upLink`/`rmLink`/`setStandby` refuse it (gameplay) |
| "An active deal with no row" is ambiguous | A per-deal `made` flag (§5) |
| `NKN` flips inside `compute()` | It is always `NN+4` |
**Grafted from the other designs:**
- From nets: the two-sided route-server rule; cones through players; PNI lead from `hstr`, with capacity set by the smaller side; the Tier 1 clique star.
- From gameplay: waves, tenders, poaching, consortium seats, notice on each player's own clock, and the LOA handshake.
**Rejected:** players as `NETS` entries (a mutable catalog, a rescaled `NSH`), reach bitmaps (they break between builds), a Tier 1 that depends on other players, automatic ratio strikes, and own-day timers that end a deal (they fire within seconds at 8×; own-day notice only paces each side's own teardown).
## 2. Mechanics
### 2.1 Pseudo carriers (`src/game/30-networks/45-player-carriers.js`, new)
`mpBind(s)` does three things:
1. deletes every `mp:*` key;
2. registers `{id:'mp:'+pid, name, asn, type:'t2', pol:'open', share:0, price:1, pops:[], up:[], ix:[], cc:'', col, blurb:tr('mp.another_player'), mp:1}` for each `s.mpx.who` entry;
3. sets `MPB.k`.
It runs at the start of every `sanitize` and every `compute()` (`if(MPB.k!==(S.mpx?S.mpx.k:''))mpBind(S)`). That covers the route worker, slot switches, imports, the failed-load rollback (`91-slots.js:105`) and puzzles. `nocWinState` (`94-dashboard/90-noc-window.js:45`) calls it too.
Because the carrier has `pops:[]` and is not in `NETS`, no catalog list ever offers a player:
- `sellsAt` and `buyTransit`;
- the intern's providers, `peerAll` and `pniAll`;
- the peering desk and own-exchange joins.
The `peer` action returns at `ixMembers(city).includes(net)` (`40-sites-peering-caches.js:14`).
### 2.2 Transit between players (the Tier 1 endgame)
**Who can sell:** a player publishes `tp` ($/Gbps/month) while `R.reach >= 0.99` and they have at least one POP.
**Buying:** "Buy transit from X here" posts a `t` deal (city, tier, LAG). The server makes it `live` at once (a price list is a standing offer) when all of these hold:
- the seller's card has `tp`;
- both cards list the city;
- there is no cycle;
- the limits hold.
**Price:** `min(tp, mpCap(city))`, where `mpCap = 2 × the cheapest catalog transitPerG(n,city,false)` there, or the catalog median if nobody sells there.
- Both sides compute it from the static catalog, ignoring each save's own `priceMul`.
- Both clamp again when they receive the deal.
**Buyer side: an ordinary `S.transit` row** `{id:'mt-'+deal, net:'mp:'+seller, city, tier, n, mp:deal, mpp:price}`.
- **Comes free:** the router port (`40-ports.js:20`), p95 history (`10-day-tick.js:37`), hot ports, traceroute, incidents, the panels, and `isTier1()===false`.
- **Billing:** `transitMo` (`40-billing.js:9`) uses `t.mpp` instead of `transitPerG(...)*S.priceMul`. The commit floor, `PORT.tmo` and `krFee` still apply.
- **Capacity:** `30-compute.js:53` multiplies by `t.mpf` = min(1, the seller's `sv[city]`/0.95), in 0.05 steps.
- **Reach:** `:54`'s `ok` also needs `!mm.has(n)` (the seller's `miss`).
- **Route cache:** the hash of every miss set joins the flags at `:70` (`+(S.mpx?S.mpx.xk:'')`), so `rcExitKey` rebuilds when a seller's reach changes.
- **Outage:** `t.down=S.day+1` when the seller's POP is down or the seller has left.
**Seller side: a `sell` entry in `S.mpx.deals`, never in `S.biz`.**
- **Load:** `mpDem(bizBw)` after the biz loop (`:95`) adds `u`, the buyer's reported use. It leaves by catalog share over the seller's own backbone, peering and upstreams; a Tier 1 carries it settlement-free.
- **Money:** `V.mp = Σ price × max(q, 20% of port) × min(1, sfOf(R2,city)/0.95)`. `q` is the buyer's p95; the last factor is the business customers' SLA credit. `V.mp` is added to `revMo` (`:382`) and to the revshare base (`:380`).
- **Port:** the seller's port counts in `portsUsed` (`10-catalog/40-ports.js`, after `:21`).
- **Idle buyer:** if the buyer's roster `idle` is ≥ 300 s (no newer game day reached the server), load and revenue are 0.
- A paused or closed buyer has no traffic to bill, and a fast seller cannot bill a frozen buyer.
- An alt account has to keep playing, and still pays at most the capped price.
**Loops:**
- The server returns 409 `loop` if the seller already buys from the buyer, directly or through others (a search over at most 12 players).
- Clients build the player-transit graph from `who[].pt` and add edges sorted by (buyer pid, seller pid), dropping any that closes a cycle, so every client drops the same edge.
- So reach passes down a reseller chain one push per hop, never settling at a false 1.
**Tier 1 stays defined by the built-in networks.**
- `R.reach` only sums `NSH`, so neither `isTier1` (`80-hot-ports-and-rank.js:20`) nor the mood check `R.reach>0.99` (`10-day-tick.js:51`) can depend on players.
- Buying player transit costs Tier 1, and `t1Why` already says so. Selling never does.
- Refusing to peer blocks nobody's win.
### 2.3 Peering between players, carrying traffic
**PNI (`pni` deal, always accepted by hand).** Each side adds `S.pni` `{id:'mn-'+deal, net:'mp:'+other, city, tier, n, mp:deal, ready:S.day+lead}`.
- **Lead time:** `lead = pniNow() ? 0 : leadDays(14 + hstr(deal+myPid) % 29)`, with no random numbers.
- **Cost:** each side pays its own `pniMo`.
- **Capacity:** the smaller of the two sides (theirs comes from `dl[].g`). It is 0 until both cards report `ok`: the LOA and cross-connect handshake.
**IX (`ix` deal).** The server makes it `live` if the responder's policy is open, `no` if closed, and `offer` if selective. Once live, both sides set `S.peers['mp:P@x']`.
**Route server:** no deal. P peers with me at `x` when both `S.rs[x]` and `P.rs ∋ x` hold and both policies are open. That is the same rule on both clients.
**Sessions:**
- `mpIx(x)` lists the player peers at an exchange. `ixSessions` (`20-exchanges.js:29`) stays catalog-only.
- At `30-compute.js:61`, player PNIs skip `R2.sessions++` (`if(!p.mp)`) and count in `R.mpSess` instead.
- So friends can never inflate `isTier2`/`t1Club`.
**Player traffic** (new `src/game/80-simulation/36-mp-traffic.js`). `compute.js:343` calls `mpTraffic({E,SPP,NRES,HAS,R2,carry,NN})` once, after `citySrv` (`:341-342`). The parts are handed in the way `ddosLoad` gets them (`:188`).
- **Demand:** each POP sends `cityEye[c]·w_P` to each active player P.
- `w_P = min(0.02, (biz_P + 0.3·eye_P)/75000)`, and `Σw ≤ 0.1`.
- **Exits that reach P:**
- rank 2: a ready PNI with P, or an IX exit with `mpIx(x) ∋ P`;
- rank 2.5: the same exits toward Q when P buys from Q, which gives cones through players;
- rank 3: player transit from Q when `P===Q` or `Q.mr ∋ P`, and catalog transit when `P.on`;
- `pref:'low'` moves an exit to rank 4.
- **Pushing:** exits are sorted by distance once per POP. Traffic goes along `walkI(SPP[c],ci,e.ci)` and is limited by `l.res`, `NRES` and `e.cap-e.used`.
- **Recording:** each push calls `carry(l,e.ek,NN+3,…)`. `NKN` is always `NN+4` (`:130`), and that column is named `'players'` at `:16`.
- **Effects:**
- Transit p95, hot ports and link loads include player traffic, so peering saves transit money.
- `R2.mp={dem,srv,peer,lost,full,by}` records the totals.
- The pass runs after every catalog flow, so `R.served`, `R.demand`, moods, levels, `peerShare` and Tier 1 never change.
**Cost of a de-peering war:**
- `computeMoney` applies `V.eyeballs *= 1 - mp.lost/(demand+mp.dem)`, where `lost` is traffic with no route at all.
- Two transit-free Tier 1 players who won't peer cannot reach each other: catalog Tier 1s don't pass on routes they learn from peers. Each loses up to 2% of eyeball revenue, which is real Level 3 vs Cogent drama at a bounded cost. Neither loses Tier 1.
- Two eyeball players who don't peer pay transit p95 for each other's traffic.
**Clique star (cosmetic):** card `cq=1` when you are Tier 1 and reach every player whose card says `t1` by your own PNI or IX session. The leaderboard sorts the star first.
**De-peering:** `end` the deal. Each side removes its rows 7 own days after it first sees the end.
### 2.4 Competition
**Overlap:** `clComp` (`75-customer-lifecycle.js:30`) also counts rival players whose card POPs cover the customer's cities. The rolls stay hash-stable (`clR`).
**Poaching:**
- `clLeave` (`:64`), for "cheap" or "multi" with a rival POP in the city, posts the customer to `/lost`.
- The server gives it to one rival, chosen by `hstr`, as a gift.
- The rival checks it with `okBiz`, `BIZ_T` and `rate ≤ catalog×mkt()×1.2`, then puts it in `S.offers` with `ref` set to the loser's name.
**Tenders:**
- **Issue:** while at least two players are active (`idle` < 300 s), the server issues `{n, city}` every 5 real minutes. The city is seeded from the active players' POPs.
- **Content:** derived from `hstr(seed|n)` and the `BIZ_T` lists, so every client sees the same tender.
- **Bids:** a ratio r from 0.6 to 1.0. You can bid while paused, and an optional standing auto-bid covers your cities.
- **Closing:** after 10 real minutes, or once every active player has bid. Wall-clock time, because no game clock is shared.
- **Winner:** the best `(1.2-r)·sq`, where `sq` is served share. The tender goes into `S.offers` with `mp:1`, expiring in 10 own days, and is signed with the normal `accept`.
### 2.5 Shared fiber
**Waves and IRUs (`wave`/`iru` deals):**
- **Seller side:** books spectrum or pairs via `+mpSold(l.id)` in the three counters (`60-requirements.js:72,75`, `37-fiber-broker.js:16`). It earns `V.mp += rate×(fiberOk?1:0)`.
- **Buyer side:** an `S.links` row `{kind:'wave'|'df', own:false, mo:price, mp:deal}`, which copies cut/eqDown/ready from `dl`.
**Consortium seats:** built like `seatBuy` (`86-specialist.js:4`), at `ownCabCost(km)×myPairs/totalPairs` (`36-specialist.js:54`).
**Deferred:**
- Joint exchanges, which need an id namespace (`isIx`, `50-sanitize.js:2`).
- An opt-in "Tier 1 must reach every Tier 1 player" rule.
## 3. Server (`scripts/lib/mp-deals.js`, pure logic, with routes in phase 1's `scripts/lib/mp.js`)
**The deal record** is public to the session, like PeeringDB. The session keeps a counter `dv`, bumped on every change.
```
{id:'d'+base36, k:'t'|'pni'|'ix'|'wave'|'iru', a, b, s (seller), at (city|ix|'a|b'), tier, n, price, slots, st, rev, t0, tl, te, by, why}
```
| from | event | to | allowed for |
|---|---|---|---|
| – | create `t` | `live`, or 409 `not_selling`/`no_pop`/`loop`/`dup`/`limit` | the buyer |
| – | create `ix` | `live` (b open and present) / `no` (b closed) / `offer` | a |
| – | create `pni`/`wave`/`iru` | `offer` | a |
| `offer` | accept / decline / withdraw / 7 days pass | `live` / `no` / `gone` / `gone` | b / b / a / server |
| `live` | end | `end` (`quit`) | a or b |
| `live` | a side's card never reports `ok` within 7 days | `end` (`unbuilt`) | server |
| `live` | no card from a party for 14 days | `end` (`idle`) | server |
| any open deal | a party leaves or is pruned | `end` (`left`) | server |
| `no`/`gone`/`end` | 7 days pass | deleted | server |
**Errors:** every write sends `rev`. A stale `rev` or an illegal transition gets 409, and the wrong party gets 403.
**Limits:**
- one open deal per (pair, kind, place);
- 10 open offers and 24 live deals per player;
- 300 deals per session;
- price 0.05–50, tier 0–15, n 1–8;
- 30 writes per minute per player.
**Feed:** the server writes a line for each transition ("X sells transit to Y in Frankfurt", "X de-peered Y").
**Endpoints:**
- `POST /api/mp/sessions/:code/deals {k,to,at,tier,n,price?,slots?}` returns 201 `{deal,dv}`.
- `POST …/deals/:id {op,rev}` with `op` one of accept, decline, withdraw or end.
- `POST …/lost` reports a lost customer; `POST …/tenders/:n/bid {r}`; `PUT …/autobid`.
- The roster responses (`GET` the session, and `PUT` the card or save) add:
- `deals[]` (my deals, any state) and `dv`. Other players' links come from their cards' `pt`;
- `tenders[]` and my `gifts[]`;
- each player's `idle`: seconds since their card last carried a newer day.
So nothing needs extra polling.
## 4. Card fields beyond phase 1
Every field below is added to both `cleanCard` and `mpCardOk`. Phase 1's `transit` field stays catalog-only, because `NET_RE` would silently drop `mp:` ids.
| field | content |
|---|---|
| `nv` | build version |
| `pt` | pids I buy transit from |
| `rs` | exchanges with my route server on |
| `tp` | my transit price, or null |
| `miss` | catalog ids I can't reach, biggest share first, ≤160 (a reach of 0.99 can still miss 72) |
| `on` | 1 if the internet of built-in networks can reach me: catalog transit, PNIs with every `t1Need()` network, or a seller with `on` |
| `mr` | pids I reach |
| `eye`, `biz` | Gbps, 2 significant digits |
| `sq` | served share |
| `sv` | `{city: delivered share}` where I sell, ≤64, in 0.05 steps |
| `dl` | `[{id,u,q,g,ok,up,cut,eq,rdy}]`, one per live deal, ≤64 |
| `cq` | clique star |
The card grows by about 4 KB at most. ASNs need nothing new: phase 1 already sends the catalog ASNs to avoid (`mpAvoid`, `mp.js:238`).
## 5. Client day flow (`src/game/60-features/89-player-deals.js`, new)
Phase 1's `mpRosterOk` is extended to whitelist `deals`, `dv`, `tenders`, `gifts` and `idle` (plus new `MP_FEED` kinds). The validated roster stays in `MP.roster`, never in S. `mpDay(d)` runs first in `dayPre`, right after `S.day++` (`10-day-tick.js:10`):
1. **Copy changes in.** If `dv`, `idle` or any card changed, rebuild `S.mpx.who` and `S.mpx.deals` from the validated data, with values in steps. Then recompute `k`/`xk` and call `mpBind(S)`.
2. **Reconcile each deal:**
- **live, not `made`:** create my row (`S.pops[at]`, `portOk`, `portGate`, `spend(setup)`) and set `made`. If that fails, the deal waits under a "waiting on you" badge, with no client timer; the server ends it as `unbuilt`.
- **live, `made`, but the row is gone** (for example after a decommission, which `decomImpact` warns about): post `end` with `why:'gone'`. Decommissioning a city where I sell also ends those sell deals.
- **ended** (or missing from the server's list): set `until=d+notice` (14 own days for transit, 7 for the rest) and remove the rows when it passes.
3. **Copy the coupling values onto the rows:**
- on transit rows: `t.mpf` and `t.down`;
- on PNI rows: their side's capacity and whether it is ready;
- on link rows: cut, eqDown and ready;
- on my seller entries: `u`, `q` and whether the buyer is active.
4. `compute()` runs (worker or not), then `dayPost`, then phase 1's push carries the new fields. `dl` comes from yesterday's R.
**My own clicks** (`mpOffer`, `mpAnswer`, `mpEnd`, `mpSell`, `mpBid`) apply as soon as the server answers, with `mpApply();after()`. If `RW.job` is set, they apply at the next `dayPre` instead.
Multiplayer code never calls `Math.random`.
## 6. Saves and sanitize
**New field:** `S.mpx = null | {k, xk, dv, who:[≤11], deals:[≤64]}`. `deals` holds only my own deals. Cones, `on` and who-buys-from-whom come from `who[].pt`.
- `mpx:null` is the default in `newGame` (`80-new-game.js:4`), so old saves get null.
**Order in `sanitize`:** move phase 1's `mpSanitize(s)` from `50-sanitize.js:113` up to `:21`, then call `mpxSanitize(s)`. Both now run before `opsSanitize` (`:22`) and every `isNet` filter (`:34-35, :54-55`).
**`mpxSanitize`:**
- **When it is null:** unless `MP_API` is stamped and `s.mp` is valid in normal mode. An imported multiplayer save then just loses its player rows.
- **Players (`who`):** pids checked against the regex, unique, never my own.
- **Names:** stripped like the phase 1 server does (control characters and `<>&"'\``, at most 32). They are not escaped, because `labOf`/`hotPorts` print catalog names unescaped too.
- **Ids:** pass `isCity`/`isIx`. `miss` must be catalog ids, and `pt`/`mr` must be pids in `who`.
- **Numbers:** clamped and stepped.
- **Deals:** kinds from a whitelist, the other party present, `at` checked, `tier` within `PORT`, the price at most `mpCap`.
- **Loops:** `pt` edges are dropped in (buyer, seller) pid order.
- **Keys:** `k`/`xk` are recomputed, never trusted.
- **Last step:** it ends with `mpBind(s)`.
**`mpOrphans(s)`** runs right after `:113`:
- it drops tagged `transit`/`pni`/`links`/`peers` entries that have no deal;
- it drops untagged rows on `mp:` networks;
- it strips `mp`/`mpp`/`mpf` from untagged rows, so a forged `mpp:0` gives no free transit.
**`RK_SKIP`:** `mpx` stays off it, because `compute` reads it. Phase 1's `mp` stays on, because `compute` must never read it; the `route-skip.test.js` proxy enforces both.
**Size:** at most +15 KB per save.
## 7. Ordered steps
Each step ends with `npm test` green, the i18n check clean, MCP classification, a CHANGELOG bullet and perf numbers.
**1. Dormant core (no server, no UI).**
- `45-player-carriers.js`.
- `80-new-game.js:4`; `50-sanitize.js:21`/`:113`.
- `30-compute.js`:
- `:28` bind check;
- `:53-54` `mpf` and `miss`;
- `:61` `if(!p.mp)`;
- `:62` `*(p.mp?mpPniF(p):1)`;
- `:70` `xk`;
- `:95` `mpDem`;
- `:130`/`:16` the players column;
- `:375-382` `V.mp`.
- `40-billing.js:9`; `40-ports.js:21`.
- **Guards:**
- `lagT`/`lagP`/`cancelTransit` (`20-pops-transit-ix.js:6,7,11`), `unpeer`/`cancelPni` (`40-sites-peering-caches.js:16,30`) and `downT` (`21-ix-downgrade.js:6`) route to `mpEnd` or a renegotiation offer;
- `cleanPipe` (`80-security-and-china.js:8`) refuses `mp` rows;
- `trExits` (`50-traceroute.js:20`) applies `miss`, and `hotPorts` (`80-hot-ports-and-rank.js:4`) applies `mpf`;
- `connUp` (`40-connections.js:18`) shows no upgrade for these rows;
- the intern (`95-standing-orders.js:155,180,250`) skips `mp` rows;
- `upLink`/`rmLink`/`setStandby` (`60-links.js:2,6`).
- `src/agent/30-docs.js`.
- **Tests:** `mp-sanitize`, and `mp-transit` with `S.mpx` injected.
**2. Deals and transit, end to end.**
- `scripts/lib/mp-deals.js` and the `mp.js` routes and timers.
- The card fields.
- `89-player-deals.js`, called from `10-day-tick.js:10`.
- `90-actions/92-player-deals.js`, classified in `src/agent/20-commands.js`.
- `95-modals/49-player-deals.js`: a Deals tab in the session sheet, a bottom sheet at 360 px.
- `90-noc-window.js:45`; `decomImpact`; all six languages.
- **Tests:** `mp-deals-server`, and `mp-transit` with `fetch` mocked.
**3. Peering and player traffic.**
- `pni`/`ix` deals, `mpIx`, and `36-mp-traffic.js` with its hook at `:343`.
- The `V.eyeballs` factor, `R.mpSess` and the star.
- Player Gbps in the PNI list and the connections list.
- **Test:** `mp-peering`.
**4. Competition:** `clComp`, poaching, tenders.
**5. Shared fiber:** waves, IRUs, seats.
**6. `scripts/mp-soak.js`:** opt-in, never part of `npm test`.
## 8. Performance budget
**Single-player.** Each `compute()` costs one string comparison, one property read per transit and PNI row, and one more `ACN` column per edge.
- `npm run perf -- --base-ref origin/main` must stay within noise (≤1%).
- `emptyR()` gains no keys; `R.mp`, `R.mpSess` and `V.mp` exist only when `S.mpx` is set.
**Multiplayer.** The carrier mechanics are measured above: 32.3 → 33.2 ms. A new `big-network-mp` workload (the fixture plus 11 players and 20 deals, built by `scripts/perf-mp-fixture.js`) must meet:
- `mpTraffic` ≤ 1.5 ms (one exit sort per POP, then O(players×exits), with paths cached for each pair of cities);
- `mpBind` ≤ 0.1 ms;
- warm `compute` ≤ +5% compared with the same fixture without players.
A cold route happens only when `xk` changes, at most once a game day. Report jsdom and `--browser` numbers.
## 9. Test plan
**`mp-deals-server`** (spawned server, temporary directory):
- every transition and who may make it (403/409);
- the policy outcomes for `ix` (live, no, offer);
- 409 `loop` on A→B→C→A;
- the limits;
- the `unbuilt`, `idle` and `left` ends, and expiry, with an injected clock;
- card validation;
- restart persistence.
**`mp-transit`:**
- the buyer's exit and label, `transitMo` using `mpp`, `isTier1` false;
- `mpf` scales capacity, and `miss` blocks reach and changes `xk`;
- the seller's demand rises by `u`, `V.mp` follows the formula, and the seller keeps Tier 1;
- an idle buyer gives zero load and revenue;
- a forged `mpp` is stripped;
- worker parity (the `route-worker.test.js` pattern);
- no `Math.random` calls;
- the inbox is never applied mid-day.
**`mp-peering`:**
- a PNI carries traffic only once both ends are ready;
- de-peering raises transit p95;
- two unpeered Tier 1 players lose revenue, and both stay Tier 1;
- 24 player PNIs leave `R.sessions` unchanged;
- C reaches B through A's cone;
- the route-server rule is two-sided;
- the PNI lead time is stable.
**`mp-sanitize`:**
- fuzzing does not throw and stays bounded: 1,000 entries, HTML in names, loops, unknown ids, `mp:` rows in a single-player save;
- old saves load;
- a multiplayer-to-single-player slot switch clears every `mp:*`;
- `<img onerror>` stays text in the panels and the Deals sheet at 360 px.
**`mp-competition` and `mp-fiber`:**
- rival players raise `clComp`;
- gifts are validated;
- every client derives the same tender;
- cuts are copied;
- a bought wave can't be upgraded.
**Existing gates:**
- `route-skip` (same digest with `S.mpx` null or empty), `compute-idempotent`, `routing-reference`, `route-cache`;
- `gameplay-rules`, plus a check that no `mp:` id is in `NETS`/`NSH`;
- `persist`, `save-size`, `save-text`, `mcp-commands`, `i18n`, `pages`, `build`, `multiplayer`, `mp-server`.
**Soak test (the "hardcore" local run):**
- The server plus 12 seeded jsdom players in `worker_threads` (about 0.5 GB each, with `--jobs` capped).
- Each plays about 2,000 days at its own speed, with a random agent making, answering and ending deals.
- During the run: server restarts, reloads through `migrate`, a player leaving, tampered cards and a burst of 409s.
- It checks: no errors or NaN, an acyclic deal graph, each seller's `V.mp` matching the buyer's bill, every save reloading, and a single-player control game keeping `main`'s digest.
## 10. Failure modes
| Case | Handling |
|---|---|
| The other player is paused or offline | Their last card stands: an idle buyer brings no load or money, and a buyer keeps the seller's last values. After 14 days the server ends the deal (`idle`) |
| A player leaves | The deal ends (`left`) and each side tears down after notice. `mpBind` drops the carrier on the next sanitize |
| Server down | Play goes on with the frozen `S.mpx`. New deals fail with one toast |
| Two devices | Phase 1's seq/409 picks the save; `made` settles the rows |
| Version skew | Unknown `miss` ids are dropped; networks the seller's build lacks count as reachable |
| Tampered card or save | Whitelists, clamps, steps, local price caps, orphan stripping. Money comes only from local formulas |

View file

@ -0,0 +1,55 @@
# What is left (as of 2026-11-07)
Work in this fork, pushed to the `vanvik` Forgejo remote (never to `origin`). Built so far: the build standard, multiplayer
phase 1, dark mode (#80), IPv4 address space (#150), express fiber (#58) and satellite teleports (#83). Everything below is
planned or known, not built.
## Promised and not done yet
1. **Router model and line system set in one place only.** The build standard (`S.popStd.g`, `S.popStd.sys`) and two
standing-order settings say the same thing: the `routers` order's `model` (upstream 1e7638c) and the `optup` order's
`sys` (upstream 647e302). Neither ever steps down, so they do not fight, but a player can pick two different targets.
Plan: the Build standard sheet becomes the only place to pick them. The `routers` order reads its model from the
standard, and `optup` its line system (their lists turn into a line "from the build standard: X, change"); sanitize
moves an old `model`/`sys` setting into `S.popStd` when the standard has none.
2. **One owner per fiber for line systems and optics.** `std` (sys/opt targets: a quiet fiber, or a parallel link with
room) and `optup` (one full routing without the fiber, one a night) can each darken a fiber in the same shift. Let `std`
use `optup`'s check (`opsDarkOk`) for line-system swaps, or skip fibers `optup` is working on. Today `std` also holds
any fiber that carries an express with traffic; `opsDarkOk` would handle that case by itself.
## Next features
3. **Wave B: #97 co-op companies** (several players run one network with roles, budgets and approvals), host-authoritative
over the multiplayer server, and **multiplayer phase 2** (players as carriers in each other's simulations: transit,
peering, PNIs, shared fiber): design in `docs/plans/multiplayer-phase2.md`.
4. **Wave C: #144 directional traffic**, last and on its own: keep the totals, split them by traffic profile, utilization is
the busier direction. It comes after #58 because both touch link capacity (express channels now count too).
## 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,
the server does not verify them; a save over ~60 KB sends only the card when the tab closes; the HUD chip in phone
landscape wider than 760 px was not measured. Behind a reverse proxy, run the server with `--trust-proxy`, or every
player shares one address for the rate limits.
- **Build standard:** the game menu has 8 tiles in a multiplayer game (7 otherwise), so the last row is not full; a wave
the standard just upgraded can still be handed back the same day by `decom` if a bigger parallel link carries it.
- **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
and the web manifest stay light; the WebGL map was checked by tests only, not by eye in a real GPU browser.
- **IPv4 (#150):** the intern does not manage addresses (optional in the issue); transfers are instant; lease-out income
is not in the investor revenue share; blocks granted to old saves can be sold after two years (a one-off windfall);
CGNAT annoyance costs refunds but does not slow broadband growth; the NOC window's address-space button does nothing.
- **Express fiber (#58):** splicing a whole fiber pair through a city was left out on purpose (every fiber end is a POP;
expresses cover the need); loss and MTU incidents on a fiber do not reduce the expresses on it; the fiber panel's
"n of max channels" line does not count express slots (the Express section does); regen sites added later do not charge
regen cards for express channels.
- **Satellites (#83):** no WISP zones, no satellite incidents (rain fade, sun outage), 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
- `npm run perf -- --browser` needs Chromium (`sudo pacman -S chromium`, then `PERF_CHROME=/usr/bin/chromium`); only the
jsdom benchmark has been run.
- Upstream release tags are not on `vanvik` yet: `git push vanvik --tags` if wanted.
- The merged worktrees under `.claude/worktrees/` and their `worktree-wf_*` branches can be removed.