@typeonce/ritmo-devtools 0.13.0 → 0.15.0

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 (92) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +336 -58
  3. package/dist/Desync.d.ts +49 -0
  4. package/dist/Desync.d.ts.map +1 -0
  5. package/dist/Desync.js +51 -0
  6. package/dist/Desync.js.map +1 -0
  7. package/dist/Determinism.d.ts +17 -6
  8. package/dist/Determinism.d.ts.map +1 -1
  9. package/dist/Determinism.js +11 -3
  10. package/dist/Determinism.js.map +1 -1
  11. package/dist/Format.d.ts +43 -8
  12. package/dist/Format.d.ts.map +1 -1
  13. package/dist/Format.js +63 -31
  14. package/dist/Format.js.map +1 -1
  15. package/dist/Fuzz.d.ts +268 -0
  16. package/dist/Fuzz.d.ts.map +1 -0
  17. package/dist/Fuzz.js +355 -0
  18. package/dist/Fuzz.js.map +1 -0
  19. package/dist/Invariant.d.ts +6 -2
  20. package/dist/Invariant.d.ts.map +1 -1
  21. package/dist/Invariant.js.map +1 -1
  22. package/dist/Lint.d.ts +9 -3
  23. package/dist/Lint.d.ts.map +1 -1
  24. package/dist/Lint.js.map +1 -1
  25. package/dist/PlaywrightEngine.d.ts +29 -0
  26. package/dist/PlaywrightEngine.d.ts.map +1 -0
  27. package/dist/PlaywrightEngine.js +193 -0
  28. package/dist/PlaywrightEngine.js.map +1 -0
  29. package/dist/Replay.d.ts +43 -34
  30. package/dist/Replay.d.ts.map +1 -1
  31. package/dist/Replay.js +27 -33
  32. package/dist/Replay.js.map +1 -1
  33. package/dist/Session.d.ts +214 -17
  34. package/dist/Session.d.ts.map +1 -1
  35. package/dist/Session.js +563 -57
  36. package/dist/Session.js.map +1 -1
  37. package/dist/Verify.d.ts +147 -0
  38. package/dist/Verify.d.ts.map +1 -0
  39. package/dist/Verify.js +151 -0
  40. package/dist/Verify.js.map +1 -0
  41. package/dist/cli.js +136 -8
  42. package/dist/cli.js.map +1 -1
  43. package/dist/index.d.ts +4 -2
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +4 -2
  46. package/dist/index.js.map +1 -1
  47. package/dist/internal/dependencyScan.d.ts +44 -0
  48. package/dist/internal/dependencyScan.d.ts.map +1 -0
  49. package/dist/internal/dependencyScan.js +313 -0
  50. package/dist/internal/dependencyScan.js.map +1 -0
  51. package/dist/internal/fuzzNetwork.d.ts +56 -0
  52. package/dist/internal/fuzzNetwork.d.ts.map +1 -0
  53. package/dist/internal/fuzzNetwork.js +96 -0
  54. package/dist/internal/fuzzNetwork.js.map +1 -0
  55. package/dist/internal/values.d.ts +9 -1
  56. package/dist/internal/values.d.ts.map +1 -1
  57. package/dist/internal/values.js +11 -1
  58. package/dist/internal/values.js.map +1 -1
  59. package/dist/internal/verifyRunner.d.ts +19 -0
  60. package/dist/internal/verifyRunner.d.ts.map +1 -0
  61. package/dist/internal/verifyRunner.js +47 -0
  62. package/dist/internal/verifyRunner.js.map +1 -0
  63. package/dist/internal/version.d.ts +1 -1
  64. package/dist/internal/version.js +1 -1
  65. package/package.json +28 -3
  66. package/src/Desync.ts +100 -0
  67. package/src/Determinism.ts +46 -11
  68. package/src/Format.ts +99 -34
  69. package/src/Fuzz.ts +544 -0
  70. package/src/Invariant.ts +6 -2
  71. package/src/Lint.ts +9 -3
  72. package/src/PlaywrightEngine.ts +229 -0
  73. package/src/Replay.ts +98 -74
  74. package/src/Session.ts +806 -72
  75. package/src/Verify.ts +273 -0
  76. package/src/cli.ts +131 -8
  77. package/src/index.ts +4 -2
  78. package/src/internal/dependencyScan.ts +356 -0
  79. package/src/internal/fuzzNetwork.ts +130 -0
  80. package/src/internal/values.ts +20 -1
  81. package/src/internal/verifyRunner.ts +46 -0
  82. package/src/internal/version.ts +1 -1
  83. package/dist/Monitor.d.ts +0 -101
  84. package/dist/Monitor.d.ts.map +0 -1
  85. package/dist/Monitor.js +0 -602
  86. package/dist/Monitor.js.map +0 -1
  87. package/dist/internal/monitor.d.ts +0 -126
  88. package/dist/internal/monitor.d.ts.map +0 -1
  89. package/dist/internal/monitor.js +0 -279
  90. package/dist/internal/monitor.js.map +0 -1
  91. package/src/Monitor.ts +0 -713
  92. package/src/internal/monitor.ts +0 -370
