@typeonce/ritmo-devtools 0.22.0 → 0.24.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 (54) hide show
  1. package/CHANGELOG.md +83 -0
  2. package/README.md +61 -10
  3. package/dist/Desync.d.ts +2 -2
  4. package/dist/Desync.d.ts.map +1 -1
  5. package/dist/Desync.js +2 -1
  6. package/dist/Desync.js.map +1 -1
  7. package/dist/Format.d.ts +8 -1
  8. package/dist/Format.d.ts.map +1 -1
  9. package/dist/Format.js +13 -2
  10. package/dist/Format.js.map +1 -1
  11. package/dist/Fuzz.d.ts +12 -5
  12. package/dist/Fuzz.d.ts.map +1 -1
  13. package/dist/Fuzz.js +8 -1
  14. package/dist/Fuzz.js.map +1 -1
  15. package/dist/Replay.d.ts +50 -13
  16. package/dist/Replay.d.ts.map +1 -1
  17. package/dist/Replay.js +59 -8
  18. package/dist/Replay.js.map +1 -1
  19. package/dist/Session.d.ts +7 -15
  20. package/dist/Session.d.ts.map +1 -1
  21. package/dist/Session.js +41 -3
  22. package/dist/Session.js.map +1 -1
  23. package/dist/Verify.d.ts +11 -2
  24. package/dist/Verify.d.ts.map +1 -1
  25. package/dist/Verify.js +12 -7
  26. package/dist/Verify.js.map +1 -1
  27. package/dist/cli.js +19 -6
  28. package/dist/cli.js.map +1 -1
  29. package/dist/internal/packageVersions.d.ts +28 -0
  30. package/dist/internal/packageVersions.d.ts.map +1 -0
  31. package/dist/internal/packageVersions.js +144 -0
  32. package/dist/internal/packageVersions.js.map +1 -0
  33. package/dist/internal/replayStart.d.ts +18 -0
  34. package/dist/internal/replayStart.d.ts.map +1 -0
  35. package/dist/internal/replayStart.js +16 -0
  36. package/dist/internal/replayStart.js.map +1 -0
  37. package/dist/internal/skillLink.d.ts +1 -9
  38. package/dist/internal/skillLink.d.ts.map +1 -1
  39. package/dist/internal/skillLink.js +29 -6
  40. package/dist/internal/skillLink.js.map +1 -1
  41. package/dist/internal/version.d.ts +1 -1
  42. package/dist/internal/version.js +1 -1
  43. package/package.json +3 -3
  44. package/src/Desync.ts +3 -2
  45. package/src/Format.ts +15 -2
  46. package/src/Fuzz.ts +17 -5
  47. package/src/Replay.ts +104 -17
  48. package/src/Session.ts +41 -34
  49. package/src/Verify.ts +21 -9
  50. package/src/cli.ts +18 -6
  51. package/src/internal/packageVersions.ts +150 -0
  52. package/src/internal/replayStart.ts +16 -0
  53. package/src/internal/skillLink.ts +31 -8
  54. package/src/internal/version.ts +1 -1
package/src/Replay.ts CHANGED
@@ -16,9 +16,17 @@
16
16
  * playtester's "save replay" button, call `recorder.save(reason)` from a
17
17
  * key or button handler in the host.
18
18
  * - `session(make, file, { invariants })` restores the start and replays
19
- * the ticks in a normal devtools `Session`; `verify` replays twice and compares the
20
- * checkpoint hashes to find nondeterminism; `extract` cuts a range of
19
+ * the ticks in a normal devtools `Session`; `extract` cuts a range of
21
20
  * ticks into a small replay with its own start, for a test.
21
+ * `Verify.acrossEngines` replays twice and compares the checksums to find
22
+ * nondeterminism.
23
+ *
24
+ * A window that starts at tick 0, the world when the recorder started, is
25
+ * compared with the recording's checksums. Once it rolls past tick 0 it
26
+ * starts from a save, which does not hold what the game still had in flight
27
+ * (events not yet read, what each `added()` / `changed()` reader had already
28
+ * seen), so its checksums are not compared: such a replay is for reproducing
29
+ * and inspecting a bug. `Determinism.check` verifies determinism.
22
30
  *
23
31
  * Every service the recorded schedule needs must be a `snapshot()` source of
24
32
  * plain data (input) or plain data itself (rules, config); anything else is
@@ -64,6 +72,7 @@ import type * as Snapshot from "@typeonce/ritmo/Snapshot"
64
72
 
65
73
  import * as Format from "./Format.ts"
