@hadoku/game-server 0.0.0-stage → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/LICENSE +21 -0
  2. package/dist/base-path.d.ts +29 -0
  3. package/dist/base-path.js +30 -0
  4. package/dist/busy.d.ts +40 -0
  5. package/dist/busy.js +23 -0
  6. package/dist/capacity.d.ts +9 -0
  7. package/dist/capacity.js +6 -0
  8. package/dist/config.d.ts +247 -0
  9. package/dist/config.js +271 -0
  10. package/dist/edge-auth.d.ts +43 -0
  11. package/dist/edge-auth.js +47 -0
  12. package/dist/erase/anonymise.d.ts +7 -0
  13. package/dist/erase/anonymise.js +7 -0
  14. package/dist/erase/index.d.ts +18 -0
  15. package/dist/erase/index.js +20 -0
  16. package/dist/erase/legacy-ids.d.ts +7 -0
  17. package/dist/erase/legacy-ids.js +24 -0
  18. package/dist/erase/recordings.d.ts +26 -0
  19. package/dist/erase/recordings.js +128 -0
  20. package/dist/erase/rooms.d.ts +63 -0
  21. package/dist/erase/rooms.js +67 -0
  22. package/dist/gate.d.ts +27 -0
  23. package/dist/gate.js +15 -0
  24. package/dist/http/client-events.d.ts +25 -0
  25. package/dist/http/client-events.js +15 -0
  26. package/dist/http/page.d.ts +26 -0
  27. package/dist/http/page.js +35 -0
  28. package/dist/http/prepared.d.ts +14 -0
  29. package/dist/http/prepared.js +16 -0
  30. package/dist/http/request.d.ts +59 -0
  31. package/dist/http/request.js +37 -0
  32. package/dist/http/room-core.d.ts +160 -0
  33. package/dist/http/room-core.js +278 -0
  34. package/dist/http/trim.d.ts +23 -0
  35. package/dist/http/trim.js +76 -0
  36. package/dist/http/usage.d.ts +22 -0
  37. package/dist/http/usage.js +16 -0
  38. package/dist/kernel.d.ts +4 -0
  39. package/dist/kernel.js +26 -0
  40. package/dist/log.d.ts +9 -0
  41. package/dist/log.js +9 -0
  42. package/dist/people.d.ts +105 -0
  43. package/dist/people.js +145 -0
  44. package/dist/play/clock.d.ts +39 -0
  45. package/dist/play/clock.js +81 -0
  46. package/dist/play/diagnostics.d.ts +21 -0
  47. package/dist/play/diagnostics.js +35 -0
  48. package/dist/play/engine-runtime.d.ts +200 -0
  49. package/dist/play/engine-runtime.js +309 -0
  50. package/dist/play/game-adapter.d.ts +158 -0
  51. package/dist/play/game-adapter.js +1 -0
  52. package/dist/play/host.d.ts +482 -0
  53. package/dist/play/host.js +950 -0
  54. package/dist/play/jvm-transport.d.ts +25 -0
  55. package/dist/play/jvm-transport.js +1 -0
  56. package/dist/play/local-jvm.d.ts +325 -0
  57. package/dist/play/local-jvm.js +829 -0
  58. package/dist/play/match/hosted.d.ts +92 -0
  59. package/dist/play/match/hosted.js +151 -0
  60. package/dist/play/match/outcome.d.ts +26 -0
  61. package/dist/play/match/outcome.js +21 -0
  62. package/dist/play/match/shell.d.ts +378 -0
  63. package/dist/play/match/shell.js +613 -0
  64. package/dist/play/recording/retention.d.ts +36 -0
  65. package/dist/play/recording/retention.js +89 -0
  66. package/dist/play/recording/writer.d.ts +185 -0
  67. package/dist/play/recording/writer.js +90 -0
  68. package/dist/play/relay-socket.d.ts +128 -0
  69. package/dist/play/relay-socket.js +194 -0
  70. package/dist/play/runtimes/in-process.d.ts +47 -0
  71. package/dist/play/runtimes/in-process.js +43 -0
  72. package/dist/play/runtimes/relay-match.d.ts +166 -0
  73. package/dist/play/runtimes/relay-match.js +240 -0
  74. package/dist/play/runtimes/relay.d.ts +128 -0
  75. package/dist/play/runtimes/relay.js +183 -0
  76. package/dist/play/runtimes/streamed.d.ts +116 -0
  77. package/dist/play/runtimes/streamed.js +148 -0
  78. package/dist/play/start-queue.d.ts +65 -0
  79. package/dist/play/start-queue.js +187 -0
  80. package/dist/room/avatar.d.ts +1 -0
  81. package/dist/room/avatar.js +28 -0
  82. package/dist/room/caller.d.ts +21 -0
  83. package/dist/room/caller.js +1 -0
  84. package/dist/room/constants.d.ts +27 -0
  85. package/dist/room/constants.js +27 -0
  86. package/dist/room/events.d.ts +59 -0
  87. package/dist/room/events.js +174 -0
  88. package/dist/room/identity.d.ts +89 -0
  89. package/dist/room/identity.js +98 -0
  90. package/dist/room/lobby.d.ts +426 -0
  91. package/dist/room/lobby.js +880 -0
  92. package/dist/room/membership.d.ts +64 -0
  93. package/dist/room/membership.js +76 -0
  94. package/dist/room/provisioning.d.ts +22 -0
  95. package/dist/room/provisioning.js +46 -0
  96. package/dist/room/record.d.ts +63 -0
  97. package/dist/room/record.js +39 -0
  98. package/dist/room/room-list.d.ts +67 -0
  99. package/dist/room/room-list.js +66 -0
  100. package/dist/room/seats.d.ts +39 -0
  101. package/dist/room/seats.js +58 -0
  102. package/dist/room/session.d.ts +91 -0
  103. package/dist/room/session.js +156 -0
  104. package/dist/room/socket-auth.d.ts +2 -0
  105. package/dist/room/socket-auth.js +10 -0
  106. package/dist/room/watching.d.ts +35 -0
  107. package/dist/room/watching.js +72 -0
  108. package/dist/room/watchparty-link.d.ts +1 -0
  109. package/dist/room/watchparty-link.js +17 -0
  110. package/dist/stream/alloc.d.ts +115 -0
  111. package/dist/stream/alloc.js +368 -0
  112. package/dist/stream/index.d.ts +66 -0
  113. package/dist/stream/index.js +293 -0
  114. package/dist/telemetry.d.ts +46 -0
  115. package/dist/telemetry.js +25 -0
  116. package/dist/testPort.d.ts +1 -0
  117. package/dist/testPort.js +28 -0
  118. package/package.json +36 -4
  119. package/README.md +0 -3