@@ -0,0 +1,229 @@
1
+ /**
2
+ * `Verify.Engine`s for real browsers, in Node: Chromium, WebKit, and
3
+ * Firefox, headless through Playwright. The game's entry is served by a Vite
4
+ * dev server and loaded in each browser beside a small runner, which plays
5
+ * the replay with the entry's `replayTarget` and returns the checksums.
6
+ *
7
+ * `playwright` and `vite` are optional peer dependencies: install them, and
8
+ * the browsers, only where this runs (a CI job, a machine checking a replay):
9
+ *
10
+ * ```sh
11
+ * npm install --save-dev playwright vite
12
+ * npx playwright install chromium webkit firefox
13
+ * ```
14
+ *
15
+ * One that is missing makes each engine fail with `EngineMissing` naming
16
+ * the install command; the others still run.
17
+ *
18
+ * The entry is served by a bare dev server rooted at `root`: imports
19
+ * resolve through `node_modules`, the game's `vite.config` is not read, and
20
+ * it must load in a browser (no Node built-ins).
21
+ *
22
+ * @module PlaywrightEngine
23
+ * @docGroup devtools
24
+ *
25
+ * @example
26
+ * ```ts
27
+ * const browsers = PlaywrightEngine.make({ entry: "src/replay-target.ts", browsers: ["chromium", "webkit", "firefox"] })
28
+ * const verified = await Verify.acrossEngines(replayTarget, file, { engines: browsers.engines })
29
+ * await browsers.close()
30
+ * ```
31
+ */
32
+ import { extname, resolve, sep } from "node:path"
33
+ import { fileURLToPath } from "node:url"
34
+
35
+ import * as Result from "@typeonce/ritmo/Result"
36
+ import type * as Snapshot from "@typeonce/ritmo/Snapshot"
37
+
38
+ import type { Runner } from "./internal/verifyRunner.ts"
39
+ import type * as Replay from "./Replay.ts"
40
+ import type * as Verify from "./Verify.ts"
41
+
42
+ /** A browser engine Playwright runs. */
43
+ export type Browser = "chromium" | "webkit" | "firefox"
44
+
45
+ /** Every browser engine, in report order. */
46
+ export const browsers: ReadonlyArray<Browser> = ["chromium", "webkit", "firefox"]
47
+
48
+ /** Whether `name` is a browser engine Playwright runs (for parsing a command line). */
49
+ export const isBrowser = (name: string): name is Browser => (browsers as ReadonlyArray<string>).includes(name)
50
+
51
+ /** Which entry to load, and in which browsers. */
52
+ export interface Options {
53
+ /** The module exporting `replayTarget`, the `make(playback)` factory `Replay.session` takes. */
54
+ readonly entry: string
55
+ readonly browsers: ReadonlyArray<Browser>
56
+ /** The dev server's root: where `node_modules` is found. Defaults to the working directory. */
57
+ readonly root?: string
58
+ }
59
+
60
+ /** The browser engines, and how to stop them. */
61
+ export interface Engines {
62
+ /** One `Verify.Engine` per browser, in `options.browsers` order: pass them to `Verify.acrossEngines`. */
63
+ readonly engines: ReadonlyArray<Verify.Engine>
64
+ /** Closes the browsers and the dev server. Call it when the check is done. */
65
+ readonly close: () => Promise<void>
66
+ }
67
+
68
+ interface Page {
69
+ readonly evaluate: <R, A>(run: (argument: A) => R | Promise<R>, argument: A) => Promise<R>
70
+ }
71
+
72
+ interface Server {
73
+ readonly url: string
74
+ readonly close: () => Promise<void>
75
+ }
76
+
77
+ type Failed = Omit<Verify.EngineMissing, "engine"> | Omit<Verify.EngineFailed, "engine">
78
+
79
+ const missing = (reason: string, install: string): Failed => ({ _tag: "EngineMissing", reason, install })
80
+ const failed = (message: string): Failed => ({ _tag: "EngineFailed", message })
81
+ const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error)
82
+
83
+ /** A path as a dev server URL path: `/@fs/` and the absolute path, with forward slashes. */
84
+ const fsPath = (path: string): string => `/@fs/${path.split(sep).join("/").replace(/^\/+/, "")}`
85
+
86
+ /** The page side, beside this file: `.ts` in the workspace, `.js` once built. */
87
+ const runnerPath = (): string => {
88
+ const self = fileURLToPath(import.meta.url)
89
+ return fileURLToPath(new URL(`./internal/verifyRunner${extname(self)}`, import.meta.url))
90
+ }
91
+
92
+ /**
93
+ * The browser engines for `options.entry`. Nothing starts until an engine
94
+ * is first used: the dev server once, each browser on its own engine's first
95
+ * `trace`.
96
+ */
97
+ export const make = (options: Options): Engines => {
98
+ const root = resolve(options.root ?? ".")
99
+ const entry = resolve(root, options.entry)
100
+ let server: Promise<Result.Result<Server, Failed>> | undefined
101
+ const pages = new Map<Browser, Promise<Result.Result<Page, Failed>>>()
102
+ const closers: Array<() => Promise<void>> = []
103
+
104
+ const startServer = async (): Promise<Result.Result<Server, Failed>> => {
105
+ let vite: typeof import("vite")
106
+ try {
107
+ vite = await import("vite")
108
+ } catch {
109
+ return Result.failure(missing("vite is not installed", "npm install --save-dev vite"))
110
+ }
111
+ const html = [
112
+ "<!doctype html><meta charset=\"utf-8\"><title>ritmo verify</title>",
113
+ "<script type=\"module\">",
114
+ `import { start } from ${JSON.stringify(fsPath(runnerPath()))}`,
115
+ `globalThis.__ritmoVerify = start(${JSON.stringify(fsPath(entry))})`,
116
+ "</script>"
117
+ ].join("\n")
118
+ try {
119
+ const dev = await vite.createServer({
120
+ root,
121
+ configFile: false,
122
+ logLevel: "silent",
123
+ clearScreen: false,
124
+ appType: "custom",
125
+ server: { host: "127.0.0.1", port: 0, hmr: false, watch: null, fs: { strict: false } },
126
+ // Discovery would optimize dependencies mid-run and reload the page.
127
+ optimizeDeps: { noDiscovery: true, include: [] },
128
+ plugins: [{
129
+ name: "ritmo-verify",
130
+ configureServer: (dev) => {
131
+ dev.middlewares.use("/__ritmo-verify", (_request, response) => {
132
+ response.setHeader("content-type", "text/html")
133
+ response.end(html)
134
+ })
135
+ }
136
+ }]
137
+ })
138
+ await dev.listen()
139
+ const address = dev.httpServer?.address()
140
+ if (address === null || address === undefined || typeof address === "string") {
141
+ await dev.close()
142
+ return Result.failure(failed("the Vite dev server did not report its port"))
143
+ }
144
+ return Result.success({ url: `http://127.0.0.1:${address.port}/__ritmo-verify`, close: () => dev.close() })
145
+ } catch (error) {
146
+ return Result.failure(failed(`the Vite dev server did not start: ${messageOf(error)}`))
147
+ }
148
+ }
149
+
150
+ const openPage = async (browser: Browser): Promise<Result.Result<Page, Failed>> => {
151
+ let playwright: typeof import("playwright")
152
+ try {
153
+ playwright = await import("playwright")
154
+ } catch {
155
+ return Result.failure(missing("playwright is not installed", `npm install --save-dev playwright && npx playwright install ${browser}`))
156
+ }
157
+ server ??= startServer()
158
+ const served = await server
159
+ if (!served.ok) return served
160
+ let launched: Awaited<ReturnType<typeof playwright.chromium.launch>>
161
+ try {
162
+ launched = await playwright[browser].launch()
163
+ } catch (error) {
164
+ const message = messageOf(error)
165
+ return Result.failure(/Executable doesn't exist|playwright install/i.test(message)
166
+ ? missing(`the ${browser} browser is not downloaded`, `npx playwright install ${browser}`)
167
+ : failed(`${browser} did not launch: ${message}`))
168
+ }
169
+ closers.push(() => launched.close())
170
+ try {
171
+ const page = await launched.newPage()
172
+ const errors: Array<string> = []
173
+ page.on("pageerror", (error) => errors.push(error.message))
174
+ await page.goto(served.value.url)
175
+ const started = await page.evaluate(async () => {
176
+ const result = await (Reflect.get(globalThis, "__ritmoVerify") as Promise<Result.Result<unknown, string>> | undefined)
177
+ if (result === undefined) return "the runner did not start"
178
+ if (!result.ok) return result.error
179
+ Reflect.set(globalThis, "__ritmoRunner", result.value)
180
+ return undefined
181
+ })
182
+ if (started !== undefined) return Result.failure(failed([started, ...errors].join("\n")))
183
+ return Result.success(page)
184
+ } catch (error) {
185
+ return Result.failure(failed(`the page did not load: ${messageOf(error)}`))
186
+ }
187
+ }
188
+
189
+ const engine = (browser: Browser): Verify.Engine => {
190
+ const page = () => {
191
+ let opened = pages.get(browser)
192
+ if (opened === undefined) {
193
+ opened = openPage(browser)
194
+ pages.set(browser, opened)
195
+ }
196
+ return opened
197
+ }
198
+ const call = async <A>(run: (page: Page) => Promise<Result.Result<A, string>>): Promise<Result.Result<A, Verify.EngineError>> => {
199
+ const opened = await page()
200
+ if (!opened.ok) return Result.failure({ ...opened.error, engine: browser })
201
+ try {
202
+ const result = await run(opened.value)
203
+ return result.ok ? result : Result.failure({ _tag: "EngineFailed", engine: browser, message: result.error })
204
+ } catch (error) {
205
+ return Result.failure({ _tag: "EngineFailed", engine: browser, message: messageOf(error) })
206
+ }
207
+ }
208
+ // These functions are sent to the page as source and run there: they reach only the page's globals.
209
+ // What crosses is the replay file in, and plain results out.
210
+ return {
211
+ name: browser,
212
+ trace: (file) => call((opened) => opened.evaluate((input: Replay.ReplayFile) =>
213
+ (Reflect.get(globalThis, "__ritmoRunner") as Runner).trace(input), file)),
214
+ snapshotAt: (file, tick) => call<Snapshot.WorldSnapshot>((opened) => opened.evaluate((input: { readonly file: Replay.ReplayFile; readonly tick: number }) =>
215
+ (Reflect.get(globalThis, "__ritmoRunner") as Runner).snapshotAt(input.file, input.tick), { file, tick }))
216
+ }
217
+ }
218
+
219
+ return {
220
+ engines: options.browsers.map(engine),
221
+ close: async () => {
222
+ await Promise.all(closers.splice(0).map((close) => close().catch(() => undefined)))
223
+ const started = await server
224
+ server = undefined
225
+ pages.clear()
226
+ if (started?.ok === true) await started.value.close()
227
+ }
228
+ }
229
+ }
package/src/Replay.ts CHANGED
@@ -4,7 +4,8 @@
4
4
  *
