@hadoku/game-server 0.0.0-stage → 0.1.6

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 +35 -4
  119. package/README.md +0 -3
@@ -0,0 +1,25 @@
1
+ /** One `--host` bridge JVM's line protocol, wherever the JVM runs. */
2
+ export interface JvmTransport {
3
+ /** The JVM's host id: what `--host <hostId>` was given. */
4
+ readonly hostId: string;
5
+ /** One protocol line (JSON, no newline) to the JVM's stdin. Lines are delivered in order. */
6
+ send(line: string): void;
7
+ /** Every stdout line, in order. One listener; set before the first line can arrive. */
8
+ onLine(listener: (line: string) => void): void;
9
+ /** The JVM, or the link to it, is gone for good. Fires once. Lines after it are dropped. */
10
+ onExit(listener: (reason: string) => void): void;
11
+ /** End the JVM now. Idempotent. Fires onExit. */
12
+ kill(): void;
13
+ /** Let go without killing (coordinator restart); a later `attach` takes it back. */
14
+ release(): void;
15
+ }
16
+ export interface JvmLauncher {
17
+ /** Boot a new `--host` JVM. Its first line is `warm` (or it exits). */
18
+ launch(hostId: string, opts: {
19
+ xmxMb: number;
20
+ }): JvmTransport;
21
+ /** JVMs still running from an earlier coordinator. */
22
+ running(): Promise<string[]>;
23
+ /** Take one back. Lines it printed while nobody was attached are replayed first, in order. */
24
+ attach(hostId: string): JvmTransport;
25
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,325 @@
1
+ /**
2
+ * `--host` bridge JVMs on THIS machine: the local `JvmLauncher` (`jvm-transport.ts` is the seam;
3
+ * `remote/launcher.ts` is the same seam over a claw's agent). The coordinator (`host.ts`) places
4
+ * matches into JVMs; this file starts them, reaches their line streams and settles what they
5
+ * leave on disk.
6
+ *
7
+ * What is generic to any process hosted this way — the fifo transport, pid liveness, the run-dir
8
+ * and crash-record bookkeeping — lives in `engine-runtime.ts`; what is here is Forge's own:
9
+ * compiling and launching the bridge, its preferences, and `stageRunDir`'s Forge-specific profile
10
+ * layout. `forgeEngineRuntime` at the bottom of this file is `EngineRuntime` mapped onto that, and
11
+ * `LocalJvm`'s own spawn (below) launches through its `argv`, appending only the host id `argv`'s
12
+ * sketch has no room for — `host.ts` itself still places matches through `localJvmLauncher`'s
13
+ * `JvmLauncher`, not `EngineRuntime` directly; lifting the pool itself onto `EngineRuntime`, so a
14
+ * non-Forge engine shares the same coordinator, is w105's.
15
+ *
16
+ * ## The run directory
17
+ *
18
+ * Every local JVM gets `<workDir>/<hostId>` (`stageRunDir`): Forge's profile, a `res` symlink,
19
+ * empty user and cache dirs, two fifos, `launch.json` (its pid), the coordinator's `jvm.json` and
20
+ * per-match streams, and `bridge.stderr.txt`. `workDir` is on tmpfs by default, so a directory
21
+ * nobody removes is RAM nobody gets back. What happens to it is decided when the JVM is gone:
22
+ *
23
+ * - **A clean end is removed whole**: the coordinator asked the JVM to go and it went.
24
+ * - **Anything else is a crash record**, pruned to `CRASH_RECORD_FILES` (stderr, the
25
+ * coordinator's `jvm.json` with every match's decks, and a `crash.json` saying how it ended).
26
+ * The exit reason names its path.
27
+ * - **Crash records are bounded**: the newest `CRASH_RECORDS_KEPT`, none older than
28
+ * `CRASH_RECORD_MAX_AGE_MS`.
29
+ * - **The boot sweep** (`sweepRunDirs`, run when the launcher is made) removes what an earlier
30
+ * process left, and spares a directory some process is standing in (`/proc/<pid>/cwd` — so
31
+ * another server's live JVM survives), one changed in the last `RUN_DIR_FRESH_MS`, and crash
32
+ * records within the bound. A live directory whose `launch.json` pid IS the process standing in
33
+ * it is one of ours, and `running()` offers it back. A live one-match JVM from before many
34
+ * matches per JVM (`m-…`, `spare-…`) is ended: nothing re-attaches one any more. Where `/proc`
35
+ * cannot be read the sweep does nothing and says so.
36
+ *
37
+ * ## A JVM outlives its server (Wave 22, §E)
38
+ *
39
+ * A deploy must not end live games, so a JVM survives the server that started it:
40
+ *
41
+ * 1. **The transport is not an inherited pipe**, which dies with its process. The run dir holds
42
+ * two named pipes, `in.fifo` and `out.fifo`, and the JVM's stdin/stdout are fds on those. Both
43
+ * ends open them **`O_RDWR`**, which on Linux succeeds without a peer and means neither side
44
+ * ever sees EOF (each is its own last writer). The bridge exits on stdin EOF. stderr is an
45
+ * `O_APPEND` fd on `bridge.stderr.txt`, for the same reason.
46
+ * 2. **The JVM is not in our process group, and nothing kills it on the way out**: `detached`,
47
+ * `unref`, and no exit hook.
48
+ * 3. **The next process finds it** by `launch.json`, confirmed through `/proc/<pid>/cwd` (a
49
+ * recycled pid is some other program, in some other directory), and `attach` re-opens the
50
+ * fifos. Lines the JVM wrote while nobody was attached are still in `out.fifo`, so they are the
51
+ * first ones read. Rebuilding each MATCH from its history is the coordinator's (`host.ts`).
52
+ *
53
+ * ## The bridge, compiled once
54
+ *
55
+ * See `bridgeLaunch`.
56
+ *
57
+ * ## Configuration (environment)
58
+ *
59
+ * CARDTABLE_FORGE_JAR the fat jar, `forge-gui-desktop-*-jar-with-dependencies.jar` (required)
60
+ * CARDTABLE_FORGE_RES Forge's `forge-gui/res` directory (required)
61
+ * CARDTABLE_JAVA a JDK 21 `java`; default: `$JAVA_HOME/bin/java`, then `java` on `PATH`,
62
+ * the fleet's managed JDK (`defaultJava`, D14 amended 2026-11-02)
63
+ * CARDTABLE_PLAY_WORK_DIR per-JVM run directories; default `<os tmpdir>/cardtable-play`
64
+ * CARDTABLE_PLAY_JVM_OPTS extra JVM flags, space-separated; an `-Xmx` here beats `JVM_HEAP_MB`
65
+ * CARDTABLE_PLAY_WARM_JVM `0` to keep no JVM booted ahead of a match; default on
66
+ * CARDTABLE_PLAY_MATCHES_PER_JVM matches one JVM hosts at most; default `MATCHES_PER_JVM`
67
+ * CARDTABLE_PLAY_BRIDGE_CACHE where the compiled bridge is kept; default `~/.cache/cardtable/bridge`
68
+ * CARDTABLE_AI_FLAT_MC how hard the AI a person plays thinks: `off`, `base`, `lite` or `max`
69
+ * (`AiFlatMc`); default `AI_FLAT_MC`. Read per match, so a restart of the
70
+ * server flips it for every match started after, on JVMs already running too
71
+ *
72
+ * The bridge needs a JDK — `javac` to compile, or `jdk.compiler` for the source launcher it falls
73
+ * back to — which is why the user-local Temurin comes first, ahead of whatever `java` is on `PATH`
74
+ * (on the production host that is a JRE with no `javac`).
75
+ */
76
+ import { type EngineRuntime, type SweepResult } from './engine-runtime.js';
77
+ import type { JvmLauncher } from './jvm-transport.js';
78
+ /**
79
+ * Forge's server drops a client it has read nothing from for this long
80
+ * (`FServerManager.HEARTBEAT_TIMEOUT_SECONDS`, `forge.net.heartbeatTimeout`, default 45 s;
81
+ * its clients write a heartbeat every 15 s). Every client of a bridge's server is a
82
+ * loopback `FGameClient` in the same JVM, so the only thing that silences one is the
83
+ * whole JVM pausing — and a dropped client is never reconnected: the seat's every later
84
+ * press is lost (hosting-test-plan C2b: a 60 s pause wedged the match for good). A day is
85
+ * far past any pause a JVM comes back from; a JVM that stops for longer is
86
+ * `UNRESPONSIVE_MS`'s to end (host.ts), not Forge's.
87
+ */
88
+ export declare const FORGE_HEARTBEAT_TIMEOUT_S = 86400;
89
+ /**
90
+ * Flags every bridge JVM gets, before the heap cap and the operator's `jvmOpts` (so a later flag
91
+ * of theirs wins). `ExitOnOutOfMemoryError`: G1 has no GC-overhead limit, and without this a JVM
92
+ * out of heap never exits — its games die of `OutOfMemoryError` and the JVM limps on
93
+ * (hosting-test-plan B4: 62 % GC, act p99 14.6 s). With it the JVM exits (code 3), which fails
94
+ * every match on it through the exit path.
95
+ */
96
+ export declare const BRIDGE_JVM_FLAGS: readonly string[];
97
+ export interface JvmHostConfig {
98
+ java: string;
99
+ jar: string;
100
+ res: string;
101
+ workDir: string;
102
+ jvmOpts: string[];
103
+ bridgeSource: string;
104
+ /** Compiled bridges, one directory per version. See `bridgeLaunch`. */
105
+ bridgeCache: string;
106
+ /**
107
+ * A JVM asked to stop (`{"t":"stop"}` to its host id) is killed after this long, and a
108
+ * match asked to stop is let go after `MATCH_STOP_MS` (host.ts).
109
+ */
110
+ stopGraceMs: number;
111
+ /** Keep one booted JVM with room for the next match. See host.ts, "The warm JVM". */
112
+ warmJvm: boolean;
113
+ /** Matches one JVM hosts at most. Default `MATCHES_PER_JVM`. */
114
+ perJvm?: number;
115
+ /** Each JVM's heap cap, unless `jvmOpts` names an `-Xmx` of its own. Default `JVM_HEAP_MB`. */
116
+ xmxMb?: number;
117
+ /** A JVM silent this long is killed and every match on it failed. Default `UNRESPONSIVE_MS` (host.ts); see "Liveness". */
118
+ unresponsiveMs?: number;
119
+ /** Each match's `AiFlatMc`, sent with its `start`. Absent is `off`. */
120
+ aiFlatMc?: AiFlatMc;
121
+ }
122
+ /**
123
+ * Forge's Flat Monte Carlo AI: on each decision with more than one sensible play, the AI plays
124
+ * each out a few times on a copy of the game and takes the best (`FlatMonteCarloPicker`).
125
+ * `off` is the heuristic AI alone; `base` the AI profile's own search (450 ms a decision, 2 s a
126
+ * turn); `lite` Forge's phone setting (600 ms, 2.5 s, plus its attack search and a look at the
127
+ * opponent's next turn for small decisions); `max` its desktop setting (1.5 s, 6 s, more lines,
128
+ * more samples, the opponent's turn always). `PlayBridge.java`'s `MatchContext.aiFlatMc`.
129
+ */
130
+ export type AiFlatMc = 'off' | 'base' | 'lite' | 'max';
131
+ /** `CARDTABLE_AI_FLAT_MC`'s default. See docs/planning/flat-mc-ai.md for the measurement behind it. */
132
+ export declare const AI_FLAT_MC: AiFlatMc;
133
+ /**
134
+ * `CARDTABLE_AI_FLAT_MC`: unset is {@link AI_FLAT_MC}; anything that is not a level is `off`, so a
135
+ * typo made while turning it down in a hurry never leaves it on.
136
+ */
137
+ export declare function aiFlatMcFrom(raw: string | undefined): AiFlatMc;
138
+ /**
139
+ * See host.ts, "Many matches per JVM". `CARDTABLE_PLAY_MATCHES_PER_JVM` overrides it. 25 since
140
+ * 2026-10-28: a claw's 4 GB slice holds one JVM, and two claws at 25 make the operator's 50
141
+ * concurrent matches. A slice held 50 paced matches inside every quality gate (hosting-test-plan
142
+ * A2), so 25 is half of what was proven; the limit is the slice's 4 cores, not the heap.
143
+ */
144
+ export declare const MATCHES_PER_JVM = 25;
145
+ /**
146
+ * Each JVM's heap cap: the budget for {@link MATCHES_PER_JVM} matches. A JVM is ~172 MB live idle
147
+ * and ~10 MB per match (Wave 9 lane D; 4–9 MB in hosting-test-plan B3), so 25 matches live in
148
+ * ~420 MB of a 2 GB heap. G1 does not hand committed heap back, so a JVM's RSS is budgeted at its
149
+ * peak: ~2.3 GB with metaspace, code cache and Netty.
150
+ */
151
+ export declare const JVM_HEAP_MB = 2048;
152
+ export type JvmAvailability = {
153
+ ok: true;
154
+ config: JvmHostConfig;
155
+ } | {
156
+ ok: false;
157
+ reason: string;
158
+ };
159
+ /** Where compiled bridges are kept, shared by every tree on the host (keyed by `bridgeVersion`). */
160
+ export declare function defaultBridgeCache(env?: NodeJS.ProcessEnv): string;
161
+ /**
162
+ * Resolve the JVM host's configuration, or say exactly what is missing. `bridgeSource` is the game's
163
+ * own bridge (Magic's is `@hadoku/magic-server/root`'s `BRIDGE_SOURCE`): the platform knows no game's tree.
164
+ */
165
+ export declare function jvmHostConfig(bridgeSource: string, env?: NodeJS.ProcessEnv): JvmAvailability;
166
+ /**
167
+ * A compiled bridge nobody has launched for this long is removed when the next
168
+ * one is compiled. Far past `ORPHAN_MAX_MS`, so no JVM that could still load a
169
+ * class from it is alive.
170
+ */
171
+ export declare const BRIDGE_CACHE_MAX_AGE_MS: number;
172
+ /**
173
+ * What a bridge JVM is launched with after its flags: `-cp <classpath> <main>`.
174
+ *
175
+ * Launching the SOURCE (`java -cp <jar> PlayBridge.java`, JEP 330) compiles the
176
+ * whole file inside every JVM before `main` runs — about 0.6 s of a 5 s cold
177
+ * start (median 5.68 s against 5.03 s over sixteen alternating starts,
178
+ * 2026-10-06). So it is
179
+ * compiled once instead, by the `javac` beside `config.java`, into a directory
180
+ * named for a hash of everything that decides the result: the source's bytes,
181
+ * the jar it is compiled against, and the JDK. An edited bridge is therefore a
182
+ * different directory, never a stale one, and it still takes effect at the next
183
+ * JVM with no restart, as it did under the source launcher. `-proc:none` is what
184
+ * that launcher does too.
185
+ *
186
+ * Two processes may compile the same version at once (a deploy beside a CI job):
187
+ * each compiles into its own temporary directory and RENAMES it into place, so
188
+ * a JVM never sees half a directory, and the loser's copy is deleted. The
189
+ * directory name carries the main's own name as well as `bridgeVersion`
190
+ * (below) precisely so this stays true even though two different mains
191
+ * (`PlayBridge`, `PoolService`) can share a version: each still gets its own
192
+ * directory, so a reader finding ITS main's class already there is never
193
+ * looking at one another process is still mid-write on for a DIFFERENT main.
194
+ *
195
+ * With no `javac` there (a `java` from `PATH`), or a compile that fails, this is
196
+ * the source launcher exactly as before, and a failed compile is logged. Each
197
+ * `jvm-spawned` line says which one that JVM got.
198
+ *
199
+ * `-sourcepath <bridgeSource's own directory>` is on every `javac` invocation
200
+ * (wave 73 §D): `PlayBridge.java` and `PoolService.java` sit beside each other
201
+ * there, and `PoolService.java` calls `PlayBridge.forgeCardName` — a
202
+ * package-private static method, reachable because both are top-level classes
203
+ * in the same (unnamed) package — so compiling `PoolService.java` alone needs
204
+ * `javac` to find and compile `PlayBridge.java` too. It is a no-op for
205
+ * `PlayBridge.java`'s own compile: nothing in that file references a sibling
206
+ * class `javac` cannot already resolve from the jar, so `-sourcepath` is never
207
+ * consulted for it, and the compiled output is unchanged.
208
+ */
209
+ /** What compiling and launching a bridge reads from a host's configuration. */
210
+ export type BridgeConfig = Pick<JvmHostConfig, 'java' | 'jar' | 'bridgeSource' | 'bridgeCache'>;
211
+ export declare function bridgeLaunch(config: BridgeConfig, log: (entry: Record<string, unknown>) => void): {
212
+ args: string[];
213
+ how: 'compiled' | 'source';
214
+ };
215
+ /**
216
+ * Every input that decides a compiled bridge's cache directory. Not just
217
+ * `config.bridgeSource`'s own bytes: `javac`'s `-sourcepath` (above) can pull
218
+ * ANY `.java` file beside it into the compile, so the key has to cover every
219
+ * sibling in that directory, hashed in a fixed (sorted) order for a
220
+ * deterministic digest — otherwise an edit to a file that IS referenced,
221
+ * with the referencing file itself unchanged, would keep the old key and so
222
+ * silently serve a stale compiled class for it.
223
+ *
224
+ * Covering the whole directory means `PlayBridge.java`'s own key also changes
225
+ * when `PoolService.java` changes, and vice versa, even on an edit that
226
+ * changes nothing either file's compile actually depends on. Accepted for
227
+ * simplicity: the alternative is having `javac` report exactly which
228
+ * siblings it resolved for THAT compile (it does not expose this), and
229
+ * tracking it per bridge source — real staleness is worse than an occasional
230
+ * needless recompile.
231
+ *
232
+ * Exported so the key itself is unit-testable (`host.test.ts`, "an edited
233
+ * SIBLING .java changes the key too") without a real compile.
234
+ */
235
+ export declare function bridgeVersion(config: BridgeConfig): string;
236
+ /** `{hostId, pid, startedAt}`: what a later process finds a running JVM by. Written at launch. */
237
+ export declare const LAUNCH_RECORD_FILE = "launch.json";
238
+ /**
239
+ * Write `file` whole or not at all: into a temporary file beside it, then renamed over
240
+ * it. `writeFileSync` in place truncates first, so a full disk left `jvm.json` empty and
241
+ * its match un-re-attachable (hosting-test-plan C6); here a failed write leaves the old
242
+ * file as it was, and throws.
243
+ */
244
+ export declare function writeFileAtomic(file: string, text: string): void;
245
+ /**
246
+ * Forge resolves `res/` against the working directory (`ForgeConstants.RES_DIR`
247
+ * is "res/" when the version string carries no "git"), and reads its user and
248
+ * cache dirs from `forge.profile.properties` there. So each match gets its own
249
+ * directory — the same staging `scripts/spike/tierc/run.sh` does — and
250
+ * nothing is written into the Forge build it reads from. Exported for
251
+ * `multi-match.jvm.test.ts`, which stages a `--host` JVM itself.
252
+ */
253
+ export declare function stageRunDir(config: JvmHostConfig, name: string): string;
254
+ /**
255
+ * Forge preferences every match runs with, and why each one is here.
256
+ *
257
+ * These are **Forge's own settings**, not rules: each turns off a desktop-UI
258
+ * behaviour that makes no sense for a browser client, and the file is the
259
+ * documented way to set them (`AbstractPreferences`). A JVM is one match, so
260
+ * the file is written per run directory and nothing outlives it.
261
+ */
262
+ export declare const FORGE_PREFERENCES: Readonly<Record<string, string>>;
263
+ /** Crash records kept at most, newest first. See "The run directory". */
264
+ export declare const CRASH_RECORDS_KEPT = 20;
265
+ /** A crash record older than this is removed. */
266
+ export declare const CRASH_RECORD_MAX_AGE_MS: number;
267
+ /** The boot sweep leaves a directory changed this recently: another process may be staging it. */
268
+ export declare const RUN_DIR_FRESH_MS = 60000;
269
+ /**
270
+ * What a crashed JVM's directory is pruned to. `crash.json` marks it as a record; `jvm.json` is the
271
+ * coordinator's record of the matches it hosted, with their decks, so one can be replayed.
272
+ */
273
+ export declare const CRASH_RECORD_FILES: readonly ["bridge.stderr.txt", "jvm.json", "crash.json"];
274
+ /** Why a JVM that did not end cleanly ended — written as `crash.json`. */
275
+ export interface CrashRecord {
276
+ id: string;
277
+ reason: string;
278
+ code: number | null;
279
+ signal: string | null;
280
+ at: string;
281
+ }
282
+ /** `<run>/launch.json`, or null when it is missing, unreadable or not one. */
283
+ export declare function readLaunchRecord(run: string): {
284
+ hostId: string;
285
+ pid: number;
286
+ startedAt: string;
287
+ } | null;
288
+ /**
289
+ * Remove the run directories an earlier process left behind, and hand back the JVMs that are
290
+ * still running. See "The run directory" and "A JVM outlives its server" in the module header for
291
+ * what it spares and why.
292
+ */
293
+ export declare function sweepRunDirs(workDir: string, now?: number): SweepResult;
294
+ /** Number of bridge JVMs this process currently has running. */
295
+ export declare function liveJvmCount(): number;
296
+ export interface LocalLauncherOptions {
297
+ /** Sweep `workDir` of what an earlier process left (`sweepRunDirs`) now. Default true. */
298
+ sweep?: boolean;
299
+ log?: (entry: Record<string, unknown>) => void;
300
+ }
301
+ /** {@link JvmLauncher} for JVMs on this machine, plus what its boot sweep found. */
302
+ export type LocalJvmLauncher = JvmLauncher & {
303
+ readonly swept: SweepResult | null;
304
+ };
305
+ /**
306
+ * `--host` JVMs on this machine, one run directory each (`<workDir>/<hostId>`), reached over the
307
+ * directory's fifos so a later process can take one back. The boot sweep runs here, once, when the
308
+ * launcher is made: it removes what an earlier process left and finds the JVMs still running.
309
+ */
310
+ export declare function localJvmLauncher(config: JvmHostConfig, options?: LocalLauncherOptions): LocalJvmLauncher;
311
+ /**
312
+ * `EngineRuntime` (`engine-runtime.ts`) mapped onto Forge's own code. `LocalJvm`'s constructor
313
+ * (below) launches through this `spawn` — the actual `child_process.spawn` call lives here, not
314
+ * in `LocalJvm`, which only builds the argv and hands it over — rather than building the child
315
+ * process itself; `host.ts` itself still places matches through `localJvmLauncher`'s
316
+ * `JvmLauncher`, never `EngineRuntime` directly — lifting the POOL onto `EngineRuntime`, so a
317
+ * non-Forge engine shares the same coordinator, is still ahead of this.
318
+ *
319
+ * One honest gap, unchanged: the sketch's `argv(dir, size)` carries no host id, so Forge's real
320
+ * spawn appends `'--host', hostId` itself, after exactly these flags — the interface doesn't carry
321
+ * a host id to launch with.
322
+ */
323
+ export declare function forgeEngineRuntime(config: JvmHostConfig, log: (entry: Record<string, unknown>) => void): EngineRuntime & {
324
+ spawn: NonNullable<EngineRuntime['spawn']>;
325
+ };