@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
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,7 +155,10 @@ 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
163
  - `write`: a component a system's write query changed to a different value
147
164
  (writing back an equal value is not recorded). `resource`,
@@ -149,7 +166,9 @@ f186 update - transition Game/Flow Playing -> Paused applied
149
166
  values. Failed systems show `(rolled back)`.
150
167
  - `queued ...` then `applyDeferred: ...`: a command queued by a system, then
151
168
  its structural effect when a marker applied it. The system named on the
152
- 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).
153
172
  - `skipped: <condition> is false`: a run condition held the system back;
154
173
  `discarded N Event` means messages published meanwhile are lost to it.
155
174
  - `missed ...`: the system could not see entries dropped before it ran.
@@ -158,37 +177,32 @@ f186 update - transition Game/Flow Playing -> Paused applied
158
177
  - Large objects print only their changed paths:
159
178
  `~ up.held: false -> true, left.held: false -> true`.
160
179
 
161
- ## 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:
162
183
 
163
- `Monitor.attach(runtime, { schedules, host: window })` adds a panel to a running game for
164
- people who want to see how it works without reading its code. Toggle it
165
- with the backslash key or the corner button. It observes the runtime only while it is
166
- open, so a closed monitor costs nothing.
167
-
168
- ```ts
169
- const monitor = Monitor.attach(runtime, {
170
- schedules: { fixedUpdate: step, frame }, // the schedule objects you tick
171
- host: window, // its document, timers, events, and clock
172
- pick: (event) => entityUnderPointer(event), // optional: "Pick on screen"
173
- locate: (entity) => clientPositionOf(entity) // optional: ring on the selected entity
174
- })
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
175
193
  ```
176
194
 
177
- - **Overview:** time per schedule tick, the busiest systems, entity counts
178
- per component as sparklines (a line that only rises is a leak), state
179
- machines, and alerts (failed systems, NaN or infinite writes, messages
180
- discarded by skipped systems).
181
- - **Systems:** every schedule as its systems in order, grouped by run
182
- conditions. Each system shows what it writes, emits, spawns (learned
183
- while running), and reads. A dot shows whether it is working, idle, or
184
- skipped. Hover a name to light up its writers (orange) and readers (blue).
185
- Click a system for rates, skip reasons, spawn kinds, and its last error.
186
- - **Entity:** pick an entity on screen, by id, or by component, and follow
187
- its components live along with the changes systems make to it.
188
-
189
- Timings include tracing overhead, so compare systems with each other rather
190
- than with a run where the monitor is closed. `Monitor.Collector` is the same
191
- 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.
192
206
 
193
207
  ## Report warnings
194
208
 
@@ -202,6 +216,7 @@ data without DOM, for a custom UI.
202
216
  | `system-failed` | A system returned an expected failure or threw. |
203
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"`. |
204
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. |
205
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`. |
206
221
 
207
222
  The report also starts with the static lints from `describe()`.
@@ -231,6 +246,11 @@ export const lintTarget = async () => {
231
246
  }
232
247
  ```
233
248
 
249
+ A debug script that needs the same runtime and host schedules (a
250
+ `scripts/debug.ts` that builds a `Session`) imports `lintTarget` and calls
251
+ it, instead of repeating the wiring: `const { runtime, schedules } = await
252
+ lintTarget()`.
253
+
234
254
  When nothing needs describing, the simulation's own entry module can export
235
255
  `lintTarget` instead.
236
256
 
@@ -248,11 +268,33 @@ skipped and does not fail. The check needs Node 22.15 or later.
248
268
  | Code | Meaning |
249
269
  |---|---|
250
270
  | `uncovered-simulation-module` | The simulation loads this file, but no simulation override in `.oxlintrc.json` covers it, so oxlint never checks it for platform, time, randomness, or math calls. Add it to the override's `files`, or stop importing values from it. Exits with 1. |
