@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.
- package/CHANGELOG.md +83 -0
- package/README.md +61 -10
- package/dist/Desync.d.ts +2 -2
- package/dist/Desync.d.ts.map +1 -1
- package/dist/Desync.js +2 -1
- package/dist/Desync.js.map +1 -1
- package/dist/Format.d.ts +8 -1
- package/dist/Format.d.ts.map +1 -1
- package/dist/Format.js +13 -2
- package/dist/Format.js.map +1 -1
- package/dist/Fuzz.d.ts +12 -5
- package/dist/Fuzz.d.ts.map +1 -1
- package/dist/Fuzz.js +8 -1
- package/dist/Fuzz.js.map +1 -1
- package/dist/Replay.d.ts +50 -13
- package/dist/Replay.d.ts.map +1 -1
- package/dist/Replay.js +59 -8
- package/dist/Replay.js.map +1 -1
- package/dist/Session.d.ts +7 -15
- package/dist/Session.d.ts.map +1 -1
- package/dist/Session.js +41 -3
- package/dist/Session.js.map +1 -1
- package/dist/Verify.d.ts +11 -2
- package/dist/Verify.d.ts.map +1 -1
- package/dist/Verify.js +12 -7
- package/dist/Verify.js.map +1 -1
- package/dist/cli.js +19 -6
- package/dist/cli.js.map +1 -1
- package/dist/internal/packageVersions.d.ts +28 -0
- package/dist/internal/packageVersions.d.ts.map +1 -0
- package/dist/internal/packageVersions.js +144 -0
- package/dist/internal/packageVersions.js.map +1 -0
- package/dist/internal/replayStart.d.ts +18 -0
- package/dist/internal/replayStart.d.ts.map +1 -0
- package/dist/internal/replayStart.js +16 -0
- package/dist/internal/replayStart.js.map +1 -0
- package/dist/internal/skillLink.d.ts +1 -9
- package/dist/internal/skillLink.d.ts.map +1 -1
- package/dist/internal/skillLink.js +29 -6
- package/dist/internal/skillLink.js.map +1 -1
- package/dist/internal/version.d.ts +1 -1
- package/dist/internal/version.js +1 -1
- package/package.json +3 -3
- package/src/Desync.ts +3 -2
- package/src/Format.ts +15 -2
- package/src/Fuzz.ts +17 -5
- package/src/Replay.ts +104 -17
- package/src/Session.ts +41 -34
- package/src/Verify.ts +21 -9
- package/src/cli.ts +18 -6
- package/src/internal/packageVersions.ts +150 -0
- package/src/internal/replayStart.ts +16 -0
- package/src/internal/skillLink.ts +31 -8
- 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`; `
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
264
|
-
|
|
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
|
-
|
|
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
|
|
299
|
-
if (
|
|
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
|
-
/**
|
|
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
|
-
|
|
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<
|
|
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,
|
|
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,
|
|
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
|
-
> =
|
|
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
|
-
?
|
|
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 `
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
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
|