@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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 hadoku-cardtable contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The base-path contract, checked at boot — cardtable's binding of the
3
+ * platform kernel (`@hadoku/service-kernel/http`).
4
+ *
5
+ * This is the one thing about a loopback-UI app that breaks SILENTLY, so it is
6
+ * the one thing this server refuses to guess about.
7
+ *
8
+ * The edge gives us stripPrefix: hadoku.me/cardtable/assets/x.js arrives here
9
+ * as /assets/x.js, which we serve happily. But the BROWSER is at
10
+ * hadoku.me/cardtable/, so a bundle built with the default base emits
11
+ * `src="/assets/x.js"` — an absolute URL with no prefix. The browser asks the
12
+ * edge for hadoku.me/assets/x.js, which is not this app's route, and the page
13
+ * renders blank with a 404 in the console and a 200 on every server-side probe.
14
+ * games-host shipped exactly this: its edge stripPrefix and its backend's base
15
+ * path are two independent declarations of one fact, and nothing compared them.
16
+ *
17
+ * So: compare them here, once, at boot, and say precisely what to change.
18
+ */
19
+ import { type BasePathVerdict, sendIndex } from '@wolffm/service-kernel/http';
20
+ export type { BasePathVerdict };
21
+ export { sendIndex };
22
+ /**
23
+ * The embed bundle's two fixed-name files (D21): `apps/ui/vite.embed.config.ts`
24
+ * emits them, watchparty imports the `.js`. Every other file in the bundle is
25
+ * content-hashed; these are the only ones whose bytes change under one name.
26
+ */
27
+ export declare const EMBED_ENTRIES: readonly ["cardtable-embed.js", "cardtable-embed.css"];
28
+ /** The page served in place of a bundle that would render blank, under cardtable's own name. */
29
+ export declare function diagnosticPage(verdict: BasePathVerdict, basePrefix: string): string;
@@ -0,0 +1,30 @@
1
+ /**
2
+ * The base-path contract, checked at boot — cardtable's binding of the
3
+ * platform kernel (`@hadoku/service-kernel/http`).
4
+ *
5
+ * This is the one thing about a loopback-UI app that breaks SILENTLY, so it is
6
+ * the one thing this server refuses to guess about.
7
+ *
8
+ * The edge gives us stripPrefix: hadoku.me/cardtable/assets/x.js arrives here
9
+ * as /assets/x.js, which we serve happily. But the BROWSER is at
10
+ * hadoku.me/cardtable/, so a bundle built with the default base emits
11
+ * `src="/assets/x.js"` — an absolute URL with no prefix. The browser asks the
12
+ * edge for hadoku.me/assets/x.js, which is not this app's route, and the page
13
+ * renders blank with a 404 in the console and a 200 on every server-side probe.
14
+ * games-host shipped exactly this: its edge stripPrefix and its backend's base
15
+ * path are two independent declarations of one fact, and nothing compared them.
16
+ *
17
+ * So: compare them here, once, at boot, and say precisely what to change.
18
+ */
19
+ import { diagnosticPage as kernelDiagnosticPage, sendIndex } from '@wolffm/service-kernel/http';
20
+ export { sendIndex };
21
+ /**
22
+ * The embed bundle's two fixed-name files (D21): `apps/ui/vite.embed.config.ts`
23
+ * emits them, watchparty imports the `.js`. Every other file in the bundle is
24
+ * content-hashed; these are the only ones whose bytes change under one name.
25
+ */
26
+ export const EMBED_ENTRIES = ['cardtable-embed.js', 'cardtable-embed.css'];
27
+ /** The page served in place of a bundle that would render blank, under cardtable's own name. */
28
+ export function diagnosticPage(verdict, basePrefix) {
29
+ return kernelDiagnosticPage(verdict, basePrefix, 'Cardtable');
30
+ }
package/dist/busy.d.ts ADDED
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Adapter: cardtable's binding of `@hadoku/service-kernel/lifecycle`'s busy probe (w93-K2).
3
+ *
4
+ * The kernel knows only the report's shape, `isLocalProbe` and the HTTP plumbing (fail-safe on
5
+ * `report`'s own throw, 404 to anything proxied). What counts as cardtable's "destroyable work" —
6
+ * a live match or a drafting pod, never a warm JVM or an idle lobby — stays here, unchanged from
7
+ * before this moved (`docs` below is the same text as always).
8
+ *
9
+ * ## What counts as busy — destroyable work, not connections
10
+ *
11
+ * - a match that is `starting` or `running`: a Forge JVM with players seated;
12
+ * - a draft that is `drafting`: picks made, packs mid-pass, held in memory.
13
+ *
14
+ * NOT counted, deliberately:
15
+ *
16
+ * - a match that is `over`, `failed` or `stopped` — finished, nothing left to lose;
17
+ * - a `complete` draft;
18
+ * - **the warm JVM.** `liveJvmCount()` includes it and would report busy every
19
+ * minute of the day; it is a pre-booted process with nobody in it;
20
+ * - **connected-but-idle clients and open lobbies.** They reconnect fine, they
21
+ * never disconnect on their own, and counting them would make every deploy sit
22
+ * until its deadline — at which point the deadline kills the real match anyway.
23
+ */
24
+ import type { BusyReport } from '@wolffm/service-kernel/lifecycle';
25
+ export { isLocalProbe, type BusyReport, type BusyRun } from '@wolffm/service-kernel/lifecycle';
26
+ export interface BusySources {
27
+ matches(): ReadonlyArray<{
28
+ id: string;
29
+ status: string;
30
+ seats: ReadonlyArray<unknown>;
31
+ anyoneHere?: () => boolean;
32
+ }>;
33
+ drafts(): ReadonlyArray<{
34
+ id: string;
35
+ status: string | undefined;
36
+ packNumber?: number;
37
+ pickNumber?: number;
38
+ }>;
39
+ }
40
+ export declare function busyReport(src: BusySources): BusyReport;
package/dist/busy.js ADDED
@@ -0,0 +1,23 @@
1
+ export { isLocalProbe } from '@wolffm/service-kernel/lifecycle';
2
+ const BUSY_MATCH = new Set(['starting', 'running']);
3
+ export function busyReport(src) {
4
+ const runs = [];
5
+ for (const m of src.matches()) {
6
+ if (!BUSY_MATCH.has(m.status))
7
+ continue;
8
+ // A running match whose seats have all gone (past the grace) holds nobody's game:
9
+ // the zombie of m-09487f336215 held every deploy for hours on 2026-10-04.
10
+ if (m.status === 'running' && m.anyoneHere !== undefined && !m.anyoneHere())
11
+ continue;
12
+ runs.push({ id: m.id, kind: 'match', label: `${m.seats.length} seats, ${m.status}` });
13
+ }
14
+ for (const d of src.drafts()) {
15
+ if (d.status !== 'drafting')
16
+ continue;
17
+ const at = d.packNumber !== undefined && d.pickNumber !== undefined
18
+ ? `pack ${d.packNumber} pick ${d.pickNumber}`
19
+ : 'in progress';
20
+ runs.push({ id: d.id, kind: 'draft', label: at });
21
+ }
22
+ return { busy: runs.length > 0, count: runs.length, runs };
23
+ }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Cardtable's binding of the kernel's capacity sampler: a card image request (`http/card-art.ts`)
3
+ * is a redirect to the art host, one per card a page draws, so it is counted on its own as
4
+ * `artRedirects`, never timed nor logged a line each. `index.ts` hands it to `createGameServer`.
5
+ */
6
+ export declare const ART_REDIRECTS: {
7
+ path: (path: string) => boolean;
8
+ field: string;
9
+ };
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Cardtable's binding of the kernel's capacity sampler: a card image request (`http/card-art.ts`)
3
+ * is a redirect to the art host, one per card a page draws, so it is counted on its own as
4
+ * `artRedirects`, never timed nor logged a line each. `index.ts` hands it to `createGameServer`.
5
+ */
6
+ export const ART_REDIRECTS = { path: (path) => path.startsWith('/api/art/'), field: 'artRedirects' };
@@ -0,0 +1,247 @@
1
+ /**
2
+ * Runtime config for the Cardtable loopback-UI tunnel server.
3
+ *
4
+ * Every value is env-overridable so the PM2 wrapper (which pulls them from the
5
+ * vault broker) can inject them without a code edit.
6
+ */
7
+ /**
8
+ * The site's own directory (`apps/server`, whose `dist/` PM2 runs), whatever the process's working directory — PM2
9
+ * starts us from the repo root, `pnpm start` from the package dir, and the two must agree. Bundled,
10
+ * this module is part of `apps/server/dist/*.js`, so it is `dist/`'s parent; run as source (tests,
11
+ * tsx) it is `packages/game-server/src/`, and the app it configures is `apps/server` beside it.
12
+ */
13
+ export declare const APP_ROOT: string;
14
+ /** The in-clone paths a state dir replaces, for the boot move (`state-dir.ts`). */
15
+ export declare const LEGACY_STATE: {
16
+ readonly dataDir: string;
17
+ readonly logDir: string;
18
+ };
19
+ export declare const CONFIG: {
20
+ /** Port this server listens on. cloudflared points the tunnel hostname here. */
21
+ readonly port: number;
22
+ /**
23
+ * Loopback only. The tunnel is the single ingress; binding 0.0.0.0 would put
24
+ * this on the LAN with no gate in front of it, because the gate is at the edge.
25
+ */
26
+ readonly host: string;
27
+ /**
28
+ * The public prefix the BROWSER sees: hadoku.me/cardtable/…
29
+ *
30
+ * Edge-router stripPrefixes it before forwarding, so THIS process is served
31
+ * root paths — but every URL the built bundle emits must still carry the
32
+ * prefix, or the browser requests /assets/x.js instead of /cardtable/assets/x.js
33
+ * and the page loads blank. assertBasePath() checks that at boot.
34
+ */
35
+ readonly basePrefix: string;
36
+ /**
37
+ * The built SPA this server serves off local disk. There is no GitHub-Pages
38
+ * shell and no published micro-frontend bundle for a loopback-UI app — this
39
+ * directory IS the front end, and `pnpm build` in the child repo produces it.
40
+ */
41
+ readonly webDir: string;
42
+ /**
43
+ * Tier floor enforced here as a SECOND seal, independent of route-tiers.ts.
44
+ *
45
+ * The edge gate is the real one, but it lives in another repo on another
46
+ * deploy cadence, and the tunnel hostname is reachable without it. A floor
47
+ * here means a route-tiers edit cannot silently widen this app on its own.
48
+ */
49
+ readonly minTier: string;
50
+ /**
51
+ * Shared secret edge-router stamps as X-Edge-Auth on everything it proxies
52
+ * (workers/shared/edgeAuth.ts). Identity headers are believed ONLY when this
53
+ * matches. Unset = FAIL CLOSED: every request is degraded to public/anon.
54
+ */
55
+ readonly edgeAuthSecret: string;
56
+ /**
57
+ * Bare-local dev escape hatch. With EDGE_AUTH_SECRET unset this server fails
58
+ * closed and strips tier/identity from every request, which locks a local
59
+ * browser out of its own app. Never set where the tunnel host is reachable.
60
+ */
61
+ readonly allowUnverifiedEdge: boolean;
62
+ /**
63
+ * Identity granted to a header-less caller while allowUnverifiedEdge is on.
64
+ * Defaults to the floor, so `pnpm dev` serves the app to a local browser
65
+ * instead of 404ing it. Read ONLY on that path — it grants nothing in
66
+ * production, where the hatch is off and provenance decides.
67
+ */
68
+ readonly devTier: string;
69
+ /**
70
+ * This server's own service-tier key for the game-stats store and for
71
+ * people's prefs rows, from the vault via the PM2 wrapper. Unset = match
72
+ * stats are off (logged once), and a music-review read or write is refused
73
+ * by prefs-api and answers 502.
74
+ */
75
+ readonly serviceKey: string;
76
+ /**
77
+ * The prefs mount people's own rows are read and written on (`http/musicReviewStore.ts`),
78
+ * without `/api/v1`, with the same service key.
79
+ */
80
+ readonly prefsBaseUrl: string;
81
+ /**
82
+ * Where security telemetry is posted (`/health/api/telemetry` under it), with
83
+ * the same service key as the stats. Unset key = telemetry is off (logged once).
84
+ */
85
+ readonly monitoringBaseUrl: string;
86
+ /** Watchparty's origin, whose sprites draw a member's character on a room's link preview (`http/preview.ts`). */
87
+ readonly watchpartyBaseUrl: string;
88
+ /** Every user id this server has admitted, so `caller-first-seen` fires once per account. */
89
+ readonly callersSeenFile: string;
90
+ /** The prefs mount the stats are reported to, without `/api/v1`. */
91
+ readonly statsBaseUrl: string;
92
+ /**
93
+ * ArchiveBot's webhook secret for this app, from the vault via the PM2 wrapper. Prod's wrapper
94
+ * holds it and PPE's does not, which is what keeps release notes a prod-only post. Unset = the
95
+ * boot announcement is skipped (`announce.ts`).
96
+ */
97
+ readonly archivebotSecret: string;
98
+ /** ArchiveBot's webhook server, on loopback beside this one. */
99
+ readonly archivebotUrl: string;
100
+ /** `CARDTABLE_STATE_DIR`, resolved; empty when unset (the in-clone layout). */
101
+ readonly stateDir: string;
102
+ /** Structured access log destination (gitignored, created on boot). */
103
+ readonly logDir: string;
104
+ /**
105
+ * The server's persisted state: the state dir itself when one is set, else
106
+ * `data/` beside the log directory. `data/` is gitignored, so a `git pull`
107
+ * deploy leaves it alone; e2e sets CARDTABLE_LOG_DIR and therefore gets its
108
+ * own directory rather than production's.
109
+ */
110
+ readonly dataDir: string;
111
+ /** Every pod that played a round, kept past its room (`CARDTABLE_TOURNAMENTS_FILE`). */
112
+ readonly tournamentsFile: string;
113
+ /** The front page's scheduled events (`CARDTABLE_EVENTS_FILE`). */
114
+ readonly eventsFile: string;
115
+ /** The lobby's rooms, one file each (`CARDTABLE_ROOMS_DIR`). */
116
+ readonly roomsDir: string;
117
+ /** The sound builder's uploads and assignments (`CARDTABLE_SOUNDS_DIR`). */
118
+ readonly soundsDir: string;
119
+ /**
120
+ * How long a draft bot takes over a pick (`CARDTABLE_DRAFT_BOT_PICK_MS`): every
121
+ * bot holding a pack takes one card per turn. Long enough that bots do not
122
+ * drain a pod into the slowest human's pile at once, short enough that a
123
+ * quick drafter rarely waits on one.
124
+ */
125
+ readonly draftBotPickMs: number;
126
+ /**
127
+ * A CubeCobra draftbot service for the bots' picks (`room/draftbot.ts`), and its
128
+ * `X-Internal-Token`. Unset: no draftbot, every bot pick is the heuristic's.
129
+ */
130
+ readonly draftbotUrl: string;
131
+ readonly draftbotToken: string;
132
+ /** Each draft's state, so a pod survives a restart (`CARDTABLE_DRAFTS_DIR`). */
133
+ readonly draftsDir: string;
134
+ /** A friend's Cube Cobra imports, flat `<id>.json` (`CARDTABLE_CUBES_DIR`). */
135
+ readonly cubesDir: string;
136
+ /** Every match's action log and public stream (`play/recording/`, `CARDTABLE_RECORDINGS_DIR`). */
137
+ readonly recordingsDir: string;
138
+ /** Every game both players walked away from, kept to be resumed (`play/parked.ts`, `CARDTABLE_PARKED_DIR`). */
139
+ readonly parkedDir: string;
140
+ /** The card catalog the pools resolve against (`CARDTABLE_CATALOG`). */
141
+ readonly catalogPath: string;
142
+ /** The art mirror's log (`upload-art`, `CARDTABLE_ART_MIRROR`): which CDN object holds each card image. Missing, every image is Scryfall's. */
143
+ readonly artMirrorPath: string;
144
+ /**
145
+ * `CARDTABLE_NEW_ROOM_FORMAT=newest` pins every new room to the newest
146
+ * Standard era instead of a random one: the e2e harnesses set it, because
147
+ * their specs read a fresh room's pool and a run must not depend on a draw.
148
+ */
149
+ readonly newRoomFormat: string | undefined;
150
+ /**
151
+ * Where Forge matches run (`CARDTABLE_PLAY_HOSTS`): `local`, this machine, as always (the
152
+ * default until the claw acceptance run passes), or `claws`, placed across the hosting claws'
153
+ * agents with this machine as the backstop (`play/placement/`). Anything else is `local`.
154
+ */
155
+ readonly playHosts: "local" | "claws";
156
+ /**
157
+ * The hosting alerts' Discord webhook, from the vault via the PM2 wrapper
158
+ * (`.devvault.json`: `DISCORD_CARDTABLE_ALERT_WEBHOOK`). Unset = alerts are logged, not posted.
159
+ */
160
+ readonly alertWebhook: string;
161
+ /** How long, past the fencing window, the claws' agents hold their JVMs for the next server on a restart. */
162
+ readonly restartGraceMs: number;
163
+ /** The operator's time-boxed force of the backstop host onto the Forge backstop: a JSON file `{"until":"<ISO>"}`. */
164
+ readonly backstopForceFile: string;
165
+ /** `CARDTABLE_PLAY_PROBE=1`: the e2e harness's dev diagnostics — the scenario routes and the frame and stop traces. Never on in production. */
166
+ readonly playProbe: boolean;
167
+ /**
168
+ * `CARDTABLE_PLAY_REJOIN_GRACE_MS`: how long a match nobody is at waits before it is parked
169
+ * (`play/socket.ts`'s `PlayDeps.rejoinGraceMs`). Unset is play's own five minutes; a spec that
170
+ * parks a game sets it shorter. Never set by the deploy path.
171
+ */
172
+ readonly playRejoinGraceMs: number | undefined;
173
+ /**
174
+ * `CARDTABLE_E2E_UNCHECKED_POOLS=1`: the jar-less e2e stack's own escape
175
+ * hatch, wave 73 §A follow-up (CI `check` run 39715510788: a jar-less
176
+ * server can never pass a plan's verdict, so `Lobby.startDraft` refused
177
+ * `plan-not-ready` forever and `draft.spec`'s "two friends draft a whole
178
+ * pod" never dealt).
179
+ *
180
+ * With it, `room/plan.ts`'s `checkCards` answers OK for a source whose
181
+ * cards all resolved (`missingText` still refuses — this is an escape from
182
+ * "no jar", never from "no catalog text") instead of refusing with "Forge
183
+ * is not available". A source checked WITH a jar is unaffected either way:
184
+ * nothing here ever stands in for a real `forge.check`.
185
+ *
186
+ * Nothing in this repo's own deploy path (the PM2 wrapper, the vault
187
+ * broker) ever sets this — `config.test.ts` pins that a config built from
188
+ * a bare `process.env` (nothing set) reads `false`. `e2e/harness.ts` sets
189
+ * it on its OWN jar-less server only (never `e2e/play/harness.ts`'s,
190
+ * which has a real jar and keeps running the real check regardless of
191
+ * this flag). `index.ts` logs a boot warning whenever it reads true, the
192
+ * same register `EDGE_AUTH_SECRET`'s own dev hatch warns at.
193
+ */
194
+ readonly testUncheckedPools: boolean;
195
+ /**
196
+ * `CARDTABLE_E2E_NO_RATE_LIMITS=1`: both e2e stacks' escape from the
197
+ * per-caller limits on making rooms, organizing events and starting matches
198
+ * (`http/request.ts`'s `perCallerLimit`). One test identity makes every room
199
+ * and starts every match of a whole run, far past any limit a person meets.
200
+ * Never set by the deploy path; `config.test.ts` pins it false from a bare
201
+ * environment, and `index.ts` warns at boot whenever it reads true.
202
+ */
203
+ readonly testNoRateLimits: boolean;
204
+ /**
205
+ * `CARDTABLE_E2E_PEOPLE_STAND_IN=1`: look people up (`people.ts`) without a
206
+ * service key, from the e2e edge's prefs-api stand-in at `prefsBaseUrl`. The
207
+ * e2e stacks hold no key, which is what keeps match stats off there, and
208
+ * without this no spec could see a look. Never set by the deploy path.
209
+ */
210
+ readonly testPeopleStandIn: boolean;
211
+ /**
212
+ * `CARDTABLE_CATALOG_REFRESH`: on by default, so production needs no
213
+ * cross-repo change to keep its catalog current with Scryfall's daily
214
+ * bulk file (`pools/refresh.ts`, wave 74 §G). `index.ts` starts the job
215
+ * only when this reads `true`.
216
+ *
217
+ * Off (`'0'`) is for every server that is NOT production: CI's forge-e2e
218
+ * on the claws, every dev/e2e server a session boots, and a lane's own
219
+ * manual smoke-boot. Each of those would otherwise run `createCatalogRefresh`
220
+ * against `CARDTABLE_SCRYFALL_DIR ?? ~/.local/share/cardtable/scryfall` at
221
+ * its own boot — a real Scryfall download, every time, into land.sh's
222
+ * SHARED art cache when the default path is in play (`e2e/harness.ts` and
223
+ * `e2e/play/harness.ts` set this to `'0'` in the server env they spawn,
224
+ * for exactly this reason — one lane's `.partial` file there is what
225
+ * found this).
226
+ */
227
+ readonly catalogRefresh: boolean;
228
+ /**
229
+ * `CARDTABLE_PLAY_SEED`: fixes Forge's shuffles, the coin toss and the precon
230
+ * pick for every match this server starts, or undefined (production) for an
231
+ * unseeded one. Read at each start, not at boot, so a test can set it.
232
+ */
233
+ readonly playSeed: number | undefined;
234
+ /** Container n's noVNC port is this plus n (the static bench publishes 127.0.0.1:6080+n). */
235
+ readonly streamBasePort: number;
236
+ /** The first host port a room's seat stream may take — see `stream/alloc.ts`. */
237
+ readonly roomStreamBasePort: number;
238
+ /** The name every room stream container this server owns starts with; `scripts/stream/container.sh` reads the same variable. */
239
+ readonly streamNamePrefix: string;
240
+ };
241
+ /**
242
+ * Where a Forge match's run directories go (`CARDTABLE_PLAY_WORK_DIR`). Takes the
243
+ * environment as an argument, as `play/host.ts`'s `jvmHostConfig` does, so a test
244
+ * can point one host at its own directory.
245
+ */
246
+ export declare function playWorkDir(env?: NodeJS.ProcessEnv): string;
247
+ export declare const INDEX_HTML: string;