@typeonce/ritmo-devtools 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +336 -58
  3. package/dist/Desync.d.ts +49 -0
  4. package/dist/Desync.d.ts.map +1 -0
  5. package/dist/Desync.js +51 -0
  6. package/dist/Desync.js.map +1 -0
  7. package/dist/Determinism.d.ts +17 -6
  8. package/dist/Determinism.d.ts.map +1 -1
  9. package/dist/Determinism.js +11 -3
  10. package/dist/Determinism.js.map +1 -1
  11. package/dist/Format.d.ts +43 -8
  12. package/dist/Format.d.ts.map +1 -1
  13. package/dist/Format.js +63 -31
  14. package/dist/Format.js.map +1 -1
  15. package/dist/Fuzz.d.ts +268 -0
  16. package/dist/Fuzz.d.ts.map +1 -0
  17. package/dist/Fuzz.js +355 -0
  18. package/dist/Fuzz.js.map +1 -0
  19. package/dist/Invariant.d.ts +6 -2
  20. package/dist/Invariant.d.ts.map +1 -1
  21. package/dist/Invariant.js.map +1 -1
  22. package/dist/Lint.d.ts +9 -3
  23. package/dist/Lint.d.ts.map +1 -1
  24. package/dist/Lint.js.map +1 -1
  25. package/dist/PlaywrightEngine.d.ts +29 -0
  26. package/dist/PlaywrightEngine.d.ts.map +1 -0
  27. package/dist/PlaywrightEngine.js +193 -0
  28. package/dist/PlaywrightEngine.js.map +1 -0
  29. package/dist/Replay.d.ts +43 -34
  30. package/dist/Replay.d.ts.map +1 -1
  31. package/dist/Replay.js +27 -33
  32. package/dist/Replay.js.map +1 -1
  33. package/dist/Session.d.ts +214 -17
  34. package/dist/Session.d.ts.map +1 -1
  35. package/dist/Session.js +563 -57
  36. package/dist/Session.js.map +1 -1
  37. package/dist/Verify.d.ts +147 -0
  38. package/dist/Verify.d.ts.map +1 -0
  39. package/dist/Verify.js +151 -0
  40. package/dist/Verify.js.map +1 -0
  41. package/dist/cli.js +136 -8
  42. package/dist/cli.js.map +1 -1
  43. package/dist/index.d.ts +4 -2
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +4 -2
  46. package/dist/index.js.map +1 -1
  47. package/dist/internal/dependencyScan.d.ts +44 -0
  48. package/dist/internal/dependencyScan.d.ts.map +1 -0
  49. package/dist/internal/dependencyScan.js +313 -0
  50. package/dist/internal/dependencyScan.js.map +1 -0
  51. package/dist/internal/fuzzNetwork.d.ts +56 -0
  52. package/dist/internal/fuzzNetwork.d.ts.map +1 -0
  53. package/dist/internal/fuzzNetwork.js +96 -0
  54. package/dist/internal/fuzzNetwork.js.map +1 -0
  55. package/dist/internal/values.d.ts +9 -1
  56. package/dist/internal/values.d.ts.map +1 -1
  57. package/dist/internal/values.js +11 -1
  58. package/dist/internal/values.js.map +1 -1
  59. package/dist/internal/verifyRunner.d.ts +19 -0
  60. package/dist/internal/verifyRunner.d.ts.map +1 -0
  61. package/dist/internal/verifyRunner.js +47 -0
  62. package/dist/internal/verifyRunner.js.map +1 -0
  63. package/dist/internal/version.d.ts +1 -1
  64. package/dist/internal/version.js +1 -1
  65. package/package.json +28 -3
  66. package/src/Desync.ts +100 -0
  67. package/src/Determinism.ts +46 -11
  68. package/src/Format.ts +99 -34
  69. package/src/Fuzz.ts +544 -0
  70. package/src/Invariant.ts +6 -2
  71. package/src/Lint.ts +9 -3
  72. package/src/PlaywrightEngine.ts +229 -0
  73. package/src/Replay.ts +98 -74
  74. package/src/Session.ts +806 -72
  75. package/src/Verify.ts +273 -0
  76. package/src/cli.ts +131 -8
  77. package/src/index.ts +4 -2
  78. package/src/internal/dependencyScan.ts +356 -0
  79. package/src/internal/fuzzNetwork.ts +130 -0
  80. package/src/internal/values.ts +20 -1
  81. package/src/internal/verifyRunner.ts +46 -0
  82. package/src/internal/version.ts +1 -1
  83. package/dist/Monitor.d.ts +0 -101
  84. package/dist/Monitor.d.ts.map +0 -1
  85. package/dist/Monitor.js +0 -602
  86. package/dist/Monitor.js.map +0 -1
  87. package/dist/internal/monitor.d.ts +0 -126
  88. package/dist/internal/monitor.d.ts.map +0 -1
  89. package/dist/internal/monitor.js +0 -279
  90. package/dist/internal/monitor.js.map +0 -1
  91. package/src/Monitor.ts +0 -713
  92. package/src/internal/monitor.ts +0 -370