5
5
  * A replay is a debug artifact, not a long-term test: open it, find the bug
6
6
  * with `why` / `journal`, `extract` the few ticks that show it into a test,
7
- * then delete the replay.
7
+ * then delete the replay. `Fuzz.run` writes one too: the shrunk input that
8
+ * breaks an invariant, ready to become that test.
8
9
  *
9
10
  * - `recorder(runtime, options)` keeps a rolling window of one schedule's
10
11
  * ticks: periodic world snapshots (so the window has a start), what each
@@ -12,8 +13,8 @@
12
13
  * (stored as changes from the previous tick), and every `runtime.send`.
13
14
  * Time and randomness live in the world, so that is everything the
14
15
  * simulation reads. `save(reason)` hands the file to a `Sink`.
15
- * - `session(make, file)` restores the start and replays the ticks in a
16
- * normal devtools `Session`; `verify` replays twice and compares the
16
+ * - `session(make, file, { invariants })` restores the start and replays
17
+ * the ticks in a normal devtools `Session`; `verify` replays twice and compares the
17
18
  * checkpoint hashes to find nondeterminism; `extract` cuts a range of
18
19
  * ticks into a small replay with its own start, for a test.
19
20
  *
@@ -48,9 +49,10 @@
48
49
  import type { Clock, HostClock } from "@typeonce/ritmo"
