@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
package/README.md CHANGED
@@ -1,23 +1,8 @@
1
1
  # `@typeonce/ritmo-devtools`
2
2
 
3
- `Determinism.check` compares the same scripted simulation twice, including
4
- transient components that snapshots omit:
5
-
6
- ```ts
7
- const result = Determinism.check(({ hostClock }) => makeSimulation(hostClock), {
8
- schedule: "update", frames: 1800, hostClock: HostClock.test()
9
- })
10
- if (!result.ok) throw new Error(JSON.stringify(result))
11
- ```
12
-
13
- The factory returns `{ runtime, schedules }`, with a fresh debug runtime on
14
- every call. A difference reports its frame, value path, and the first system
15
- or schedule marker found by a diagnostic rerun. This checks the supplied
16
- inputs on the current JavaScript engine.
17
-
18
3
  Debug sessions for `ritmo` runtimes: run schedules headless, keep a trace
19
- history, and ask what happened as text. Built for coding agents first; the
20
- same data will back human-facing tools.
4
+ history, and ask what happened as text. Built for coding agents: every
5
+ answer is text and data, and nothing draws in the page.
21
6
 
22
7
  ```sh
23
8
  pnpm add -D @typeonce/ritmo-devtools
@@ -37,9 +22,11 @@ const runtime = Game.Runtime.make({
37
22
  services,
38
23
  debug: import.meta.env.DEV ? { hostClock: BrowserHostClock.make(window) } : undefined
39
24
  }).value
40
- if (runtime.debug !== undefined) Monitor.attach({ debug: runtime.debug }, { schedules, host: window })
41
25
  ```
42
26
 
