diff --git a/apps/server/src/hub-join-cache.test.ts b/apps/server/src/hub-join-cache.test.ts new file mode 100644 index 000000000..e949fd14e --- /dev/null +++ b/apps/server/src/hub-join-cache.test.ts @@ -0,0 +1,130 @@ +// #2519: a token-less join is answered from one shared join picture (the snapshot and log list, at most 2 s old) and then +// every ring batch after it. The oracle is the product client: two Connections (each with its Replica) join the same world +// at the same moment, one with the cache off (a fresh snapshot) and one on (the shared picture, built earlier), while six +// Souls walk; both must reach the same replica state, heartbeat by heartbeat, with no resync. The world clock is driven +// tick by tick; Date is mocked so the picture's age is exact. +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { createServer } from 'node:http'; +import { once } from 'node:events'; +import { setImmediate as turn } from 'node:timers/promises'; +import { WebSocket } from 'ws'; +import { Connection } from '@souls/client'; +import { marsFactory, EDEN_COMMONS_WORLD } from '@souls/engine-mars'; +import { anonymousHello } from '../../../packages/client/src/hello.ts'; +import { Db } from './db.ts'; +import { WorldHost } from './world.ts'; +import { config } from './config.ts'; +import { Auth } from './auth.ts'; +import { Hub } from './hub.ts'; +import { optionsFor } from './deck.ts'; + +const factory = await marsFactory(EDEN_COMMONS_WORLD); +type Seen = { raw: string[]; logs: Set; talk: Set; plays: Set; takeEnds: Set; hashes: Map; mismatches: number }; +const until = async (ok: () => boolean, what: string) => { for (let i = 0; i < 2000 && !ok(); i++) await new Promise((r) => setTimeout(r, 5)); assert.ok(ok(), what); }; + +async function world(t: import('node:test').TestContext, name: string) { + t.mock.timers.enable({ apis: ['Date'], now: 1_800_000_000_000 }); + const db = new Db(':memory:'), host = new WorldHost(db, factory, name, 1e9, name); host.boot(); host.drainInputs(); + for (const n of ['a', 'b', 'c', 'd', 'e', 'f']) void host.enqueue('birth', 'test', { soulId: `s_${n}`, entityId: `h_${n}`, name: n, description: 'test soul', owner: 'system' }); + for (let i = 0; i < 3; i++) { host.tickOnce(); host.drainInputs(); } + for (let i = 0; i < 3; i++) db.saveTalk(host.worldId, { tick: i, at: 0, from: 's_a', to: 's_b', fromName: 'a', toName: 'b', act: 'say', text: `line ${i}`, place: null }); + const cfg = { ...config, worldId: host.worldId, worldKey: 'eden', brainMode: 'fake' as const, budgetUsdPerDay: 0, publicUrl: 'http://127.0.0.1:0' }; + const server = createServer((_req, res) => { res.statusCode = 404; res.end(); }), hub = new Hub(server, host, new Auth(cfg, db), db); + hub.brain = { camera: null, ticker: [], narratives: new Map(), inflight: new Map(), mode: 'fake', callsToday: 0 } as never; + await new Promise((r) => server.listen(0, '127.0.0.1', r)); const port = (server.address() as { port: number }).port; + const conns: Connection[] = []; + t.after(async () => { for (const c of conns) c.close(); await hub.closeClients('stopping'); hub.stopTimers(); server.close(); host.stop(); db.close(); }); + let k = 0; + /** `ticks` world ticks (20 a second), each Soul choosing an act every 170, the event loop turning after each. */ + const drive = async (ticks: number) => { + for (let i = 0; i < ticks; i++, k++) { + if (k % 170 === 7) for (const m of host.minds.values()) { + const opts = optionsFor(host, m); if (!opts.length) continue; const o = opts[(k + m.name.charCodeAt(0)) % opts.length]; + void host.enqueue('decision', 'test', { soulId: m.soulId, entityId: m.entityId, option: o.id, label: o.label, steps: o.steps, reevalTicks: 600, fallback: false, trigger: 'test', card: o.card, target: o.cardTarget, manner: 'warmly', approachLen: o.approachLen }); + } + host.tickOnce(); await turn(); + } + }; + /** A product client as the page opens it (all take transports, columns), and what it saw. */ + const viewer = (cache: boolean) => { + const seen: Seen = { raw: [], logs: new Set(), talk: new Set(), plays: new Set(), takeEnds: new Set(), hashes: new Map(), mismatches: 0 }; + const c: Connection = new Connection(`ws://127.0.0.1:${port}/ws`, async () => null, { + onLog: (es) => { for (const e of es) seen.logs.add(e.seq); }, onTalk: (ls) => { for (const l of ls) seen.talk.add(l.id); }, + onPlays: (ps) => { for (const p of ps) seen.plays.add(p.seq); }, onTakes: (m) => { for (const ch of m.chunks) seen.takeEnds.add((ch as { toTick: number }).toTick); }, + onChange: () => { const hb = c.heartbeat; if (hb && c.replica.seq === hb.seq && !seen.hashes.has(hb.seq)) seen.hashes.set(hb.seq, c.replica.viewHash(hb.tick)); if (c.stats.lastCheck === 'mismatch') seen.mismatches++; }, + }, (u) => { (hub as unknown as { joinCacheOn: boolean }).joinCacheOn = cache; const ws = new WebSocket(u); ws.on('message', (d) => seen.raw.push(String(d))); return ws as never; }, undefined, undefined, undefined, true); + conns.push(c); return { c, seen }; + }; + /** Both clients join now, the uncached one first; the cache flag is set as each socket opens. */ + const pair = async () => { + const off = viewer(false); off.c.connect(); await until(() => off.c.replica.ready, 'the uncached client has its snapshot'); + const on = viewer(true); on.c.connect(); await until(() => on.c.replica.ready, 'the cached client has its snapshot'); + return { off, on }; + }; + /** An anonymous page join that only builds the shared picture. */ + const prime = async () => { + (hub as unknown as { joinCacheOn: boolean }).joinCacheOn = true; + const ws = new WebSocket(`ws://127.0.0.1:${port}/ws?hello=${encodeURIComponent(anonymousHello(true))}`), raw: string[] = []; + ws.on('message', (d) => raw.push(String(d))); + await until(() => raw.some((s) => s.startsWith('{"t":"snapshot"')), 'the priming join has its snapshot'); + ws.close(); await once(ws, 'close'); return JSON.parse(raw.find((s) => s.startsWith('{"t":"snapshot"'))!) as { tick: number; seq: number }; + }; + return { host, hub, drive, pair, prime, t }; +} +const snapshotOf = (s: Seen) => JSON.parse(s.raw.find((x) => x.startsWith('{"t":"snapshot"'))!) as { tick: number; seq: number }; +const from = (a: Set, b: Set) => { const lo = Math.max(Math.min(...a), Math.min(...b)); return [[...a].filter((x) => x >= lo).sort((x, y) => x - y), [...b].filter((x) => x >= lo).sort((x, y) => x - y)]; }; + +/** The oracle: the same replica state at every heartbeat both saw, and the same log, talk, plays and takes. */ +function oracle(off: { c: Connection; seen: Seen }, on: { c: Connection; seen: Seen }, resyncs: [number, number]) { + assert.deepEqual([off.c.stats.resyncs, on.c.stats.resyncs], resyncs, 'resyncs (uncached, cached)'); + assert.deepEqual([off.seen.mismatches, on.seen.mismatches], [0, 0], 'no view hash mismatch'); + const common = [...off.seen.hashes.keys()].filter((s) => on.seen.hashes.has(s)); + assert.ok(common.length >= 10, `heartbeats compared over 60 s: ${common.length}`); + for (const s of common) assert.equal(on.seen.hashes.get(s), off.seen.hashes.get(s), `viewHash at heartbeat seq ${s}`); + assert.equal(on.c.stats.lastCheck, 'ok'); assert.equal(off.c.stats.lastCheck, 'ok'); + const [la, lb] = from(off.seen.logs, on.seen.logs); assert.ok(la.length > 0, 'log events'); assert.deepEqual(lb, la, 'log sequences'); + assert.deepEqual([...on.seen.talk].sort(), [...off.seen.talk].sort(), 'talk ids'); assert.ok(off.seen.talk.size > 0); + assert.deepEqual([...on.seen.plays].sort(), [...off.seen.plays].sort(), 'play sequences'); assert.ok(off.seen.plays.size > 0, 'cards were played'); + assert.deepEqual([...on.seen.takeEnds].sort(), [...off.seen.takeEnds].sort(), 'take end ticks'); assert.ok(off.seen.takeEnds.size >= 50, 'takes'); +} + +test('A1: a join from the shared picture (1.5 s old, batches replayed) reaches the fresh join\'s replica for 60 s', async (t) => { + const w = await world(t, 'hub-join-cache-a1'); + await w.drive(40); + const primed = await w.prime(); + await w.drive(30); t.mock.timers.tick(1_500); // the Souls walk on; the picture is 1.5 s old + const { off, on } = await w.pair(); + const a = snapshotOf(off.seen), b = snapshotOf(on.seen); + assert.deepEqual([b.tick, b.seq], [primed.tick, primed.seq], 'the cached client got the shared picture'); + assert.ok(a.tick > b.tick && a.seq > b.seq, 'and it is older than the fresh one'); + const replayed = on.seen.raw.filter((s) => s.startsWith('{"t":"batch"')).map((s) => JSON.parse(s).seq); + assert.deepEqual(replayed, Array.from({ length: a.seq - b.seq }, (_, i) => b.seq + 1 + i), 'every batch after the picture, in order'); + assert.ok(on.seen.raw.findIndex((s) => s.startsWith('{"t":"log"')) < on.seen.raw.findIndex((s) => s.startsWith('{"t":"batch"')), 'its log before the batches'); + await w.drive(1_200); // 60 s + await until(() => on.c.replica.seq === w.host.currentBatchSeq && off.c.replica.seq === w.host.currentBatchSeq, 'both clients caught up'); + oracle(off, on, [0, 0]); +}); + +test('A2: a join in the 2 s after a recovery takes a new picture; a resync is answered fresh; both converge', async (t) => { + const w = await world(t, 'hub-join-cache-a2'); + await w.drive(40); + const primed = await w.prime(); + await w.drive(20); t.mock.timers.tick(500); + for (const l of w.host.listeners) l.onApplied?.({ seq: 1, tick: 0, kind: 'rules', author: 'world:recovery', payload: { recovery: {} }, at: 0 } as never); + t.mock.timers.tick(500); // 1 s after the picture, 0.5 s after the recovery + const { off, on } = await w.pair(); + const a = snapshotOf(off.seen), b = snapshotOf(on.seen); + assert.ok(b.seq > primed.seq, 'not the picture from before the recovery'); + assert.deepEqual([b.tick, b.seq], [a.tick, a.seq], 'a picture of now'); + await w.drive(600); + t.mock.timers.tick(2_100); // past the per-socket resync spacing + const before = on.seen.raw.filter((s) => s.startsWith('{"t":"snapshot"')).length; + on.c.resync('test'); + await until(() => on.seen.raw.filter((s) => s.startsWith('{"t":"snapshot"')).length === before + 1, 'the resync snapshot'); + const r = JSON.parse(on.seen.raw.filter((s) => s.startsWith('{"t":"snapshot"')).at(-1)!) as { tick: number; reason: string }; + assert.deepEqual([r.tick, r.reason], [w.host.engine.world.tick, 'resync: test'], 'answered from the world as it is now'); + await w.drive(600); + await until(() => on.c.replica.seq === w.host.currentBatchSeq && off.c.replica.seq === w.host.currentBatchSeq, 'both clients caught up'); + oracle(off, on, [0, 1]); +}); diff --git a/apps/server/src/hub.ts b/apps/server/src/hub.ts index 59c54188f..1fefcfab4 100644 --- a/apps/server/src/hub.ts +++ b/apps/server/src/hub.ts @@ -43,6 +43,8 @@ const publicStats = (st: ServerStats): ServerStats => ({ ...st, brain: { mode: s const MAX_BUFFERED = 1_000_000; /** Longest the world clock waits for a join set (lane P5); under the frame loop's 1 s elapsed cap, so no world time is lost. */ const JOIN_HOLD_MS = 750, JOIN_HOLD_REST_MS = 2_000; +/** #2519: the oldest a cached anonymous join picture may be. */ +const JOIN_CACHE_MS = 2_000; /** A world's stop waits this long for its sockets to finish the close handshake, then cuts the rest (Hub.closeClients). */ export const CLOSE_GRACE_MS = 500; @@ -93,6 +95,13 @@ export class Hub { epoch = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`; build = 'dev'; private lastTakeTick = -1; + /** #2519 (SIM_JOIN_CACHE, on unless '0'): a token-less join's heavy part, the snapshot (stringified once per negotiated + * form) and the log list, built at most once every JOIN_CACHE_MS and shared; each joiner then gets the ring's batches + * after it (each stringified once for all of them: a booting world's first batch holds megabytes of log), so its + * replica ends where a fresh snapshot's would. `ring`/`engine`: the ones it was built from (a recovery + * replaces both and also clears it). */ + private readonly joinCacheOn: boolean; + private joinCache: {at:number;seq:number;ring:unknown;engine:unknown;snapshot:Extract;log:string;wire:Map;batches:Map}|null = null; /** #1221: the oldest batch a client may resume from: nothing before the last recovery still holds. */ private resumeFrom = 0; /** take-entities-ref/1: one table registry for every peer that announced it (see packages/protocol take-entities-wire). */ @@ -108,7 +117,7 @@ export class Hub { private stationV2?:CandidateStationV2; constructor(server: Server, host: WorldHost, auth: Auth, db: Db,lifecycleSouls?:Souls,station?:CandidateStationV1,stationV2?:CandidateStationV2) { - this.host = host; this.auth = auth; this.db = db; this.persistTakes = worldConfig(host).env.TAKES_PERSIST === '1'; + this.host = host; this.auth = auth; this.db = db; this.persistTakes = worldConfig(host).env.TAKES_PERSIST === '1'; this.joinCacheOn = worldConfig(host).env.SIM_JOIN_CACHE !== '0'; if(station){if(station.host!==host)throw new Error('station must belong to selected Hub host');this.station=station;} if(stationV2){if(stationV2.host!==host)throw new Error('V2 station must belong to selected Hub host');this.stationV2=stationV2;} // Internal opt-in only; production bootstrap does not supply this adapter. @@ -131,10 +140,11 @@ export class Hub { onApplied: e => { if (e.kind === 'rules' && e.payload?.recovery) { // #1221: the world took a step back; everyone gets the picture again where they are. A new epoch or a closed socket // would make every page tear its whole view down and lose who it was following. Nothing from before this resumes. - this.lastTakeTick=host.engine.world.tick; this.resumeFrom=host.currentBatchSeq+1; + this.lastTakeTick=host.engine.world.tick; this.resumeFrom=host.currentBatchSeq+1; this.joinCache=null; for (const c of this.clients) if (c.ready) this.send(c, {t: 'snapshot', reason: 'world restored', ...host.snapshotView()}); } if(e.kind==='station-rules-era-v1'){ + this.joinCache=null; for(const c of this.clients){if(!c.ready)continue; if(c.stationContract==='station-live/1')this.welcomeClient(c); this.send(c,{t:'snapshot',reason:'recorded physical checkpoint',...host.snapshotView()}); @@ -240,9 +250,21 @@ export class Hub { c.joinSend=true;c.awaitingTakes=true; try{ const canResume = typeof m.since === 'number' && m.epoch === this.epoch && m.since >= this.resumeFrom && ring.length > 0 && m.since >= ring[0].seq - 1 && m.since <= this.host.currentBatchSeq; + // #2519: a token-less page join takes the shared picture and its log, then every ring batch after it + const cached = !canResume && m.token === undefined && m.since === undefined ? this.joinPicture() : null; if (canResume) for (const b of ring) { if (b.seq > m.since!) this.send(c, { t: 'batch', ...b, log: b.log.map(publicEvent) }); } + else if (cached) { + const wire = this.joinWire(cached, c); + if (this.sendWire(c, wire.s) && wire.table !== null && c.takeEntities) c.takeEntities.last = wire.table; + this.sendWire(c, cached.log); + for (const b of ring) if (b.seq > cached.seq) { + let s = cached.batches.get(b.seq); + if (s === undefined) cached.batches.set(b.seq, s = JSON.stringify({ t: 'batch', ...b, log: b.log.map(publicEvent) } satisfies ServerMsg)); + this.sendWire(c, s); + } + } else this.send(c, { t: 'snapshot', reason: typeof m.since === 'number' ? 'too far behind; full snapshot' : 'join', ...this.host.snapshotView() }); - this.send(c, { t: 'log', events: this.db.tailEvents(this.host.worldId, 150, true).map(e=>joinLogEvent(publicEvent(e))) }); + if (!cached) this.send(c, { t: 'log', events: this.db.tailEvents(this.host.worldId, 150, true).map(e=>joinLogEvent(publicEvent(e))) }); this.send(c, { t: 'kernel', view: this.host.kernelView() }); this.send(c, { t: 'plays', plays: this.host.recentPlays.slice(-60) }); this.send(c, { t: 'talk', lines: this.db.recentTalk(40) }); @@ -268,6 +290,39 @@ export class Hub { ...(this.station||this.stationV2?{stationContract:c.stationContract}:{}),...(c.takeTransport?{takeTransport:c.takeTransport}:{}),...(c.takeEntities?{takeEntities:TAKE_ENTITIES_WIRE_V1}:{}),...(c.takeEntities?.join?{takeEntitiesJoin:TAKE_ENTITIES_JOIN_V1}:{}),...(c.takeChunks?{takeChunks:TAKE_CHUNKS_WIRE_V1}:{})}); if(sent)c.publishedMe=JSON.stringify(c.me);return sent; } + /** #2519: the shared join picture, rebuilt when missing, JOIN_CACHE_MS old, from another ring or engine (a recovery), or + * older than the ring's first batch (the batches after it could not all be replayed). */ + private joinPicture(){ + if (!this.joinCacheOn) return null; + const h = this.host, ring = h.ring, now = Date.now(), j = this.joinCache; + if (j && now - j.at < JOIN_CACHE_MS && j.ring === ring && j.engine === h.engine && j.seq >= this.resumeFrom - 1 && (ring.length ? j.seq >= ring[0].seq - 1 : j.seq === h.currentBatchSeq)) return j; + const snapshot = { t: 'snapshot' as const, reason: 'join', ...h.snapshotView() }; + const log = JSON.stringify({ t: 'log', events: this.db.tailEvents(h.worldId, 150, true).map(e => joinLogEvent(publicEvent(e))) } satisfies ServerMsg); + return this.joinCache = { at: now, seq: snapshot.seq, ring, engine: h.engine, snapshot, log, wire: new Map(), batches: new Map() }; + } + /** The cached snapshot in this peer's negotiated form (take-entities-join/1, columns/1), stringified once per form. */ + private joinWire(j: NonNullable, c: Client) { + const join = !!c.takeEntities?.join, columns = !!c.snapshotColumns, key = `${join}|${columns}`; + let w = j.wire.get(key); + if (!w) j.wire.set(key, w = this.snapshotWire(j.snapshot, join, columns)); + return w; + } + /** A snapshot as one peer gets it: with its registered entity table id (take-entities-join/1) and/or the table in the + * column form (columns/1). `table`: the id that becomes the peer's last table, or null. */ + private snapshotWire(m: Extract, join: boolean, columns: boolean): {s:string;table:number|null} { + const joined = join ? this.takeEntities.register(m.entities) : null; + if (!joined && !columns) return { s: JSON.stringify(m), table: null }; + const { entities, ...rest } = m; + return { s: JSON.stringify(joined ? { ...rest, entitiesTable: joined.id } : rest).slice(0, -1) + ',"entities":' + (columns ? this.columnsOf(entities, joined?.json) : joined!.json) + '}', table: joined?.id ?? null }; + } + /** A message already stringified for this peer (a join's cached part): the transport half of `send`. */ + private sendWire(c: Client, s: string) { + if (!this.host.clockAvailable) { c.ready = false; c.ws.close(1013, 'world unavailable'); return false; } + if (c.ws.readyState !== 1) return false; + c.sent += s.length; + if (c.joinSend) { c.joinPending = (c.joinPending ?? 0) + 1; c.ws.send(s, () => { c.joinPending = (c.joinPending ?? 1) - 1; }); } else c.ws.send(s); + return true; + } private sendStation(c:Client){ if(c.stationContract==='station-live/2'&&this.stationV2)this.send(c,{t:'station-v2',view:this.stationV2.view()}); else if(c.stationContract==='station-live/1'&&this.station)this.send(c,{t:'station',view:this.station.view()}); @@ -297,10 +352,10 @@ export class Hub { const inner=(v:unknown)=>mode==='wire'?stringifyTakeBoundaryWireV1(v):JSON.stringify(v); // take-entities-join/1: the snapshot names its entity table, which becomes this peer's last table (its next take's // table then travels as a reference or a patch against it) - const joined=current.t==='snapshot'&&c.takeEntities?.join?this.takeEntities.register(current.entities):null; - if(joined)nextTable=joined.id; + const snap=current.t==='snapshot'&&(c.takeEntities?.join||c.snapshotColumns)?this.snapshotWire(current,!!c.takeEntities?.join,!!c.snapshotColumns):null; + if(snap&&snap.table!==null)nextTable=snap.table; s=cached[key]??(()=>{ - if(joined||current.t==='snapshot'&&c.snapshotColumns){const {entities,...rest}=current as Extract;return JSON.stringify(joined?{...rest,entitiesTable:joined.id}:rest).slice(0,-1)+',"entities":'+(c.snapshotColumns?this.columnsOf(entities,joined?.json):joined!.json)+'}';} + if(snap)return snap.s; const packed=entities?JSON.stringify({t:'take-entities',contract:TAKE_ENTITIES_WIRE_V1,ids:entities.envelope.ids}).slice(0,-1)+',"payload":'+inner(entities.envelope.payload)+'}':inner(stream); return chunks?JSON.stringify({t:'take-chunks',contract:TAKE_CHUNKS_WIRE_V1,ids:chunks.ids,same:chunks.same}).slice(0,-1)+',"payload":'+packed+'}':packed; })(); @@ -312,8 +367,7 @@ export class Hub { c.ready=false;c.ws.send(JSON.stringify({t:'error',code:'takes.transport-invalid',message:'The take transport cannot be encoded exactly.'}));c.ws.close(1011,'invalid take transport');return false; } s=this.kernelWire(c,current,s); - c.sent += s.length; - if(c.joinSend){c.joinPending=(c.joinPending??0)+1;c.ws.send(s,()=>{c.joinPending=(c.joinPending??1)-1;});}else c.ws.send(s); + this.sendWire(c,s); if(nextTable!==undefined&&c.takeEntities)c.takeEntities.last=nextTable; if(nextTake!==undefined&&c.takeChunks)c.takeChunks.last=nextTake; if(current.t==='takes'&¤t.chunks.length)c.awaitingTakes=false; diff --git a/changes/2519-join-cache.md b/changes/2519-join-cache.md new file mode 100644 index 000000000..59edd80e3 --- /dev/null +++ b/changes/2519-join-cache.md @@ -0,0 +1,4 @@ +--- +type: perf +--- +A crowd of new visitors arriving at once costs a world far less: they share one picture of it instead of each having one made. diff --git a/docs/architecture/load.md b/docs/architecture/load.md index 230d97057..062f3e548 100644 --- a/docs/architecture/load.md +++ b/docs/architecture/load.md @@ -38,6 +38,8 @@ Every file that owns a cost has a **dial** and exposes `setLoadLevel(level: Leve **The world page is built at most once per 2 s** ([#2515](https://github.com/soulsimulation/souls/issues/2515)). The page (the web build's `index.html` with the inline config, snapshot key and world clock) has no cookie, nonce or per-caller value, so the launcher keeps the world's answer for 2 s and serves it to every arrival: 200 arrivals at 20 a second cost the world 6 page builds, not 200. It is kept by world-relative path, world process and the host headers its URLs are made from, never by query or cookie, so a random query string is still a hit. Only an answer the world marks `X-Sim-Page` is kept (its other HTML routes, such as `/studio`, are proxied as before), and only a GET that asks for HTML (`Accept: text/html`, a browser's arrival) is a candidate, so a long-poll or an agent's read never waits behind another caller's request. The launcher sets the robots tag for each request by the world's own rule: `X-Sim-Page: index` and no query means indexable, anything else gets `noindex`. A page up to 2 s old may name a snapshot key that has since moved; the snapshot route then answers the current world with `no-store`, which costs one miss. +**Anonymous socket joins share one picture ([#2519](https://github.com/soulsimulation/souls/issues/2519)).** A token-less `hello` (the page's entry socket, no `since`) is answered from the hub's join cache: the welcome (fresh), the snapshot already stringified for that peer's negotiated form (columns/1, take-entities-join/1), the 150-event log list, then every ring batch after the snapshot's `seq`, then the rest of the join set as built for any join. The cache is rebuilt once it is 2 s old, when the ring or the engine it came from is replaced or no longer reaches back to it, and after a recovery or a station era change. On Eden 2026 this was about 50 ms of main thread per join (snapshot view 13 ms, its stringify and column packing 13 ms, the log list 25 ms). A resync, a resume and every signed-in join build their own, as before. `SIM_JOIN_CACHE=0` turns it off. + Admission (L2, `apps/server/src/load/admission.ts`): one outstanding heavy (C1/C2) request per Soul; per-Soul CPU-ms token bucket (refill `min(200, 20 × frameBudget / awake)` ms/s, so the Souls' buckets together refill at the frame budget's own throughput; capacity 2,000 ms, charged measured handler time; was `min(200, 500/awake) × {1, ½, ¼}` until srv-admission-calib); the god holds a reserved 25 % of the request budget (its bucket unchanged: 125 ms/s × {1, ½, ¼, ¼}); heavy handlers run from a dispatcher after `tickOnce` within a frame budget (at most 25 ms of each 50 ms at green, less above, calibrated to the tick: §1), round-robin across Souls, writes before reads; a job whose deadline passed is answered `world.busy` without running; a job whose socket closed is dropped. Shedding order: duplicate concurrent → C3 to launcher cache → C2 over budget → C2 past deadline (oldest first) → C1 past deadline only. **The person watching sees a slowed Soul** ([#456](https://github.com/soulsimulation/souls/issues/456)). Every admission refusal answered to a Soul's token (`soul.slow-down` and its cool-down, `world.busy`, `world.crowded`; never `soul.busy`, which is the agent overlapping its own requests, nor the god's), from the HTTP middleware and the read workers' port alike, goes to `Admission.onRefused`. `load/soul-slowed.ts` turns it into `slowed: {reason, until}` on that Soul's public card (`PublicSoul.slowed`). The field is present only while the refusal lasts. The chip and the card show a short line and clear it at `until` with no event. A card is re-sent only when the page's `until` would lapse while refusals continue, when the reason changes, or when the wait grows by at least 5 s: at most once a second per Soul. The launcher's own refusals (`client.rate`, `account.rate`) are not in it yet ([#1482](https://github.com/soulsimulation/souls/issues/1482)).