package/dist/Fuzz.d.ts ADDED
@@ -0,0 +1,268 @@
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 Move = Fuzz.input(Input, {
37
+ * generate: (random) => ({ dx: random.integer(-2, 3) }),
38
+ * neutral: { dx: 0 }
39
+ * })
40
+ * const found = Fuzz.run(make, { schedule: "update", inputs: [Move], invariants: [InsideArena], frames: 600, seed: 7 })
41
+ * if (!found.ok && found.error._tag === "Found") {
42
+ * sink.save(found.error.replay) // the shrunk timeline that still fails
43
+ * console.log(found.error.violation) // the invariant, failure, or defect it hit
44
+ * }
45
+ * ```
46
+ */
47
+ import { Clock } from "@typeonce/ritmo";
48
+ import type { Descriptor } from "@typeonce/ritmo/Descriptor";
49
+ import * as Result from "@typeonce/ritmo/Result";
50
+ import type { AnyScheduleOrder, ExecutableScheduleDefinition, Source } from "@typeonce/ritmo/Schedule";
51
+ import type { Schema } from "@typeonce/ritmo/Schema";
52
+ import type * as Snapshot from "@typeonce/ritmo/Snapshot";
53
+ import type * as Checkpoint from "@typeonce/ritmo/Checkpoint";
54
+ import type * as CoreDescriptor from "@typeonce/ritmo/Descriptor";
55
+ import * as Random from "@typeonce/ritmo/Random";
56
+ import type * as Netcode from "@typeonce/ritmo-netcode/Netcode";
57
+ import type { Invariant } from "./Invariant.ts";
58
+ import * as Rendered from "./Rendered.ts";
59
+ import * as Replay from "./Replay.ts";
60
+ import * as Session from "./Session.ts";
61
+ type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>;
62
+ /** One fuzzed source, made with {@link input}: what `run` feeds a `snapshot()` service every frame. */
63
+ export interface Input<Name extends string = string, Data = unknown> {
64
+ /** The source service's name. */
65
+ readonly name: Name;
66
+ /** The value for `frame` (counting from 1), drawn from the run's seeded generator. */
67
+ readonly generate: (random: Random.Random, frame: number) => Data;
68
+ /** The input of a player who does nothing: what shrinking moves values toward. */
69
+ readonly neutral: Data;
70
+ }
71
+ /**
72
+ * Declares how to fuzz one `snapshot()` source: `generate` draws its value
73
+ * for a frame, of the type the source returns, and `neutral` is the idle
74
+ * value. Pass the result in `run`'s `inputs`. The source is a
75
+ * `snapshot()`-only service (`Schedule.Source`, `InputCapture.SourceOf<...>`
76
+ * for browser input, whose `Controls` action set draws a value with
77
+ * `random` and has `idle` for `neutral`). Use `Keyboard.scripted` (or a
78
+ * scripted source) instead to replay one known sequence.
79
+ */
80
+ export declare const input: <const Name extends string, Value extends Source<unknown>>(descriptor: Descriptor<"service", Name, Value> & Replay.ValidateSource<Name, Value>, options: {
81
+ readonly generate: (random: Random.Random, frame: number) => Replay.SourceData<Value>;
82
+ readonly neutral: Replay.SourceData<Value>;
83
+ }) => Input<Name, Replay.SourceData<Value>>;
84
+ /**
85
+ * Every seat's input of a networked game, made with {@link seats}: per
86
+ * frame, one value per seat. Alone it fuzzes the seats source like any
87
+ * `input`; with `run`'s `network`, each seat's value is that peer's local
88
+ * input.
89
+ */
90
+ export interface Seats<Name extends string = string, Data = unknown> extends Input<Name, ReadonlyArray<Data>> {
91
+ /** The schema remote input is decoded with, as given to `Netcode.seats`. */
92
+ readonly codec: CoreDescriptor.Codec<any, any>;
93
+ /** How many seats: over a network, how many peers. */
94
+ readonly count: number;
95
+ /** The input of a seat that pressed nothing, as given to `Netcode.seats`. */
96
+ readonly idle: Data;
97
+ }
98
+ /**
99
+ * Declares how to fuzz the seats of a networked game: the
100
+ * `Netcode.Source` service its simulation captures, the input `codec` and
101
+ * `idle` input the game gives `Netcode.seats`, `count` seats, and
102
+ * `generate` for one seat's input on a frame. Pass it as the only input of a
103
+ * `run` with `network`; `make` provides the service with
104
+ * `playback.source(descriptor)` (over a network, that is the peer's
105
+ * `seats.source`). Use `input` for a game without seats.
106
+ */
107
+ 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: {
108
+ readonly codec: C & CoreDescriptor.CheckedCodec<C>;
109
+ readonly count: number;
110
+ readonly generate: (random: Random.Random, frame: number, seat: number) => NoInfer<CoreDescriptor.CodecType<C>>;
111
+ readonly idle: NoInfer<CoreDescriptor.CodecType<C>>;
112
+ }) => Seats<Name, CoreDescriptor.CodecType<C>>;
113
+ /**
114
+ * How `run` joins the peers when it fuzzes over a network: the seeded link
115
+ * faults (`MemoryNetworkLink.make`'s), kept fixed while shrinking, and the
116
+ * `Netcode.rollback` options every peer's session takes.
117
+ */
118
+ export interface Network {
119
+ /** The link's seed: drops and delays repeat for the same seed. */
120
+ readonly seed: number;
121
+ readonly latencyMS: number;
122
+ /** Up to this much extra delay per message (0 by default). */
123
+ readonly jitterMS?: number;
124
+ /** The share of messages dropped, from 0 to 1 (0 by default). */
125
+ readonly loss?: number;
126
+ /** The simulation's fixed step: the test clock moves one step per frame. */
127
+ readonly step: Clock.Step;
128
+ /** Idle frames played after the fuzzed ones, so late input and checksums arrive (120 by default). */
129
+ readonly settle?: number;
130
+ readonly inputDelay?: number;
131
+ readonly maxRollback?: number;
132
+ /** Ticks between checksum comparisons (10 by default here, to find a desync close to its cause). */
133
+ readonly checksumEvery?: number;
134
+ }
135
+ /** What `run` fuzzes, how long, and how hard it shrinks. */
136
+ export interface Options<Name extends string, Names extends string, Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>>> {
137
+ /** The schedule to fuzz: the one ticked once per simulation step. Its name in the replay. */
138
+ readonly schedule: Name;
139
+ /** Ticked once before the fuzzed frames, with every input neutral: the replay starts after it. */
140
+ readonly setup?: Names;
141
+ /** The fuzzed sources, each from `input`. */
142
+ readonly inputs: readonly [Input, ...Array<Input>];
143
+ /** Checked after every frame, in order, as in `Session.make`. */
144
+ readonly invariants?: Invariants;
145
+ /** Frames per run, a whole number above 0. */
146
+ readonly frames: number;
147
+ /** Runs to try, each with a fresh simulation; run `i` draws from seed `seed + i`. Defaults to 10. */
148
+ readonly runs?: number;
149
+ /** The first run's seed (an integer). A found bug reports the seed of its run. */
150
+ readonly seed: number;
151
+ /** Simulations shrinking may run before it stops with the smallest timeline so far. Defaults to 500. */
152
+ readonly shrinkAttempts?: number;
153
+ }
154
+ /** What a fuzzed run hit. */
155
+ export type Violation = {
156
+ readonly _tag: "InvariantViolated";
157
+ readonly invariant: string;
158
+ readonly message: string;
159
+ } | {
160
+ readonly _tag: "SystemFailed";
161
+ readonly system: string;
162
+ readonly error: unknown;
163
+ }
164
+ /** A system threw, or `invariant` names the invariant whose check threw (a bug in the check). */
165
+ | {
166
+ readonly _tag: "Defect";
167
+ readonly invariant: string | undefined;
168
+ readonly error: unknown;
169
+ }
170
+ /**
171
+ * Over a `network`: the session of `seat` failed. `Desynced` is a
172
+ * determinism bug (`Desync.compare` its `snapshot` with the other seat's:
173
+ * the sessions keep them); `TickFailed` and `CheckpointLost` stop a real
174
+ * session too.
175
+ */
176
+ | {
177
+ readonly _tag: "SessionFailed";
178
+ readonly seat: number;
179
+ readonly error: Netcode.SessionError<unknown>;
180
+ };
181
+ /** A bug the fuzzer found: the error side of `run`. */
182
+ export interface Found {
183
+ readonly _tag: "Found";
184
+ readonly violation: Violation;
185
+ /** The seed of the run that found it: `run` with this `seed` and `runs: 1` finds it again. */
186
+ readonly seed: number;
187
+ /** The frame the shrunk timeline fails at: its length, or later over a `network` (the frame a peer saw it). */
188
+ readonly frame: number;
189
+ /**
190
+ * The shrunk timeline as a replay; `Replay.session(make, replay, { invariants })` plays it to the violation.
191
+ * Over a `network`, it plays every seat's input on one runtime: step it to see what each tick did,
192
+ * and find the failure again with `run` and the same seeds.
193
+ */
194
+ readonly replay: Replay.ReplayFile;
195
+ /**
196
+ * Whether the replay, opened with `Replay.session`, hits the violation
197
+ * again. `false` means restoring the start lost state the bug needs
198
+ * (transient components): reproduce it with `seed` instead.
199
+ */
200
+ readonly reproduces: boolean;
201
+ /**
202
+ * How shrinking went: simulations run, candidates kept, and the frames of input before and after
203
+ * (the failing frame, but over a `network`, where a desync shows a few frames after its cause).
204
+ */
205
+ readonly shrink: {
206
+ readonly attempts: number;
207
+ readonly steps: number;
208
+ readonly fromFrames: number;
209
+ readonly toFrames: number;
210
+ };
211
+ }
212
+ /** A run failed, but the same input did not fail again: the simulation reads something besides its input. */
213
+ export interface Flaky {
214
+ readonly _tag: "Flaky";
215
+ readonly violation: Violation;
216
+ readonly seed: number;
217
+ readonly frame: number;
218
+ }
219
+ /** The options or the factory cannot be fuzzed; `message` says why. */
220
+ export interface InvalidOptions {
221
+ readonly _tag: "InvalidOptions";
222
+ readonly message: string;
223
+ }
224
+ /** The world after setup cannot be saved (a `"~encode"` rejected it), so no replay could start there. */
225
+ export interface Unreplayable {
226
+ readonly _tag: "Unreplayable";
227
+ readonly error: Snapshot.SnapshotError;
228
+ }
229
+ /** Why `run` did not pass. */
230
+ export type FuzzError = Found | Flaky | InvalidOptions | Unreplayable;
231
+ /** Every run completed: how many, of how many frames, from which seed. */
232
+ export interface Passed {
233
+ readonly runs: number;
234
+ readonly frames: number;
235
+ readonly seed: number;
236
+ }
237
+ /**
238
+ * Over a `network`: the only input is a `Fuzz.seats`, the fuzzed schedule
239
+ * must rewind and the runtime save (as for `Netcode.rollback`).
240
+ */
241
+ type NetworkChecks<Net, S extends Schema.Any, Fuzzed> = [
242
+ Net
243
+ ] extends [Network] ? {
244
+ readonly inputs: readonly [Seats];
245
+ } & Checkpoint.ValidateRewindable<Fuzzed> & Snapshot.Gate<S, unknown> : unknown;
246
+ /**
247
+ * Fuzzes `options.schedule` of the simulation `make` builds. Each run makes
248
+ * a fresh runtime with `make(playback)` (the `Replay.session` factory),
249
+ * ticks `setup` once, then ticks the schedule up to `frames` times with
250
+ * every input's `generate`d value, checking `invariants` after each frame.
251
+ * The first run that fails is shrunk and returned as a `Found` with a
252
+ * replay; a schedule name that `make` does not return, an invariant that
253
+ * reads what the runtime does not provide, or a schedule service that could
254
+ * not be replayed does not compile.
255
+ *
256
+ * With `network`, every seat of the one `Fuzz.seats` input plays on its own
257
+ * peer (a fresh `make` each, seat 0 ticking `setup`) through
258
+ * `Netcode.rollback` over a seeded `MemoryNetworkLink`, and the invariants
259
+ * are checked on every peer after each frame. A session failure is a
260
+ * `SessionFailed` violation; a schedule that cannot be rewound, or a
261
+ * runtime that cannot save, does not compile.
262
+ */
263
+ 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]> & {
264
+ /** Fuzz every seat as its own peer over a seeded faulty network, with `Netcode.rollback` sessions. */
265
+ readonly network?: Net;
266
+ } & NetworkChecks<Net, S, Schedules[Name]>) => Result.Result<Rendered.Rendered<Passed>, FuzzError>;
267
+ export {};
268
+ //# sourceMappingURL=Fuzz.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Fuzz.d.ts","sourceRoot":"","sources":["../src/Fuzz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAA;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AACtG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,KAAK,QAAQ,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,KAAK,UAAU,MAAM,4BAA4B,CAAA;AAC7D,OAAO,KAAK,KAAK,cAAc,MAAM,4BAA4B,CAAA;AACjE,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAA;AAChD,OAAO,KAAK,KAAK,OAAO,MAAM,iCAAiC,CAAA;AAI/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC,KAAK,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,IAAI,4BAA4B,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAA;AAErH,uGAAuG;AACvG,MAAM,WAAW,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,GAAG,OAAO;IACjE,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjE,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CACvB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,CAAC,OAAO,CAAC,cAChE,UAAU,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,WAC1E;IACP,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;CAC3C,KACA,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAsF,CAAA;AAE7H;;;;;GAKG;AACH,MAAM,WAAW,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,IAAI,GAAG,OAAO,CAAE,SAAQ,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAC3G,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC9C,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CACpB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,cAAc,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,cACjF,UAAU,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,WAC3E;IACP,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/G,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;CACpD,KACA,KAAK,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,CAOxC,CAAA;AAEF;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAA;IACzB,qGAAqG;IACrG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,oGAAoG;IACpG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,4DAA4D;AAC5D,MAAM,WAAW,OAAO,CACtB,IAAI,SAAS,MAAM,EACnB,KAAK,SAAS,MAAM,EACpB,UAAU,SAAS,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;IAErE,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;IACvB,kGAAkG;IAClG,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;IAClD,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qGAAqG;IACrG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wGAAwG;IACxG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,6BAA6B;AAC7B,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5F;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AACrF,iGAAiG;GAC/F;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AAC9F;;;;;GAKG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAA;CAAE,CAAA;AAE5G,uDAAuD;AACvD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+GAA+G;IAC/G,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,UAAU,CAAA;IAClC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAC/H;AAED,6GAA6G;AAC7G,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,yGAAyG;AACzG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAA;CACvC;AAED,8BAA8B;AAC9B,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG,cAAc,GAAG,YAAY,CAAA;AAErE,0EAA0E;AAC1E,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAwED;;;GAGG;AACH,KAAK,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,MAAM,IAClD;IAAC,GAAG;CAAC,SAAS,CAAC,OAAO,CAAC,GACnB;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,CAAA;CAAE,GAAG,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,GACzG,OAAO,CAAA;AAEb;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,GAAG,GACd,CAAC,SAAS,MAAM,CAAC,GAAG,EACpB,IAAI,EACJ,KAAK,CAAC,SAAS,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EACtE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,SAAS,SAAS,MAAM,EACxB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,CAAC,IAAI,SAAS,MAAM,SAAS,GAAG,MAAM,EAC3C,KAAK,CAAC,UAAU,SAAS,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,GAAG,SAAS,EAAE,EACzF,KAAK,CAAC,GAAG,SAAS,OAAO,GAAG,SAAS,GAAG,SAAS,QAE3C,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,WAC5F,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,EAAE,UAAU,CAAC,GACjE,OAAO,CAAC,kBAAkB,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,GACrE,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAC1C;IACA,sGAAsG;IACtG,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,CAAA;CACvB,GACC,aAAa,CAAC,GAAG,EAAE,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,KACzC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CA+KpD,CAAA"}
package/dist/Fuzz.js ADDED
@@ -0,0 +1,355 @@
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 Move = Fuzz.input(Input, {
37
+ * generate: (random) => ({ dx: random.integer(-2, 3) }),
38
+ * neutral: { dx: 0 }
39
+ * })
40
+ * const found = Fuzz.run(make, { schedule: "update", inputs: [Move], invariants: [InsideArena], frames: 600, seed: 7 })
41
+ * if (!found.ok && found.error._tag === "Found") {
42
+ * sink.save(found.error.replay) // the shrunk timeline that still fails
43
+ * console.log(found.error.violation) // the invariant, failure, or defect it hit
44
+ * }
45
+ * ```
46
+ */
47
+ import { Clock } from "@typeonce/ritmo";
48
+ import * as Result from "@typeonce/ritmo/Result";
49
+ import * as Random from "@typeonce/ritmo/Random";
50
+ import * as FuzzNetwork from "./internal/fuzzNetwork.js";
51
+ import * as Rendered from "./Rendered.js";
52
+ import * as Replay from "./Replay.js";
53
+ import * as Session from "./Session.js";
54
+ /**
55
+ * Declares how to fuzz one `snapshot()` source: `generate` draws its value
56
+ * for a frame, of the type the source returns, and `neutral` is the idle
57
+ * value. Pass the result in `run`'s `inputs`. The source is a
58
+ * `snapshot()`-only service (`Schedule.Source`, `InputCapture.SourceOf<...>`
59
+ * for browser input, whose `Controls` action set draws a value with
60
+ * `random` and has `idle` for `neutral`). Use `Keyboard.scripted` (or a
61
+ * scripted source) instead to replay one known sequence.
62
+ */
63
+ export const input = (descriptor, options) => ({ name: descriptor.name, generate: options.generate, neutral: options.neutral });
64
+ /**
65
+ * Declares how to fuzz the seats of a networked game: the
66
+ * `Netcode.Source` service its simulation captures, the input `codec` and
67
+ * `idle` input the game gives `Netcode.seats`, `count` seats, and
68
+ * `generate` for one seat's input on a frame. Pass it as the only input of a
69
+ * `run` with `network`; `make` provides the service with
70
+ * `playback.source(descriptor)` (over a network, that is the peer's
71
+ * `seats.source`). Use `input` for a game without seats.
72
+ */
73
+ export const seats = (descriptor, options) => ({
74
+ name: descriptor.name,
75
+ codec: options.codec,
76
+ count: options.count,
77
+ idle: options.idle,
78
+ neutral: Array.from({ length: options.count }, () => options.idle),
79
+ generate: (random, frame) => Array.from({ length: options.count }, (_, seat) => options.generate(random, frame, seat))
80
+ });
81
+ /** Two violations are the same bug when they name the same invariant, system, or kind of defect. */
82
+ const signature = (violation) => violation._tag === "InvariantViolated" ? `invariant ${violation.invariant}`
83
+ : violation._tag === "SystemFailed" ? `system ${violation.system}`
84
+ : violation._tag === "SessionFailed" ? `session ${violation.error._tag}`
85
+ : `defect ${violation.invariant ?? ""}`;
86
+ const describe = (violation) => {
87
+ if (violation._tag === "InvariantViolated")
88
+ return `invariant ${violation.invariant} broke: ${violation.message}`;
89
+ if (violation._tag === "SessionFailed")
90
+ return `seat ${violation.seat}'s session failed with ${violation.error._tag}${"tick" in violation.error ? ` at tick ${violation.error.tick}` : ""}`;
91
+ const error = violation.error instanceof Error ? violation.error.message : JSON.stringify(violation.error) ?? String(violation.error);
92
+ if (violation._tag === "SystemFailed")
93
+ return `${violation.system} failed: ${error}`;
94
+ return violation.invariant === undefined ? `a system threw: ${error}` : `invariant ${violation.invariant} threw: ${error}`;
95
+ };
96
+ const violationOf = (stop) => {
97
+ switch (stop.reason) {
98
+ case "completed":
99
+ case "until":
100
+ return undefined;
101
+ case "invariant":
102
+ return { _tag: "InvariantViolated", invariant: stop.invariant, message: stop.message };
103
+ case "failure":
104
+ return { _tag: "SystemFailed", system: stop.system, error: stop.error };
105
+ case "ignored-failure":
106
+ return { _tag: "SystemFailed", system: stop.system ?? stop.schedule, error: stop.error };
107
+ case "defect":
108
+ return { _tag: "Defect", invariant: undefined, error: stop.error };
109
+ case "invariant-threw":
110
+ return { _tag: "Defect", invariant: stop.invariant, error: stop.error };
111
+ case "missingRequirements":
112
+ return { _tag: "InvalidOptions", message: `the fuzzed schedule's runtime is missing requirements: ${JSON.stringify(stop.requirements)}` };
113
+ case "tickOrder":
114
+ return { _tag: "InvalidOptions", message: `the fuzzed schedule's tick order is invalid: ${stop.issues.join("; ")}` };
115
+ }
116
+ };
117
+ const same = (left, right) => left === right || JSON.stringify(left) === JSON.stringify(right);
118
+ const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
119
+ /** Values closer to `neutral` than `value`: `neutral` itself, then `value` with one field set to neutral's. */
120
+ const simpler = (value, neutral) => {
121
+ if (same(value, neutral))
122
+ return [];
123
+ const candidates = [neutral];
124
+ // Every seat's input: one seat at a time.
125
+ if (Array.isArray(value) && Array.isArray(neutral) && value.length === neutral.length) {
126
+ value.forEach((item, index) => {
127
+ for (const candidate of simpler(item, neutral[index])) {
128
+ const next = value.map((other, at) => at === index ? candidate : other);
129
+ if (!same(next, neutral))
130
+ candidates.push(next);
131
+ }
132
+ });
133
+ }
134
+ if (isRecord(value) && isRecord(neutral)) {
135
+ const keys = Object.keys(value).filter((key) => !same(value[key], neutral[key]));
136
+ if (keys.length > 1)
137
+ for (const key of keys)
138
+ candidates.push({ ...value, [key]: neutral[key] });
139
+ }
140
+ return candidates;
141
+ };
142
+ /**
143
+ * Fuzzes `options.schedule` of the simulation `make` builds. Each run makes
144
+ * a fresh runtime with `make(playback)` (the `Replay.session` factory),
145
+ * ticks `setup` once, then ticks the schedule up to `frames` times with
146
+ * every input's `generate`d value, checking `invariants` after each frame.
147
+ * The first run that fails is shrunk and returned as a `Found` with a
148
+ * replay; a schedule name that `make` does not return, an invariant that
149
+ * reads what the runtime does not provide, or a schedule service that could
150
+ * not be replayed does not compile.
151
+ *
152
+ * With `network`, every seat of the one `Fuzz.seats` input plays on its own
153
+ * peer (a fresh `make` each, seat 0 ticking `setup`) through
154
+ * `Netcode.rollback` over a seeded `MemoryNetworkLink`, and the invariants
155
+ * are checked on every peer after each frame. A session failure is a
156
+ * `SessionFailed` violation; a schedule that cannot be rewound, or a
157
+ * runtime that cannot save, does not compile.
158
+ */
159
+ export const run = (make, options) => {
160
+ const invalid = (message) => Result.failure({ _tag: "InvalidOptions", message });
161
+ const runs = options.runs ?? 10;
162
+ const budget = options.shrinkAttempts ?? 500;
163
+ if (!Number.isSafeInteger(options.frames) || options.frames < 1)
164
+ return invalid("frames must be a whole number above 0");
165
+ if (!Number.isSafeInteger(runs) || runs < 1)
166
+ return invalid("runs must be a whole number above 0");
167
+ if (!Number.isSafeInteger(options.seed))
168
+ return invalid("seed must be an integer");
169
+ if (!Number.isSafeInteger(budget) || budget < 0)
170
+ return invalid("shrinkAttempts must be a whole number, 0 or more");
171
+ const inputs = options.inputs;
172
+ const indexOf = new Map(inputs.map((entry, index) => [entry.name, index]));
173
+ if (indexOf.size !== inputs.length)
174
+ return invalid("each input must fuzz a different source");
175
+ const neutral = inputs.map((entry) => entry.neutral);
176
+ // `run`'s signature checked the invariants against this runtime's provisions.
177
+ const invariants = (options.invariants ?? []);
178
+ const network = options.network;
179
+ let plan;
180
+ if (network !== undefined) {
181
+ const only = inputs[0];
182
+ if (inputs.length !== 1 || !("codec" in only) || !("count" in only))
183
+ return invalid("over a network, give inputs exactly one Fuzz.seats");
184
+ const seated = only;
185
+ const settle = network.settle ?? 120;
186
+ if (!Number.isSafeInteger(settle) || settle < 0)
187
+ return invalid("network.settle must be a whole number, 0 or more");
188
+ plan = {
189
+ name: seated.name, codec: seated.codec, count: seated.count, idle: seated.idle,
190
+ make, schedule: options.schedule, setup: options.setup, invariants: options.invariants ?? [],
191
+ step: network.step, seed: network.seed, latencyMS: network.latencyMS, jitterMS: network.jitterMS ?? 0, loss: network.loss ?? 0, settle,
192
+ inputDelay: network.inputDelay, maxRollback: network.maxRollback, checksumEvery: network.checksumEvery ?? 10
193
+ };
194
+ }
195
+ /**
196
+ * Runs one fresh simulation over `timeline`; `record` also saves it as a replay with that reason
197
+ * (a text: saved even when it passes).
198
+ */
199
+ const simulateOne = (timeline, record) => {
200
+ let current = neutral;
201
+ const asked = new Set();
202
+ const unknown = [];
203
+ const playback = {
204
+ source: (descriptor) => {
205
+ asked.add(descriptor.name);
206
+ const index = indexOf.get(descriptor.name);
207
+ if (index === undefined)
208
+ unknown.push(descriptor.name);
209
+ // The value was generated for this source's `input`, whose type `input` checked against the descriptor.
210
+ return { snapshot: () => (index === undefined ? undefined : current[index]) };
211
+ },
212
+ constant: () => undefined
213
+ };
214
+ const target = make(playback);
215
+ if (unknown.length > 0)
216
+ 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` } };
217
+ const unread = inputs.filter((entry) => !asked.has(entry.name)).map((entry) => entry.name);
218
+ if (unread.length > 0)
219
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make never asked playback.source for ${unread.join(", ")}: provide the fuzzed source with playback.source(...)` } };
220
+ const schedules = target.schedules;
221
+ const schedule = schedules[options.schedule];
222
+ if (schedule === undefined)
223
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make returned no schedule ${options.schedule}` } };
224
+ const runtime = target.runtime;
225
+ if (options.setup !== undefined) {
226
+ const setup = schedules[options.setup];
227
+ if (setup === undefined)
228
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make returned no schedule ${options.setup}` } };
229
+ const ticked = runtime.tryTick(setup);
230
+ if (!ticked.ok)
231
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: `setup failed with every input neutral: ${JSON.stringify(ticked.error)}` } };
232
+ }
233
+ const start = runtime.snapshot();
234
+ if (!start.ok)
235
+ return { kind: "invalid", error: { _tag: "Unreplayable", error: start.error } };
236
+ const sink = Replay.memorySink();
237
+ // One window over the whole timeline, with its only snapshot at the start.
238
+ // `run`'s signature checked that the schedule's services can be recorded.
239
+ const recorder = record === undefined ? undefined : Replay.recorder(runtime, {
240
+ schedule, name: options.schedule, keep: timeline.length + 1, every: timeline.length + 1, step: Clock.hz(1), sink, hostClock: target.hostClock
241
+ });
242
+ const session = Session.make(runtime, { schedules: { [options.schedule]: schedule }, hostClock: target.hostClock, invariants, history: 1 });
243
+ let ticked = 0;
244
+ current = timeline[0] ?? neutral;
245
+ const played = session.run(options.schedule, {
246
+ frames: timeline.length,
247
+ until: () => {
248
+ ticked += 1;
249
+ current = timeline[ticked] ?? neutral;
250
+ return false;
251
+ }
252
+ });
253
+ session.close();
254
+ const found = violationOf(played.data.stop);
255
+ const frame = ticked + 1;
256
+ const reason = found?._tag === "InvalidOptions" || record === undefined ? undefined
257
+ : typeof record === "string" ? record
258
+ : found === undefined ? undefined
259
+ : record(found, frame);
260
+ const file = reason === undefined ? undefined : recorder?.save(reason);
261
+ recorder?.stop();
262
+ if (found === undefined)
263
+ return { kind: "passed", file };
264
+ if (found._tag === "InvalidOptions")
265
+ return { kind: "invalid", error: found };
266
+ return { kind: "violated", violation: found, frame, file };
267
+ };
268
+ /** Over the network: every seat on its own peer. The replay plays the same timeline on one runtime. */
269
+ const simulate = (timeline, record) => {
270
+ if (plan === undefined)
271
+ return simulateOne(timeline, record);
272
+ const played = FuzzNetwork.play(plan, timeline);
273
+ if (played.kind === "invalid")
274
+ return { kind: "invalid", error: { _tag: "InvalidOptions", message: played.message } };
275
+ if (played.kind === "passed")
276
+ return played;
277
+ const one = record === undefined ? undefined : simulateOne(timeline.slice(0, played.frame), record(played.violation, played.frame));
278
+ return { kind: "violated", violation: played.violation, frame: played.frame, file: one?.kind === "invalid" ? undefined : one?.file };
279
+ };
280
+ for (let index = 0; index < runs; index++) {
281
+ const seed = options.seed + index;
282
+ const random = Random.make(seed);
283
+ const timeline = [];
284
+ for (let frame = 1; frame <= options.frames; frame++)
285
+ timeline.push(inputs.map((entry) => entry.generate(random, frame)));
286
+ const first = simulate(timeline, undefined);
287
+ if (first.kind === "invalid")
288
+ return Result.failure(first.error);
289
+ if (first.kind === "passed")
290
+ continue;
291
+ const target = signature(first.violation);
292
+ let attempts = 0;
293
+ let steps = 0;
294
+ let best = timeline.slice(0, first.frame);
295
+ /** Whether `candidate` still fails the same way; on success, `best` becomes it, cut at its failing frame. */
296
+ const fails = (candidate) => {
297
+ attempts += 1;
298
+ const outcome = simulate(candidate, undefined);
299
+ if (outcome.kind !== "violated" || signature(outcome.violation) !== target)
300
+ return false;
301
+ best = candidate.slice(0, outcome.frame);
302
+ steps += 1;
303
+ return true;
304
+ };
305
+ if (!fails(best))
306
+ return Result.failure({ _tag: "Flaky", violation: first.violation, seed, frame: first.frame });
307
+ steps = 0;
308
+ shrink: for (let changed = true; changed;) {
309
+ changed = false;
310
+ // Drop ranges of frames, halving the range when no range of that size can go.
311
+ for (let size = Math.max(1, Math.floor(best.length / 2)); size >= 1; size = Math.floor(size / 2)) {
312
+ for (let from = 0; from < best.length && best.length > 1;) {
313
+ if (attempts >= budget)
314
+ break shrink;
315
+ if (fails([...best.slice(0, from), ...best.slice(from + size)]))
316
+ changed = true;
317
+ else
318
+ from += size;
319
+ }
320
+ }
321
+ // Move each remaining value toward its input's neutral.
322
+ for (let frame = 0; frame < best.length; frame++) {
323
+ for (let slot = 0; slot < inputs.length; slot++) {
324
+ for (const candidate of simpler(best[frame][slot], neutral[slot])) {
325
+ if (attempts >= budget)
326
+ break shrink;
327
+ const values = [...best[frame]];
328
+ values[slot] = candidate;
329
+ if (fails([...best.slice(0, frame), values, ...best.slice(frame + 1)])) {
330
+ changed = true;
331
+ break;
332
+ }
333
+ }
334
+ }
335
+ }
336
+ }
337
+ 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)`);
338
+ if (final.kind !== "violated" || final.file === undefined || signature(final.violation) !== target) {
339
+ return Result.failure({ _tag: "Flaky", violation: first.violation, seed, frame: first.frame });
340
+ }
341
+ const opened = Replay.session(make, final.file, { invariants });
342
+ const replayed = opened.ok ? violationOf(opened.value.play().data.run.stop) : undefined;
343
+ return Result.failure({
344
+ _tag: "Found",
345
+ violation: final.violation,
346
+ seed,
347
+ frame: final.frame,
348
+ replay: final.file,
349
+ reproduces: replayed !== undefined && replayed._tag !== "InvalidOptions" && signature(replayed) === target,
350
+ shrink: { attempts, steps, fromFrames: Math.min(first.frame, timeline.length), toFrames: best.length }
351
+ });
352
+ }
353
+ 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`));
354
+ };
355
+ //# sourceMappingURL=Fuzz.js.map