49
50
  import type * as Debug from "@typeonce/ritmo/Debug"
50
51
  import type { Descriptor } from "@typeonce/ritmo/Descriptor"
52
+ import type * as Inspector from "@typeonce/ritmo/Inspector"
51
53
  import type * as Requirement from "@typeonce/ritmo/Requirement"
52
54
  import * as Result from "@typeonce/ritmo/Result"
53
- import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
55
+ import type { AnyScheduleOrder, ExecutableScheduleDefinition, IsPlain, Source } from "@typeonce/ritmo/Schedule"
54
56
  import type { Schema } from "@typeonce/ritmo/Schema"
55
57
  import type * as Snapshot from "@typeonce/ritmo/Snapshot"
56
58
 
@@ -65,29 +67,6 @@ type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, a
65
67
  /** The `@typeonce/ritmo-devtools` version written into replay files. */
66
68
  export const version = libraryVersion
67
69
 
68
- /** An input service: one value per call, such as a keyboard's actions this step. */
69
- export interface Source<Data> {
70
- readonly snapshot: () => Data
71
- }
72
-
73
- /**
74
- * Whether a type is plain data (what JSON keeps): no functions, maps, sets,
75
- * or class instances with methods. Recursive types are checked once.
76
- */
77
- export type IsPlain<T> = false extends PlainMember<T, never> ? false : true
78
-
79
- // Checks one member of a union at a time (the conditional distributes), so a
80
- // recursive type is recognised when it comes back (`Seen`).
81
- type PlainMember<T, Seen> =
82
- T extends string | number | boolean | null | undefined ? true
83
- : [T] extends [Seen] ? true
84
- : T extends (...args: ReadonlyArray<never>) => unknown ? false
85
- : T extends ReadonlyArray<infer Element> ? PlainMember<Element, Seen | T>
86
- : T extends object ? PlainField<T, keyof T, Seen | T>
87
- : false
88
-
89
- type PlainField<T, K extends keyof T, Seen> = K extends keyof T ? PlainMember<T[K], Seen> : never
90
-
91
70
  type ServiceNeeds<Schedule> = Extract<Requirement.Of<Schedule>, Descriptor<"service", string, any>>