66
74
  import type { Invariant } from "./Invariant.ts"
75
+ import { savedStart } from "./internal/replayStart.ts"
67
76
  import { libraryVersion } from "./internal/version.ts"
68
77
  import * as Rendered from "./Rendered.ts"
69
78
  import * as Session from "./Session.ts"
@@ -119,7 +128,11 @@ export interface ReplayFile {
119
128
  readonly savedAt: number
120
129
  /** Services that are plain data, as they were (rules, config). */
121
130
  readonly constants: Readonly<Record<string, unknown>>
122
- /** The world at the end of tick `start.tick`; replay starts with the tick after it. */
131
+ /**
132
+ * The world at the end of tick `start.tick`; replay starts with the tick after it.
133
+ * Tick 0 is the world when the recorder started; a later tick is a save the
134
+ * rolling window moved to, and a replay from it does not compare checksums.
135
+ */
123
136
  readonly start: {
124
137
  readonly tick: number
125
138
  readonly snapshot: Snapshot.WorldSnapshot
@@ -157,7 +170,10 @@ export interface RecorderOptions<S extends Schema.Any, Root, Recorded extends An
157
170
  readonly schedule: Recorded
158
171
  /** Its name in the file and in the replay's session. */
159
172
  readonly name: string
160
- /** Seconds of play to keep. */
173
+ /**
174
+ * Seconds of play to keep. Once a run is longer, the window starts from a
175
+ * later save, and a replay of it does not compare checksums (see `PlayResult`).
176
+ */
161
177
  readonly keep: number
162
178
  /** The schedule's fixed step (`Clock.hz(...)`), the same the game's clock runs at. */
163
179
  readonly step: Clock.Step
@@ -260,8 +276,14 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
260
276
  let tick = 0
261
277
  let sent: Array<{ readonly event: string; readonly value: unknown }> = []
262
278
  let ticks: Array<TickRecord> = []
263
- /** Snapshot points still needed: the newest one at or before the window start, and every later one. */
264
- let points: Array<{ readonly tick: number; readonly snapshot: Snapshot.WorldSnapshot; readonly pendingCommands: number }> = []
279
+ /**
280
+ * Snapshot points still needed: the newest one at or before the window
281
+ * start, and every later one. `at` is the runtime's change tick then, for
282
+ * `rewind`.
283
+ */
284
+ let points: Array<{ readonly tick: number; readonly snapshot: Snapshot.WorldSnapshot; readonly pendingCommands: number; readonly at: number }> = []
285
+ /** The change tick each recorded tick of the window started at, for `rewind`. */
286
+ let starts: Array<{ readonly tick: number; readonly at: number }> = []
265
287
  let checkpoints: Array<{ readonly tick: number; readonly hash: string }> = []
266
288
  const previous = new Map<string, string>()
267
289
  const broken = new Set<string>()
@@ -270,7 +292,8 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
270
292
  const snapshot = runtime.snapshot()
271
293
  // A tick whose world a `"~encode"` rejects is no starting point; the window keeps the previous one.
272
294
  if (!snapshot.ok) return
273
- points.push({ tick, snapshot: snapshot.value, pendingCommands: runtime.debug.dump({ limit: 0 }).pendingCommands.length })
295
+ const dumped = runtime.debug.dump({ limit: 0 })
296
+ points.push({ tick, snapshot: snapshot.value, pendingCommands: dumped.pendingCommands.length, at: dumped.tick })
274
297
  const checksum = runtime.checksum()
275
298
  checkpoints.push({ tick, hash: worldHash(checksum) })
276
299
  const windowStart = tick - keepTicks
@@ -285,6 +308,7 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
285
308
  const carried: Record<string, ReadonlyArray<unknown>> = {}
286
309
  for (const record of ticks) if (record.tick <= start && record.services !== undefined) Object.assign(carried, record.services)
287
310
  ticks = ticks.filter((record) => record.tick > start)
311
+ starts = starts.filter((entry) => entry.tick > start)
288
312
  const first = ticks[0]
289
313
  if (first !== undefined && Object.keys(carried).length > 0) {
290
314
  ticks[0] = { ...first, services: { ...carried, ...first.services } }
@@ -294,9 +318,41 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
294
318
  }
295
319
  takePoint()
296
320
 
321
+ /**
322
+ * A rewind to a checkpoint at change tick `toTick` undid the recorded
323
+ * ticks that started at or after it, and the game runs them again: forget
324
+ * them, so the file keeps each tick's last run. The host's sends they
325
+ * carried are still unread after the rewind, so the next tick carries
326
+ * them. A rewind past every snapshot point starts the window again here.
327
+ */
328
+ const rewind = (toTick: number): void => {
329
+ const undone = starts.findIndex((entry) => entry.at >= toTick)
330
+ if (undone === -1) return
331
+ const back = starts[undone]!.tick - 1
332
+ sent = [...ticks.filter((record) => record.tick > back).flatMap((record) => record.sent ?? []), ...sent]
333
+ tick = back
334
+ ticks = ticks.filter((record) => record.tick <= back)
335
+ starts = starts.slice(0, undone)
336
+ checkpoints = checkpoints.filter((checkpoint) => checkpoint.tick <= back)
337
+ points = points.filter((point) => point.tick <= back && point.at <= toTick)
338
+ // Service values are stored as changes from the previous kept tick.
339
+ previous.clear()
340
+ for (const record of ticks) {
341
+ for (const [name, values] of Object.entries(record.services ?? {})) previous.set(name, JSON.stringify(values))
342
+ }
343
+ if (points.length === 0) {
344
+ ticks = []
345
+ starts = []
346
+ checkpoints = []
347
+ previous.clear()
348
+ takePoint()
349
+ }
350
+ }
351
+
297
352
  const save = (reason: string): ReplayFile => {
298
- const start = points[0]
299
- if (start === undefined) throw new Error("no tick of this run could be saved: a `~encode` rejected the world every time (see runtime.snapshot())")
353
+ const point = points[0]
354
+ if (point === undefined) throw new Error("no tick of this run could be saved: a `~encode` rejected the world, or commands were queued (end the schedule with applyDeferred()), every time (see runtime.snapshot())")
355
+ const start = { tick: point.tick, snapshot: point.snapshot, pendingCommands: point.pendingCommands }
300
356
  const file: ReplayFile = {
301
357
  format: "ritmo-replay",
302
358
  version: 1,
@@ -325,9 +381,14 @@ export const recorder = <S extends Schema.Any, Root, const Recorded extends AnyS
325
381
  if (options.saveOn?.failure === true) save(Format.ignoredFailure(event))
326
382
  return
327
383
  }
384
+ if (event.type === "rewind") {
385
+ if (event.ok) rewind(event.toTick)
386
+ return
387
+ }
328
388
  if (!event.schedules.includes(options.schedule)) return
329
389
  if (event.type === "tick.start") {
330
390
  tick += 1
391
+ starts.push({ tick, at: event.tick })
331
392
  current = new Map()
332
393
  return
333
394
  }
@@ -471,12 +532,36 @@ export interface SessionOptions<
471
532
  readonly labels?: Labels
472
533
  }
473
534
 
474
- /** What one `ReplaySession.play` did: the session run, and the checkpoints that differ. */
535
+ /** A recorded checkpoint whose hash differs in the replay. */
536
+ export interface Divergence {
537
+ readonly tick: number
538
+ readonly recorded: string
539
+ readonly replayed: string
540
+ }
541
+
542
+ /**
543
+ * Whether `play` compared the replay's checksums with the recording's.
544
+ *
545
+ * - `Compared`: the replay starts at tick 0, where the recorded run did.
546
+ * `diverged` lists the checkpoints whose hash differs, empty when every one
547
+ * matches. A difference is nondeterminism, a code change since recording,
548
+ * or something in flight when the recorder started (an event emitted by a
549
+ * schedule ticked before it).
550
+ * - `NotCompared`: the replay starts from a save of a later tick (a rolling
551
+ * window). A save does not hold events in flight or what each reader had
552
+ * already seen, so an ordinary game replays to other checksums from it;
553
+ * `reason` says so. The replay still plays and its session explains it.
554
+ * Check determinism with `Determinism.check`, or a replay recorded from tick 0.
555
+ */
556
+ export type Checkpoints =
557
+ | { readonly _tag: "Compared"; readonly diverged: ReadonlyArray<Divergence> }
558
+ | { readonly _tag: "NotCompared"; readonly reason: string }
559
+
560
+ /** What one `ReplaySession.play` did: the session run, and how its checksums compare with the recording's. */
475
561
  export interface PlayResult {
476
562
  /** The session's run of the replayed ticks. */
477
563
  readonly run: Session.RunResult
478
- /** Recorded checkpoints whose hash differs in this replay: the simulation is not deterministic, or the code changed. */
479
- readonly diverged: ReadonlyArray<{ readonly tick: number; readonly recorded: string; readonly replayed: string }>
564
+ readonly checkpoints: Checkpoints
480
565
  }
481
566
 
482
567
  /** An opened replay, from `session`, restored to its start and ready to `play`. */
@@ -484,7 +569,7 @@ export interface ReplaySession<S extends Schema.Any, Names extends string> {
484
569
  /** The devtools session the ticks run in: `why`, `journal`, `report` work as in any run. */
485
570
  readonly session: Session.Session<S, Names>
486
571
  readonly file: ReplayFile
487
- /** Replays the recorded ticks (up to `to`, the recorder's tick number) and compares checkpoints. */
572
+ /** Replays the recorded ticks (up to `to`, the recorder's tick number) and compares checkpoints when the replay starts at tick 0. */
488
573
  readonly play: (options?: { readonly to?: number }) => Rendered.Rendered<PlayResult>
489
574
  /** Hashes of the world at the end of each replayed tick so far. */
490
575
  readonly hashes: () => ReadonlyMap<number, string>
@@ -559,12 +644,13 @@ export const session = <
559
644
  const startChecksum = target.runtime.checksum()
560
645
  const hashes = new Map<number, string>([[ran, worldHash(startChecksum)]])
561
646
  const recorded = new Map(file.checkpoints.map(({ tick, hash }) => [tick, hash] as const))
647
+ const notCompared = savedStart(file)
562
648
  const last = file.ticks.at(-1)?.tick ?? file.start.tick
563
649
 
564
650
  const play = (options: { readonly to?: number } = {}): Rendered.Rendered<PlayResult> => {
565
651
  const to = Math.min(options.to ?? last, last)
566
652
  const frames = Math.max(0, to - ran)
567
- const diverged: Array<{ readonly tick: number; readonly recorded: string; readonly replayed: string }> = []
653
+ const diverged: Array<Divergence> = []
568
654
  const run = replay.run(file.schedule, {
569
655
  frames,
570
656
  // `until` runs after each frame: the tick is checked, and the next one's input set up before it runs.
@@ -574,14 +660,15 @@ export const session = <
574
660
  const hash = worldHash(checksum)
575
661
  hashes.set(ran, hash)
576
662
  const expected = recorded.get(ran)
577
- if (expected !== undefined && expected !== hash) diverged.push({ tick: ran, recorded: expected, replayed: hash })
663
+ if (notCompared === undefined && expected !== undefined && expected !== hash) diverged.push({ tick: ran, recorded: expected, replayed: hash })
578
664
  prepare(ran + 1)
579
665
  return false
580
666
  }
581
667
  })
582
- return Rendered.make({ run: run.data, diverged }, diverged.length === 0
668
+ if (notCompared !== undefined) return Rendered.make({ run: run.data, checkpoints: { _tag: "NotCompared", reason: notCompared } }, `${run.text}\n${notCompared}`)
669
+ return Rendered.make({ run: run.data, checkpoints: { _tag: "Compared", diverged } }, diverged.length === 0
583
670
  ? `${run.text}\ncheckpoints match`
584
- : `${run.text}\nDIVERGED at ${diverged.map((entry) => `tick ${entry.tick}`).join(", ")}: the simulation is not deterministic, or the code changed since recording`)
671
+ : `${run.text}\nDIVERGED at ${diverged.map((entry) => `tick ${entry.tick}`).join(", ")}: the simulation is not deterministic, the code changed since recording, or something was in flight when the recorder started (an event a schedule ticked before it emitted)`)
585
672
  }
586
673
 
587
674
  /** Sets up tick `next`: its sends, and its sources' values. */
package/src/Session.ts CHANGED
@@ -94,29 +94,16 @@ export interface Target<
94
94
  readonly machineValues: Machines
95
95
  }
96
96
 
97
- type InvariantRequirementErrors<
98
- Invariants extends ReadonlyArray<Invariant>,
99
- Services extends Record<string, unknown>,
100
- Resources extends object,
101
- Machines extends Record<string, unknown>
102
- > = Runtime.ValidateInspector<Invariants[number]["inspector"], Services, Resources, Machines> extends {
103
- readonly __fixRuntimeRequirements__: infer Errors
104
- }
105
- ? Errors
106
- : never
107
-
108
97
  /**
109
98
  * Rejects invariants whose inspectors read a resource, service, or machine
110
- * the runtime does not provide, naming each one.
99
+ * the runtime does not provide, naming each one (as `runtime.inspect` does).
111
100
  */
112
101
  export type ValidateInvariants<
113
102
  Invariants extends ReadonlyArray<Invariant>,
114
103
  Services extends Record<string, unknown>,
115
104
  Resources extends object,
116
105
  Machines extends Record<string, unknown>
117
- > = [InvariantRequirementErrors<Invariants, Services, Resources, Machines>] extends [never]
118
- ? unknown
119
- : { readonly __fixInvariantRequirements__: InvariantRequirementErrors<Invariants, Services, Resources, Machines> }
106
+ > = Runtime.ValidateInspector<Invariants[number]["inspector"], Services, Resources, Machines>
120
107
 
121
108
  /**
122
109
  * Names entities in devtools text: a `Game.Inspector` returning a
@@ -135,17 +122,6 @@ export type ValidateInvariants<
135
122
  */
136
123
  export type LabelsInspector<Root = any> = Inspector.InspectorDefinition<any, unknown, Root, any, any>
137
124
 
138
- type LabelsRequirementErrors<
139
- Labels extends Inspector.Inspector.Any,
140
- Services extends Record<string, unknown>,
141
- Resources extends object,
142
- Machines extends Record<string, unknown>
143
- > = Runtime.ValidateInspector<Labels, Services, Resources, Machines> extends {
144
- readonly __fixRuntimeRequirements__: infer Errors
145
- }
146
- ? Errors
147
- : never
148
-
149
125
  /**
150
126
  * Rejects a `labels` inspector that does not return a
151
127
  * `ReadonlyMap<number, string>`, or that reads a resource, service, or
@@ -159,9 +135,7 @@ export type ValidateLabels<
159
135
  > = [Labels] extends [never]
160
136
  ? unknown
161
137
  : [Inspector.Inspector.Value<Labels>] extends [ReadonlyMap<number, string>]
162
- ? [LabelsRequirementErrors<Labels, Services, Resources, Machines>] extends [never]
163
- ? unknown
164
- : { readonly __fixLabelsRequirements__: LabelsRequirementErrors<Labels, Services, Resources, Machines> }
138
+ ? Runtime.ValidateInspector<Labels, Services, Resources, Machines>
165
139
  : { readonly __fixLabels__: "labels must return a ReadonlyMap<number, string> from entity id to label" }
166
140
 
167
141
  /** What `Session.make` drives and checks, and how it prints. */
@@ -298,7 +272,7 @@ export interface JournalFilter<S extends Schema.Any> {
298
272
  /** Schedule path prefix, for example `update`. */
299
273
  readonly schedule?: string
300
274
  readonly kinds?: ReadonlyArray<Format.LineKind>
301
- /** Keep only the most recent `n` lines. */
275
+ /** Keep only the most recent `n` lines, and the rewinds between and after them. */
302
276
  readonly limit?: number
303
277
  /**
304
278
  * Include lines that record no change (equal-value writes, transitions to
@@ -356,7 +330,7 @@ export interface SystemStats {
356
330
  readonly failures: number
357
331
  /** Runs skipped by a `when` condition (the messages published meanwhile were discarded). */
358
332
  readonly skips: number
359
- /** Runs paused by a `pauseWhen` condition (the messages published meanwhile were held). */
333
+ /** Runs paused by a `pauseWhile` condition (the messages published meanwhile were held). */
360
334
  readonly pauses: number
361
335
  readonly totalMs: number
362
336
  readonly maxMs: number
@@ -398,6 +372,8 @@ export interface Report {
398
372
  readonly lints: ReadonlyArray<Debug.Lint>
399
373
  /** Live entities and entities per component now. */
400
374
  readonly population: Debug.Population
375
+ /** Rewinds to a checkpoint in the session (rejected ones not counted); `journal({ kinds: ["rewind"] })` lists those still in history. */
376
+ readonly rewinds: number
401
377
  }
402
378
 
403
379
  /** What `session.system(name)` shows: the system's declared access, its stats, and its recent journal lines. */
@@ -623,6 +599,9 @@ export const make = <
623
599
  const history: Array<FrameRecord> = []
624
600
  let current: FrameRecord = { frame: debug.frame(), events: [] }
625
601
  history.push(current)
602
+ /** Per rewind, the frames in history it undid. */
603
+ const undone = new WeakMap<Debug.RewindEvent, readonly [number, number]>()
604
+ let rewinds = 0
626
605
 
627
606
  const stats = new Map<string, { runs: number; failures: number; skips: number; pauses: number; totalMs: number; maxMs: number }>()
628
607
  const statsOf = (system: string) => {
@@ -836,6 +815,17 @@ export const make = <
836
815
  warn("transition-failed", `transition:${event.machine}:${String(event.from)}:${String(event.to)}`, `transition ${Format.transition(event)} ${event.outcome}`, event.frame)
837
816
  }
838
817
  break
818
+ case "rewind": {
819
+ if (!event.ok) break
820
+ rewinds += 1
821
+ // The frames that started at or after the checkpoint's tick.
822
+ const first = history.find((entry) => {
823
+ const start = entry.events[0]
824
+ return start?.type === "frame" && start.tick >= event.toTick
825
+ })
826
+ if (first !== undefined) undone.set(event, [first.frame, event.frame])
827
+ break
828
+ }
839
829
  // A frame starts above; schedule bounds and restores carry nothing to check.
840
830
  case "frame":
841
831
  case "schedule.start":
@@ -1153,6 +1143,13 @@ export const make = <
1153
1143
  const labels = labelsAt(entry.frame)
1154
1144
  for (const event of entry.events) {
1155
1145
  const position = at++
1146
+ if (event.type === "rewind") {
1147
+ // A rewind undid the lines before it, whatever they are about.
1148
+ const [line] = Format.lines(event, format, labels)
1149
+ if (line!.noop && filter.verbose !== true) hidden += 1
1150
+ else result.push({ line: { ...line!, text: Format.rewind(event, undone.get(event)) }, at: position })
1151
+ continue
1152
+ }
1156
1153
  for (const line of Format.lines(event, format, labels)) {
1157
1154
  if (filter.entity !== undefined && line.entity !== filter.entity) continue
1158
1155
  if (subject !== undefined && line.subject !== subject && !(line.kind === "effect" && line.subject === undefined && filter.entity !== undefined)) continue
@@ -1167,7 +1164,15 @@ export const make = <
1167
1164
  }
1168
1165
  }
1169
1166
  }
1170
- return filter.limit === undefined ? result : result.slice(-filter.limit)
1167
+ if (filter.limit === undefined || filter.limit === 0) return result
1168
+ // The last `limit` lines that are not rewinds, with the rewinds after the first of them.
1169
+ let from = result.length
1170
+ for (let kept = 0; from > 0 && kept < filter.limit;) {
1171
+ from -= 1
1172
+ if (result[from]!.line.kind !== "rewind") kept += 1
1173
+ }
1174
+ while (from < result.length && result[from]!.line.kind === "rewind") from += 1
1175
+ return result.slice(from)
1171
1176
  }
