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