92
71
 
93
72
  type UnrecordableService<Need> =
@@ -161,6 +140,7 @@ export const memorySink = (): Sink & { readonly files: ReadonlyArray<ReplayFile>
161
140
  export interface Recordable<S extends Schema.Any, Root> {
162
141
  readonly debug: Debug.Handle<S, Root>
163
142
  readonly snapshot: () => Result.Result<Snapshot.WorldSnapshot, Snapshot.SnapshotError>
143
+ readonly checksum: () => Result.Result<string, Snapshot.SnapshotError>
164
144
  readonly services: Readonly<Record<string, unknown>>
165
145
  readonly inspect: (inspector: never) => unknown
166
146
  }
@@ -202,7 +182,7 @@ export interface Recorder {
202
182
  readonly stop: () => void
203
183
  }
204
184
 
205
- /** FNV-1a over a string, as 8 hex digits: a cheap fingerprint for checkpoints and schemas. */
185
+ /** FNV-1a over a string, as 8 hex digits: a cheap fingerprint for schemas and encode failures. */
206
186
  const fingerprint = (text: string): string => {
207
187
  let hash = 0x811c9dc5
208
188
  for (let index = 0; index < text.length; index++) {
@@ -224,9 +204,10 @@ export const schemaHash = <S extends Schema.Any, Root>(debug: Debug.Handle<S, Ro
224
204
  }))
225
205
  }
226
206
 
227
- // A world that cannot be saved hashes its encode failure, so a replay that reaches it diverges visibly.
228
- const worldHash = (snapshot: Result.Result<Snapshot.WorldSnapshot, Snapshot.SnapshotError>): string =>
229
- fingerprint(JSON.stringify(snapshot.ok ? snapshot.value : snapshot.error))
207
+ // The world's `runtime.checksum()`. A world that cannot be saved hashes its
208
+ // encode failure, so a replay that reaches it diverges visibly.
209
+ const worldHash = (checksum: Result.Result<string, Snapshot.SnapshotError>): string =>
210
+ checksum.ok ? checksum.value : fingerprint(JSON.stringify(checksum.error))
230
211
 
