@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/src/Fuzz.ts ADDED
@@ -0,0 +1,544 @@
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
+
58
+ import * as FuzzNetwork from "./internal/fuzzNetwork.ts"
59
+
60
+ import type { Invariant } from "./Invariant.ts"
61
+ import * as Rendered from "./Rendered.ts"
62
+ import * as Replay from "./Replay.ts"
63
+ import * as Session from "./Session.ts"
64
+
65
+ type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>
66
+
67
+ /** One fuzzed source, made with {@link input}: what `run` feeds a `snapshot()` service every frame. */
68
+ export interface Input<Name extends string = string, Data = unknown> {
69
+ /** The source service's name. */
70
+ readonly name: Name
71
+ /** The value for `frame` (counting from 1), drawn from the run's seeded generator. */
72
+ readonly generate: (random: Random.Random, frame: number) => Data
73
+ /** The input of a player who does nothing: what shrinking moves values toward. */
74
+ readonly neutral: Data
75
+ }
76
+
77
+ /**
78
+ * Declares how to fuzz one `snapshot()` source: `generate` draws its value
79
+ * for a frame, of the type the source returns, and `neutral` is the idle
80
+ * value. Pass the result in `run`'s `inputs`. The source is a
81
+ * `snapshot()`-only service (`Schedule.Source`, `InputCapture.SourceOf<...>`
82
+ * for browser input, whose `Controls` action set draws a value with
83
+ * `random` and has `idle` for `neutral`). Use `Keyboard.scripted` (or a
84
+ * scripted source) instead to replay one known sequence.
85
+ */
86
+ export const input = <const Name extends string, Value extends Source<unknown>>(
87
+ descriptor: Descriptor<"service", Name, Value> & Replay.ValidateSource<Name, Value>,
88
+ options: {
89
+ readonly generate: (random: Random.Random, frame: number) => Replay.SourceData<Value>
90
+ readonly neutral: Replay.SourceData<Value>
91
+ }
92
+ ): Input<Name, Replay.SourceData<Value>> => ({ name: descriptor.name, generate: options.generate, neutral: options.neutral })
93
+
94
+ /**
95
+ * Every seat's input of a networked game, made with {@link seats}: per
96
+ * frame, one value per seat. Alone it fuzzes the seats source like any
97
+ * `input`; with `run`'s `network`, each seat's value is that peer's local
98
+ * input.
99
+ */
100
+ export interface Seats<Name extends string = string, Data = unknown> extends Input<Name, ReadonlyArray<Data>> {
101
+ /** The schema remote input is decoded with, as given to `Netcode.seats`. */
102
+ readonly codec: CoreDescriptor.Codec<any, any>
103
+ /** How many seats: over a network, how many peers. */
104
+ readonly count: number
105
+ /** The input of a seat that pressed nothing, as given to `Netcode.seats`. */
106
+ readonly idle: Data
107
+ }
108
+
109
+ /**
110
+ * Declares how to fuzz the seats of a networked game: the
111
+ * `Netcode.Source` service its simulation captures, the input `codec` and
112
+ * `idle` input the game gives `Netcode.seats`, `count` seats, and
113
+ * `generate` for one seat's input on a frame. Pass it as the only input of a
114
+ * `run` with `network`; `make` provides the service with
115
+ * `playback.source(descriptor)` (over a network, that is the peer's
116
+ * `seats.source`). Use `input` for a game without seats.
117
+ */
118
+ export const seats = <const Name extends string, const C extends CoreDescriptor.Codec<any, any>>(
119
+ descriptor: Descriptor<"service", Name, Netcode.Source<CoreDescriptor.CodecType<C>>>,
120
+ options: {
121
+ readonly codec: C & CoreDescriptor.CheckedCodec<C>
122
+ readonly count: number
123
+ readonly generate: (random: Random.Random, frame: number, seat: number) => NoInfer<CoreDescriptor.CodecType<C>>
124
+ readonly idle: NoInfer<CoreDescriptor.CodecType<C>>
125
+ }
126
+ ): Seats<Name, CoreDescriptor.CodecType<C>> => ({
127
+ name: descriptor.name,
128
+ codec: options.codec,
129
+ count: options.count,
130
+ idle: options.idle,
131
+ neutral: Array.from({ length: options.count }, () => options.idle),
132
+ generate: (random, frame) => Array.from({ length: options.count }, (_, seat) => options.generate(random, frame, seat))
133
+ })
134
+
135
+ /**
136
+ * How `run` joins the peers when it fuzzes over a network: the seeded link
137
+ * faults (`MemoryNetworkLink.make`'s), kept fixed while shrinking, and the
138
+ * `Netcode.rollback` options every peer's session takes.
139
+ */
140
+ export interface Network {
141
+ /** The link's seed: drops and delays repeat for the same seed. */
142
+ readonly seed: number
143
+ readonly latencyMS: number
144
+ /** Up to this much extra delay per message (0 by default). */
145
+ readonly jitterMS?: number
146
+ /** The share of messages dropped, from 0 to 1 (0 by default). */
147
+ readonly loss?: number
148
+ /** The simulation's fixed step: the test clock moves one step per frame. */
149
+ readonly step: Clock.Step
150
+ /** Idle frames played after the fuzzed ones, so late input and checksums arrive (120 by default). */
151
+ readonly settle?: number
152
+ readonly inputDelay?: number
153
+ readonly maxRollback?: number
154
+ /** Ticks between checksum comparisons (10 by default here, to find a desync close to its cause). */
155
+ readonly checksumEvery?: number
156
+ }
157
+
158
+ /** What `run` fuzzes, how long, and how hard it shrinks. */
159
+ export interface Options<
160
+ Name extends string,
161
+ Names extends string,
162
+ Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>>
163
+ > {
164
+ /** The schedule to fuzz: the one ticked once per simulation step. Its name in the replay. */
165
+ readonly schedule: Name
166
+ /** Ticked once before the fuzzed frames, with every input neutral: the replay starts after it. */
167
+ readonly setup?: Names
168
+ /** The fuzzed sources, each from `input`. */
169
+ readonly inputs: readonly [Input, ...Array<Input>]
170
+ /** Checked after every frame, in order, as in `Session.make`. */
171
+ readonly invariants?: Invariants
172
+ /** Frames per run, a whole number above 0. */
173
+ readonly frames: number
174
+ /** Runs to try, each with a fresh simulation; run `i` draws from seed `seed + i`. Defaults to 10. */
175
+ readonly runs?: number
176
+ /** The first run's seed (an integer). A found bug reports the seed of its run. */
177
+ readonly seed: number
178
+ /** Simulations shrinking may run before it stops with the smallest timeline so far. Defaults to 500. */
179
+ readonly shrinkAttempts?: number
180
+ }
181
+
182
+ /** What a fuzzed run hit. */
183
+ export type Violation =
184
+ | { readonly _tag: "InvariantViolated"; readonly invariant: string; readonly message: string }
185
+ | { readonly _tag: "SystemFailed"; readonly system: string; readonly error: unknown }
186
+ /** A system threw, or `invariant` names the invariant whose check threw (a bug in the check). */
187
+ | { readonly _tag: "Defect"; readonly invariant: string | undefined; readonly error: unknown }
188
+ /**
189
+ * Over a `network`: the session of `seat` failed. `Desynced` is a
190
+ * determinism bug (`Desync.compare` its `snapshot` with the other seat's:
191
+ * the sessions keep them); `TickFailed` and `CheckpointLost` stop a real
192
+ * session too.
193
+ */
194
+ | { readonly _tag: "SessionFailed"; readonly seat: number; readonly error: Netcode.SessionError<unknown> }
195
+
196
+ /** A bug the fuzzer found: the error side of `run`. */
197
+ export interface Found {
198
+ readonly _tag: "Found"
199
+ readonly violation: Violation
200
+ /** The seed of the run that found it: `run` with this `seed` and `runs: 1` finds it again. */
201
+ readonly seed: number
202
+ /** The frame the shrunk timeline fails at: its length, or later over a `network` (the frame a peer saw it). */
203
+ readonly frame: number
204
+ /**
205
+ * The shrunk timeline as a replay; `Replay.session(make, replay, { invariants })` plays it to the violation.
206
+ * Over a `network`, it plays every seat's input on one runtime: step it to see what each tick did,
207
+ * and find the failure again with `run` and the same seeds.
208
+ */
209
+ readonly replay: Replay.ReplayFile
210
+ /**
211
+ * Whether the replay, opened with `Replay.session`, hits the violation
212
+ * again. `false` means restoring the start lost state the bug needs
213
+ * (transient components): reproduce it with `seed` instead.
214
+ */
215
+ readonly reproduces: boolean
216
+ /**
217
+ * How shrinking went: simulations run, candidates kept, and the frames of input before and after
218
+ * (the failing frame, but over a `network`, where a desync shows a few frames after its cause).
219
+ */
220
+ readonly shrink: { readonly attempts: number; readonly steps: number; readonly fromFrames: number; readonly toFrames: number }
221
+ }
222
+
223
+ /** A run failed, but the same input did not fail again: the simulation reads something besides its input. */
224
+ export interface Flaky {
225
+ readonly _tag: "Flaky"
226
+ readonly violation: Violation
227
+ readonly seed: number
228
+ readonly frame: number
229
+ }
230
+
231
+ /** The options or the factory cannot be fuzzed; `message` says why. */
232
+ export interface InvalidOptions {
233
+ readonly _tag: "InvalidOptions"
234
+ readonly message: string
235
+ }
236
+
237
+ /** The world after setup cannot be saved (a `"~encode"` rejected it), so no replay could start there. */
238
+ export interface Unreplayable {
239
+ readonly _tag: "Unreplayable"
240
+ readonly error: Snapshot.SnapshotError
241
+ }
242
+
243
+ /** Why `run` did not pass. */
244
+ export type FuzzError = Found | Flaky | InvalidOptions | Unreplayable
245
+
246
+ /** Every run completed: how many, of how many frames, from which seed. */
247
+ export interface Passed {
248
+ readonly runs: number
249
+ readonly frames: number
250
+ readonly seed: number
251
+ }
252
+
253
+ /** A timeline: per frame, the value of each input, in `inputs` order. */
254
+ type Timeline = ReadonlyArray<ReadonlyArray<unknown>>
255
+
256
+ type Outcome =
257
+ | { readonly kind: "passed"; readonly file?: Replay.ReplayFile | undefined }
258
+ | { readonly kind: "violated"; readonly violation: Violation; readonly frame: number; readonly file: Replay.ReplayFile | undefined }
259
+ | { readonly kind: "invalid"; readonly error: InvalidOptions | Unreplayable }
260
+
261
+ /** Two violations are the same bug when they name the same invariant, system, or kind of defect. */
262
+ const signature = (violation: Violation): string =>
263
+ violation._tag === "InvariantViolated" ? `invariant ${violation.invariant}`
264
+ : violation._tag === "SystemFailed" ? `system ${violation.system}`
265
+ : violation._tag === "SessionFailed" ? `session ${violation.error._tag}`
266
+ : `defect ${violation.invariant ?? ""}`
267
+
268
+ const describe = (violation: Violation): string => {
269
+ if (violation._tag === "InvariantViolated") return `invariant ${violation.invariant} broke: ${violation.message}`
270
+ if (violation._tag === "SessionFailed") return `seat ${violation.seat}'s session failed with ${violation.error._tag}${"tick" in violation.error ? ` at tick ${violation.error.tick}` : ""}`
271
+ const error = violation.error instanceof Error ? violation.error.message : JSON.stringify(violation.error) ?? String(violation.error)
272
+ if (violation._tag === "SystemFailed") return `${violation.system} failed: ${error}`
273
+ return violation.invariant === undefined ? `a system threw: ${error}` : `invariant ${violation.invariant} threw: ${error}`
274
+ }
275
+
276
+ const violationOf = (stop: Session.Stop): Violation | InvalidOptions | undefined => {
277
+ switch (stop.reason) {
278
+ case "completed":
279
+ case "until":
280
+ return undefined
281
+ case "invariant":
282
+ return { _tag: "InvariantViolated", invariant: stop.invariant, message: stop.message }
283
+ case "failure":
284
+ return { _tag: "SystemFailed", system: stop.system, error: stop.error }
285
+ case "ignored-failure":
286
+ return { _tag: "SystemFailed", system: stop.system ?? stop.schedule, error: stop.error }
287
+ case "defect":
288
+ return { _tag: "Defect", invariant: undefined, error: stop.error }
289
+ case "invariant-threw":
290
+ return { _tag: "Defect", invariant: stop.invariant, error: stop.error }
291
+ case "missingRequirements":
292
+ return { _tag: "InvalidOptions", message: `the fuzzed schedule's runtime is missing requirements: ${JSON.stringify(stop.requirements)}` }
293
+ case "tickOrder":
294
+ return { _tag: "InvalidOptions", message: `the fuzzed schedule's tick order is invalid: ${stop.issues.join("; ")}` }
295
+ }
296
+ }
297
+
298
+ const same = (left: unknown, right: unknown): boolean => left === right || JSON.stringify(left) === JSON.stringify(right)
299
+
300
+ const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
301
+ typeof value === "object" && value !== null && !Array.isArray(value)
302
+
303
+ /** Values closer to `neutral` than `value`: `neutral` itself, then `value` with one field set to neutral's. */
304
+ const simpler = (value: unknown, neutral: unknown): Array<unknown> => {
305
+ if (same(value, neutral)) return []
306
+ const candidates: Array<unknown> = [neutral]
307
+ // Every seat's input: one seat at a time.
308
+ if (Array.isArray(value) && Array.isArray(neutral) && value.length === neutral.length) {
309
+ value.forEach((item, index) => {
310
+ for (const candidate of simpler(item, neutral[index])) {
311
+ const next = value.map((other, at) => at === index ? candidate : other)
312
+ if (!same(next, neutral)) candidates.push(next)
313
+ }
314
+ })
315
+ }
316
+ if (isRecord(value) && isRecord(neutral)) {
317
+ const keys = Object.keys(value).filter((key) => !same(value[key], neutral[key]))
318
+ if (keys.length > 1) for (const key of keys) candidates.push({ ...value, [key]: neutral[key] })
319
+ }
320
+ return candidates
321
+ }
322
+
323
+ /**
324
+ * Over a `network`: the only input is a `Fuzz.seats`, the fuzzed schedule
325
+ * must rewind and the runtime save (as for `Netcode.rollback`).
326
+ */
327
+ type NetworkChecks<Net, S extends Schema.Any, Fuzzed> =
328
+ [Net] extends [Network]
329
+ ? { readonly inputs: readonly [Seats] } & Checkpoint.ValidateRewindable<Fuzzed> & Snapshot.Gate<S, unknown>
330
+ : unknown
331
+
332
+ /**
333
+ * Fuzzes `options.schedule` of the simulation `make` builds. Each run makes
334
+ * a fresh runtime with `make(playback)` (the `Replay.session` factory),
335
+ * ticks `setup` once, then ticks the schedule up to `frames` times with
336
+ * every input's `generate`d value, checking `invariants` after each frame.
337
+ * The first run that fails is shrunk and returned as a `Found` with a
338
+ * replay; a schedule name that `make` does not return, an invariant that
339
+ * reads what the runtime does not provide, or a schedule service that could
340
+ * not be replayed does not compile.
341
+ *
342
+ * With `network`, every seat of the one `Fuzz.seats` input plays on its own
343
+ * peer (a fresh `make` each, seat 0 ticking `setup`) through
344
+ * `Netcode.rollback` over a seeded `MemoryNetworkLink`, and the invariants
345
+ * are checked on every peer after each frame. A session failure is a
346
+ * `SessionFailed` violation; a schedule that cannot be rewound, or a
347
+ * runtime that cannot save, does not compile.
348
+ */
349
+ export const run = <
350
+ S extends Schema.Any,
351
+ Root,
352
+ const Schedules extends Readonly<Record<string, AnySchedule<S, Root>>>,
353
+ Services extends Record<string, unknown>,
354
+ Resources extends object,
355
+ Machines extends Record<string, unknown>,
356
+ const Name extends keyof Schedules & string,
357
+ const Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [],
358
+ const Net extends Network | undefined = undefined
359
+ >(
360
+ make: (playback: Replay.Playback) => Replay.Target<S, Root, Schedules, Services, Resources, Machines>,
361
+ options: Options<Name, NoInfer<keyof Schedules & string>, Invariants>
362
+ & Session.ValidateInvariants<Invariants, Services, Resources, Machines>
363
+ & Replay.ValidateRecordable<Schedules[Name]>
364
+ & {
365
+ /** Fuzz every seat as its own peer over a seeded faulty network, with `Netcode.rollback` sessions. */
366
+ readonly network?: Net
367
+ }
368
+ & NetworkChecks<Net, S, Schedules[Name]>
369
+ ): Result.Result<Rendered.Rendered<Passed>, FuzzError> => {
370
+ const invalid = (message: string) => Result.failure<FuzzError>({ _tag: "InvalidOptions", message })
371
+ const runs = options.runs ?? 10
372
+ const budget = options.shrinkAttempts ?? 500
373
+ if (!Number.isSafeInteger(options.frames) || options.frames < 1) return invalid("frames must be a whole number above 0")
374
+ if (!Number.isSafeInteger(runs) || runs < 1) return invalid("runs must be a whole number above 0")
375
+ if (!Number.isSafeInteger(options.seed)) return invalid("seed must be an integer")
376
+ if (!Number.isSafeInteger(budget) || budget < 0) return invalid("shrinkAttempts must be a whole number, 0 or more")
377
+ const inputs: ReadonlyArray<Input> = options.inputs
378
+ const indexOf = new Map(inputs.map((entry, index) => [entry.name, index] as const))
379
+ if (indexOf.size !== inputs.length) return invalid("each input must fuzz a different source")
380
+ const neutral: ReadonlyArray<unknown> = inputs.map((entry) => entry.neutral)
381
+ // `run`'s signature checked the invariants against this runtime's provisions.
382
+ const invariants = (options.invariants ?? []) as readonly []
383
+ const network: Network | undefined = options.network
384
+ let plan: FuzzNetwork.NetworkPlan | undefined
385
+ if (network !== undefined) {
386
+ const only = inputs[0]!
387
+ if (inputs.length !== 1 || !("codec" in only) || !("count" in only)) return invalid("over a network, give inputs exactly one Fuzz.seats")
388
+ const seated = only as Seats
389
+ const settle = network.settle ?? 120
390
+ if (!Number.isSafeInteger(settle) || settle < 0) return invalid("network.settle must be a whole number, 0 or more")
391
+ plan = {
392
+ name: seated.name, codec: seated.codec, count: seated.count, idle: seated.idle,
393
+ make, schedule: options.schedule, setup: options.setup, invariants: options.invariants ?? [],
394
+ step: network.step, seed: network.seed, latencyMS: network.latencyMS, jitterMS: network.jitterMS ?? 0, loss: network.loss ?? 0, settle,
395
+ inputDelay: network.inputDelay, maxRollback: network.maxRollback, checksumEvery: network.checksumEvery ?? 10
396
+ }
397
+ }
398
+
399
+ /**
400
+ * Runs one fresh simulation over `timeline`; `record` also saves it as a replay with that reason
401
+ * (a text: saved even when it passes).
402
+ */
403
+ const simulateOne = (timeline: Timeline, record: ((violation: Violation, frame: number) => string) | string | undefined): Outcome => {
404
+ let current = neutral
405
+ const asked = new Set<string>()
406
+ const unknown: Array<string> = []
407
+ const playback: Replay.Playback = {
408
+ source: <const SourceName extends string, Value extends Source<unknown>>(descriptor: Descriptor<"service", SourceName, Value>): Source<Replay.SourceData<Value>> => {
409
+ asked.add(descriptor.name)
410
+ const index = indexOf.get(descriptor.name)
411
+ if (index === undefined) unknown.push(descriptor.name)
412
+ // The value was generated for this source's `input`, whose type `input` checked against the descriptor.
413
+ return { snapshot: () => (index === undefined ? undefined : current[index]) as Replay.SourceData<Value> }
414
+ },
415
+ constant: () => undefined
416
+ }
417
+ const target = make(playback)
418
+ if (unknown.length > 0) 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` } }
419
+ const unread = inputs.filter((entry) => !asked.has(entry.name)).map((entry) => entry.name)
420
+ if (unread.length > 0) return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make never asked playback.source for ${unread.join(", ")}: provide the fuzzed source with playback.source(...)` } }
421
+ const schedules: Readonly<Record<string, AnySchedule<S, Root> | undefined>> = target.schedules
422
+ const schedule = schedules[options.schedule]
423
+ if (schedule === undefined) return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make returned no schedule ${options.schedule}` } }
424
+ const runtime: Session.Target<S, Root> & Replay.Recordable<S, Root> = target.runtime
425
+ if (options.setup !== undefined) {
426
+ const setup = schedules[options.setup]
427
+ if (setup === undefined) return { kind: "invalid", error: { _tag: "InvalidOptions", message: `make returned no schedule ${options.setup}` } }
428
+ const ticked = runtime.tryTick(setup)
429
+ if (!ticked.ok) return { kind: "invalid", error: { _tag: "InvalidOptions", message: `setup failed with every input neutral: ${JSON.stringify(ticked.error)}` } }
430
+ }
431
+ const start = runtime.snapshot()
432
+ if (!start.ok) return { kind: "invalid", error: { _tag: "Unreplayable", error: start.error } }
433
+
434
+ const sink = Replay.memorySink()
435
+ // One window over the whole timeline, with its only snapshot at the start.
436
+ // `run`'s signature checked that the schedule's services can be recorded.
437
+ const recorder = record === undefined ? undefined : Replay.recorder(runtime, {
438
+ schedule, name: options.schedule, keep: timeline.length + 1, every: timeline.length + 1, step: Clock.hz(1), sink, hostClock: target.hostClock
439
+ } as never)
440
+ const session = Session.make(runtime, { schedules: { [options.schedule]: schedule }, hostClock: target.hostClock, invariants, history: 1 })
441
+ let ticked = 0
442
+ current = timeline[0] ?? neutral
443
+ const played = session.run(options.schedule, {
444
+ frames: timeline.length,
445
+ until: () => {
446
+ ticked += 1
447
+ current = timeline[ticked] ?? neutral
448
+ return false
449
+ }
450
+ })
451
+ session.close()
452
+ const found = violationOf(played.data.stop)
453
+ const frame = ticked + 1
454
+ const reason = found?._tag === "InvalidOptions" || record === undefined ? undefined
455
+ : typeof record === "string" ? record
456
+ : found === undefined ? undefined
457
+ : record(found, frame)
458
+ const file = reason === undefined ? undefined : recorder?.save(reason)
459
+ recorder?.stop()
460
+ if (found === undefined) return { kind: "passed", file }
461
+ if (found._tag === "InvalidOptions") return { kind: "invalid", error: found }
462
+ return { kind: "violated", violation: found, frame, file }
463
+ }
464
+
465
+ /** Over the network: every seat on its own peer. The replay plays the same timeline on one runtime. */
466
+ const simulate = (timeline: Timeline, record: ((violation: Violation, frame: number) => string) | undefined): Outcome => {
467
+ if (plan === undefined) return simulateOne(timeline, record)
468
+ const played = FuzzNetwork.play(plan, timeline)
469
+ if (played.kind === "invalid") return { kind: "invalid", error: { _tag: "InvalidOptions", message: played.message } }
470
+ if (played.kind === "passed") return played
471
+ const one = record === undefined ? undefined : simulateOne(timeline.slice(0, played.frame), record(played.violation, played.frame))
472
+ return { kind: "violated", violation: played.violation, frame: played.frame, file: one?.kind === "invalid" ? undefined : one?.file }
473
+ }
474
+
475
+ for (let index = 0; index < runs; index++) {
476
+ const seed = options.seed + index
477
+ const random = Random.make(seed)
478
+ const timeline: Array<ReadonlyArray<unknown>> = []
479
+ for (let frame = 1; frame <= options.frames; frame++) timeline.push(inputs.map((entry) => entry.generate(random, frame)))
480
+ const first = simulate(timeline, undefined)
481
+ if (first.kind === "invalid") return Result.failure(first.error)
482
+ if (first.kind === "passed") continue
483
+ const target = signature(first.violation)
484
+ let attempts = 0
485
+ let steps = 0
486
+ let best: Timeline = timeline.slice(0, first.frame)
487
+ /** Whether `candidate` still fails the same way; on success, `best` becomes it, cut at its failing frame. */
488
+ const fails = (candidate: Timeline): boolean => {
489
+ attempts += 1
490
+ const outcome = simulate(candidate, undefined)
491
+ if (outcome.kind !== "violated" || signature(outcome.violation) !== target) return false
492
+ best = candidate.slice(0, outcome.frame)
493
+ steps += 1
494
+ return true
495
+ }
496
+ if (!fails(best)) return Result.failure({ _tag: "Flaky", violation: first.violation, seed, frame: first.frame })
497
+ steps = 0
498
+ shrink: for (let changed = true; changed;) {
499
+ changed = false
500
+ // Drop ranges of frames, halving the range when no range of that size can go.
501
+ for (let size = Math.max(1, Math.floor(best.length / 2)); size >= 1; size = Math.floor(size / 2)) {
502
+ for (let from = 0; from < best.length && best.length > 1;) {
503
+ if (attempts >= budget) break shrink
504
+ if (fails([...best.slice(0, from), ...best.slice(from + size)])) changed = true
505
+ else from += size
506
+ }
507
+ }
508
+ // Move each remaining value toward its input's neutral.
509
+ for (let frame = 0; frame < best.length; frame++) {
510
+ for (let slot = 0; slot < inputs.length; slot++) {
511
+ for (const candidate of simpler(best[frame]![slot], neutral[slot])) {
512
+ if (attempts >= budget) break shrink
513
+ const values = [...best[frame]!]
514
+ values[slot] = candidate
515
+ if (fails([...best.slice(0, frame), values, ...best.slice(frame + 1)])) {
516
+ changed = true
517
+ break
518
+ }
519
+ }
520
+ }
521
+ }
522
+ }
523
+ const final = simulate(best, (violation, frame) =>
524
+ `fuzz seed ${seed}${network === undefined ? "" : ` over network seed ${network.seed}`}: ${describe(violation)} at frame ${frame} (shrunk from ${Math.min(first.frame, timeline.length)} frames)`)
525
+ if (final.kind !== "violated" || final.file === undefined || signature(final.violation) !== target) {
526
+ return Result.failure({ _tag: "Flaky", violation: first.violation, seed, frame: first.frame })
527
+ }
528
+ const opened = Replay.session(make, final.file, { invariants })
529
+ const replayed = opened.ok ? violationOf(opened.value.play().data.run.stop) : undefined
530
+ return Result.failure({
531
+ _tag: "Found",
532
+ violation: final.violation,
533
+ seed,
534
+ frame: final.frame,
535
+ replay: final.file,
536
+ reproduces: replayed !== undefined && replayed._tag !== "InvalidOptions" && signature(replayed) === target,
537
+ shrink: { attempts, steps, fromFrames: Math.min(first.frame, timeline.length), toFrames: best.length }
538
+ })
539
+ }
540
+ return Result.success(Rendered.make(
541
+ { runs, frames: options.frames, seed: options.seed },
542
+ `${runs} run${runs === 1 ? "" : "s"} of ${options.frames} frames from seed ${options.seed}: no invariant broke, no system failed, nothing threw`
543
+ ))
544
+ }
package/src/Invariant.ts CHANGED
@@ -8,6 +8,10 @@
8
8
  * invariant that reads a resource, service, or machine the runtime does not
9
9
  * provide. The invariant is named after its inspector.
10
10
  *
11
+ * Write entities in the message as `e${id}`: a session with `labels` prints
12
+ * each one with its label (`player e12`) in the run summary; the run's
13
+ * `stop.message` keeps the text the inspector returned.
14
+ *
11
15
  * Use `Invariant.fromInspector` for checks over the world during a session.
12
16
  * Use `Game.Inspector` with `runtime.inspect(...)` directly for one-off reads
13
17
  * in tests and scripts.
@@ -20,9 +24,9 @@
20
24
  * const PlayerInsideWorld = Invariant.fromInspector(Game.Inspector("player inside world", {
21
25
  * queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
22
26
  * }, ({ queries }) => {
23
- * for (const { data } of queries.players.each()) {
27
+ * for (const { entity, data } of queries.players.each()) {
24
28
  * const { x } = data.position.get()
25
- * if (x < 0 || x > WORLD_WIDTH) return `player at x=${x}`
29
+ * if (x < 0 || x > WORLD_WIDTH) return `e${entity.id} at x=${x}`
26
30
  * }
27
31
  * return undefined
28
32
  * }))
package/src/Lint.ts CHANGED
@@ -6,13 +6,16 @@
6
6
  * Run it from a game's `check` script with the CLI:
7
7
  *
8
8
  * ```sh