1172
1177
 
1173
1178
  const renderLines = (header: string, lines: ReadonlyArray<Format.Line>): string =>
@@ -1525,9 +1530,11 @@ export const make = <
1525
1530
  })),
1526
1531
  streams: debug.streams().filter((stream) => stream.heldBy !== undefined || stream.readers.some((reader) => reader.lagged)),
1527
1532
  lints: debug.describe().lints,
1528
- population: debug.population()
1533
+ population: debug.population(),
1534
+ rewinds
1529
1535
  }
1530
- const lines = [`${data.frames} frames run (${rangeText()})`, "", ...Format.lintLines(data.lints), "", "# Systems (by total time)"]
1536
+ const rewound = rewinds === 0 ? "" : `; ${rewinds} rewinds to a checkpoint (journal({ kinds: ["rewind"] }) lists them)`
1537
+ const lines = [`${data.frames} frames run (${rangeText()})${rewound}`, "", ...Format.lintLines(data.lints), "", "# Systems (by total time)"]
1531
1538
  for (const entry of systems) {
1532
1539
  lines.push(`${entry.system}: ${entry.runs} runs, avg ${Format.value(entry.runs === 0 ? 0 : entry.totalMs / entry.runs)}ms, max ${Format.value(entry.maxMs)}ms${entry.failures > 0 ? `, ${entry.failures} failures` : ""}${entry.skips > 0 ? `, ${entry.skips} skips` : ""}${entry.pauses > 0 ? `, ${entry.pauses} pauses` : ""}`)
1533
1540
  }