231
212
  const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null
232
213
 
@@ -281,10 +262,10 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
281
262
 
282
263
  const takePoint = () => {
283
264
  const snapshot = runtime.snapshot()
284
- // A tick whose world an `encode` rejects is no starting point; the window keeps the previous one.
265
+ // A tick whose world a `"~encode"` rejects is no starting point; the window keeps the previous one.
285
266
  if (!snapshot.ok) return
286
267
  points.push({ tick, snapshot: snapshot.value, pendingCommands: runtime.debug.dump({ limit: 0 }).pendingCommands.length })
287
- checkpoints.push({ tick, hash: worldHash(snapshot) })
268
+ checkpoints.push({ tick, hash: worldHash(runtime.checksum()) })
288
269
  const windowStart = tick - keepTicks
289
270
  let firstNeeded = -1
290
271
  for (let index = 0; index < points.length; index++) if (points[index]!.tick <= windowStart) firstNeeded = index
@@ -308,7 +289,7 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
308
289
 
309
290
  const save = (reason: string): ReplayFile => {
310
291
  const start = points[0]
311
- if (start === undefined) throw new Error("no tick of this run could be saved: an `encode` rejected the world every time (see runtime.snapshot())")
292
+ if (start === undefined) throw new Error("no tick of this run could be saved: a `~encode` rejected the world every time (see runtime.snapshot())")
312
293
  const file: ReplayFile = {
313
294
  format: "ritmo-replay",
314
295
  version: 1,
@@ -414,13 +395,32 @@ export const parse = (data: unknown): Result.Result<ReplayFile, ReplayError> =>
414
395
  return Result.success(data as unknown as ReplayFile)
415
396
  }
416
397
 
398
+ /** What a `snapshot()` source service returns: the data a replay records and a fuzzed input generates. */
399
+ export type SourceData<Value extends Source<unknown>> = ReturnType<Value["snapshot"]>
400
+
401
+ /**
402
+ * Rejects a source service a plain recorded source could not stand in for:
403
+ * one declared as the whole device, with more than `snapshot()` (`rebind`,
404
+ * `dispose`). Resolves to `unknown` for a `snapshot()`-only source.
405
+ */
406
+ export type ValidateSource<Name extends string, Value extends Source<unknown>> =
407
+ Source<SourceData<Value>> extends Value
408
+ ? unknown
409
+ : `${Name} has more than snapshot(), so a replay cannot provide it: declare the service as only its snapshot() source (InputCapture.SourceOf<typeof device> for browser input), and keep the device in the host`
410
+
417
411
  /**
418
412
  * What a replay hands the game's `make` function: the recorded input, as
419
413
  * sources to provide in place of the live ones, and the recorded constants.
420
414
  */
421
415
  export interface Playback {
422
- /** A source returning, call by call, what the recorded one returned at the current tick. */
423
- readonly source: <const Name extends string, Data>(descriptor: Descriptor<"service", Name, Source<Data>>) => Source<Data>
416
+ /**
417
+ * A source returning, call by call, what the recorded one returned at the
418
+ * current tick. `descriptor` is a `snapshot()`-only source service
419
+ * (`Schedule.Source`, `InputCapture.SourceOf<...>`, `Netcode.Source`).
420
+ */
421
+ readonly source: <const Name extends string, Value extends Source<unknown>>(
422
+ descriptor: Descriptor<"service", Name, Value> & ValidateSource<Name, Value>
423
+ ) => Source<SourceData<Value>>
424
424
  /** A constant service's recorded value (`undefined` if it was not recorded). */
425
425
  readonly constant: <const Name extends string, Value>(descriptor: Descriptor<"service", Name, Value>) => unknown
426
426
  }
@@ -431,14 +431,37 @@ export interface Playback {
431
431
  * name, and the clock the replay session times runs with
432
432
  * (`HostClock.test()` for identical text output).
433
433
  */
434
- export interface Target<S extends Schema.Any, Root> {
434
+ export interface Target<
435
+ S extends Schema.Any,
436
+ Root,
437
+ Schedules extends Readonly<Record<string, AnySchedule<S, Root>>> = Readonly<Record<string, AnySchedule<S, Root>>>,
438
+ Services extends Record<string, unknown> = Record<string, unknown>,
439
+ Resources extends object = object,
440
+ Machines extends Record<string, unknown> = Record<string, unknown>
441
+ > {
435
442
  readonly hostClock: HostClock.HostClock
436
- readonly runtime: Session.Target<S, Root> & {
443
+ readonly runtime: Session.Target<S, Root, Services, Resources, Machines> & {
437
444
  readonly snapshot: () => Result.Result<Snapshot.WorldSnapshot, Snapshot.SnapshotError>
445
+ readonly checksum: () => Result.Result<string, Snapshot.SnapshotError>
438
446
  readonly restore: (data: unknown) => Result.Result<void, Snapshot.RestoreError>
439
447
  readonly send: (descriptor: never, value: never) => void
440
448
  }
441
- readonly schedules: Readonly<Record<string, AnySchedule<S, Root>>>
449
+ readonly schedules: Schedules
450
+ }
451
+
452
+ /** How `session` checks the replayed ticks and names what they touch. */
453
+ export interface SessionOptions<
454
+ Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [],
455
+ Labels extends Session.LabelsInspector = never
456
+ > {
457
+ /**
458
+ * Checked after every replayed tick, as in `Session.make`: `play` stops at
459
+ * the first violation. Pass the invariants a `Fuzz.run` found broken, so
460
+ * the replay stops where the bug shows.
461
+ */
462
+ readonly invariants?: Invariants
463
+ /** Names entities in the session's text, as `Session.make`'s `labels` does. */
464
+ readonly labels?: Labels
442
465
  }
443
466
 
444
467
  /** What one `ReplaySession.play` did: the session run, and the checkpoints that differ. */
@@ -458,17 +481,34 @@ export interface ReplaySession<S extends Schema.Any, Names extends string> {
458
481
  readonly play: (options?: { readonly to?: number }) => Rendered.Rendered<PlayResult>
459
482
  /** Hashes of the world at the end of each replayed tick so far. */
460
483
  readonly hashes: () => ReadonlyMap<number, string>
461
- /** The world as plain data now, or the value an `encode` rejected. */
484
+ /** The world as plain data now, or the value a `"~encode"` rejected. */
462
485
  readonly snapshot: () => Result.Result<Snapshot.WorldSnapshot, Snapshot.SnapshotError>
463
486
  }
464
487
 
488
+
465
489
  /**
466
490
  * Opens a replay: builds the game with `make(playback)`, checks the schema,
467
- * restores the start, and returns a session ready to `play`.
491
+ * restores the start, and returns a session ready to `play`, checking
492
+ * `options.invariants` after every tick and naming entities with
493
+ * `options.labels`, as `Session.make` does. An invariant or a labels
494
+ * inspector that reads something the runtime does not provide does not
495
+ * compile.
468
496
  */
469
- export const session = <S extends Schema.Any, Root>(
470
- make: (playback: Playback) => Target<S, Root>,
471
- file: ReplayFile
497
+ export const session = <
498
+ S extends Schema.Any,
499
+ Root,
500
+ Schedules extends Readonly<Record<string, AnySchedule<S, Root>>>,
501
+ Services extends Record<string, unknown>,
502
+ Resources extends object,
503
+ Machines extends Record<string, unknown>,
504
+ const Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [],
505
+ const Labels extends Session.LabelsInspector<Root> = never
506
+ >(
507
+ make: (playback: Playback) => Target<S, Root, Schedules, Services, Resources, Machines>,
508
+ file: ReplayFile,
509
+ options?: SessionOptions<Invariants, Labels> &
510
+ Session.ValidateInvariants<Invariants, Services, Resources, Machines> &
511
+ Session.ValidateLabels<Labels, Services, Resources, Machines>
472
512
  ): Result.Result<ReplaySession<S, string>, ReplayError> => {
473
513
  /** The last tick replayed (the start's tick before any). */
474
514
  let ran = file.start.tick
@@ -488,7 +528,8 @@ export const session = <S extends Schema.Any, Root>(
488
528
  constant: (descriptor) => file.constants[descriptor.name]
489
529
  }
490
530
  const target = make(playback)
491
- const schedule = target.schedules[file.schedule]
531
+ const schedules: Readonly<Record<string, AnySchedule<S, Root> | undefined>> = target.schedules
532
+ const schedule = schedules[file.schedule]
492
533
  if (schedule === undefined) return Result.failure({ _tag: "MissingSchedule", schedule: file.schedule })
493
534
  const current = schemaHash(target.runtime.debug)
494
535
  if (current !== file.schema) {
@@ -496,10 +537,19 @@ export const session = <S extends Schema.Any, Root>(
496
537
  }
497
538
  const restored = target.runtime.restore(file.start.snapshot)
498
539
  if (!restored.ok) return Result.failure({ _tag: "RestoreFailed", error: restored.error })
499
- const replay = Session.make(target.runtime, { schedules: { [file.schedule]: schedule }, hostClock: target.hostClock })
540
+ const runtime: Session.Target<S, Root> = target.runtime
541
+ // The signature checked the invariants and the labels against this runtime's provisions.
542
+ const invariants = (options?.invariants ?? []) as readonly []
543
+ const labels = options?.labels as Inspector.InspectorDefinition<any, ReadonlyMap<number, string>, Root, any, never> | undefined
544
+ const replay = Session.make(runtime, {
545
+ schedules: { [file.schedule]: schedule },
546
+ hostClock: target.hostClock,
547
+ invariants,
548
+ ...(labels === undefined ? {} : { labels })
549
+ })
500
550
  const send = target.runtime.send as (descriptor: { readonly kind: "event"; readonly name: string; readonly key: symbol }, value: unknown) => void
501
551
  const events = new Map(target.runtime.debug.describe().events.map(({ name }) => [name, { kind: "event" as const, name, key: Symbol.for(`ritmo/event/${name}`) }]))
502
- const hashes = new Map<number, string>([[ran, worldHash(target.runtime.snapshot())]])
552
+ const hashes = new Map<number, string>([[ran, worldHash(target.runtime.checksum())]])
503
553
  const recorded = new Map(file.checkpoints.map(({ tick, hash }) => [tick, hash] as const))
504
554
  const last = file.ticks.at(-1)?.tick ?? file.start.tick
505
555
 
@@ -512,7 +562,7 @@ export const session = <S extends Schema.Any, Root>(
512
562
  // `until` runs after each frame: the tick is checked, and the next one's input set up before it runs.
513
563
  until: () => {
514
564
  ran += 1
515
- const hash = worldHash(target.runtime.snapshot())
565
+ const hash = worldHash(target.runtime.checksum())
516
566
  hashes.set(ran, hash)
517
567
  const expected = recorded.get(ran)
518
568
  if (expected !== undefined && expected !== hash) diverged.push({ tick: ran, recorded: expected, replayed: hash })
@@ -546,32 +596,6 @@ export const session = <S extends Schema.Any, Root>(
546
596
  })
547
597
  }
548
598
 
549
- /**
550
- * Replays twice and compares the world after every tick: different hashes
551
- * mean the simulation reads something the replay does not hold (wall time,
552
- * `Math.random`, host state).
553
- */
554
- export const verify = <S extends Schema.Any, Root>(
555
- make: (playback: Playback) => Target<S, Root>,
556
- file: ReplayFile
557
- ): Result.Result<Rendered.Rendered<{ readonly deterministic: boolean; readonly firstDifference: number | undefined; readonly diverged: PlayResult["diverged"] }>, ReplayError> => {
558
- const first = session(make, file)
559
- if (!first.ok) return first
560
- const second = session(make, file)
561
- if (!second.ok) return second
562
- const played = first.value.play()
563
- second.value.play()
564
- const ticks = [...first.value.hashes().keys()].sort((left, right) => left - right)
565
- const firstDifference = ticks.find((tick) => first.value.hashes().get(tick) !== second.value.hashes().get(tick))
566
- const deterministic = firstDifference === undefined
567
- return Result.success(Rendered.make(
568
- { deterministic, firstDifference, diverged: played.data.diverged },
569
- deterministic
570
- ? `deterministic over ${ticks.length - 1} ticks${played.data.diverged.length === 0 ? ", and matches the recording" : `, but differs from the recording at tick ${played.data.diverged[0]!.tick}`}`
571
- : `NOT deterministic: two replays differ from tick ${firstDifference}`
572
- ))
573
- }
574
-
575
599
  /**
576
600
  * Cuts ticks `from`..`to` (recorder tick numbers) into a smaller replay that
577
601
  * starts at the end of tick `from - 1`: few enough ticks to keep next to a