271
+ | `skill-not-linked` | Neither `.agents/skills/ritmo` nor `.claude/skills/ritmo` links the skill in `node_modules/@typeonce/ritmo/skills/ritmo`, so the game's agent does not read the playbooks for this Ritmo version. Link it (`SETUP.md` step 2). A note: the exit code is unchanged. |
272
+ | `skill-copied` | The folder holds a copy of the skill (or links somewhere else), which goes stale on the next upgrade. Replace it with the link. A note: the exit code is unchanged. |
251
273
 
252
274
  The trace shows what systems wrote, not what they read. When a system writes
253
275
  a wrong value from correct inputs, the journal narrows the bug to that
254
276
  system (it runs, in order, and writes this value) and the rest is its code.
255
277
 
278
+ ## Determinism
279
+
280
+ `Determinism.check` compares the same scripted simulation twice, including
281
+ transient components that snapshots omit:
282
+
283
+ ```ts
284
+ const result = Determinism.check(({ hostClock }) => makeSimulation(hostClock), {
285
+ schedule: "update", frames: 1800, hostClock: HostClock.test()
286
+ })
287
+ if (!result.ok) throw new Error(JSON.stringify(result))
288
+ ```
289
+
290
+ The factory returns `{ runtime, schedules }`, with a fresh debug runtime on
291
+ every call. A difference reports its frame, value path, and the first system
292
+ or schedule marker found by a diagnostic rerun; inside an entity, it names
293
+ the entity (`entity`) and, given `labels` (the session's labels inspector),
294
+ its `label`. This checks the supplied inputs on the current JavaScript
295
+ engine; [Verify across engines](#verify-across-engines) plays a replay in
296
+ Node and real browsers.
297
+
256
298
  ## Desyncs
257
299
 
258
300
  Peers of a networked game (`@typeonce/ritmo-netcode`) compare checksums of
@@ -262,15 +304,20 @@ carries its own. `Desync.compare` lists what differs, entities by id and
262
304
  values by path, in a stable order:
263
305
 
264
306
  ```ts
265
- console.log(Desync.compare(mine.snapshot, theirs.snapshot))
307
+ console.log(Desync.compare(mine.snapshot, theirs.snapshot, { labels: runtime.inspect(Labels) }))
266
308
  // 2 differences (mine -> theirs):
267
- // entity 12 Game/Position.x: 40 -> 41
309
+ // player e12 Game/Position.x: 40 -> 41
268
310
  // resource Game/Rng: 1730 -> 2210
269
311
  ```
270
312
 
271
313
  The first difference is where to look: rerun the match headless and ask a
272
314
  `Session` `why` that value changed.
273
315
 
316
+ A `Netcode.syncTest` made with `keepSnapshots: true` fails with
317
+ `RewindDiffers` carrying the world before and after a rewind:
318
+ `Desync.compare(error.snapshots.expected, error.snapshots.actual)` names
319
+ what the rewind did not put back.
320
+
274
321
  ## Replays
275
322
 
276
323
  A replay is the last seconds of a play session as a file: a debug artifact
@@ -285,7 +332,7 @@ const recorder = Replay.recorder(runtime, {
285
332
  hostClock: BrowserHostClock.make(window), // for savedAt
286
333
  saveOn: { failure: true, invariants: [DeadAreGone] } // saves by itself
287
334
  })
288
- Monitor.attach(runtime, { schedules, host: window, replay: recorder }) // adds "Save replay"
335
+ recorder.save("player stuck") // on demand, e.g. from a dev-only key
289
336
 
290
337
  // vite.config.ts: writes posted replays to .replays/<time>.json and logs them.
291
338
  plugins: [ReplayVitePlugin.plugin()]
@@ -312,13 +359,214 @@ const file = Replay.parse(JSON.parse(readFileSync(".replays/....json", "utf8")))
312
359
  const replay = file.ok ? Replay.session(make, file.value) : file
313
360
  replay.value.play() // run the ticks; reports checkpoint divergence
314
361
  replay.value.session.why(12, Position) // a normal Session over the replayed frames
315
- Replay.verify(make, file.value) // replays twice: nondeterminism shows up
362
+ Replay.session(make, file.value, { labels: Labels }) // names entities, as in Session.make
363
+ await Verify.acrossEngines(make, file.value) // replays twice here and against the recording
316
364
  Replay.extract(make, file.value, { from: 1400, to: 1412 }) // a small replay for a test
317
365
  ```
318
366
 
367
+ `Replay.session(make, file, { invariants })` checks invariants after every
368
+ replayed tick, so `play()` stops where one breaks, as a `Session` run does.
369
+
370
+ `playback.source(descriptor)` takes any `snapshot()`-only source service:
371
+ `Schedule.Source<T>`, `Netcode.Source<T>`, or browser input declared as
372
+ `InputCapture.SourceOf<...>` (a device, a `Controls` merge, or a pool; see
373
+ [the browser README](https://github.com/typeonce-dev/ritmo/blob/main/packages/browser/README.md)).
374
+ A service declared as the whole device, with `rebind` and `dispose`, is a
375
+ compile error naming that fix: a replay can only stand in for its
376
+ `snapshot()`, so the page keeps the device to rebind it.
377
+
319
378
  A replay recorded with another schema fails with "replay recorded with an
320
379
  older schema".
321
380
 
381
+ ## Verify across engines
382
+
383
+ `Verify.acrossEngines` is the one replay check. With no engines it plays
384
+ the replay twice in this process and against the recording, the check a
385
+ test runs; `ritmo-devtools verify` plays the same replay in Node and in real
386
+ browser engines and reports the first tick whose world differs, with every
387
+ value that differs there. Run it before
388
+ trusting a lockstep or rollback match across browsers, and in CI on a
389
+ committed replay of the game:
390
+
391
+ ```sh
392
+ ritmo-devtools verify src/replay-target.ts replays/boss-fight.json --engines node,chromium,webkit,firefox
393
+ # NOT verified: 1800 ticks of simulate
394
+ # node: agrees with a second node run and the recording over 1800 ticks
395
+ # chromium: agrees with node over 1800 ticks
396
+ # tick 1412: webkit differs from node in e41 Game/Position.x (40.000000000000014 -> 40)
397
+ # 1 difference (node -> webkit):
398
+ # e41 Game/Position.x: 40.000000000000014 -> 40
399
+ # firefox: not installed (the firefox browser is not downloaded): npx playwright install firefox
400
+ ```
401
+
402
+ `<entry>` exports `replayTarget`, the `make(playback)` factory
403
+ `Replay.session` takes (above). It must load in a browser too: keep Node
404
+ built-ins out of it.
405
+
406
+ ```ts
407
+ // src/replay-target.ts
408
+ export const replayTarget = (playback: Replay.Playback) => {
409
+ const hostClock = HostClock.test()
410
+ return { runtime: makeRuntime({ input: playback.source(Input), debug: { hostClock } }), schedules: { simulate }, hostClock }
411
+ }
412
+ ```
413
+
414
+ - Node always runs, as the reference: twice (a difference is
415
+ nondeterminism here) and against the recording's checkpoints (a
416
+ difference is a code change since recording, or the recording engine).
417
+ `--engines node`, the default, needs no other dependency.
418
+ - Browser engines run headless through Playwright, with the entry served by
419
+ a bare Vite dev server (the game's `vite.config` is not read). Install
420
+ them where the check runs: `npm install --save-dev playwright vite` and
421
+ `npx playwright install chromium webkit firefox`. An engine that is not
422
+ installed is printed with its install command and fails the check.
423
+ - Exit codes: 0 every engine agrees, 1 one differs or did not run, 2 usage
424
+ error (arguments, a file that is not a replay, an entry without
425
+ `replayTarget`). `--json` prints the result as JSON.
426
+
427
+ The same check from code, for a game's own test (leave out `engines` to
428
+ check this process alone):
429
+
430
+ ```ts
431
+ import { Verify } from "@typeonce/ritmo-devtools"
432
+ import * as PlaywrightEngine from "@typeonce/ritmo-devtools/PlaywrightEngine"
433
+
434
+ const browsers = PlaywrightEngine.make({ entry: "src/replay-target.ts", browsers: ["chromium", "webkit", "firefox"] })
435
+ const verified = await Verify.acrossEngines(replayTarget, file, { engines: browsers.engines })
436
+ await browsers.close()
437
+ if (!verified.ok && verified.error._tag === "NotVerified") {
438
+ for (const outcome of verified.error.outcomes) if (outcome._tag === "Diverged") console.log(outcome.tick, outcome.differences)
439
+ }
440
+ ```
441
+
442
+ The error side is `ReplayInvalid` (the replay does not open here) or
443
+ `NotVerified`, one outcome per engine: `Agreed`, `Diverged` (`tick`,
444
+ `against`, `differences`), `EngineMissing` (`install`), or `EngineFailed`.
445
+ For another host (a webview, a console), run `Verify.trace` and
446
+ `Verify.snapshotAt` there and wrap them as a `Verify.Engine`.
447
+
448
+ ## Scan dependencies
449
+
450
+ oxlint skips `node_modules`, so a dependency the simulation calls can still
451
+ use `Math.sin`, `Date.now`, or `Math.random`. `ritmo-devtools scan <entry>`
452
+ resolves every file the simulation entry imports, `node_modules` included,
453
+ and runs `ritmo/use-ops-for-math`, `ritmo/use-clock-for-time`, and
454
+ `ritmo/use-random-for-randomness` over them, grouped by package:
455
+
456
+ ```sh
457
+ ritmo-devtools scan src/simulation/index.ts
458
+ # fake-physics (2 findings)
459
+ # node_modules/fake-physics/index.js:4:17 ritmo/use-ops-for-math Math.sin
460
+ # node_modules/fake-physics/index.js:6:32 ritmo/use-random-for-randomness Math.random
461
+ #
462
+ # scanned 4 files in 2 packages imported by src/simulation/index.ts: 2 findings in 1 package
463
+ ```
464
+
465
+ - A finding is a hint, not a verdict: code the simulation never calls is
466
+ fine. For a dependency it calls, vendor it into the game's source and run
467
+ `oxlint --fix`, or replace it. A clean scan does not prove the run is
468
+ deterministic: confirm with `ritmo-devtools verify` or `Netcode.syncTest`.
469
+ - It uses the game's `oxlint` and `@typeonce/oxlint-plugin-ritmo`, and
470
+ `rolldown` to resolve imports the way a build does (Vite 8 includes it;
471
+ otherwise `npm install --save-dev rolldown`). A missing tool is printed
472
+ with its install command.
473
+ - Exit codes: 0 whenever the scan ran, with or without findings, 2 usage
474
+ error (arguments, an unreadable entry, an import that does not resolve, a
475
+ missing tool). `--json` prints
476
+ `{ entry, files, packages: [{ name, files, findings: [{ file, line, column, rule, snippet }] }] }`.
477
+
478
+ ## Fuzzing
479
+
480
+ `Fuzz.run` finds a bug before anyone plays into it: seeded random input,
481
+ run headless against the game's invariants, until an invariant breaks, a
482
+ system fails, or something throws. It then shrinks the failing input to the
483
+ few frames that still fail the same way, and returns them as a replay file.
484
+
485
+ ```ts
486
+ import { Fuzz, Replay } from "@typeonce/ritmo-devtools"
487
+ import * as ReplayNodeSink from "@typeonce/ritmo-devtools/ReplayNodeSink"
488
+
489
+ // One fuzzed snapshot() source: a value of its type for each frame, and the idle value.
490
+ const Pads = Fuzz.input(PadInput, {
491
+ generate: (random, frame) => ({ key: random.integer(0, 5), aim: random.range(-1, 1) }),
492
+ neutral: { key: 0, aim: 0 }
493
+ })
494
+ // `make` is the replay factory (above): it builds the game on playback.source(PadInput).
495
+ const found = Fuzz.run(make, {
496
+ schedule: "update", setup: "setup", // setup is ticked once first, every input neutral
497
+ inputs: [Pads], invariants: [HealthNeverNegative],
498
+ frames: 3000, runs: 10, seed: 7 // run i draws from seed 7 + i
499
+ })
500
+ if (!found.ok && found.error._tag === "Found") {
501
+ ReplayNodeSink.make({ directory: ".replays" }).save(found.error.replay)
502
+ console.log(found.error.violation) // InvariantViolated | SystemFailed | Defect
503
+ console.log(found.error.shrink) // { attempts, steps, fromFrames: 1412, toFrames: 4 }
504
+ }
505
+ ```
506
+
507
+ - A browser game fuzzes through the same descriptor its page and replays
508
+ read: `Fuzz.input(ControlsInput, { generate: (random) =>
509
+ Actions.random(random, devices), neutral: Actions.idle(devices) })` draws
510
+ merged input a real merge could report (button states, vectors of length
511
+ at most 1); `Players.random(random, frame, { devices, seats })` does it
512
+ for a local multiplayer pool.
513
+ - `random` is a seeded `Random` from `@typeonce/ritmo`; the same seed
514
+ draws the same input, so a found bug's `seed` with `runs: 1` finds it
515
+ again. Every source `make` asks `playback.source` for must be a fuzzed
516
+ input; give plain-data services (rules, config) directly.
517
+ - Shrinking drops ranges of frames, then moves each remaining value to
518
+ `neutral` (whole, then one field at a time), re-running the simulation for
519
+ every candidate. `shrinkAttempts` (500) bounds it.
520
+ - The error side is `Found` (with the shrunk `replay`, `seed`, `frame`, and
521
+ `reproduces`: whether `Replay.session` replays it to the same violation),
522
+ `Flaky` (the same input did not fail again: run `Determinism.check`),
523
+ `InvalidOptions`, or `Unreplayable` (the world after setup cannot be saved).
524
+
525
+ The shrunk replay is the regression test:
526
+
527
+ ```ts
528
+ const file = Replay.parse(JSON.parse(readFileSync(".replays/....json", "utf8")))
529
+ const opened = file.ok ? Replay.session(make, file.value, { invariants: [HealthNeverNegative] }) : file
530
+ expect(opened.ok && opened.value.play().data.run.stop.reason).toBe("completed") // fails until the fix
531
+ ```
532
+
533
+ ### Over a network
534
+
535
+ The same `Fuzz.run` fuzzes a rollback game over a faulty network. Give it one
536
+ `Fuzz.seats` input (every seat's input per frame) and `network`: each seat
537
+ plays on its own peer, a fresh `make(playback)`, joined by a seeded
538
+ `MemoryNetworkLink` and driven by a `Netcode.rollback` session from
539
+ [`@typeonce/ritmo-netcode`](https://github.com/typeonce-dev/ritmo/blob/main/packages/netcode/README.md).
540
+
541
+ ```ts
542
+ // The seats service the simulation captures; make provides it with playback.source(Seats).
543
+ const Players = Fuzz.seats(Seats, {
544
+ codec: PlayerInput, count: 2, idle: { dx: 0, fire: false }, // as given to Netcode.seats
545
+ generate: (random, frame, seat) => ({ dx: random.integer(-1, 2), fire: random.next() < 0.2 })
546
+ })
547
+ const found = Fuzz.run(make, {
548
+ schedule: "simulate", setup: "setup", inputs: [Players], invariants: [HealthNeverNegative],
549
+ frames: 600, seed: 7,
550
+ network: { seed: 3, latencyMS: 60, jitterMS: 40, loss: 0.1, step } // faults repeat for the same seed
551
+ })
552
+ if (!found.ok && found.error._tag === "Found" && found.error.violation._tag === "SessionFailed") {
553
+ console.log(found.error.violation.seat, found.error.violation.error) // Desynced, with this peer's save of the tick
554
+ }
555
+ ```
556
+
557
+ - A session failure (`Desynced`, `TickFailed`, `CheckpointLost`, or the
558
+ session ending) is a `SessionFailed` violation; invariants are checked on
559
+ every peer after each frame. `settle` idle frames (120) follow the fuzzed
560
+ ones so late input and checksums arrive; checksums are compared every 10
561
+ ticks unless `checksumEvery` says otherwise.
562
+ - Shrinking keeps the network seed and shrinks the input timeline, one seat
563
+ at a time. The `replay` plays the shrunk timeline on one runtime (step it
564
+ to see each tick); `reproduces` is `false` for a desync, which needs two
565
+ peers: find it again with the same `seed`, `runs: 1`, and `network`.
566
+ - A `simulate` that cannot be rewound, or a runtime that cannot save, does
567
+ not compile, as for `Netcode.rollback`. Run `Netcode.syncTest` first: it
568
+ finds state a rewind cannot put back on one peer, faster.
569
+
322
570
  ## Recording a browser session
323
571
 
324
572
  ```ts
package/dist/Desync.d.ts CHANGED
@@ -5,31 +5,51 @@
5
5
  * A `Netcode` session made with `keepSnapshots: true` fails with `Desynced`
6
6
  * carrying this peer's save of the tick whose checksums differ; the other
7
7
  * peer's session carries its own. `compare(mine, theirs)` lists every
8
- * difference, entities by id and values by path, so an agent can see which
8
+ * difference, entities by id (and label, given `labels`) and values by path, so an agent can see which
9
9
  * component or resource went apart first, then find the system that wrote
10
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.
11
13
  *
12
14
  * @module Desync
13
15
  * @docGroup devtools
14
16
  *
15
17
  * @example
16
18
  * ```ts
19
+ * declare const sessions: readonly [Netcode.Session<{ dx: number }, unknown>, Netcode.Session<{ dx: number }, unknown>]
20
+ * declare const input: { dx: number }
21
+ * const Labels = Game.Inspector("labels", {
22
+ * queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
23
+ * }, ({ queries }) => new Map(queries.players.each().map((match) => [match.entity.id, "player"] as const)))
24
+ * // ---cut---
17
25
  * const left = sessions[0].advance(input)
18
26
  * const right = sessions[1].advance(input)
19
27
  * if (!left.ok && left.error._tag === "Desynced" && !right.ok && right.error._tag === "Desynced") {
20
- * console.log(Desync.compare(left.error.snapshot!, right.error.snapshot!))
28
+ * console.log(Desync.compare(left.error.snapshot!, right.error.snapshot!, { labels: runtime.inspect(Labels) }))
21
29
  * }
22
30
  * ```
23
31
  */
24
32
  import type * as Snapshot from "@typeonce/ritmo/Snapshot";
33
+ import * as Format from "./Format.ts";
25
34
  import * as Rendered from "./Rendered.ts";
26
35
  /** One value that differs: where, and each side's (`undefined`: absent on that side). */
27
36
  export interface Difference {
28
37
  /** `nextEntity`, `entity 12`, `entity 12 Game/Position.x`, `resource Game/Score`, `machine Game/Round`, `relation Game/ChildOf`, or `scope Game/Wave`. */
29
38
  readonly path: string;
39
+ /** The entity the difference is in, when it is in one. */
40
+ readonly entity: number | undefined;
30
41
  readonly mine: unknown;
31
42
  readonly theirs: unknown;
32
43
  }
44
+ /** How `compare` prints. */
45
+ export interface CompareOptions {
46
+ /**
47
+ * Names entities in the text (`player e12 Game/Position.x`): the map the
48
+ * session's `labels` inspector returns, read with `runtime.inspect(Labels)`
49
+ * on either peer. Without it entities print as `e12`.
50
+ */
51
+ readonly labels?: Format.Labels;
52
+ }
33
53
  /** Every difference between two saves, in a stable order: the next id, entities by id, then resources, machines, relations, and scopes by name. */
34
- export declare const compare: (mine: Snapshot.WorldSnapshot, theirs: Snapshot.WorldSnapshot) => Rendered.Rendered<ReadonlyArray<Difference>>;
54
+ export declare const compare: (mine: Snapshot.WorldSnapshot, theirs: Snapshot.WorldSnapshot, options?: CompareOptions) => Rendered.Rendered<ReadonlyArray<Difference>>;
35
55
  //# sourceMappingURL=Desync.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Desync.d.ts","sourceRoot":"","sources":["../src/Desync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,KAAK,QAAQ,MAAM,0BAA0B,CAAA;AAGzD,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,0JAA0J;IAC1J,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AA4BD,mJAAmJ;AACnJ,eAAO,MAAM,OAAO,SAAU,QAAQ,CAAC,aAAa,UAAU,QAAQ,CAAC,aAAa,KAAG,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAmBjI,CAAA"}
1
+ {"version":3,"file":"Desync.d.ts","sourceRoot":"","sources":["../src/Desync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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 CHANGED
@@ -2,48 +2,50 @@ import * as Format from "./Format.js";
2
2
  import * as Rendered from "./Rendered.js";
3
3
  const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
4
4
  /** The leaves where two values differ, under `path`. */
5
- const differences = (path, mine, theirs, into) => {
5
+ const differences = (path, entity, mine, theirs, into) => {
6
6
  if (Format.sameValue(mine, theirs))
7
7
  return;
8
8
  if (isRecord(mine) && isRecord(theirs)) {
9
9
  for (const key of [...new Set([...Object.keys(mine), ...Object.keys(theirs)])].sort()) {
10
- differences(`${path}.${key}`, mine[key], theirs[key], into);
10
+ differences(`${path}.${key}`, entity, mine[key], theirs[key], into);
11
11
  }
12
12
  return;
13
13
  }
14
14
  if (Array.isArray(mine) && Array.isArray(theirs) && mine.length === theirs.length) {
15
- mine.forEach((item, index) => differences(`${path}[${index}]`, item, theirs[index], into));
15
+ mine.forEach((item, index) => differences(`${path}[${index}]`, entity, item, theirs[index], into));
16
16
  return;
17
17
  }
18
- into.push({ path, mine, theirs });
18
+ into.push({ path, entity, mine, theirs });
19
19
  };
20
20
  /** Each named entry of two records, compared under `kind name`. */
21
- const byName = (kind, mine, theirs, into) => {
21
+ const byName = (kind, entity, mine, theirs, into) => {
22
22
  for (const name of [...new Set([...Object.keys(mine), ...Object.keys(theirs)])].sort()) {
23
- differences(`${kind} ${name}`, mine[name], theirs[name], into);
23
+ differences(`${kind} ${name}`, entity, mine[name], theirs[name], into);
24
24
  }
25
25
  };
26
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) => {
27
+ export const compare = (mine, theirs, options = {}) => {
28
28
  const found = [];
29
- differences("nextEntity", mine.nextEntity, theirs.nextEntity, found);
29
+ differences("nextEntity", undefined, mine.nextEntity, theirs.nextEntity, found);
30
30
  const mineById = new Map(mine.entities.map((entity) => [entity.id, entity.components]));
31
31
  const theirsById = new Map(theirs.entities.map((entity) => [entity.id, entity.components]));
32
32
  for (const id of [...new Set([...mineById.keys(), ...theirsById.keys()])].sort((a, b) => a - b)) {
33
33
  const left = mineById.get(id);
34
34
  const right = theirsById.get(id);
35
35
  if (left === undefined || right === undefined)
36
- found.push({ path: `entity ${id}`, mine: left, theirs: right });
36
+ found.push({ path: `entity ${id}`, entity: id, mine: left, theirs: right });
37
37
  else
38
- byName(`entity ${id}`, left, right, found);
38
+ byName(`entity ${id}`, id, left, right, found);
39
39
  }
40
- byName("resource", mine.resources, theirs.resources, found);
41
- byName("machine", mine.machines, theirs.machines, found);
42
- byName("relation", mine.relations, theirs.relations, found);
43
- byName("scope", mine.scopes, theirs.scopes, found);
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)}`;
44
46
  const text = found.length === 0
45
47
  ? "The saves are equal."
46
- : [`${found.length} difference${found.length === 1 ? "" : "s"} (mine -> theirs):`, ...found.map(({ path, mine, theirs }) => ` ${path}: ${Format.value(mine)} -> ${Format.value(theirs)}`)].join("\n");
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");
47
49
  return Rendered.make(found, text);
48
50
  };
49
51
  //# sourceMappingURL=Desync.js.map