9
- * ritmo-devtools lint src/simulation.ts
9
+ * ritmo-devtools lint src/lint.ts
10
10
  * ```
11
11
  *
12
12
  * The entry module exports `lintTarget`, a function that builds the game's
13
13
  * headless runtime (made with `debug: { hostClock }`) and names its schedules: the
14
14
  * ones ticked headless in `schedules`, and the ones that need a renderer or
15
15
  * other host services in `describe` (described and linted, never run).
16
+ * Keep the entry beside the simulation, not inside it, and import the host
17
+ * schedules inside `lintTarget`: the entry is then the one module that loads
18
+ * both, and the simulation never imports render or audio code.
16
19
  *
17
20
  * Use `Session.make(...).describe()` instead to read the lints while
18
21
  * debugging; this module is for the pass/fail check.
@@ -22,8 +25,11 @@
22
25
  *
23
26
  * @example
24
27
  * ```ts
25
- * // src/simulation.ts
26
- * export const lintTarget = (): Lint.Target<typeof Game.schema, typeof Game.schema> => {
28
+ * // src/lint.ts
29
+ * import { createSimulation } from "./simulation.ts"
30
+ *
31
+ * export const lintTarget = async (): Promise<Lint.Target<typeof Game.schema, typeof Game.schema>> => {
32
+ * const { render } = await import("./render.ts")
27
33
  * const sim = createSimulation({ keyboard: Keyboard.scripted(bindings, []) })
28
34
  * return { runtime: sim.runtime, schedules: { setup: sim.setup, update: sim.update }, describe: { render } }
29
35
  * }