package/src/Verify.ts CHANGED
@@ -7,7 +7,9 @@
7
7
  *
8
8
  * - `acrossEngines(make, file, { engines })` plays the replay twice here
9
9
  * (the reference, and a repeat of it), compares the reference with the
10
- * recording's checkpoints, then with each engine's per-tick checksums. On
10
+ * recording's checkpoints (when the replay starts at tick 0: a rolling
11
+ * window's later start is a save, which does not hold events in flight,
12
+ * see `Replay.Checkpoints`), then with each engine's per-tick checksums. On
11
13
  * the first tick an engine differs, it loads both worlds at that tick and
12
14
  * names every differing value, as `Desync.compare` does.
13
15
  * - An `Engine` is any place that can run the game: `PlaywrightEngine`
@@ -43,6 +45,7 @@ import type * as Snapshot from "@typeonce/ritmo/Snapshot"
43
45
 
44
46
  import * as Desync from "./Desync.ts"
45
47
  import * as Format from "./Format.ts"
48
+ import { savedStart } from "./internal/replayStart.ts"
46
49
  import * as Rendered from "./Rendered.ts"
47
50
  import * as Replay from "./Replay.ts"
48
51
 
@@ -135,9 +138,16 @@ export interface Diverged {
135
138
  /** What one engine's check found. */
136
139
  export type Outcome = Agreed | Diverged | EngineError
137
140
 
138
- /** Every engine agreed: the replay is deterministic here, matches its recording, and plays the same everywhere. */
141
+ /** Every engine agreed: the replay is deterministic here, matches its recording (or says why it was not compared), and plays the same everywhere. */
139
142
  export interface Verified {
140
143
  readonly schedule: string
144
+ /**
145
+ * `matched`: the reference run reached every checkpoint of the recording.
146
+ * `notCompared`: the replay starts from a save of a later tick (a rolling
147
+ * window), which does not hold events in flight, so the recording's
148
+ * checkpoints were not compared; the runs here and in each engine were.
149
+ */
150
+ readonly recording: "matched" | "notCompared"
141
151
  /** Ticks compared, the start's tick not counted. */
142
152
  readonly ticks: number
143
153
  /** `node` first, then each engine. */
@@ -201,7 +211,8 @@ export const acrossEngines = async <S extends Schema.Any, Root>(
201
211
  const repeat = trace(make, file)
202
212
  const repeated = repeat.ok ? firstDifference(reference.value, repeat.value) : undefined
203
213
  // As `Replay.session` does, the recording is compared on the replayed ticks, not on the start it restores.
204
- const checkpoints = file.checkpoints.filter(({ tick }) => tick > file.start.tick)
214
+ const notCompared = savedStart(file)
215
+ const checkpoints = notCompared === undefined ? file.checkpoints.filter(({ tick }) => tick > file.start.tick) : []
205
216
  const recorded = firstDifference(reference.value.filter(({ tick }) => checkpoints.some((checkpoint) => checkpoint.tick === tick)), checkpoints)
206
217
  if (!repeat.ok) {
207
218
  outcomes.push({ _tag: "EngineFailed", engine: "node", message: `a second run did not open: ${JSON.stringify(repeat.error)}` })
@@ -224,11 +235,12 @@ export const acrossEngines = async <S extends Schema.Any, Root>(
224
235
  if (outcomes.every((outcome) => outcome._tag === "Agreed")) {
225
236
  const engines = outcomes.map((outcome) => outcome.engine)
226
237
  return Result.success(Rendered.make(
227
- { schedule: file.schedule, ticks, engines },
228
- `verified ${ticks} ticks of ${file.schedule} on ${engines.join(", ")}: every engine reaches the same world as node after every tick, and node matches the recording`
238
+ { schedule: file.schedule, recording: notCompared === undefined ? "matched" : "notCompared", ticks, engines },
239
+ `verified ${ticks} ticks of ${file.schedule} on ${engines.join(", ")}: every engine reaches the same world as node after every tick, ${notCompared === undefined ? "and node matches the recording" : `and the recording ${notCompared}`}`
229
240
  ))
230
241
  }
231
- return Result.failure({ _tag: "NotVerified", outcomes, text: [`NOT verified: ${ticks} ticks of ${file.schedule}`, ...outcomes.map(describe)].join("\n") })
242
+ const lines = [`NOT verified: ${ticks} ticks of ${file.schedule}`, ...outcomes.map((outcome) => describe(outcome, notCompared))]
243
+ return Result.failure({ _tag: "NotVerified", outcomes, text: [...lines, ...notCompared === undefined ? [] : [`the recording ${notCompared}`]].join("\n") })
232
244
  }
233
245
 
234
246
  /** Loads both worlds at `tick` and lists what differs. */
@@ -255,11 +267,11 @@ const explain = async (
255
267
  const where = ({ path, entity }: Desync.Difference): string =>
256
268
  entity === undefined ? path : `${Format.entity(entity)}${path.slice(`entity ${entity}`.length)}`
257
269
 
258
- /** One outcome as text: the first line names the engine, the tick, and the first difference. */
259
- const describe = (outcome: Outcome): string => {
270
+ /** One outcome as text: the first line names the engine, the tick, and the first difference. `notCompared`: why the recording was not compared. */
271
+ const describe = (outcome: Outcome, notCompared: string | undefined): string => {
260
272
  switch (outcome._tag) {
261
273
  case "Agreed":
262
- return `${outcome.engine}: agrees with ${outcome.engine === "node" ? "a second node run and the recording" : "node"} over ${outcome.ticks} ticks`
274
+ return `${outcome.engine}: agrees with ${outcome.engine !== "node" ? "node" : notCompared === undefined ? "a second node run and the recording" : "a second node run"} over ${outcome.ticks} ticks`
263
275
  case "EngineMissing":
264
276
  return `${outcome.engine}: not installed (${outcome.reason}): ${outcome.install}`
265
277
  case "EngineFailed":
package/src/cli.ts CHANGED
@@ -21,10 +21,18 @@
21
21
  * A missing or unreadable config, one with `extends`, or one that never turns
22
22
  * the rule on prints why the check was skipped and does not fail.
23
23
  *
24
- * Last, it notes each Ritmo skill (`ritmo`, `ritmo-prototype`, `ritmo-onboarding`, `ritmo-polish`) the project
25
- * does not link from the installed package (`.agents/skills/<skill>` or
26
- * `.claude/skills/<skill>`, see `SETUP.md`), or holds a copy of it that goes
27
- * stale on upgrade. The note never fails the lint.
24
+ * It checks that every Ritmo package the game installs is one version: from
25
+ * the working directory, each `@typeonce` package it resolves, and every copy
26
+ * those resolve in turn (npm, yarn, and pnpm layouts). Copies at different
27
+ * versions (`@typeonce/ritmo-browser` 0.22 beside `@typeonce/ritmo` 0.23
28
+ * installs a second core under browser) print one `mismatched-versions`
29
+ * warning naming each copy, and exit with 1.
30
+ *
31
+ * Last, it notes each skill `@typeonce/ritmo` ships (every folder in its
32
+ * installed `skills`) that the project does not link from the installed
33
+ * package (`.agents/skills/<skill>` or `.claude/skills/<skill>`, see
34
+ * `SETUP.md`), or holds a copy of that goes stale on upgrade. The note never
35
+ * fails the lint.
28
36
  *
29
37
  * `verify` imports `<entry>` (a module exporting `replayTarget`, the
30
38
  * `make(playback)` factory `Replay.session` takes), plays the replay file in
@@ -47,7 +55,7 @@
47
55
  * is printed with its install command and exits with 2.
48
56
  *
49
57
  * Exit codes: 0 ok (and every `scan` that ran), 1 lint warning, uncovered
50
- * module, or an engine that differs or did not run, 2 usage error (for `scan`
58
+ * module, mismatched versions, or an engine that differs or did not run, 2 usage error (for `scan`
51
59
  * also an unreadable entry, an import that does not resolve, or a missing tool).
52
60
  * Requires Node 22.15 or later for `module.registerHooks`; on older Node it
53
61
  * prints that coverage was not checked.
@@ -60,6 +68,7 @@ import { resolve } from "node:path"
60
68
  import { pathToFileURL } from "node:url"
61
69
 
62
70
  import * as DependencyScan from "./internal/dependencyScan.ts"
71
+ import * as PackageVersions from "./internal/packageVersions.ts"
63
72
  import * as SimulationCoverage from "./internal/simulationCoverage.ts"
64
73
  import * as SkillLink from "./internal/skillLink.ts"
65
74
  import * as Lint from "./Lint.ts"
@@ -123,10 +132,13 @@ const lint = async (entry: string): Promise<number> => {
123
132
  if (text !== "") console.log(text)
124
133
  return report.data.ok && (!coverage.checked || coverage.uncovered.length === 0) ? 0 : 1
125
134
  })()
135
+ const versions = PackageVersions.check(process.cwd())
136
+ const mismatch = PackageVersions.format(versions)
137
+ if (mismatch !== "") console.log(mismatch)
126
138
  // A note only: it never changes the exit code.
127
139
  const skill = SkillLink.format(SkillLink.check(process.cwd()))
128
140
  if (skill !== "") console.log(skill)
129
- return status
141
+ return versions._tag === "Mismatched" ? 1 : status
130
142
  }
131
143
 
132
144
  const engineNames = ["node", "chromium", "webkit", "firefox"] as const