27
+ In the browser, record a replay (see [Replays](#replays)) and debug it
28
+ headless with a `Session`.
29
+
43
30
  ## The debugging loop
44
31
 
45
32
  1. **Get a headless runtime.** Keep the game's simulation (schema, systems,
@@ -61,15 +48,27 @@ if (runtime.debug !== undefined) Monitor.attach({ debug: runtime.debug }, { sche
61
48
  3. **Reproduce.** Script the input with `Keyboard.scripted(bindings, timeline)`
62
49
  (or replay a recorded browser session), add an invariant that encodes the
63
50
  bug (`Invariant.fromInspector(Game.Inspector(...))`, returning a message
64
- when violated), and `session.run("update", { frames: 600 })`. The run stops at the
51
+ when violated), and `session.run("update", { frames: 600 })`. Give the
52
+ session `labels` for the entities the bug is about, so every line says
53
+ `player e12` instead of `e12`. The run stops at the
65
54
  first frame the invariant fails, a system fails, or a system throws.
66
55
  4. **Explain.** `session.why(entity, Component)` and
67
56
  `session.whyResource(Resource)` show the latest changes and which system
68
57
  made them; `why` also names the systems whose declared `spawns` could
69
- have spawned the entity. `session.journal({ frames: [from, to], entity })`
58
+ have spawned the entity. When the writer only passed on a wrong input,
59
+ raise `depth` to follow what it declared it reads, one system further
60
+ back per step. `session.journal({ frames: [from, to], entity })`
70
61
  shows everything that touched an entity around the failure.
71
62
  `session.report()` lists warnings the trace collected and the current
72
63
  entity counts per component. `run()` prints the warnings it raised.
64
+ When the wrong value appears within one frame, between two systems,
65
+ step that frame: run up to the frame before it, then
66
+ `const frame = session.step("update")`, `frame.until(ApplyDamage)` stops
67
+ before that system, `session.dump(...)` / `why` / `journal` show the
68
+ world and the partial frame, `frame.next()` runs one step (a system or
69
+ a marker), and `frame.finish()` runs the rest and reports the frame as
70
+ `run` does, invariants included. `frame.check()` asks the invariants
71
+ mid-frame, where one may legitimately fail until a later marker applies.
73
72
  5. **Fix and keep it.** Rerun the same script, then turn it into a test next
74
73
  to the game so the bug stays fixed.
75
74
 
@@ -100,12 +99,18 @@ const HealthNeverNegative = Invariant.fromInspector(Game.Inspector("health >= 0"
100
99
  const health = queries.player.each().map((match) => match.data.health.get())
101
100
  return health.some((value) => value < 0) ? `health ${health.join(", ")}` : undefined
102
101
  }))
102
+ // Labels name entities in every line: `player e12` instead of `e12`. An
103
+ // inspector returning entity id -> label; any other return does not compile.
104
+ const Labels = Game.Inspector("labels", {
105
+ queries: { players: Game.Query({ selection: { player: Game.Query.read(Player) } }) }
106
+ }, ({ queries }) => new Map(queries.players.each().map((match) => [match.entity.id, "player"] as const)))
103
107
 
104
108
  const session = Session.make(runtime, {
105
109
  hostClock, // times run(); the runtime's clock
106
110
  schedules: { setup, update }, // names used by run() and in traces
107
111
  describe: { render }, // described and linted, never run (needs a renderer)
108
112
  invariants: [HealthNeverNegative], // checked after every frame of every run
113
+ labels: Labels, // evaluated after every frame; despawned entities keep theirs
109
114
  history: 600 // frames kept for journal/why
110
115
  })
111
116
 
@@ -115,14 +120,23 @@ run.data.ok // true when completed or `until` retu
115
120
  run.data.stop // { reason: "completed" | "until" | "failure" | "defect"
116
121
  // | "invariant" | "missingRequirements" | "tickOrder", frame, ... }
117
122
 
123
+ const frame = session.step("update") // one frame, a step at a time; refuses run/tick until finished
124
+ frame.until(ApplyDamage) // runs the steps before the system value; Result: reached, or
125
+ // { reason: "failure" | "defect" | "frameEnded" | "notAhead" | ... }
126
+ session.dump({ entities: [12] }) // the world between two systems (journal and why show the partial frame)
127
+ frame.next() // exactly one step: a system or a marker
128
+ frame.check() // invariants now (may fail mid-frame); Result
129
+ frame.finish() // the rest of the frame, reported like run(name): labels, invariants
130
+
118
131
  session.describe() // schema, schedules, access, lints
119
132
  session.dump({ with: [Player], limit: 5 })// entities, resources, machines, pending commands
120
133
  session.why(12, Position) // latest changes to e12 Position
134
+ session.why(12, Health, { depth: 3 }) // and, under each, the declared reads behind it, two levels back
121
135
  session.whyResource(Score) // latest changes to a resource
122
136
  session.journal({ frames: [180, 185], entity: 12, kinds: ["write", "effect"] })
123
137
  session.journal({ system: "Game/Move", last: 10, verbose: true })
124
138
  session.system("Game/Move") // declared access, stats, recent lines
125
- session.streams() // event/transition/relation-failure retention
139
+ session.streams() // event/transition/relation-failure/dropped-relation retention
126
140
  session.report() // per-system timing and warnings
127
141
  ```
128
142
 
@@ -141,14 +155,20 @@ f186 update - transition Game/Flow Playing -> Paused applied
141
155
  - `f185`: frame number, counting every `tick`/`tryTick` call from 1, setup
142
156
  included. Keyboard timeline frames count input snapshots from 0 instead, so
143
157
  with one setup frame, timeline frame `n` is read in session frame `n + 2`.
144
- `e12`: entity 12. `&e12`: a stored handle to entity 12.
158
+ `e12`: entity 12; `player e12` when the session's `labels` name it (the
159
+ label it had at the end of that line's frame). `&e12`: a stored handle to
160
+ entity 12. Write entities as `e${id}` in invariant messages and the run
161
+ summary labels them too.
145
162
  - The schedule path shows nesting, for example `update > onEnter(Game/Flow=Paused)`.
146
- - `write`: a component written through a system's write query. `resource`,
163
+ - `write`: a component a system's write query changed to a different value
164
+ (writing back an equal value is not recorded). `resource`,
147
165
  `emit`, `next state`: resource writes, event emits, and queued machine
148
166
  values. Failed systems show `(rolled back)`.
149
167
  - `queued ...` then `applyDeferred: ...`: a command queued by a system, then
150
168
  its structural effect when a marker applied it. The system named on the
151
- effect line is the one that queued it.
169
+ effect line is the one that queued it. A despawn also lists each edge it
170
+ dropped: `Game/Targeting from e7 to e12 dropped: e12 despawned` (what
171
+ `Game.System.readDroppedRelations` delivers).
152
172
  - `skipped: <condition> is false`: a run condition held the system back;
153
173
  `discarded N Event` means messages published meanwhile are lost to it.
154
174
  - `missed ...`: the system could not see entries dropped before it ran.
@@ -157,37 +177,32 @@ f186 update - transition Game/Flow Playing -> Paused applied
157
177
  - Large objects print only their changed paths:
158
178
  `~ up.held: false -> true, left.held: false -> true`.
159
179
 
160
- ## Live monitor (browser)
180
+ `why` and `whyResource` with `depth` above 1 indent, under each change,
181
+ what the writing system declared it reads, with the latest traced fact that
182
+ could have produced it; each `depth` step goes one system further back:
161
183
 
162
- `Monitor.attach(runtime, { schedules, host: window })` adds a panel to a running game for
163
- people who want to see how it works without reading its code. Toggle it
164
- with the backslash key or the corner button. It observes the runtime only while it is
165
- open, so a closed monitor costs nothing.
166
-
167
- ```ts
168
- const monitor = Monitor.attach(runtime, {
169
- schedules: { fixedUpdate: step, frame }, // the schedule objects you tick
170
- host: window, // its document, timers, events, and clock
171
- pick: (event) => entityUnderPointer(event), // optional: "Pick on screen"
172
- locate: (entity) => clientPositionOf(entity) // optional: ring on the selected entity
173
- })
184
+ ```
185
+ e12 Game/Health is now 40; last 1 changes (oldest first):
186
+ could have spawned it: Game/SpawnEnemy
187
+ indented: what each writing system declared it reads, and the latest fact that could have produced it (declared: possible causes, not observed reads)
188
+ f181 update Game/ApplyDamage write e12 Game/Health 70 -> 40
189
+ read Game/Damage [{amount:30}] (declared), emitted by Game/Hitscan at f181
190
+ read Game/Position of 14 matching entities now (declared; the trace does not say which it read)
191
+ read resource Game/Aim {target:12} (declared), written by Game/AimAtNewest at f180
192
+ read e12 Game/Armor 5 (declared), spawned by Game/SpawnEnemy at f3
174
193
  ```
175
194
 
176
- - **Overview:** time per schedule tick, the busiest systems, entity counts
177
- per component as sparklines (a line that only rises is a leak), state
178
- machines, and alerts (failed systems, NaN or infinite writes, messages
179
- discarded by skipped systems).
180
- - **Systems:** every schedule as its systems in order, grouped by run
181
- conditions. Each system shows what it writes, emits, spawns (learned
182
- while running), and reads. A dot shows whether it is working, idle, or
183
- skipped. Hover a name to light up its writers (orange) and readers (blue).
184
- Click a system for rates, skip reasons, spawn kinds, and its last error.
185
- - **Entity:** pick an entity on screen, by id, or by component, and follow
186
- its components live along with the changes systems make to it.
187
-
188
- Timings include tracing overhead, so compare systems with each other rather
189
- than with a run where the monitor is closed. `Monitor.Collector` is the same
190
- data without DOM, for a custom UI.
195
+ - The trace records writes, not reads, so every indented line is a
196
+ possible cause, marked `(declared)`, not a read that was observed.
197
+ - An event read lists what was published to it since the system's previous
198
+ run, and by whom (`runtime.send` for the host). A component in the query
199
+ that wrote the value is read on the same entity: its latest change before
200
+ the run. A resource or machine: its latest change or transition.
201
+ - A query over other entities says only how many match now: the trace does
202
+ not say which one the system used. Use `journal` to narrow it down.
203
+ - A system already in the chain prints `(cycle: not followed)`; `limit`
204
+ caps the reads under each line (`…+N more declared reads`). In `.data`,
205
+ these lines have `kind: "read"` and `depth` 1 or more.
191
206
 
192
207
  ## Report warnings
193
208
 
@@ -201,6 +216,7 @@ data without DOM, for a custom UI.
201
216
  | `system-failed` | A system returned an expected failure or threw. |
202
217
  | `ignored-failure` | A `tick` / `tryTick` result failed and nobody read its `ok` before the next tick (or the session's `report()`): the failure went unnoticed and later systems did not run. `run` stops on it with `reason: "ignored-failure"`. |
203
218
  | `non-finite-value` | A system wrote NaN or an infinity into a component, resource, event, or spawned entity. The message names the entity and path; `why()` shows the history. |
219
+ | `out-of-range` | A system wrote a number outside the `range` its descriptor declares for that field (`meta: { hp: { range: [0, 100] } }`), in a write, a resource, or a spawned or inserted component. One count per write; the message names the entity, field, value, range, system, and first frame. The range is advisory: the schema decides what is valid. |
204
220
  | `population-growing` | A component's count rose through every quarter of a run of 60+ frames: its lowest count in each quarter was higher than in the quarter before. Bursts that are cleaned up do not trigger it; entities that are never despawned do. `run()` returns the counts in `growing`. |
205
221
 
206
222
  The report also starts with the static lints from `describe()`.
@@ -212,17 +228,35 @@ script. `<entry>` exports `lintTarget` (see the `Lint` module): it prints
212
228
  every lint of the schedules with its fix and exits with 1 on a warning.
213
229
 
214
230
  ```sh
215
- ritmo-devtools lint src/simulation.ts
231
+ ritmo-devtools lint src/lint.ts
232
+ ```
233
+
234
+ Keep the entry beside the simulation, not inside it, when `describe` needs
235
+ host schedules: it is the one module that imports both, so the simulation
236
+ never imports render or audio code. Load the host schedules inside
237
+ `lintTarget`:
238
+
239
+ ```ts
240
+ // src/lint.ts
241
+ import { makeRuntime, setup, update } from "./simulation/index.ts"
242
+
243
+ export const lintTarget = async () => {
244
+ const { render } = await import("./render/index.ts")
245
+ return { runtime: makeRuntime({ debug: { hostClock: HostClock.test() } }), schedules: { setup, update }, describe: { render } }
246
+ }
216
247
  ```
217
248
 
249
+ When nothing needs describing, the simulation's own entry module can export
250
+ `lintTarget` instead.
251
+
218
252
  It also checks that the oxlint simulation rules from
219
253
  `@typeonce/oxlint-plugin-ritmo` cover the simulation. Every module that
220
254
  importing `<entry>` loads, inside the directory of the `.oxlintrc.json` in the
221
255
  working directory and outside `node_modules`, must have
222
256
  `ritmo/keep-simulation-headless` on there (overrides apply in order, the last
223
- match wins; `ignorePatterns` matches are uncovered). Modules imported inside
224
- `lintTarget` or later (render schedules passed to `describe`) are host code
225
- and are not checked, nor are type-only imports. A missing config, one with
257
+ match wins; `ignorePatterns` matches are uncovered). The entry itself, and
258
+ modules imported inside `lintTarget` or later (render schedules passed to
259
+ `describe`), are host code and are not checked, nor are type-only imports. A missing config, one with
226
260
  `extends`, or one that never turns the rule on prints why the check was
227
261
  skipped and does not fail. The check needs Node 22.15 or later.
228
262
 
@@ -234,6 +268,49 @@ The trace shows what systems wrote, not what they read. When a system writes
234
268
  a wrong value from correct inputs, the journal narrows the bug to that
235
269
  system (it runs, in order, and writes this value) and the rest is its code.
236
270
 
271
+ ## Determinism
272
+
273
+ `Determinism.check` compares the same scripted simulation twice, including
274
+ transient components that snapshots omit:
275
+
276
+ ```ts
277
+ const result = Determinism.check(({ hostClock }) => makeSimulation(hostClock), {
278
+ schedule: "update", frames: 1800, hostClock: HostClock.test()
279
+ })
280
+ if (!result.ok) throw new Error(JSON.stringify(result))
281
+ ```
282
+
283
+ The factory returns `{ runtime, schedules }`, with a fresh debug runtime on
284
+ every call. A difference reports its frame, value path, and the first system
285
+ or schedule marker found by a diagnostic rerun; inside an entity, it names
286
+ the entity (`entity`) and, given `labels` (the session's labels inspector),
287
+ its `label`. This checks the supplied inputs on the current JavaScript
288
+ engine; [Verify across engines](#verify-across-engines) plays a replay in
289
+ Node and real browsers.
290
+
291
+ ## Desyncs
292
+
293
+ Peers of a networked game (`@typeonce/ritmo-netcode`) compare checksums of
294
+ confirmed ticks. When they differ, a session made with `keepSnapshots: true`
295
+ fails with `Desynced` carrying its save of that tick, and the other peer's
296
+ carries its own. `Desync.compare` lists what differs, entities by id and
297
+ values by path, in a stable order:
298
+
299
+ ```ts
300
+ console.log(Desync.compare(mine.snapshot, theirs.snapshot, { labels: runtime.inspect(Labels) }))
301
+ // 2 differences (mine -> theirs):
302
+ // player e12 Game/Position.x: 40 -> 41
303
+ // resource Game/Rng: 1730 -> 2210
304
+ ```
305
+
306
+ The first difference is where to look: rerun the match headless and ask a
307
+ `Session` `why` that value changed.
308
+
309
+ A `Netcode.syncTest` made with `keepSnapshots: true` fails with
310
+ `RewindDiffers` carrying the world before and after a rewind:
311
+ `Desync.compare(error.snapshots.expected, error.snapshots.actual)` names
312
+ what the rewind did not put back.
313
+
237
314
  ## Replays
238
315
 
239
316
  A replay is the last seconds of a play session as a file: a debug artifact
@@ -248,7 +325,7 @@ const recorder = Replay.recorder(runtime, {
248
325
  hostClock: BrowserHostClock.make(window), // for savedAt
249
326
  saveOn: { failure: true, invariants: [DeadAreGone] } // saves by itself
250
327
  })
251
- Monitor.attach(runtime, { schedules, host: window, replay: recorder }) // adds "Save replay"
328
+ recorder.save("player stuck") // on demand, e.g. from a dev-only key
252
329
 
253
330
  // vite.config.ts: writes posted replays to .replays/<time>.json and logs them.
254
331
  plugins: [ReplayVitePlugin.plugin()]
@@ -275,13 +352,214 @@ const file = Replay.parse(JSON.parse(readFileSync(".replays/....json", "utf8")))
275
352
  const replay = file.ok ? Replay.session(make, file.value) : file
276
353
  replay.value.play() // run the ticks; reports checkpoint divergence
277
354
  replay.value.session.why(12, Position) // a normal Session over the replayed frames
278
- Replay.verify(make, file.value) // replays twice: nondeterminism shows up
355
+ Replay.session(make, file.value, { labels: Labels }) // names entities, as in Session.make
356
+ await Verify.acrossEngines(make, file.value) // replays twice here and against the recording
279
357
  Replay.extract(make, file.value, { from: 1400, to: 1412 }) // a small replay for a test
280
358
  ```
281
359
 
360
+ `Replay.session(make, file, { invariants })` checks invariants after every
361
+ replayed tick, so `play()` stops where one breaks, as a `Session` run does.
362
+
363
+ `playback.source(descriptor)` takes any `snapshot()`-only source service:
364
+ `Schedule.Source<T>`, `Netcode.Source<T>`, or browser input declared as
365
+ `InputCapture.SourceOf<...>` (a device, a `Controls` merge, or a pool; see
366
+ [the browser README](https://github.com/typeonce-dev/ritmo/blob/main/packages/browser/README.md)).
367
+ A service declared as the whole device, with `rebind` and `dispose`, is a
368
+ compile error naming that fix: a replay can only stand in for its
369
+ `snapshot()`, so the page keeps the device to rebind it.
370
+
282
371
  A replay recorded with another schema fails with "replay recorded with an
283
372
  older schema".
284
373
 
374
+ ## Verify across engines
375
+
376
+ `Verify.acrossEngines` is the one replay check. With no engines it plays
377
+ the replay twice in this process and against the recording, the check a
378
+ test runs; `ritmo-devtools verify` plays the same replay in Node and in real
379
+ browser engines and reports the first tick whose world differs, with every
380
+ value that differs there. Run it before
381
+ trusting a lockstep or rollback match across browsers, and in CI on a
382
+ committed replay of the game:
383
+
384
+ ```sh
385
+ ritmo-devtools verify src/replay-target.ts replays/boss-fight.json --engines node,chromium,webkit,firefox
386
+ # NOT verified: 1800 ticks of simulate
387
+ # node: agrees with a second node run and the recording over 1800 ticks
388
+ # chromium: agrees with node over 1800 ticks
389
+ # tick 1412: webkit differs from node in e41 Game/Position.x (40.000000000000014 -> 40)
390
+ # 1 difference (node -> webkit):
391
+ # e41 Game/Position.x: 40.000000000000014 -> 40
392
+ # firefox: not installed (the firefox browser is not downloaded): npx playwright install firefox
393
+ ```
394
+
395
+ `<entry>` exports `replayTarget`, the `make(playback)` factory
396
+ `Replay.session` takes (above). It must load in a browser too: keep Node
397
+ built-ins out of it.
398
+
399
+ ```ts
400
+ // src/replay-target.ts
401
+ export const replayTarget = (playback: Replay.Playback) => {
402
+ const hostClock = HostClock.test()
403
+ return { runtime: makeRuntime({ input: playback.source(Input), debug: { hostClock } }), schedules: { simulate }, hostClock }
404
+ }
405
+ ```
406
+
407
+ - Node always runs, as the reference: twice (a difference is
408
+ nondeterminism here) and against the recording's checkpoints (a
409
+ difference is a code change since recording, or the recording engine).
410
+ `--engines node`, the default, needs no other dependency.
411
+ - Browser engines run headless through Playwright, with the entry served by
412
+ a bare Vite dev server (the game's `vite.config` is not read). Install
413
+ them where the check runs: `npm install --save-dev playwright vite` and
414
+ `npx playwright install chromium webkit firefox`. An engine that is not
415
+ installed is printed with its install command and fails the check.
416
+ - Exit codes: 0 every engine agrees, 1 one differs or did not run, 2 usage
417
+ error (arguments, a file that is not a replay, an entry without
418
+ `replayTarget`). `--json` prints the result as JSON.
419
+
420
+ The same check from code, for a game's own test (leave out `engines` to
421
+ check this process alone):
422
+
423
+ ```ts
424
+ import { Verify } from "@typeonce/ritmo-devtools"
425
+ import * as PlaywrightEngine from "@typeonce/ritmo-devtools/PlaywrightEngine"
426
+
427
+ const browsers = PlaywrightEngine.make({ entry: "src/replay-target.ts", browsers: ["chromium", "webkit", "firefox"] })
428
+ const verified = await Verify.acrossEngines(replayTarget, file, { engines: browsers.engines })
429
+ await browsers.close()
430
+ if (!verified.ok && verified.error._tag === "NotVerified") {
431
+ for (const outcome of verified.error.outcomes) if (outcome._tag === "Diverged") console.log(outcome.tick, outcome.differences)
432
+ }
433
+ ```
434
+
435
+ The error side is `ReplayInvalid` (the replay does not open here) or
436
+ `NotVerified`, one outcome per engine: `Agreed`, `Diverged` (`tick`,
437
+ `against`, `differences`), `EngineMissing` (`install`), or `EngineFailed`.
438
+ For another host (a webview, a console), run `Verify.trace` and
439
+ `Verify.snapshotAt` there and wrap them as a `Verify.Engine`.
440
+
441
+ ## Scan dependencies
442
+
443
+ oxlint skips `node_modules`, so a dependency the simulation calls can still
444
+ use `Math.sin`, `Date.now`, or `Math.random`. `ritmo-devtools scan <entry>`
445
+ resolves every file the simulation entry imports, `node_modules` included,
446
+ and runs `ritmo/use-ops-for-math`, `ritmo/use-clock-for-time`, and
447
+ `ritmo/use-random-for-randomness` over them, grouped by package:
448
+
449
+ ```sh
450
+ ritmo-devtools scan src/simulation/index.ts
451
+ # fake-physics (2 findings)
452
+ # node_modules/fake-physics/index.js:4:17 ritmo/use-ops-for-math Math.sin
453
+ # node_modules/fake-physics/index.js:6:32 ritmo/use-random-for-randomness Math.random
454
+ #
455
+ # scanned 4 files in 2 packages imported by src/simulation/index.ts: 2 findings in 1 package
456
+ ```
457
+
458
+ - A finding is a hint, not a verdict: code the simulation never calls is
459
+ fine. For a dependency it calls, vendor it into the game's source and run
460
+ `oxlint --fix`, or replace it. A clean scan does not prove the run is
461
+ deterministic: confirm with `ritmo-devtools verify` or `Netcode.syncTest`.
462
+ - It uses the game's `oxlint` and `@typeonce/oxlint-plugin-ritmo`, and
463
+ `rolldown` to resolve imports the way a build does (Vite 8 includes it;
464
+ otherwise `npm install --save-dev rolldown`). A missing tool is printed
465
+ with its install command.
466
+ - Exit codes: 0 whenever the scan ran, with or without findings, 2 usage
467
+ error (arguments, an unreadable entry, an import that does not resolve, a
468
+ missing tool). `--json` prints
469
+ `{ entry, files, packages: [{ name, files, findings: [{ file, line, column, rule, snippet }] }] }`.
470
+
471
+ ## Fuzzing
472
+
473
+ `Fuzz.run` finds a bug before anyone plays into it: seeded random input,
474
+ run headless against the game's invariants, until an invariant breaks, a
475
+ system fails, or something throws. It then shrinks the failing input to the
476
+ few frames that still fail the same way, and returns them as a replay file.
477
+
478
+ ```ts
479
+ import { Fuzz, Replay } from "@typeonce/ritmo-devtools"
480
+ import * as ReplayNodeSink from "@typeonce/ritmo-devtools/ReplayNodeSink"
481
+
482
+ // One fuzzed snapshot() source: a value of its type for each frame, and the idle value.
483
+ const Pads = Fuzz.input(PadInput, {
484
+ generate: (random, frame) => ({ key: random.integer(0, 5), aim: random.range(-1, 1) }),
485
+ neutral: { key: 0, aim: 0 }
486
+ })
487
+ // `make` is the replay factory (above): it builds the game on playback.source(PadInput).
488
+ const found = Fuzz.run(make, {
489
+ schedule: "update", setup: "setup", // setup is ticked once first, every input neutral
490
+ inputs: [Pads], invariants: [HealthNeverNegative],
491
+ frames: 3000, runs: 10, seed: 7 // run i draws from seed 7 + i
492
+ })
493
+ if (!found.ok && found.error._tag === "Found") {
494
+ ReplayNodeSink.make({ directory: ".replays" }).save(found.error.replay)
495
+ console.log(found.error.violation) // InvariantViolated | SystemFailed | Defect
496
+ console.log(found.error.shrink) // { attempts, steps, fromFrames: 1412, toFrames: 4 }
497
+ }
498
+ ```
499
+
500
+ - A browser game fuzzes through the same descriptor its page and replays
501
+ read: `Fuzz.input(ControlsInput, { generate: (random) =>
502
+ Actions.random(random, devices), neutral: Actions.idle(devices) })` draws
503
+ merged input a real merge could report (button states, vectors of length
504
+ at most 1); `Players.random(random, frame, { devices, seats })` does it
505
+ for a local multiplayer pool.
506
+ - `random` is a seeded `Random` from `@typeonce/ritmo`; the same seed
507
+ draws the same input, so a found bug's `seed` with `runs: 1` finds it
508
+ again. Every source `make` asks `playback.source` for must be a fuzzed
509
+ input; give plain-data services (rules, config) directly.
510
+ - Shrinking drops ranges of frames, then moves each remaining value to
511
+ `neutral` (whole, then one field at a time), re-running the simulation for
512
+ every candidate. `shrinkAttempts` (500) bounds it.
513
+ - The error side is `Found` (with the shrunk `replay`, `seed`, `frame`, and
514
+ `reproduces`: whether `Replay.session` replays it to the same violation),
515
+ `Flaky` (the same input did not fail again: run `Determinism.check`),
516
+ `InvalidOptions`, or `Unreplayable` (the world after setup cannot be saved).
517
+
518
+ The shrunk replay is the regression test:
519
+
520
+ ```ts
521
+ const file = Replay.parse(JSON.parse(readFileSync(".replays/....json", "utf8")))
522
+ const opened = file.ok ? Replay.session(make, file.value, { invariants: [HealthNeverNegative] }) : file
523
+ expect(opened.ok && opened.value.play().data.run.stop.reason).toBe("completed") // fails until the fix
524
+ ```
525
+
526
+ ### Over a network
527
+
528
+ The same `Fuzz.run` fuzzes a rollback game over a faulty network. Give it one
529
+ `Fuzz.seats` input (every seat's input per frame) and `network`: each seat
530
+ plays on its own peer, a fresh `make(playback)`, joined by a seeded
531
+ `MemoryNetworkLink` and driven by a `Netcode.rollback` session from
532
+ [`@typeonce/ritmo-netcode`](https://github.com/typeonce-dev/ritmo/blob/main/packages/netcode/README.md).
533
+
534
+ ```ts
535
+ // The seats service the simulation captures; make provides it with playback.source(Seats).
536
+ const Players = Fuzz.seats(Seats, {
537
+ codec: PlayerInput, count: 2, idle: { dx: 0, fire: false }, // as given to Netcode.seats
538
+ generate: (random, frame, seat) => ({ dx: random.integer(-1, 2), fire: random.next() < 0.2 })
539
+ })
540
+ const found = Fuzz.run(make, {
541
+ schedule: "simulate", setup: "setup", inputs: [Players], invariants: [HealthNeverNegative],
542
+ frames: 600, seed: 7,
543
+ network: { seed: 3, latencyMS: 60, jitterMS: 40, loss: 0.1, step } // faults repeat for the same seed
544
+ })
545
+ if (!found.ok && found.error._tag === "Found" && found.error.violation._tag === "SessionFailed") {
546
+ console.log(found.error.violation.seat, found.error.violation.error) // Desynced, with this peer's save of the tick
547
+ }
548
+ ```
549
+
550
+ - A session failure (`Desynced`, `TickFailed`, `CheckpointLost`, or the
551
+ session ending) is a `SessionFailed` violation; invariants are checked on
552
+ every peer after each frame. `settle` idle frames (120) follow the fuzzed
553
+ ones so late input and checksums arrive; checksums are compared every 10
554
+ ticks unless `checksumEvery` says otherwise.
555
+ - Shrinking keeps the network seed and shrinks the input timeline, one seat
556
+ at a time. The `replay` plays the shrunk timeline on one runtime (step it
557
+ to see each tick); `reproduces` is `false` for a desync, which needs two
558
+ peers: find it again with the same `seed`, `runs: 1`, and `network`.
559
+ - A `simulate` that cannot be rewound, or a runtime that cannot save, does
560
+ not compile, as for `Netcode.rollback`. Run `Netcode.syncTest` first: it
561
+ finds state a rewind cannot put back on one peer, faster.
562
+
285
563
  ## Recording a browser session
286
564
 
287
565
  ```ts
@@ -0,0 +1,49 @@
1
+ /**
2
+ * What differs between two saves of the same tick: the report for a desync
3
+ * between peers of a networked game.
4
+ *
5
+ * A `Netcode` session made with `keepSnapshots: true` fails with `Desynced`
6
+ * carrying this peer's save of the tick whose checksums differ; the other
7
+ * peer's session carries its own. `compare(mine, theirs)` lists every
8
+ * difference, entities by id (and label, given `labels`) and values by path, so an agent can see which
9
+ * component or resource went apart first, then find the system that wrote
10
+ * it with a `Session`'s `why` on a headless rerun.
11
+ * The same goes for the two saves a `Netcode.syncTest`'s `RewindDiffers`
12
+ * carries (`keepSnapshots: true`): the first run's and the one after a rewind.
13
+ *
14
+ * @module Desync
15
+ * @docGroup devtools
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * const left = sessions[0].advance(input)
20
+ * const right = sessions[1].advance(input)
21
+ * if (!left.ok && left.error._tag === "Desynced" && !right.ok && right.error._tag === "Desynced") {
22
+ * console.log(Desync.compare(left.error.snapshot!, right.error.snapshot!, { labels: runtime.inspect(Labels) }))
23
+ * }
24
+ * ```
25
+ */
26
+ import type * as Snapshot from "@typeonce/ritmo/Snapshot";
27
+ import * as Format from "./Format.ts";
28
+ import * as Rendered from "./Rendered.ts";
29
+ /** One value that differs: where, and each side's (`undefined`: absent on that side). */
30
+ export interface Difference {
31
+ /** `nextEntity`, `entity 12`, `entity 12 Game/Position.x`, `resource Game/Score`, `machine Game/Round`, `relation Game/ChildOf`, or `scope Game/Wave`. */
32
+ readonly path: string;
33
+ /** The entity the difference is in, when it is in one. */
34
+ readonly entity: number | undefined;
35
+ readonly mine: unknown;
36
+ readonly theirs: unknown;
37
+ }
38
+ /** How `compare` prints. */
39
+ export interface CompareOptions {
40
+ /**
41
+ * Names entities in the text (`player e12 Game/Position.x`): the map the
42
+ * session's `labels` inspector returns, read with `runtime.inspect(Labels)`
43
+ * on either peer. Without it entities print as `e12`.
44
+ */
45
+ readonly labels?: Format.Labels;
46
+ }
47
+ /** Every difference between two saves, in a stable order: the next id, entities by id, then resources, machines, relations, and scopes by name. */
48
+ export declare const compare: (mine: Snapshot.WorldSnapshot, theirs: Snapshot.WorldSnapshot, options?: CompareOptions) => Rendered.Rendered<ReadonlyArray<Difference>>;
49
+ //# sourceMappingURL=Desync.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Desync.d.ts","sourceRoot":"","sources":["../src/Desync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,KAAK,QAAQ,MAAM,0BAA0B,CAAA;AAEzD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,0JAA0J;IAC1J,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AA4BD,4BAA4B;AAC5B,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAA;CAChC;AAED,mJAAmJ;AACnJ,eAAO,MAAM,OAAO,SAAU,QAAQ,CAAC,aAAa,UAAU,QAAQ,CAAC,aAAa,YAAW,cAAc,KAAQ,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAsB/J,CAAA"}
package/dist/Desync.js ADDED
@@ -0,0 +1,51 @@
1
+ import * as Format from "./Format.js";
2
+ import * as Rendered from "./Rendered.js";
3
+ const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
4
+ /** The leaves where two values differ, under `path`. */
5
+ const differences = (path, entity, mine, theirs, into) => {
6
+ if (Format.sameValue(mine, theirs))
7
+ return;
8
+ if (isRecord(mine) && isRecord(theirs)) {
9
+ for (const key of [...new Set([...Object.keys(mine), ...Object.keys(theirs)])].sort()) {
10
+ differences(`${path}.${key}`, entity, mine[key], theirs[key], into);
11
+ }
12
+ return;
13
+ }
14
+ if (Array.isArray(mine) && Array.isArray(theirs) && mine.length === theirs.length) {
15
+ mine.forEach((item, index) => differences(`${path}[${index}]`, entity, item, theirs[index], into));
16
+ return;
17
+ }
18
+ into.push({ path, entity, mine, theirs });
19
+ };
20
+ /** Each named entry of two records, compared under `kind name`. */
21
+ const byName = (kind, entity, mine, theirs, into) => {
22
+ for (const name of [...new Set([...Object.keys(mine), ...Object.keys(theirs)])].sort()) {
23
+ differences(`${kind} ${name}`, entity, mine[name], theirs[name], into);
24
+ }
25
+ };
26
+ /** Every difference between two saves, in a stable order: the next id, entities by id, then resources, machines, relations, and scopes by name. */
27
+ export const compare = (mine, theirs, options = {}) => {
28
+ const found = [];
29
+ differences("nextEntity", undefined, mine.nextEntity, theirs.nextEntity, found);
30
+ const mineById = new Map(mine.entities.map((entity) => [entity.id, entity.components]));
31
+ const theirsById = new Map(theirs.entities.map((entity) => [entity.id, entity.components]));
32
+ for (const id of [...new Set([...mineById.keys(), ...theirsById.keys()])].sort((a, b) => a - b)) {
33
+ const left = mineById.get(id);
34
+ const right = theirsById.get(id);
35
+ if (left === undefined || right === undefined)
36
+ found.push({ path: `entity ${id}`, entity: id, mine: left, theirs: right });
37
+ else
38
+ byName(`entity ${id}`, id, left, right, found);
39
+ }
40
+ byName("resource", undefined, mine.resources, theirs.resources, found);
41
+ byName("machine", undefined, mine.machines, theirs.machines, found);
42
+ byName("relation", undefined, mine.relations, theirs.relations, found);
43
+ byName("scope", undefined, mine.scopes, theirs.scopes, found);
44
+ // `entity 12 ...` prints as `player e12 ...`, like every entity in devtools text.
45
+ const where = ({ path, entity }) => entity === undefined ? path : `${Format.entity(entity, options.labels)}${path.slice(`entity ${entity}`.length)}`;
46
+ const text = found.length === 0
47
+ ? "The saves are equal."
48
+ : [`${found.length} difference${found.length === 1 ? "" : "s"} (mine -> theirs):`, ...found.map((difference) => ` ${where(difference)}: ${Format.value(difference.mine)} -> ${Format.value(difference.theirs)}`)].join("\n");
49
+ return Rendered.make(found, text);
50
+ };
51
+ //# sourceMappingURL=Desync.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Desync.js","sourceRoot":"","sources":["../src/Desync.ts"],"names":[],"mappings":"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"}