@typeonce/ritmo-devtools 0.14.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.
- package/CHANGELOG.md +241 -0
- package/README.md +296 -55
- package/dist/Desync.d.ts +17 -3
- package/dist/Desync.d.ts.map +1 -1
- package/dist/Desync.js +17 -15
- package/dist/Desync.js.map +1 -1
- package/dist/Determinism.d.ts +17 -6
- package/dist/Determinism.d.ts.map +1 -1
- package/dist/Determinism.js +11 -3
- package/dist/Determinism.js.map +1 -1
- package/dist/Format.d.ts +43 -8
- package/dist/Format.d.ts.map +1 -1
- package/dist/Format.js +63 -31
- package/dist/Format.js.map +1 -1
- package/dist/Fuzz.d.ts +268 -0
- package/dist/Fuzz.d.ts.map +1 -0
- package/dist/Fuzz.js +355 -0
- package/dist/Fuzz.js.map +1 -0
- package/dist/Invariant.d.ts +6 -2
- package/dist/Invariant.d.ts.map +1 -1
- package/dist/Invariant.js.map +1 -1
- package/dist/PlaywrightEngine.d.ts +29 -0
- package/dist/PlaywrightEngine.d.ts.map +1 -0
- package/dist/PlaywrightEngine.js +193 -0
- package/dist/PlaywrightEngine.js.map +1 -0
- package/dist/Replay.d.ts +40 -22
- package/dist/Replay.d.ts.map +1 -1
- package/dist/Replay.js +20 -27
- package/dist/Replay.js.map +1 -1
- package/dist/Session.d.ts +214 -17
- package/dist/Session.d.ts.map +1 -1
- package/dist/Session.js +563 -57
- package/dist/Session.js.map +1 -1
- package/dist/Verify.d.ts +147 -0
- package/dist/Verify.d.ts.map +1 -0
- package/dist/Verify.js +151 -0
- package/dist/Verify.js.map +1 -0
- package/dist/cli.js +136 -8
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -2
- package/dist/index.js.map +1 -1
- package/dist/internal/dependencyScan.d.ts +44 -0
- package/dist/internal/dependencyScan.d.ts.map +1 -0
- package/dist/internal/dependencyScan.js +313 -0
- package/dist/internal/dependencyScan.js.map +1 -0
- package/dist/internal/fuzzNetwork.d.ts +56 -0
- package/dist/internal/fuzzNetwork.d.ts.map +1 -0
- package/dist/internal/fuzzNetwork.js +96 -0
- package/dist/internal/fuzzNetwork.js.map +1 -0
- package/dist/internal/values.d.ts +9 -1
- package/dist/internal/values.d.ts.map +1 -1
- package/dist/internal/values.js +11 -1
- package/dist/internal/values.js.map +1 -1
- package/dist/internal/verifyRunner.d.ts +19 -0
- package/dist/internal/verifyRunner.d.ts.map +1 -0
- package/dist/internal/verifyRunner.js +47 -0
- package/dist/internal/verifyRunner.js.map +1 -0
- package/dist/internal/version.d.ts +1 -1
- package/dist/internal/version.js +1 -1
- package/package.json +28 -3
- package/src/Desync.ts +34 -17
- package/src/Determinism.ts +46 -11
- package/src/Format.ts +99 -34
- package/src/Fuzz.ts +544 -0
- package/src/Invariant.ts +6 -2
- package/src/PlaywrightEngine.ts +229 -0
- package/src/Replay.ts +87 -43
- package/src/Session.ts +806 -72
- package/src/Verify.ts +273 -0
- package/src/cli.ts +131 -8
- package/src/index.ts +3 -2
- package/src/internal/dependencyScan.ts +356 -0
- package/src/internal/fuzzNetwork.ts +130 -0
- package/src/internal/values.ts +20 -1
- package/src/internal/verifyRunner.ts +46 -0
- package/src/internal/version.ts +1 -1
- package/dist/Monitor.d.ts +0 -101
- package/dist/Monitor.d.ts.map +0 -1
- package/dist/Monitor.js +0 -602
- package/dist/Monitor.js.map +0 -1
- package/dist/internal/monitor.d.ts +0 -126
- package/dist/internal/monitor.d.ts.map +0 -1
- package/dist/internal/monitor.js +0 -279
- package/dist/internal/monitor.js.map +0 -1
- package/src/Monitor.ts +0 -713
- 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
|
|
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,6 +49,7 @@
|
|
|
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
55
|
import type { AnyScheduleOrder, ExecutableScheduleDefinition, IsPlain, Source } from "@typeonce/ritmo/Schedule"
|
|
@@ -260,7 +262,7 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
|
|
|
260
262
|
|
|
261
263
|
const takePoint = () => {
|
|
262
264
|
const snapshot = runtime.snapshot()
|
|
263
|
-
// A tick whose world
|
|
265
|
+
// A tick whose world a `"~encode"` rejects is no starting point; the window keeps the previous one.
|
|
264
266
|
if (!snapshot.ok) return
|
|
265
267
|
points.push({ tick, snapshot: snapshot.value, pendingCommands: runtime.debug.dump({ limit: 0 }).pendingCommands.length })
|
|
266
268
|
checkpoints.push({ tick, hash: worldHash(runtime.checksum()) })
|
|
@@ -287,7 +289,7 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
|
|
|
287
289
|
|
|
288
290
|
const save = (reason: string): ReplayFile => {
|
|
289
291
|
const start = points[0]
|
|
290
|
-
if (start === undefined) throw new Error("no tick of this run could be saved:
|
|
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())")
|
|
291
293
|
const file: ReplayFile = {
|
|
292
294
|
format: "ritmo-replay",
|
|
293
295
|
version: 1,
|
|
@@ -393,13 +395,32 @@ export const parse = (data: unknown): Result.Result<ReplayFile, ReplayError> =>
|
|
|
393
395
|
return Result.success(data as unknown as ReplayFile)
|
|
394
396
|
}
|
|
395
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
|
+
|
|
396
411
|
/**
|
|
397
412
|
* What a replay hands the game's `make` function: the recorded input, as
|
|
398
413
|
* sources to provide in place of the live ones, and the recorded constants.
|
|
399
414
|
*/
|
|
400
415
|
export interface Playback {
|
|
401
|
-
/**
|
|
402
|
-
|
|
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>>
|
|
403
424
|
/** A constant service's recorded value (`undefined` if it was not recorded). */
|
|
404
425
|
readonly constant: <const Name extends string, Value>(descriptor: Descriptor<"service", Name, Value>) => unknown
|
|
405
426
|
}
|
|
@@ -410,15 +431,37 @@ export interface Playback {
|
|
|
410
431
|
* name, and the clock the replay session times runs with
|
|
411
432
|
* (`HostClock.test()` for identical text output).
|
|
412
433
|
*/
|
|
413
|
-
export interface Target<
|
|
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
|
+
> {
|
|
414
442
|
readonly hostClock: HostClock.HostClock
|
|
415
|
-
readonly runtime: Session.Target<S, Root> & {
|
|
443
|
+
readonly runtime: Session.Target<S, Root, Services, Resources, Machines> & {
|
|
416
444
|
readonly snapshot: () => Result.Result<Snapshot.WorldSnapshot, Snapshot.SnapshotError>
|
|
417
445
|
readonly checksum: () => Result.Result<string, Snapshot.SnapshotError>
|
|
418
446
|
readonly restore: (data: unknown) => Result.Result<void, Snapshot.RestoreError>
|
|
419
447
|
readonly send: (descriptor: never, value: never) => void
|
|
420
448
|
}
|
|
421
|
-
readonly schedules:
|
|
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
|
|
422
465
|
}
|
|
423
466
|
|
|
424
467
|
/** What one `ReplaySession.play` did: the session run, and the checkpoints that differ. */
|
|
@@ -438,17 +481,34 @@ export interface ReplaySession<S extends Schema.Any, Names extends string> {
|
|
|
438
481
|
readonly play: (options?: { readonly to?: number }) => Rendered.Rendered<PlayResult>
|
|
439
482
|
/** Hashes of the world at the end of each replayed tick so far. */
|
|
440
483
|
readonly hashes: () => ReadonlyMap<number, string>
|
|
441
|
-
/** The world as plain data now, or the value
|
|
484
|
+
/** The world as plain data now, or the value a `"~encode"` rejected. */
|
|
442
485
|
readonly snapshot: () => Result.Result<Snapshot.WorldSnapshot, Snapshot.SnapshotError>
|
|
443
486
|
}
|
|
444
487
|
|
|
488
|
+
|
|
445
489
|
/**
|
|
446
490
|
* Opens a replay: builds the game with `make(playback)`, checks the schema,
|
|
447
|
-
* 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.
|
|
448
496
|
*/
|
|
449
|
-
export const session = <
|
|
450
|
-
|
|
451
|
-
|
|
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>
|
|
452
512
|
): Result.Result<ReplaySession<S, string>, ReplayError> => {
|
|
453
513
|
/** The last tick replayed (the start's tick before any). */
|
|
454
514
|
let ran = file.start.tick
|
|
@@ -468,7 +528,8 @@ export const session = <S extends Schema.Any, Root>(
|
|
|
468
528
|
constant: (descriptor) => file.constants[descriptor.name]
|
|
469
529
|
}
|
|
470
530
|
const target = make(playback)
|
|
471
|
-
const
|
|
531
|
+
const schedules: Readonly<Record<string, AnySchedule<S, Root> | undefined>> = target.schedules
|
|
532
|
+
const schedule = schedules[file.schedule]
|
|
472
533
|
if (schedule === undefined) return Result.failure({ _tag: "MissingSchedule", schedule: file.schedule })
|
|
473
534
|
const current = schemaHash(target.runtime.debug)
|
|
474
535
|
if (current !== file.schema) {
|
|
@@ -476,7 +537,16 @@ export const session = <S extends Schema.Any, Root>(
|
|
|
476
537
|
}
|
|
477
538
|
const restored = target.runtime.restore(file.start.snapshot)
|
|
478
539
|
if (!restored.ok) return Result.failure({ _tag: "RestoreFailed", error: restored.error })
|
|
479
|
-
const
|
|
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
|
+
})
|
|
480
550
|
const send = target.runtime.send as (descriptor: { readonly kind: "event"; readonly name: string; readonly key: symbol }, value: unknown) => void
|
|
481
551
|
const events = new Map(target.runtime.debug.describe().events.map(({ name }) => [name, { kind: "event" as const, name, key: Symbol.for(`ritmo/event/${name}`) }]))
|
|
482
552
|
const hashes = new Map<number, string>([[ran, worldHash(target.runtime.checksum())]])
|
|
@@ -526,32 +596,6 @@ export const session = <S extends Schema.Any, Root>(
|
|
|
526
596
|
})
|
|
527
597
|
}
|
|
528
598
|
|
|
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
599
|
/**
|
|
556
600
|
* Cuts ticks `from`..`to` (recorder tick numbers) into a smaller replay that
|
|
557
601
|
* starts at the end of tick `from - 1`: few enough ticks to keep next to a
|