@@ -0,0 +1,482 @@
1
+ /**
2
+ * Where a match's Forge runs: matches placed into shared `--host` bridge JVMs.
3
+ *
4
+ * ## Many matches per JVM
5
+ *
6
+ * Every bridge JVM is a `PlayBridge --host <hostId>` (`docs/spikes/multi-match-jvm.md`): it boots
7
+ * Forge's model once, says `warm`, and then takes any number of
8
+ * `{"t":"start","match":<hostId>,"config":{…}}` lines, each starting one match on a Forge server
9
+ * of its own. Every line it prints carries its match's id, commands are routed by it, and a
10
+ * match's `stop` ends that match alone, answered by `{"t":"stopped"}`. A `stop` addressed to the
11
+ * host id ends the JVM.
12
+ *
13
+ * This file is the coordinator. `jvmHostFactory` places each match into a JVM with room — the
14
+ * fullest warm one first, so idle JVMs empty out and retire — up to `perJvm` matches each
15
+ * (`MATCHES_PER_JVM`, 25), and opens a new JVM when every one is full. Where a JVM runs and how
16
+ * its line stream is reached is a `JvmLauncher`'s (`jvm-transport.ts`): this machine's (`local-jvm.ts`), by
17
+ * default; a claw's, through a remote agent.
18
+ *
19
+ * - **A match's exit is its `stopped`.** A match asked to stop whose `stopped` never comes is let
20
+ * go after `MATCH_STOP_MS` and logged (`match-stop-unanswered`); its JVM keeps the others.
21
+ * - **A JVM's death fails EVERY match on it**, with the JVM's reason (`jvm-lost`). Nothing on
22
+ * that JVM retries in place: a failed claw always fails over (the hosting rulings), and the
23
+ * failover acts on this signal.
24
+ * - **A JVM with no matches for `IDLE_JVM_MS` is retired**, unless it is the one JVM left with
25
+ * room (the warm one).
26
+ *
27
+ * ## The warm JVM
28
+ *
29
+ * One JVM with room is kept booted ahead of the next match (unless `warmJvm` is off): when the
30
+ * last JVM with room fills, another is launched behind it. A match placed into a warm JVM starts
31
+ * at once; one placed into a JVM still booting starts the moment it is warm (its `start` waits in
32
+ * the fifo). A JVM that dies before `warm` is a failed boot: the next is tried after
33
+ * `WARM_RETRY_MS`, and after `WARM_MAX_FAILURES` in a row no JVM is kept warm — a match still
34
+ * launches one when it needs one — which is logged.
35
+ *
36
+ * ## The ceiling: at most `MAX_CONCURRENT_MATCHES` matches being played
37
+ *
38
+ * **50** since 2026-10-28 (the operator: "if we hit just 50 concurrent matches that'd be fine"):
39
+ * two claws at `MATCHES_PER_JVM` each. It was 10 while every match was its own ~0.7–1 GB JVM.
40
+ * Counted over the matches still `starting` or `running` (a finished match keeps its slot in its
41
+ * JVM for `overGraceMs`, not a place in the ceiling). `socket.ts` refuses one more with a 503
42
+ * before any JVM is spent. Each person may play at most 5 at once
43
+ * (`http/routes.ts`). The JVM count is bounded separately (`JvmPoolOptions.maxJvms`). A JVM's
44
+ * heap is capped (`JVM_HEAP_MB` for `MATCHES_PER_JVM` matches, `local-jvm.ts`) so a runaway
45
+ * cannot take the box.
46
+ *
47
+ * Nothing outside this file knows a JVM exists: `match.ts` sees a `MatchHost` — send a command,
48
+ * get lines back, stop — and a `MatchHostFactory` makes one.
49
+ *
50
+ * ## A match outlives its server (Wave 22, §E)
51
+ *
52
+ * A deploy must not end live games. The JVM survives the server (`local-jvm.ts`, "A JVM
53
+ * outlives its server"), and the next server has to be able to rebuild each match on it: a
54
+ * re-attached JVM keeps Forge's games, but `Match`'s per-seat projectors, histories, cursors and
55
+ * parked asks lived in the process that died. So:
56
+ *
57
+ * - **Every protocol line and every command of a match is appended to its own stream**,
58
+ * `<dir>/<matchId>.jsonl`, as it is read or sent; a re-attach replays that file into the new
59
+ * `Match` before a single live line reaches it. Replay is deterministic, so each seat's `seq`
60
+ * comes back identical. A line is kept as the bridge wrote it, `match` stamp and all, through
61
+ * a descriptor held open for the match's life; each append is synchronous, so the file is
62
+ * whole for any reader the moment `persist` returns — this process's own `attach`, or the next
63
+ * server's after a crash.
64
+ * - **One record per JVM**, `<dir>/jvm.json` (`JvmRecord`): its host id, when it started, when it
65
+ * was handed over, and every match on it with its epoch, its seats' owners and its spec. A
66
+ * client therefore resyncs on the cursor it already held, and seat 2 cannot come back as seat 1.
67
+ * - **At boot** the launcher offers back every JVM still running (`running()`); each is attached
68
+ * at once, and every match its record lists is offered through `orphans()`. Lines arriving for
69
+ * a match not yet claimed are kept in its stream and replayed when `attach` claims it.
70
+ * - **A degraded match is never handed over** (hosting-test-plan H4): one whose stream could not
71
+ * be written has a hole a replay would turn into a board Forge does not have. Its stream is
72
+ * renamed out of the way (a rename needs no space on a disk that just filled), `handOver` refuses
73
+ * in words, and a later boot stops it instead of offering it.
74
+ *
75
+ * **Nothing keeps an orphan for ever**: a JVM `ORPHAN_MAX_MS` past its `orphanedAt` is retired,
76
+ * not re-attached; a match nobody claims within `ORPHAN_CLAIM_MS` of boot is stopped; and a
77
+ * re-attached match whose seats never come back is stopped by `Match.armRejoinGrace`.
78
+ *
79
+ * ## Going down: what must die before we do (Wave 22, lane U)
80
+ *
81
+ * A JVM with a match that was handed over outlives us on purpose; every other must not. Measured
82
+ * against a real match JVM (lane U): `{"t":"stop"}` → gone 9355 ms, SIGTERM 4322 ms, SIGKILL
83
+ * 0 ms; an idle JVM's host stop 314 ms. pm2 SIGKILLs us after 1.6 s, so there is no budget for a
84
+ * polite end, and `reapOnExit()` is the last word, **synchronous and immediate**: every JVM with
85
+ * no handed-over match is asked to go and killed now (confirmed gone, so its run directory is
86
+ * settled), and every JVM with one is let go with its `orphanedAt` stamped.
87
+ *
88
+ * ## Liveness
89
+ *
90
+ * A JVM's pid says it exists, not that it runs: a SIGSTOPped bridge kept its match `running` for
91
+ * good (hosting-test-plan C2). So the bridge says `alive` every 2 s (`PlayBridge.ALIVE_MS`) from a
92
+ * thread of its own, and a JVM this file has heard nothing from for `UNRESPONSIVE_MS` is killed
93
+ * and every match on it failed through the exit path, exactly as a crash.
94
+ *
95
+ * Why 40 s: a 30 s stop-the-world pause must not end a match, and the silence a pause of P makes
96
+ * is at most P + one interval (2 s), so 32 s; 40 s leaves 8 s for scheduling on a loaded host.
97
+ * Forge's own client timeout is raised far past this (`FORGE_HEARTBEAT_TIMEOUT_S`). A JVM
98
+ * re-attached from an earlier server is watched only from its first line.
99
+ *
100
+ * **Per match, there is no watchdog**, because the bridge reports nothing a watchdog could read:
101
+ * `alive` is one line per JVM from a thread of its own (`PlayBridge.startAlive`), and a match's
102
+ * own lines stop for as long as a player thinks, which is not a fault. A game thread that dies is
103
+ * already the bridge's to report (`MatchContext.fail` → `fatal`, then `stopped`). What a per-match
104
+ * watchdog would need is in "What remains" of `docs/spikes/multi-match-jvm.md`.
105
+ *
106
+ * ## AI cutoffs
107
+ *
108
+ * Forge gives each AI decision a 5 s wall-clock cutoff, and past it the AI plays its best so far:
109
+ * on a host short of CPU the AI plays worse, not slower. The bridge says `cutoff` each time
110
+ * (`PlayBridge.CutoffWatch`), for the match whose game was cut, or for the JVM when no match owns
111
+ * the thread. Like `alive` it is the pool's, never a match's: it is logged (`ai-cutoff`) and handed
112
+ * to `JvmPoolOptions.onCutoff`, which placement counts against the host, and it is neither kept in
113
+ * a stream nor forwarded, so a replay never counts one twice.
114
+ *
115
+ * ## The line protocol
116
+ *
117
+ * `bridge/PlayBridge.java` writes one JSON object per line on stdout and reads one per line on
118
+ * stdin. Its class comment has the list. Stdout carries nothing else, so a line that is not JSON
119
+ * is a bug and is logged, not parsed.
120
+ */
121
+ export { bridgeDiagnostics } from './diagnostics.js';
122
+ import type { JvmLauncher } from './jvm-transport.js';
123
+ import { type JvmHostConfig } from './local-jvm.js';
124
+ export { BRIDGE_CACHE_MAX_AGE_MS, BRIDGE_JVM_FLAGS, CRASH_RECORD_FILES, CRASH_RECORD_MAX_AGE_MS, CRASH_RECORDS_KEPT, FORGE_HEARTBEAT_TIMEOUT_S, FORGE_PREFERENCES, JVM_HEAP_MB, MATCHES_PER_JVM, bridgeLaunch, bridgeVersion, jvmHostConfig, liveJvmCount, stageRunDir, sweepRunDirs, writeFileAtomic, type JvmAvailability, type JvmHostConfig, } from './local-jvm.js';
125
+ export interface SeatSpec {
126
+ /** Forge's player name. Shown to both seats, so never an identity. */
127
+ name: string;
128
+ ai: boolean;
129
+ /** `.dck` text, or null for a random Forge precon. */
130
+ deck: string | null;
131
+ }
132
+ /**
133
+ * A bot game: Forge's AI against Forge's AI, best of `bestOf`, each game drawn past `gameS` seconds
134
+ * (`PlayBridge.java`'s `playHeadless`). It runs on the same JVMs as every match and is never a `Match`:
135
+ * `play/botgames.ts` reads its lines.
136
+ */
137
+ export interface HeadlessRules {
138
+ bestOf: 1 | 3;
139
+ gameS: number;
140
+ }
141
+ export interface MatchSpec {
142
+ /**
143
+ * Seat 0 is a human in every match a player sees: the bridge refuses a match with no human seat,
144
+ * because Forge watches an AI-against-AI game through a desktop window a headless JVM cannot open.
145
+ * Only a bot game ({@link headless}) seats two AIs, and it never opens that window.
146
+ */
147
+ seats: [SeatSpec & {
148
+ ai: false;
149
+ }, SeatSpec] | [SeatSpec & {
150
+ ai: true;
151
+ }, SeatSpec & {
152
+ ai: true;
153
+ }];
154
+ /** A bot game ({@link HeadlessRules}); absent for every match a player plays or watches. */
155
+ headless?: HeadlessRules;
156
+ /** Seeds Forge's shuffles and the precon pick, for a repeatable test run. Omitted in play. */
157
+ seed?: number;
158
+ /**
159
+ * Wave 33 §S — a TEST-only starting position: the text of a Forge puzzle file's
160
+ * `[state]` section (`humanlife=`, `humanhand=`, `humanbattlefield=`,
161
+ * `activephase=`, … — `GameState.parseLine` in the deploy tree's forge-build
162
+ * cache has the full key list), with `human…` keys applying to seat 0 and
163
+ * `ai…` keys to seat 1. `bridgeConfig` spreads it onto `config.json` like every
164
+ * other `MatchSpec` field; `PlayBridge.java`'s `configFrom` reads it and
165
+ * `BridgeGui.hostMatch` applies it from `HostedMatch`'s own start-game hook —
166
+ * see that method's doc. Omitted in play: `socket.ts`'s `parseStartBody`
167
+ * accepts this key only behind `CARDTABLE_PLAY_PROBE=1` and refuses it
168
+ * otherwise, so production never sends one.
169
+ */
170
+ scenario?: string;
171
+ /**
172
+ * Start on {@link scenario}'s board with no coin toss and no mulligan — Forge's
173
+ * own Puzzle game type, which skips both (`GameAction.startGame`). Set only by
174
+ * `socket.ts` for a board-state room's own scenario; a test's scenario keeps the
175
+ * ordinary opening its drivers click through.
176
+ */
177
+ skipOpening?: boolean;
178
+ /**
179
+ * {@link scenario} is this match's own turn-start snapshot (`restoredSpec`): its board goes back
180
+ * as it was, running no replacement effect ("enters tapped", "you may pay 2 life"), where a
181
+ * board room's scenario plays each permanent's entry. Implies {@link skipOpening}.
182
+ */
183
+ restore?: boolean;
184
+ /**
185
+ * The room's format id (`room/lobby.ts`'s `FormatId`): what a card-name ask is
186
+ * narrowed to (`names.ts`). Inert in the JVM — `configFrom` never reads it — and
187
+ * kept in `config.json` so a match taken back after a restart still has it.
188
+ */
189
+ format?: string;
190
+ /**
191
+ * The room's hand smoothing setting (`room/lobby.ts`'s `RoomSettings`): the
192
+ * opening hand is the closer of two to the deck's land ratio, and each
193
+ * mulligan's redraw is weighted toward it. `PlayBridge.java`'s `configFrom`
194
+ * turns it into Forge's filtered hands. Absent is off, Forge's default — a
195
+ * spec built directly, as the jvm suites build theirs, deals what it always did.
196
+ */
197
+ handSmoothing?: boolean;
198
+ /**
199
+ * Wave 71 §E — names the seat Forge asks to choose play or draw. Every game we
200
+ * host is a fresh Forge `Match`, so Forge always treats it as the FIRST game of
201
+ * that match and tosses a coin (`GameAction.determineFirstTurnPlayer`,
202
+ * `forge/forge-game/src/main/java/forge/game/GameAction.java:2364-2416`) rather
203
+ * than asking the previous loser — this field is how the room still names that
204
+ * player. `PlayBridge.java`'s `startMatch` rigs the coin toss so the named seat
205
+ * is the one Forge asks (`SeatGui`'s `updateButtons` with `label1:'Play',
206
+ * label2:'Draw'`), which makes the published `coinToss.winner` (`match.ts:1055`)
207
+ * that seat too — the client's existing flip/notice needs no change. Omitted:
208
+ * byte-identical to today, an unrigged coin toss. Never set alongside a change
209
+ * to `forge/` — a fork change is a jar switch, and that switch is the operator's.
210
+ */
211
+ chooser?: 0 | 1;
212
+ /**
213
+ * The chess clock: each seat's time left, in ms, when this game starts — a room
214
+ * with the clock on carries what the series' last game left (`play/clock.ts`).
215
+ * Absent: no clock. Inert in the JVM, like `format`.
216
+ */
217
+ clockMs?: [number, number];
218
+ }
219
+ /**
220
+ * The four lines the host and placement read from any engine's own line type `L`; everything else
221
+ * is the game's own (w103 §H's pinned shape). Forge's full `BridgeLine` (now `bridge-protocol.ts`)
222
+ * narrows onto this through {@link isLifecycle} — TypeScript cannot narrow a generic `L extends {
223
+ * t: string }` on its `t` member directly (w100 finding 3.2), so a caller holding an `L` checks
224
+ * `isLifecycle(line)` first and reads the narrowed shape, never `line.t === 'ready'` on the bare `L`.
225
+ */
226
+ export type HostLifecycleLine = {
227
+ t: 'ready';
228
+ } | {
229
+ t: 'fatal';
230
+ message: string;
231
+ } | {
232
+ t: 'frame';
233
+ } | {
234
+ t: 'snapshot';
235
+ };
236
+ /** Narrows any engine's line onto the four the host itself understands. See {@link HostLifecycleLine}. */
237
+ export declare function isLifecycle<L extends {
238
+ t: string;
239
+ }>(line: L): line is L & HostLifecycleLine;
240
+ /** The latest `snapshot` line a match has had: what a restore starts it from. */
241
+ export interface TurnSnapshot {
242
+ turn: number;
243
+ state: string;
244
+ /** What the game held that {@link state} does not; absent or empty is the whole game. */
245
+ lossy?: readonly string[];
246
+ }
247
+ /**
248
+ * A bot game's (`MatchSpec.headless`) exit when Forge ended it on its own: the bridge plays the whole
249
+ * best-of and stops, so this is the game finishing, never its host failing.
250
+ */
251
+ export declare const PLAYED_OUT = "played out";
252
+ /**
253
+ * What a match host tells its match, generic over the engine's own line type `L` (w103 §H's pinned
254
+ * shape: Forge instantiates this `HostEvents<BridgeLine>`, `bridge-protocol.ts`).
255
+ */
256
+ export interface HostEvents<L extends {
257
+ t: string;
258
+ }, C extends {
259
+ t: string;
260
+ }> {
261
+ line(line: L): void;
262
+ /** The host is gone. `reason` says why, for the match's status. */
263
+ exit(reason: string): void;
264
+ log(entry: Record<string, unknown>): void;
265
+ /**
266
+ * Replay only (`attach`): a command an EARLIER server had already sent to this
267
+ * JVM. Nothing the bridge says records that an ask was answered, so without
268
+ * this a resumed match would re-open asks Forge has already returned from.
269
+ */
270
+ replayed?(command: C): void;
271
+ }
272
+ /** What a match sends its host, generic over the engine's own command type `C`. */
273
+ export interface MatchHost<C extends {
274
+ t: string;
275
+ }> {
276
+ send(command: C): void;
277
+ /** Ask the match to stop; force it after a grace period. Idempotent. */
278
+ stop(): void;
279
+ /**
280
+ * Write down what a re-attach or a restore of this match would need that only
281
+ * the match knows: its epoch, which participant owns each seat, and its latest
282
+ * turn-start snapshot. Absent on a host that cannot outlive the process (the
283
+ * replay host in the tests).
284
+ */
285
+ remember?(state: Durable & {
286
+ snapshot?: TurnSnapshot | null;
287
+ clockMs?: [number, number];
288
+ }): void;
289
+ /**
290
+ * The server is going down and this match is being LEFT RUNNING. Let go of
291
+ * the transport without killing anything and without settling the run
292
+ * directory, so the next process can `attach` to it. Absent on a host whose
293
+ * JVM cannot outlive us, and false when there was nothing to hand over — the
294
+ * caller then owes the seats an explanation instead.
295
+ */
296
+ handOver?(): boolean;
297
+ }
298
+ /**
299
+ * What a restart needs to resume a match, independent of the engine (w103 §H's pinned shape):
300
+ * its epoch, so a re-attached client resyncs on the cursor it holds, and which participant owns
301
+ * each seat, so a re-attach cannot seat someone at the wrong hand. `checkpoint` is w105's: a
302
+ * per-engine mid-game save, opaque to the host — whatever `GameAdapter.classify`'s `{ t:
303
+ * 'checkpoint' }` line carried last (`match/shell.ts`'s `latestCheckpoint`), written down beside
304
+ * Forge's own {@link TurnSnapshot} (`MatchRecord.snapshot`, kept unchanged this wave) rather than
305
+ * replacing it. Absent before a match's first checkpoint. `readJvmRecord`/`hostFace`'s `remember`
306
+ * pass through whatever the caller sent, never forcing it to `null` themselves.
307
+ */
308
+ export interface Durable {
309
+ epoch: string;
310
+ owners: (string | null)[];
311
+ checkpoint?: unknown;
312
+ }
313
+ /**
314
+ * A match an earlier server left running, as `orphans()` offers it: everything a re-attach needs
315
+ * and nothing a seat could not already see (`owners` are participant ids, which never leave this
316
+ * host). `epoch`/`owners`/`checkpoint` are {@link Durable}'s; `epoch` widens to `null` here (unlike
317
+ * `Durable`'s own, always-set `epoch`) because a freshly placed match has none yet — before its
318
+ * first `remember()`, it has no durable identity to resume by.
319
+ */
320
+ export interface MatchRecord extends Pick<Durable, 'owners' | 'checkpoint'> {
321
+ matchId: string;
322
+ /** The JVM it runs in. */
323
+ hostId: string;
324
+ startedAt: string;
325
+ /** The match's epoch, so a re-attached client resyncs on the cursor it holds. Null before its first `remember()`. */
326
+ epoch: string | null;
327
+ spec: MatchSpec;
328
+ /** The match's latest turn-start snapshot, absent before its first turn. */
329
+ snapshot?: TurnSnapshot | null;
330
+ /** Each seat's chess-clock time left when the match last wrote this record; absent with no clock. */
331
+ clockMs?: [number, number];
332
+ /** When the server that ran it handed its JVM over. */
333
+ orphanedAt?: string;
334
+ }
335
+ /** One JVM's record, `<dir>/jvm.json`: what a later server re-attaches it and its matches by. */
336
+ export interface JvmRecord {
337
+ hostId: string;
338
+ startedAt: string;
339
+ /** Set when a server handed this JVM over on its way out. */
340
+ orphanedAt?: string;
341
+ matches: Omit<MatchRecord, 'hostId' | 'orphanedAt'>[];
342
+ }
343
+ /**
344
+ * Makes a host for one match. `close`, when present, releases whatever the factory holds between
345
+ * matches (an idle JVM); `attachPlay`'s `close()` calls it. `orphans`/`attach` are the re-attach
346
+ * seam — a factory whose JVMs cannot outlive the process has neither.
347
+ */
348
+ export type MatchHostFactory<L extends {
349
+ t: string;
350
+ }, C extends {
351
+ t: string;
352
+ }> = ((matchId: string, spec: MatchSpec, events: HostEvents<L, C>) => MatchHost<C>) & {
353
+ close?(): void;
354
+ /** Matches still running from an earlier server, oldest first. Asked once, at boot. */
355
+ orphans?(): Promise<MatchRecord[]>;
356
+ /** Take one back: replay its stream into `events` before returning, then hand it live lines. */
357
+ attach?(record: MatchRecord, events: HostEvents<L, C>): MatchHost<C>;
358
+ /** Leave every live match running for the next process (SIGTERM). */
359
+ handOverAll?(): void;
360
+ /**
361
+ * The last word before `process.exit`: kill every JVM this process still holds with no
362
+ * handed-over match, and let go of the rest. Synchronous, immediate, and idempotent — see
363
+ * "Going down" in the module header.
364
+ */
365
+ reapOnExit?(): ReapResult;
366
+ /**
367
+ * Where a match placed now would go, for `start-queue.ts`: into a warm JVM with room (it starts
368
+ * at once), into one still booting, nowhere yet (placing it launches a JVM), or nowhere at all
369
+ * (`full`: no host may take it now; it waits until `watchRoom` says otherwise).
370
+ */
371
+ room?(): 'warm' | 'booting' | 'none' | 'full';
372
+ /** JVMs booting now. */
373
+ booting?(): number;
374
+ /** Called whenever `room()` or `booting()` may have changed. */
375
+ watchRoom?(listener: () => void): void;
376
+ };
377
+ /** What `reapOnExit` did, by JVM host id, for the shutdown log. */
378
+ export interface ReapResult {
379
+ /** Confirmed gone because we killed them, and their run directories settled. */
380
+ killed: string[];
381
+ /** Already gone, or handed over. Nothing to do and nothing owed. */
382
+ kept: string[];
383
+ /** Still running after the kill. A leak, said out loud — the boot sweep is the next chance. */
384
+ left: string[];
385
+ }
386
+ /** See "The ceiling" in the module header. Also `PlayDeps.maxMatches`'s default. */
387
+ export declare const MAX_CONCURRENT_MATCHES = 50;
388
+ /** See "Liveness" in the module header. */
389
+ export declare const UNRESPONSIVE_MS = 40000;
390
+ /**
391
+ * A match asked to stop is let go after this long without its `stopped`. The bridge concedes,
392
+ * answers parked asks as aborted until the game is over (up to 10 s), then tears the match down:
393
+ * a real match took ~9.3 s (lane U).
394
+ */
395
+ export declare const MATCH_STOP_MS = 30000;
396
+ /** A JVM with no matches for this long is retired, unless it is the warm one. */
397
+ export declare const IDLE_JVM_MS: number;
398
+ /** …and after this many failed boots in a row, no JVM is kept warm. */
399
+ export declare const WARM_MAX_FAILURES = 3;
400
+ /** `JvmRecord`'s file, in each JVM's directory. */
401
+ export declare const JVM_RECORD_FILE = "jvm.json";
402
+ /** A JVM orphaned longer than this is retired, not re-attached. */
403
+ export declare const ORPHAN_MAX_MS: number;
404
+ /** A match nobody claimed this long after boot is stopped, so ignoring `orphans()` leaks nothing. */
405
+ export declare const ORPHAN_CLAIM_MS = 60000;
406
+ /** A match's stream: every line and command, in order, for a re-attach to replay. */
407
+ export declare function streamFile(dir: string, matchId: string): string;
408
+ /**
409
+ * The `bridge.stderr.txt` of the local JVM that hosts `matchId`, found by the `match-placed`
410
+ * line the coordinator logged to that match's log. A JVM's run directory is named for the JVM,
411
+ * not the match, so this is how a test or a dump reaches a match's stderr. Null before placement.
412
+ */
413
+ export declare function matchStderrPath(workDir: string, log: readonly Record<string, unknown>[], matchId: string): string | null;
414
+ /** `<dir>/jvm.json`, or null when it is missing, unreadable or not a record. */
415
+ export declare function readJvmRecord(dir: string): JvmRecord | null;
416
+ export interface JvmPoolOptions {
417
+ /** Keep one JVM with room booted ahead of the next match. Default: `config.warmJvm`. */
418
+ warm?: boolean;
419
+ /**
420
+ * JVMs this pool will run at once, or a function read at each launch (a claw's count falls while
421
+ * it also runs the draft bot). Default `MAX_CONCURRENT_MATCHES`.
422
+ */
423
+ maxJvms?: number | (() => number);
424
+ /** Wait before launching a warm JVM again after one failed to boot. Default `WARM_RETRY_MS`. */
425
+ warmRetryMs?: number;
426
+ /** A JVM empty this long is retired, unless it is the warm one. Default `IDLE_JVM_MS`. */
427
+ idleMs?: number;
428
+ /** A match asked to stop is let go this long without its `stopped`. Default `MATCH_STOP_MS`. */
429
+ matchStopMs?: number;
430
+ /** Sweep `workDir` of what an earlier process left before the first JVM. Default true. Ignored with `launcher`. */
431
+ sweep?: boolean;
432
+ /** Where JVMs run. Default: this machine (`localJvmLauncher`). */
433
+ launcher?: JvmLauncher;
434
+ /** Forge cut an AI decision short in one of this pool's JVMs ("AI cutoffs" in the module header). */
435
+ onCutoff?: (cutoff: AiCutoff) => void;
436
+ log?: (entry: Record<string, unknown>) => void;
437
+ }
438
+ /** One `cutoff` line: its JVM, the match whose game was cut (null: the JVM's own), and the AI's top Forge frame. */
439
+ export interface AiCutoff {
440
+ hostId: string;
441
+ matchId: string | null;
442
+ where: string | null;
443
+ }
444
+ /** The JVM factory. `room()` and friends are for `start-queue.ts`, diagnostics and the benchmark. */
445
+ export type JvmHostFactory<L extends {
446
+ t: string;
447
+ }, C extends {
448
+ t: string;
449
+ }> = MatchHostFactory<L, C> & {
450
+ close(): void;
451
+ room(): 'warm' | 'booting' | 'none';
452
+ booting(): number;
453
+ watchRoom(listener: () => void): void;
454
+ orphans(): Promise<MatchRecord[]>;
455
+ attach(record: MatchRecord, events: HostEvents<L, C>): MatchHost<C>;
456
+ handOverAll(): string[];
457
+ reapOnExit(): ReapResult;
458
+ /** JVMs this pool holds, with their matches: for diagnostics and tests. */
459
+ jvms(): {
460
+ hostId: string;
461
+ warm: boolean;
462
+ draining: boolean;
463
+ adopted: boolean;
464
+ matches: string[];
465
+ }[];
466
+ /** Place nothing more into this JVM, and retire it once its matches end (a heap past `recycleWanted`). */
467
+ drain(hostId: string, why: string): void;
468
+ /**
469
+ * Kill every JVM now and launch none again: the host failed, and its matches were moved. Each
470
+ * match's exit still reaches its events, with `why`.
471
+ */
472
+ abandon(why: string): void;
473
+ };
474
+ /**
475
+ * Matches placed into shared `--host` JVMs. A match's own `HostEvents.log` receives what is about
476
+ * that match; what is about a JVM goes to `options.log`.
477
+ */
478
+ export declare function jvmHostFactory<L extends {
479
+ t: string;
480
+ }, C extends {
481
+ t: string;
482
+ }>(config: JvmHostConfig, options?: JvmPoolOptions): JvmHostFactory<L, C>;