@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/dist/Fuzz.d.ts ADDED
@@ -0,0 +1,275 @@
1
+ /**
2
+ * Seeded fuzzing that shrinks to a replay: finds a bug before anyone plays
3
+ * into it, and hands back the small input timeline that shows it.
4
+ *
5
+ * `run(make, options)` builds a fresh simulation per run with the same
6
+ * `make(playback)` factory `Replay.session` opens replays with, feeds each
7
+ * fuzzed source a value drawn from a seeded `Random` (from
8
+ * `@typeonce/ritmo`) every frame, and ticks the schedule in a `Session`
9
+ * until an invariant breaks, a system fails, or something throws. The
10
+ * failing timeline is then shrunk by delta debugging: ranges of frames are
11
+ * dropped, then each remaining value is moved toward the input's `neutral`
12
+ * (the whole value, then one field at a time), re-running the deterministic
13
+ * simulation for every candidate and keeping it only when it fails the same
14
+ * way. The result is a `Replay.ReplayFile` of the shrunk timeline, so the
15
+ * test that locks the bug in is `Replay.session(make, file, { invariants })`.
16
+ *
17
+ * A source the factory asks `playback.source` for must be a fuzzed `input`,
18
+ * and every `input` must be asked for; provide plain-data services (rules,
19
+ * config) directly. Use `Determinism.check` to check that the same input
20
+ * repeats; use `Session` to explain a failure by hand.
21
+ *
22
+ * With `network`, the same `run` fuzzes a rollback game over a faulty
23
+ * network: every seat of a `seats` input is its own peer, a fresh runtime
24
+ * from `make`, joined to the others by a seeded `MemoryNetworkLink`
25
+ * (latency, jitter, loss) and driven by a `Netcode.rollback` session. A
26
+ * desync, or any other session failure, is a `SessionFailed` violation, and
27
+ * shrinking shrinks the input timeline with the network seed fixed. Run
28
+ * `Netcode.syncTest` first: it finds state a rewind cannot put back on one
29
+ * peer, faster.
30
+ *
31
+ * @module Fuzz
32
+ * @docGroup devtools
33
+ *
34
+ * @example
35
+ * ```ts
36
+ * const Input = Descriptor.Service<{ snapshot: () => { dx: number } }>()("Game/Input")
37
+ * declare const make: (playback: Replay.Playback) => Replay.Target<typeof Game.schema, typeof Root, { readonly setup: typeof setup; readonly update: typeof update }>
38
+ * const InsideArena = Invariant.fromInspector(Game.Inspector("inside arena", {
39
+ * queries: { bodies: Game.Query({ selection: { position: Game.Query.read(Position) } }) }
40
+ * }, ({ queries }) => queries.bodies.each().some(({ data }) => data.position.get().x < 0) ? "left the arena" : undefined))
41
+ * declare const sink: Replay.Sink
42
+ * // ---cut---
43
+ * const Move = Fuzz.input(Input, {
44
+ * generate: (random) => ({ dx: random.integer(-2, 3) }),
45
+ * neutral: { dx: 0 }
46
+ * })
47
+ * const found = Fuzz.run(make, { schedule: "update", inputs: [Move], invariants: [InsideArena], frames: 600, seed: 7 })
48
+ * if (!found.ok && found.error._tag === "Found") {
49
+ * sink.save(found.error.replay) // the shrunk timeline that still fails
50
+ * console.log(found.error.violation) // the invariant, failure, or defect it hit
51
+ * }
52
+ * ```
53
+ */
54
+ import { Clock } from "@typeonce/ritmo";
55
+ import type { Descriptor } from "@typeonce/ritmo/Descriptor";
56
+ import * as Result from "@typeonce/ritmo/Result";
57
+ import type { AnyScheduleOrder, ExecutableScheduleDefinition, Source } from "@typeonce/ritmo/Schedule";
58
+ import type { Schema } from "@typeonce/ritmo/Schema";
59
+ import type * as Snapshot from "@typeonce/ritmo/Snapshot";
60
+ import type * as Checkpoint from "@typeonce/ritmo/Checkpoint";
61
+ import type * as CoreDescriptor from "@typeonce/ritmo/Descriptor";
62
+ import * as Random from "@typeonce/ritmo/Random";
63
+ import type * as Netcode from "@typeonce/ritmo-netcode/Netcode";
64
+ import type { Invariant } from "./Invariant.ts";
65
+ import * as Rendered from "./Rendered.ts";
66
+ import * as Replay from "./Replay.ts";
67
+ import * as Session from "./Session.ts";
68
+ type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>;
69
+ /** One fuzzed source, made with {@link input}: what `run` feeds a `snapshot()` service every frame. */
70
+ export interface Input<Name extends string = string, Data = unknown> {
71
+ /** The source service's name. */
72
+ readonly name: Name;
73
+ /** The value for `frame` (counting from 1), drawn from the run's seeded generator. */
74
+ readonly generate: (random: Random.Random, frame: number) => Data;
75
+ /** The input of a player who does nothing: what shrinking moves values toward. */
76
+ readonly neutral: Data;
77
+ }
78
+ /**
79
+ * Declares how to fuzz one `snapshot()` source: `generate` draws its value
80
+ * for a frame, of the type the source returns, and `neutral` is the idle
81
+ * value. Pass the result in `run`'s `inputs`. The source is a
82
+ * `snapshot()`-only service (`Schedule.Source`, `InputCapture.SourceOf<...>`
83
+ * for browser input, whose `Controls` action set draws a value with
84
+ * `random` and has `idle` for `neutral`). Use `Keyboard.scripted` (or a
85
+ * scripted source) instead to replay one known sequence.
86
+ */
87
+ export declare const input: <const Name extends string, Value extends Source<unknown>>(descriptor: Descriptor<"service", Name, Value> & Replay.ValidateSource<Name, Value>, options: {
88
+ readonly generate: (random: Random.Random, frame: number) => Replay.SourceData<Value>;
89
+ readonly neutral: Replay.SourceData<Value>;
90
+ }) => Input<Name, Replay.SourceData<Value>>;
91
+ /**
92
+ * Every seat's input of a networked game, made with {@link seats}: per
93
+ * frame, one value per seat. Alone it fuzzes the seats source like any
94
+ * `input`; with `run`'s `network`, each seat's value is that peer's local
95
+ * input.
96
+ */
97
+ export interface Seats<Name extends string = string, Data = unknown> extends Input<Name, ReadonlyArray<Data>> {
98
+ /** The schema remote input is decoded with, as given to `Netcode.seats`. */
99
+ readonly codec: CoreDescriptor.Codec<any, any>;
100
+ /** How many seats: over a network, how many peers. */
101
+ readonly count: number;
102
+ /** The input of a seat that pressed nothing, as given to `Netcode.seats`. */
103
+ readonly idle: Data;
104
+ }
105
+ /**
106
+ * Declares how to fuzz the seats of a networked game: the
107
+ * `Netcode.Source` service its simulation captures, the input `codec` and
108
+ * `idle` input the game gives `Netcode.seats`, `count` seats, and
109
+ * `generate` for one seat's input on a frame. Pass it as the only input of a
110
+ * `run` with `network`; `make` provides the service with
111
+ * `playback.source(descriptor)` (over a network, that is the peer's
112
+ * `seats.source`). Use `input` for a game without seats.
113
+ */
114
+ export declare const seats: <const Name extends string, const C extends CoreDescriptor.Codec<any, any>>(descriptor: Descriptor<"service", Name, Netcode.Source<CoreDescriptor.CodecType<C>>>, options: {
115
+ readonly codec: C & CoreDescriptor.CheckedCodec<C>;
116
+ readonly count: number;
117
+ readonly generate: (random: Random.Random, frame: number, seat: number) => NoInfer<CoreDescriptor.CodecType<C>>;
118
+ readonly idle: NoInfer<CoreDescriptor.CodecType<C>>;
119
+ }) => Seats<Name, CoreDescriptor.CodecType<C>>;
120
+ /**
121
+ * How `run` joins the peers when it fuzzes over a network: the seeded link
122
+ * faults (`MemoryNetworkLink.make`'s), kept fixed while shrinking, and the
123
+ * `Netcode.rollback` options every peer's session takes.
124
+ */
125
+ export interface Network {
126
+ /** The link's seed: drops and delays repeat for the same seed. */
127
+ readonly seed: number;
128
+ readonly latencyMS: number;
129
+ /** Up to this much extra delay per message (0 by default). */
130
+ readonly jitterMS?: number;
131
+ /** The share of messages dropped, from 0 to 1 (0 by default). */
132
+ readonly loss?: number;
133
+ /** The simulation's fixed step: the test clock moves one step per frame. */
134
+ readonly step: Clock.Step;
135
+ /** Idle frames played after the fuzzed ones, so late input and checksums arrive (120 by default). */
136
+ readonly settle?: number;
137
+ readonly inputDelay?: number;
138
+ readonly maxRollback?: number;
139
+ /** Ticks between checksum comparisons (10 by default here, to find a desync close to its cause). */
140
+ readonly checksumEvery?: number;
141
+ }
142
+ /** What `run` fuzzes, how long, and how hard it shrinks. */
143
+ export interface Options<Name extends string, Names extends string, Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>>> {
144
+ /** The schedule to fuzz: the one ticked once per simulation step. Its name in the replay. */
145
+ readonly schedule: Name;
146
+ /** Ticked once before the fuzzed frames, with every input neutral: the replay starts after it. */
147
+ readonly setup?: Names;
148
+ /** The fuzzed sources, each from `input`. */
149
+ readonly inputs: readonly [Input, ...Array<Input>];
150
+ /** Checked after every frame, in order, as in `Session.make`. */
151
+ readonly invariants?: Invariants;
152
+ /** Frames per run, a whole number above 0. */
153
+ readonly frames: number;
154
+ /** Runs to try, each with a fresh simulation; run `i` draws from seed `seed + i`. Defaults to 10. */
155
+ readonly runs?: number;
156
+ /** The first run's seed (an integer). A found bug reports the seed of its run. */
157
+ readonly seed: number;
158
+ /** Simulations shrinking may run before it stops with the smallest timeline so far. Defaults to 500. */
159
+ readonly shrinkAttempts?: number;
160
+ }
161
+ /** What a fuzzed run hit. */
162
+ export type Violation = {
163
+ readonly _tag: "InvariantViolated";
164
+ readonly invariant: string;
165
+ readonly message: string;
166
+ } | {
167
+ readonly _tag: "SystemFailed";
168
+ readonly system: string;
169
+ readonly error: unknown;
170
+ }
171
+ /** A system threw, or `invariant` names the invariant whose check threw (a bug in the check). */
172
+ | {
173
+ readonly _tag: "Defect";
174
+ readonly invariant: string | undefined;
175
+ readonly error: unknown;
176
+ }
177
+ /**
178
+ * Over a `network`: the session of `seat` failed. `Desynced` is a
179
+ * determinism bug (`Desync.compare` its `snapshot` with the other seat's:
180
+ * the sessions keep them); `TickFailed` and `CheckpointLost` stop a real
181
+ * session too.
182
+ */
183
+ | {
184
+ readonly _tag: "SessionFailed";
185
+ readonly seat: number;
186
+ readonly error: Netcode.SessionError<unknown>;
187
+ };
188
+ /** A bug the fuzzer found: the error side of `run`. */
189
+ export interface Found {
190
+ readonly _tag: "Found";
191
+ readonly violation: Violation;
192
+ /** The seed of the run that found it: `run` with this `seed` and `runs: 1` finds it again. */
193
+ readonly seed: number;
194
+ /** The frame the shrunk timeline fails at: its length, or later over a `network` (the frame a peer saw it). */
195
+ readonly frame: number;
196
+ /**
197
+ * The shrunk timeline as a replay; `Replay.session(make, replay, { invariants })` plays it to the violation.
198
+ * Over a `network`, it plays every seat's input on one runtime: step it to see what each tick did,
199
+ * and find the failure again with `run` and the same seeds.
200
+ */
201
+ readonly replay: Replay.ReplayFile;
202
+ /**
203
+ * Whether the replay, opened with `Replay.session`, hits the violation
204
+ * again. `false` means restoring the start lost state the bug needs
205
+ * (transient components): reproduce it with `seed` instead.
206
+ */
207
+ readonly reproduces: boolean;
208
+ /**
209
+ * How shrinking went: simulations run, candidates kept, and the frames of input before and after
210
+ * (the failing frame, but over a `network`, where a desync shows a few frames after its cause).
211
+ */
212
+ readonly shrink: {
213
+ readonly attempts: number;
214
+ readonly steps: number;
215
+ readonly fromFrames: number;
216
+ readonly toFrames: number;
217
+ };
218
+ }
219
+ /** A run failed, but the same input did not fail again: the simulation reads something besides its input. */
220
+ export interface Flaky {
221
+ readonly _tag: "Flaky";
222
+ readonly violation: Violation;
223
+ readonly seed: number;
224
+ readonly frame: number;
225
+ }
226
+ /** The options or the factory cannot be fuzzed; `message` says why. */
227
+ export interface InvalidOptions {
228
+ readonly _tag: "InvalidOptions";
229
+ readonly message: string;
230
+ }
231
+ /** The world after setup cannot be saved (a `"~encode"` rejected it), so no replay could start there. */
232
+ export interface Unreplayable {
233
+ readonly _tag: "Unreplayable";
234
+ readonly error: Snapshot.SnapshotError;
235
+ }
236
+ /** Why `run` did not pass. */
237
+ export type FuzzError = Found | Flaky | InvalidOptions | Unreplayable;
238
+ /** Every run completed: how many, of how many frames, from which seed. */
239
+ export interface Passed {
240
+ readonly runs: number;
241
+ readonly frames: number;
242
+ readonly seed: number;
243
+ }
244
+ /**
245
+ * Over a `network`: the only input is a `Fuzz.seats`, the fuzzed schedule
246
+ * must rewind and the runtime save (as for `Netcode.rollback`).
247
+ */
248
+ type NetworkChecks<Net, S extends Schema.Any, Fuzzed> = [
249
+ Net
250
+ ] extends [Network] ? {
251
+ readonly inputs: readonly [Seats];
252
+ } & Checkpoint.ValidateRewindable<Fuzzed> & Snapshot.Gate<S, unknown> : unknown;
253
+ /**
254
+ * Fuzzes `options.schedule` of the simulation `make` builds. Each run makes
255
+ * a fresh runtime with `make(playback)` (the `Replay.session` factory),
256
+ * ticks `setup` once, then ticks the schedule up to `frames` times with
257
+ * every input's `generate`d value, checking `invariants` after each frame.
258
+ * The first run that fails is shrunk and returned as a `Found` with a
259
+ * replay; a schedule name that `make` does not return, an invariant that
260
+ * reads what the runtime does not provide, or a schedule service that could
261
+ * not be replayed does not compile.
262
+ *
263
+ * With `network`, every seat of the one `Fuzz.seats` input plays on its own
264
+ * peer (a fresh `make` each, seat 0 ticking `setup`) through
265
+ * `Netcode.rollback` over a seeded `MemoryNetworkLink`, and the invariants
266
+ * are checked on every peer after each frame. A session failure is a
267
+ * `SessionFailed` violation; a schedule that cannot be rewound, or a
268
+ * runtime that cannot save, does not compile.
269
+ */
270
+ export declare const run: <S extends Schema.Any, Root, const Schedules extends Readonly<Record<string, AnySchedule<S, Root>>>, Services extends Record<string, unknown>, Resources extends object, Machines extends Record<string, unknown>, const Name extends keyof Schedules & string, const Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [], const Net extends Network | undefined = undefined>(make: (playback: Replay.Playback) => Replay.Target<S, Root, Schedules, Services, Resources, Machines>, options: Options<Name, NoInfer<keyof Schedules & string>, Invariants> & Session.ValidateInvariants<Invariants, Services, Resources, Machines> & Replay.ValidateRecordable<Schedules[Name]> & {
271
+ /** Fuzz every seat as its own peer over a seeded faulty network, with `Netcode.rollback` sessions. */
272
+ readonly network?: Net;
273
+ } & NetworkChecks<Net, S, Schedules[Name]>) => Result.Result<Rendered.Rendered<Passed>, FuzzError>;
274
+ export {};
275
+ //# sourceMappingURL=Fuzz.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Fuzz.d.ts","sourceRoot":"","sources":["../src/Fuzz.ts"],"names":[],"mappings":"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"}
package/dist/Fuzz.js ADDED
@@ -0,0 +1,362 @@
1
+ /**
2
+ * Seeded fuzzing that shrinks to a replay: finds a bug before anyone plays
3
+ * into it, and hands back the small input timeline that shows it.
4
+ *
5
+ * `run(make, options)` builds a fresh simulation per run with the same
6
+ * `make(playback)` factory `Replay.session` opens replays with, feeds each
7
+ * fuzzed source a value drawn from a seeded `Random` (from
8
+ * `@typeonce/ritmo`) every frame, and ticks the schedule in a `Session`
9
+ * until an invariant breaks, a system fails, or something throws. The
10
+ * failing timeline is then shrunk by delta debugging: ranges of frames are
11
+ * dropped, then each remaining value is moved toward the input's `neutral`
12
+ * (the whole value, then one field at a time), re-running the deterministic
13
+ * simulation for every candidate and keeping it only when it fails the same
14
+ * way. The result is a `Replay.ReplayFile` of the shrunk timeline, so the
15
+ * test that locks the bug in is `Replay.session(make, file, { invariants })`.
16
+ *
17
+ * A source the factory asks `playback.source` for must be a fuzzed `input`,
18
+ * and every `input` must be asked for; provide plain-data services (rules,
19
+ * config) directly. Use `Determinism.check` to check that the same input
20
+ * repeats; use `Session` to explain a failure by hand.
21
+ *
22
+ * With `network`, the same `run` fuzzes a rollback game over a faulty
23
+ * network: every seat of a `seats` input is its own peer, a fresh runtime
24
+ * from `make`, joined to the others by a seeded `MemoryNetworkLink`
25
+ * (latency, jitter, loss) and driven by a `Netcode.rollback` session. A
26
+ * desync, or any other session failure, is a `SessionFailed` violation, and
27
+ * shrinking shrinks the input timeline with the network seed fixed. Run
28
+ * `Netcode.syncTest` first: it finds state a rewind cannot put back on one
29
+ * peer, faster.
30
+ *
31
+ * @module Fuzz
32
+ * @docGroup devtools
33
+ *
34
+ * @example
35
+ * ```ts
36
+ * const Input = Descriptor.Service<{ snapshot: () => { dx: number } }>()("Game/Input")
37
+ * declare const make: (playback: Replay.Playback) => Replay.Target<typeof Game.schema, typeof Root, { readonly setup: typeof setup; readonly update: typeof update }>
38
+ * const InsideArena = Invariant.fromInspector(Game.Inspector("inside arena", {
39
+ * queries: { bodies: Game.Query({ selection: { position: Game.Query.read(Position) } }) }
40
+ * }, ({ queries }) => queries.bodies.each().some(({ data }) => data.position.get().x < 0) ? "left the arena" : undefined))
41
+ * declare const sink: Replay.Sink
42
+ * // ---cut---
43
+ * const Move = Fuzz.input(Input, {
44
+ * generate: (random) => ({ dx: random.integer(-2, 3) }),
45
+ * neutral: { dx: 0 }
46
+ * })
47
+ * const found = Fuzz.run(make, { schedule: "update", inputs: [Move], invariants: [InsideArena], frames: 600, seed: 7 })
48
+ * if (!found.ok && found.error._tag === "Found") {
49
+ * sink.save(found.error.replay) // the shrunk timeline that still fails
50
+ * console.log(found.error.violation) // the invariant, failure, or defect it hit
51
+ * }
52
+ * ```
53
+ */
54
+ import { Clock } from "@typeonce/ritmo";
55
+ import * as Result from "@typeonce/ritmo/Result";
56
+ import * as Random from "@typeonce/ritmo/Random";
57
+ import * as FuzzNetwork from "./internal/fuzzNetwork.js";
58
+ import * as Rendered from "./Rendered.js";
59
+ import * as Replay from "./Replay.js";
60
+ import * as Session from "./Session.js";
61
+ /**
62
+ * Declares how to fuzz one `snapshot()` source: `generate` draws its value
63
+ * for a frame, of the type the source returns, and `neutral` is the idle
64
+ * value. Pass the result in `run`'s `inputs`. The source is a
65
+ * `snapshot()`-only service (`Schedule.Source`, `InputCapture.SourceOf<...>`
66
+ * for browser input, whose `Controls` action set draws a value with
67
+ * `random` and has `idle` for `neutral`). Use `Keyboard.scripted` (or a
68
+ * scripted source) instead to replay one known sequence.
69
+ */
70
+ export const input = (descriptor, options) => ({ name: descriptor.name, generate: options.generate, neutral: options.neutral });
71
+ /**
72
+ * Declares how to fuzz the seats of a networked game: the
73
+ * `Netcode.Source` service its simulation captures, the input `codec` and
74
+ * `idle` input the game gives `Netcode.seats`, `count` seats, and
75
+ * `generate` for one seat's input on a frame. Pass it as the only input of a
76
+ * `run` with `network`; `make` provides the service with
77
+ * `playback.source(descriptor)` (over a network, that is the peer's
78
+ * `seats.source`). Use `input` for a game without seats.
79
+ */
80
+ export const seats = (descriptor, options) => ({
81
+ name: descriptor.name,
82
+ codec: options.codec,
83
+ count: options.count,
84
+ idle: options.idle,
85
+ neutral: Array.from({ length: options.count }, () => options.idle),
86
+ generate: (random, frame) => Array.from({ length: options.count }, (_, seat) => options.generate(random, frame, seat))
87
+ });
88
+ /** Two violations are the same bug when they name the same invariant, system, or kind of defect. */
89
+ const signature = (violation) => violation._tag === "InvariantViolated" ? `invariant ${violation.invariant}`
90
+ : violation._tag === "SystemFailed" ? `system ${violation.system}`
91
+ : violation._tag === "SessionFailed" ? `session ${violation.error._tag}`
92
+ : `defect ${violation.invariant ?? ""}`;
93
+ const describe = (violation) => {
94
+ if (violation._tag === "InvariantViolated")
95
+ return `invariant ${violation.invariant} broke: ${violation.message}`;
96
+ if (violation._tag === "SessionFailed")
97
+ return `seat ${violation.seat}'s session failed with ${violation.error._tag}${"tick" in violation.error ? ` at tick ${violation.error.tick}` : ""}`;
98
+ const error = violation.error instanceof Error ? violation.error.message : JSON.stringify(violation.error) ?? String(violation.error);
99
+ if (violation._tag === "SystemFailed")
100
+ return `${violation.system} failed: ${error}`;
101
+ return violation.invariant === undefined ? `a system threw: ${error}` : `invariant ${violation.invariant} threw: ${error}`;
102
+ };
103
+ const violationOf = (stop) => {
104
+ switch (stop.reason) {
105
+ case "completed":
106
+ case "until":
107
+ return undefined;
108
+ case "invariant":
109
+ return { _tag: "InvariantViolated", invariant: stop.invariant, message: stop.message };
110
+ case "failure":
111
+ return { _tag: "SystemFailed", system: stop.system, error: stop.error };
112
+ case "ignored-failure":
113
+ return { _tag: "SystemFailed", system: stop.system ?? stop.schedule, error: stop.error };
114
+ case "defect":
115
+ return { _tag: "Defect", invariant: undefined, error: stop.error };
116
+ case "invariant-threw":
117
+ return { _tag: "Defect", invariant: stop.invariant, error: stop.error };
118
+ case "missingRequirements":
119
+ return { _tag: "InvalidOptions", message: `the fuzzed schedule's runtime is missing requirements: ${JSON.stringify(stop.requirements)}` };
120
+ case "tickOrder":
121
+ return { _tag: "InvalidOptions", message: `the fuzzed schedule's tick order is invalid: ${stop.issues.join("; ")}` };
122
+ }
123
+ };
124
+ const same = (left, right) => left === right || JSON.stringify(left) === JSON.stringify(right);
125
+ const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
126
+ /** Values closer to `neutral` than `value`: `neutral` itself, then `value` with one field set to neutral's. */
127
+ const simpler = (value, neutral) => {
128
+ if (same(value, neutral))
129
+ return [];
130
+ const candidates = [neutral];
131
+ // Every seat's input: one seat at a time.
132
+ if (Array.isArray(value) && Array.isArray(neutral) && value.length === neutral.length) {
133
+ value.forEach((item, index) => {
134
+ for (const candidate of simpler(item, neutral[index])) {
135
+ const next = value.map((other, at) => at === index ? candidate : other);
136
+ if (!same(next, neutral))
137
+ candidates.push(next);
138
+ }
139
+ });
140
+ }
141
+ if (isRecord(value) && isRecord(neutral)) {
142
+ const keys = Object.keys(value).filter((key) => !same(value[key], neutral[key]));
143
+ if (keys.length > 1)
144
+ for (const key of keys)
145
+ candidates.push({ ...value, [key]: neutral[key] });
146
+ }
147
+ return candidates;
148
+ };
149
+ /**
150
+ * Fuzzes `options.schedule` of the simulation `make` builds. Each run makes
151
+ * a fresh runtime with `make(playback)` (the `Replay.session` factory),
152
+ * ticks `setup` once, then ticks the schedule up to `frames` times with
153
+ * every input's `generate`d value, checking `invariants` after each frame.
154
+ * The first run that fails is shrunk and returned as a `Found` with a
155
+ * replay; a schedule name that `make` does not return, an invariant that
156
+ * reads what the runtime does not provide, or a schedule service that could
157
+ * not be replayed does not compile.
158
+ *
159
+ * With `network`, every seat of the one `Fuzz.seats` input plays on its own
160
+ * peer (a fresh `make` each, seat 0 ticking `setup`) through
161
+ * `Netcode.rollback` over a seeded `MemoryNetworkLink`, and the invariants
162
+ * are checked on every peer after each frame. A session failure is a
163
+ * `SessionFailed` violation; a schedule that cannot be rewound, or a
164
+ * runtime that cannot save, does not compile.
165
+ */
166
+ export const run = (make, options) => {
167
+ const invalid = (message) => Result.failure({ _tag: "InvalidOptions", message });
168
+ const runs = options.runs ?? 10;
169
+ const budget = options.shrinkAttempts ?? 500;
170
+ if (!Number.isSafeInteger(options.frames) || options.frames < 1)
171
+ return invalid("frames must be a whole number above 0");
172
+ if (!Number.isSafeInteger(runs) || runs < 1)
173
+ return invalid("runs must be a whole number above 0");
174
+ if (!Number.isSafeInteger(options.seed))
175
+ return invalid("seed must be an integer");
176
+ if (!Number.isSafeInteger(budget) || budget < 0)
177
+ return invalid("shrinkAttempts must be a whole number, 0 or more");
178
+ const inputs = options.inputs;
179
+ const indexOf = new Map(inputs.map((entry, index) => [entry.name, index]));
180
+ if (indexOf.size !== inputs.length)
181
+ return invalid("each input must fuzz a different source");
182
+ const neutral = inputs.map((entry) => entry.neutral);
183
+ // `run`'s signature checked the invariants against this runtime's provisions.
184
+ const invariants = (options.invariants ?? []);
185
+ const network = options.network;
186
+ let plan;
187
+ if (network !== undefined) {
188
+ const only = inputs[0];
189
+ if (inputs.length !== 1 || !("codec" in only) || !("count" in only))
190
+ return invalid("over a network, give inputs exactly one Fuzz.seats");
191
+ const seated = only;
192
+ const settle = network.settle ?? 120;
193
+ if (!Number.isSafeInteger(settle) || settle < 0)
194
+ return invalid("network.settle must be a whole number, 0 or more");
195
+ plan = {
196
+ name: seated.name, codec: seated.codec, count: seated.count, idle: seated.idle,
197
+ make, schedule: options.schedule, setup: options.setup, invariants: options.invariants ?? [],
198
+ step: network.step, seed: network.seed, latencyMS: network.latencyMS, jitterMS: network.jitterMS ?? 0, loss: network.loss ?? 0, settle,
199
+ inputDelay: network.inputDelay, maxRollback: network.maxRollback, checksumEvery: network.checksumEvery ?? 10
200
+ };
201
+ }
202
+ /**
203
+ * Runs one fresh simulation over `timeline`; `record` also saves it as a replay with that reason
204
+ * (a text: saved even when it passes).
205
+ */
206
+ const simulateOne = (timeline, record) => {
207
+ let current = neutral;
208
+ const asked = new Set();
209
+ const unknown = [];
210
+ const playback = {
211
+ source: (descriptor) => {
212
+ asked.add(descriptor.name);
213
+ const index = indexOf.get(descriptor.name);
214
+ if (index === undefined)
215
+ unknown.push(descriptor.name);
216
+ // The value was generated for this source's `input`, whose type `input` checked against the descriptor.
217
+ return { snapshot: () => (index === undefined ? undefined : current[index]) };
218
+ },
219
+ constant: () => undefined
220
+ };
221
+ const target = make(playback);
222
+ if (unknown.length > 0)
223
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make asked playback.source for ${unknown.join(", ")}, which no input fuzzes: add Fuzz.input for it, or provide it directly` } };
224
+ const unread = inputs.filter((entry) => !asked.has(entry.name)).map((entry) => entry.name);
225
+ if (unread.length > 0)
226
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make never asked playback.source for ${unread.join(", ")}: provide the fuzzed source with playback.source(...)` } };
227
+ const schedules = target.schedules;
228
+ const schedule = schedules[options.schedule];
229
+ if (schedule === undefined)
230
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make returned no schedule ${options.schedule}` } };
231
+ const runtime = target.runtime;
232
+ if (options.setup !== undefined) {
233
+ const setup = schedules[options.setup];
234
+ if (setup === undefined)
235
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make returned no schedule ${options.setup}` } };
236
+ const ticked = runtime.tryTick(setup);
237
+ if (!ticked.ok)
238
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: `setup failed with every input neutral: ${JSON.stringify(ticked.error)}` } };
239
+ }
240
+ const start = runtime.snapshot();
241
+ if (!start.ok)
242
+ return { kind: "invalid", error: { _tag: "Unreplayable", error: start.error } };
243
+ const sink = Replay.memorySink();
244
+ // One window over the whole timeline, with its only snapshot at the start.
245
+ // `run`'s signature checked that the schedule's services can be recorded.
246
+ const recorder = record === undefined ? undefined : Replay.recorder(runtime, {
247
+ schedule, name: options.schedule, keep: timeline.length + 1, every: timeline.length + 1, step: Clock.hz(1), sink, hostClock: target.hostClock
248
+ });
249
+ const session = Session.make(runtime, { schedules: { [options.schedule]: schedule }, hostClock: target.hostClock, invariants, history: 1 });
250
+ let ticked = 0;
251
+ current = timeline[0] ?? neutral;
252
+ const played = session.run(options.schedule, {
253
+ frames: timeline.length,
254
+ until: () => {
255
+ ticked += 1;
256
+ current = timeline[ticked] ?? neutral;
257
+ return false;
258
+ }
259
+ });
260
+ session.close();
261
+ const found = violationOf(played.data.stop);
262
+ const frame = ticked + 1;
263
+ const reason = found?._tag === "InvalidOptions" || record === undefined ? undefined
264
+ : typeof record === "string" ? record
265
+ : found === undefined ? undefined
266
+ : record(found, frame);
267
+ const file = reason === undefined ? undefined : recorder?.save(reason);
268
+ recorder?.stop();
269
+ if (found === undefined)
270
+ return { kind: "passed", file };
271
+ if (found._tag === "InvalidOptions")
272
+ return { kind: "invalid", error: found };
273
+ return { kind: "violated", violation: found, frame, file };
274
+ };
275
+ /** Over the network: every seat on its own peer. The replay plays the same timeline on one runtime. */
276
+ const simulate = (timeline, record) => {
277
+ if (plan === undefined)
278
+ return simulateOne(timeline, record);
279
+ const played = FuzzNetwork.play(plan, timeline);
280
+ if (played.kind === "invalid")
281
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: played.message } };
282
+ if (played.kind === "passed")
283
+ return played;
284
+ const one = record === undefined ? undefined : simulateOne(timeline.slice(0, played.frame), record(played.violation, played.frame));
285
+ return { kind: "violated", violation: played.violation, frame: played.frame, file: one?.kind === "invalid" ? undefined : one?.file };
286
+ };
287
+ for (let index = 0; index < runs; index++) {
288
+ const seed = options.seed + index;
289
+ const random = Random.make(seed);
290
+ const timeline = [];
291
+ for (let frame = 1; frame <= options.frames; frame++)
292
+ timeline.push(inputs.map((entry) => entry.generate(random, frame)));
293
+ const first = simulate(timeline, undefined);
294
+ if (first.kind === "invalid")
295
+ return Result.failure(first.error);
296
+ if (first.kind === "passed")
297
+ continue;
298
+ const target = signature(first.violation);
299
+ let attempts = 0;
300
+ let steps = 0;
301
+ let best = timeline.slice(0, first.frame);
302
+ /** Whether `candidate` still fails the same way; on success, `best` becomes it, cut at its failing frame. */
303
+ const fails = (candidate) => {
304
+ attempts += 1;
305
+ const outcome = simulate(candidate, undefined);
306
+ if (outcome.kind !== "violated" || signature(outcome.violation) !== target)
307
+ return false;
308
+ best = candidate.slice(0, outcome.frame);
309
+ steps += 1;
310
+ return true;
311
+ };
312
+ if (!fails(best))
313
+ return Result.failure({ _tag: "Flaky", violation: first.violation, seed, frame: first.frame });
314
+ steps = 0;
315
+ shrink: for (let changed = true; changed;) {
316
+ changed = false;
317
+ // Drop ranges of frames, halving the range when no range of that size can go.
318
+ for (let size = Math.max(1, Math.floor(best.length / 2)); size >= 1; size = Math.floor(size / 2)) {
319
+ for (let from = 0; from < best.length && best.length > 1;) {
320
+ if (attempts >= budget)
321
+ break shrink;
322
+ if (fails([...best.slice(0, from), ...best.slice(from + size)]))
323
+ changed = true;
324
+ else
325
+ from += size;
326
+ }
327
+ }
328
+ // Move each remaining value toward its input's neutral.
329
+ for (let frame = 0; frame < best.length; frame++) {
330
+ for (let slot = 0; slot < inputs.length; slot++) {
331
+ for (const candidate of simpler(best[frame][slot], neutral[slot])) {
332
+ if (attempts >= budget)
333
+ break shrink;
334
+ const values = [...best[frame]];
335
+ values[slot] = candidate;
336
+ if (fails([...best.slice(0, frame), values, ...best.slice(frame + 1)])) {
337
+ changed = true;
338
+ break;
339
+ }
340
+ }
341
+ }
342
+ }
343
+ }
344
+ const final = simulate(best, (violation, frame) => `fuzz seed ${seed}${network === undefined ? "" : ` over network seed ${network.seed}`}: ${describe(violation)} at frame ${frame} (shrunk from ${Math.min(first.frame, timeline.length)} frames)`);
345
+ if (final.kind !== "violated" || final.file === undefined || signature(final.violation) !== target) {
346
+ return Result.failure({ _tag: "Flaky", violation: first.violation, seed, frame: first.frame });
347
+ }
348
+ const opened = Replay.session(make, final.file, { invariants });
349
+ const replayed = opened.ok ? violationOf(opened.value.play().data.run.stop) : undefined;
350
+ return Result.failure({
351
+ _tag: "Found",
352
+ violation: final.violation,
353
+ seed,
354
+ frame: final.frame,
355
+ replay: final.file,
356
+ reproduces: replayed !== undefined && replayed._tag !== "InvalidOptions" && signature(replayed) === target,
357
+ shrink: { attempts, steps, fromFrames: Math.min(first.frame, timeline.length), toFrames: best.length }
358
+ });
359
+ }
360
+ return Result.success(Rendered.make({ runs, frames: options.frames, seed: options.seed }, `${runs} run${runs === 1 ? "" : "s"} of ${options.frames} frames from seed ${options.seed}: no invariant broke, no system failed, nothing threw`));
361
+ };
362
+ //# sourceMappingURL=Fuzz.js.map