@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/Session.ts CHANGED
@@ -7,21 +7,34 @@
7
7
  * - `run(name, { frames, until })` ticks a schedule frame by frame and stops
8
8
  * at the first system failure, thrown defect, or violated invariant (an
9
9
  * invariant that throws stops it as `invariant-threw`).
10
+ * - `step(name)` begins one frame and runs it a step at a time
11
+ * (`until(System)`, `next()`, `finish()`), for a value that goes wrong
12
+ * between two systems of one frame. `journal`, `why`, and `dump` show the
13
+ * partial frame.
10
14
  * - `journal(filter)` lists what happened, one fact per line, filtered by
11
15
  * frames, entity, component, resource, event, machine, system, or kind.
12
16
  * - `why(entity, component)` lists the latest changes to one component, and
13
- * the systems whose declared `spawns` could have spawned the entity.
17
+ * the systems whose declared `spawns` could have spawned the entity. With
18
+ * `depth` above 1 it follows each change back through what the writing
19
+ * system declared it reads, one level per step (see {@link WhyOptions}).
14
20
  * - `system(name)` shows one system's declared access and recent activity.
15
21
  * - `describe()`, `dump(filter)`, `streams()` render the core debug handle.
16
22
  * - `report()` summarizes per-system timing and warnings accumulated while
17
23
  * tracing: failed systems, missed reads, commands and next states still
18
24
  * pending at the end of a frame, failed transitions, skipped systems that
19
25
  * discarded messages, sent events no system reads, NaN or infinite numbers
20
- * written anywhere, entity counts that keep growing through a run, and
26
+ * written anywhere, numbers written outside a field's declared `range`
27
+ * (the descriptor's `meta` option), entity counts that keep growing through a run, and
21
28
  * failed tick results nobody read.
22
29
  *
23
30
  * Everything returns a `Rendered` value that prints as text.
24
31
  *
32
+ * With `labels`, every entity in that text prints as `player e12` instead of
33
+ * `e12`: journal and `why` lines, `dump`, report warnings, and invariant
34
+ * messages. Labels are evaluated after every frame of a `run`, so a line
35
+ * shows the label its entity had at the end of the line's frame; an entity
36
+ * despawned by then keeps the last label it had.
37
+ *
25
38
  * @module Session
26
39
  * @docGroup devtools
27
40
  *
@@ -30,7 +43,8 @@
30
43
  * const session = Session.make(runtime, {
31
44
  * hostClock: HostClock.test(),
32
45
  * schedules: { setup: setupSchedule, update: updateSchedule },
33
- * invariants: [PlayerInsideWorld]
46
+ * invariants: [PlayerInsideWorld],
47
+ * labels: Labels
34
48
  * })
35
49
  * session.run("setup")
36
50
  * console.log(session.run("update", { frames: 300 }))
@@ -38,19 +52,19 @@
38
52
  * console.log(session.journal({ frames: [180, 185], entity: 1 }))
39
53
  * ```
40
54
  */
41
- import { HostClock } from "@typeonce/ritmo"
55
+ import { HostClock, Result } from "@typeonce/ritmo"
42
56
  import type * as Debug from "@typeonce/ritmo/Debug"
43
57
  import type * as Inspector from "@typeonce/ritmo/Inspector"
44
58
  import type * as Machine from "@typeonce/ritmo/Machine"
45
- import type * as Result from "@typeonce/ritmo/Result"
46
59
  import type * as Runtime from "@typeonce/ritmo/Runtime"
47
60
  import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
48
61
  import type { Schema } from "@typeonce/ritmo/Schema"
62
+ import type { SystemDefinition } from "@typeonce/ritmo/System"
49
63
 
50
64
  import * as Format from "./Format.ts"
51
65
  import type { Invariant } from "./Invariant.ts"
52
66
  import * as Rendered from "./Rendered.ts"
53
- import { nonFinitePath } from "./internal/values.ts"
67
+ import { nonFinitePath, rangesOf } from "./internal/values.ts"
54
68
 
55
69
  /**
56
70
  * What a session needs from a runtime: its debug handle, the dynamic
@@ -97,12 +111,59 @@ export type ValidateInvariants<
97
111
  ? unknown
98
112
  : { readonly __fixInvariantRequirements__: InvariantRequirementErrors<Invariants, Services, Resources, Machines> }
99
113
 
114
+ /**
115
+ * Names entities in devtools text: a `Game.Inspector` returning a
116
+ * `ReadonlyMap<number, string>` from entity id to label (`player`,
117
+ * `enemy:slime`). It reads the world like an invariant does and is checked
118
+ * the same way; {@link ValidateLabels} rejects one returning anything else.
119
+ * It runs only in a debug session: the game and its runtime never call it.
120
+ *
121
+ * @example
122
+ * ```ts
123
+ * const Labels = Game.Inspector("labels", {
124
+ * queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
125
+ * }, ({ queries }) => new Map(queries.players.each().map((match) => [match.entity.id, "player"] as const)))
126
+ * Session.make(runtime, { hostClock, schedules: { update }, labels: Labels })
127
+ * ```
128
+ */
129
+ export type LabelsInspector<Root = any> = Inspector.InspectorDefinition<any, unknown, Root, any, any>
130
+
131
+ type LabelsRequirementErrors<
132
+ Labels extends Inspector.Inspector.Any,
133
+ Services extends Record<string, unknown>,
134
+ Resources extends object,
135
+ Machines extends Record<string, unknown>
136
+ > = Runtime.ValidateInspector<Labels, Services, Resources, Machines> extends {
137
+ readonly __fixRuntimeRequirements__: infer Errors
138
+ }
139
+ ? Errors
140
+ : never
141
+
142
+ /**
143
+ * Rejects a `labels` inspector that does not return a
144
+ * `ReadonlyMap<number, string>`, or that reads a resource, service, or
145
+ * machine the runtime does not provide (named like invariants' are).
146
+ */
147
+ export type ValidateLabels<
148
+ Labels extends Inspector.Inspector.Any,
149
+ Services extends Record<string, unknown>,
150
+ Resources extends object,
151
+ Machines extends Record<string, unknown>
152
+ > = [Labels] extends [never]
153
+ ? unknown
154
+ : [Inspector.Inspector.Value<Labels>] extends [ReadonlyMap<number, string>]
155
+ ? [LabelsRequirementErrors<Labels, Services, Resources, Machines>] extends [never]
156
+ ? unknown
157
+ : { readonly __fixLabelsRequirements__: LabelsRequirementErrors<Labels, Services, Resources, Machines> }
158
+ : { readonly __fixLabels__: "labels must return a ReadonlyMap<number, string> from entity id to label" }
159
+
100
160
  /** What `Session.make` drives and checks, and how it prints. */
101
161
  export interface Options<
102
162
  S extends Schema.Any,
103
163
  Root,
104
164
  Names extends string,
105
- Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly []
165
+ Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly [],
166
+ Labels extends LabelsInspector<Root> = never
106
167
  > {
107
168
  /** The schedules `run` can drive, by name. Also names them in traces. */
108
169
  readonly schedules: Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>
@@ -124,6 +185,14 @@ export interface Options<
124
185
  * stops the run. Built with `Invariant.fromInspector(Game.Inspector(...))`.
125
186
  */
126
187
  readonly invariants?: Invariants
188
+ /**
189
+ * Names entities in all text output (`player e12`), from a
190
+ * {@link LabelsInspector}. Evaluated after every frame of a `run` (and
191
+ * when a query finds frames ticked outside `run`), so journal lines show
192
+ * the label from the end of their frame; despawned entities keep their
193
+ * last label.
194
+ */
195
+ readonly labels?: Labels
127
196
  /** Frames of trace history kept for `journal` and `why`. Defaults to 600. */
128
197
  readonly history?: number
129
198
  /**
@@ -156,6 +225,8 @@ export type Stop =
156
225
  | { readonly reason: "invariant"; readonly frame: number; readonly invariant: string; readonly message: string }
157
226
  /** The invariant itself threw: a bug in the check, not a violation. Fix the check, then run again. */
158
227
  | { readonly reason: "invariant-threw"; readonly frame: number; readonly invariant: string; readonly error: unknown }
228
+ /** The `labels` inspector threw: a bug in it. Fix it, then run again. */
229
+ | { readonly reason: "labels-threw"; readonly frame: number; readonly error: unknown }
159
230
  /**
160
231
  * A failed tick result nobody read (for example a setup tick the game ran
161
232
  * before this run): `frame` is the failed tick's, `skipped` the systems
@@ -229,6 +300,46 @@ export interface JournalFilter<S extends Schema.Any> {
229
300
  readonly verbose?: boolean
230
301
  }
231
302
 
303
+ /**
304
+ * How far `why` and `whyResource` look back.
305
+ *
306
+ * The trace records what systems wrote, not what they read, so a level
307
+ * past the first comes from declarations: under each change, one indented
308
+ * `read` line per read the writing system declares, each with the latest
309
+ * traced fact that could have produced the value it saw then:
310
+ *
311
+ * - an event: what was published to it since the system's previous run,
312
+ * and by which system (or `runtime.send`);
313
+ * - a component of the written entity, read in the query that wrote it: the
314
+ * latest write, spawn, or insert of it on that entity before the run;
315
+ * - a component of any other query: only how many entities match it now,
316
+ * since the trace does not say which ones the system read;
317
+ * - a resource: its latest write before the run;
318
+ * - a machine: its latest transition or field update before the run.
319
+ *
320
+ * Every such line ends in `(declared)`: a possible cause, not an observed
321
+ * read. A system already in the chain is printed with `(cycle: not
322
+ * followed)` and not followed again.
323
+ *
324
+ * @example
325
+ * ```ts
326
+ * session.why(12, Health, { depth: 3 })
327
+ * // f181 update Game/ApplyDamage write e12 Game/Health 70 -> 40
328
+ * // read Game/Damage [{amount:30}] (declared), emitted by Game/Hitscan at f181
329
+ * // read e12 Game/Aim {target:7} (declared), written by Game/AimAtNewest at f180
330
+ * ```
331
+ */
332
+ export interface WhyOptions {
333
+ /** Changes listed, and reads listed under each change. Defaults to 5. */
334
+ readonly limit?: number
335
+ /**
336
+ * Levels printed: 1 (the default) lists the changes alone; 2 adds what
337
+ * each writing system declared it reads and who produced it; 3 adds the
338
+ * reads of those producers, and so on.
339
+ */
340
+ readonly depth?: number
341
+ }
342
+
232
343
  /** One system's runs and timing over the session, in `report()` and `system(name)`. */
233
344
  export interface SystemStats {
234
345
  readonly system: string
@@ -257,6 +368,7 @@ export interface Warning {
257
368
  | "sent-event-unread"
258
369
  | "system-failed"
259
370
  | "non-finite-value"
371
+ | "out-of-range"
260
372
  | "population-growing"
261
373
  | "ignored-failure"
262
374
  readonly message: string
@@ -286,16 +398,122 @@ export interface SystemActivity {
286
398
  readonly recent: ReadonlyArray<Format.Line>
287
399
  }
288
400
 
401
+ type AnySystem = SystemDefinition<any, any, any, any, any>
402
+
403
+ /** The systems a schedule runs as its own steps: nested schedules included, transition schedules (run inside a marker) not. */
404
+ type StepSystemsIn<Entry> =
405
+ Entry extends AnySystem ? Entry
406
+ : Entry extends { readonly kind: "applyStateTransitions" } ? never
407
+ : Entry extends { readonly __order?: (_: never) => infer Order extends AnyScheduleOrder } ? StepSystemsIn<Order["entries"][number]>
408
+ : never
409
+
410
+ /**
411
+ * The systems `frame.until(...)` accepts for one schedule: the systems it
412
+ * runs as steps, so a system of another schedule does not compile. A
413
+ * schedule whose type was widened accepts any system, and `until` reports
414
+ * one it does not run as `notAhead`.
415
+ */
416
+ export type StepSystem<Schedule> = [StepSystemsIn<Schedule>] extends [never] ? AnySystem : StepSystemsIn<Schedule>
417
+
418
+ /**
419
+ * Why a step call did not get where it was asked to.
420
+ *
421
+ * - `frameEnded`: the frame already ended (its last step ran, or a system
422
+ * failed); nothing ran. `finish()` reports the frame.
423
+ * - `notAhead`: the system is not among the steps left (it already ran
424
+ * this frame, or the schedule does not run it as a step); nothing ran.
425
+ * - `failure` / `defect`: a system returned a failure or a step threw; the
426
+ * steps after it do not run this frame, and the frame ended.
427
+ * - `missingRequirements` / `tickOrder`: the frame never began, as `run`
428
+ * reports them.
429
+ */
430
+ export type StepStop =
431
+ | { readonly reason: "frameEnded"; readonly frame: number }
432
+ | { readonly reason: "notAhead"; readonly frame: number; readonly system: string; readonly remaining: ReadonlyArray<Debug.StepDescription> }
433
+ | Extract<Stop, { readonly reason: "failure" | "defect" | "missingRequirements" | "tickOrder" }>
434
+
435
+ /** Where `frame.until(system)` stopped: before `system`, which has not run yet. */
436
+ export interface StepReached {
437
+ readonly frame: number
438
+ readonly system: string
439
+ /** The steps this call ran, in order (empty when `system` was already next). */
440
+ readonly ran: ReadonlyArray<Debug.StepDescription>
441
+ }
442
+
443
+ /** The step `frame.next()` ran. */
444
+ export interface StepRan {
445
+ readonly frame: number
446
+ readonly step: Debug.StepDescription
447
+ /** `true` when it was the last step: the frame ended, and `finish()` evaluates it. */
448
+ readonly ended: boolean
449
+ }
450
+
451
+ /** A violated or throwing invariant found by `frame.check()`. */
452
+ export type CheckStop = Extract<Stop, { readonly reason: "invariant" | "invariant-threw" }>
453
+
454
+ /**
455
+ * One frame of a schedule run a step at a time, begun by `session.step(name)`.
456
+ * Each system run still commits at its end, markers apply at their position,
457
+ * and reader cursors advance as in `run`: only the pauses are new. While it
458
+ * is open, `run`, `step`, and the runtime's `tick`, `send`, `snapshot`,
459
+ * `restore`, `checkpoint`, and `rewind` are refused; `finish()` it first.
460
+ */
461
+ export interface SteppedFrame<System> {
462
+ /**
463
+ * Runs the steps (systems and markers) before `system` and stops before
464
+ * it. Takes the system value placed in the schedule, so names that repeat
465
+ * across schedules stay unambiguous and a system the schedule does not
466
+ * run does not compile.
467
+ */
468
+ readonly until: (system: System) => Rendered.Rendered<Result.Result<StepReached, StepStop>>
469
+ /** Runs exactly one step. */
470
+ readonly next: () => Rendered.Rendered<Result.Result<StepRan, StepStop>>
471
+ /** The steps not run yet, in order; empty once the frame has ended. */
472
+ readonly remaining: () => Rendered.Rendered<ReadonlyArray<Debug.StepDescription>>
473
+ /**
474
+ * Evaluates the session's invariants now, between two steps. An invariant
475
+ * may legitimately fail mid-frame (a marker later in the frame applies the
476
+ * commands that restore it), so this is only an explicit question:
477
+ * `finish()` checks the invariants at the end of the frame, as `run` does.
478
+ * Like labels, it reads the world through inspectors, which advances the
479
+ * world's change tick: tick numbers in this frame then differ from an
480
+ * unstepped run's.
481
+ */
482
+ readonly check: () => Rendered.Rendered<Result.Result<void, CheckStop>>
483
+ /**
484
+ * Runs the rest of the frame and reports it as `run(name, { frames: 1 })`
485
+ * would: the same `RunResult`, with labels and invariants evaluated at the
486
+ * end of the frame. A system failure or defect during an earlier step is
487
+ * its stop. Calling it again returns the same result.
488
+ */
489
+ readonly finish: () => Rendered.Rendered<RunResult>
490
+ }
491
+
289
492
  /** A debug session made by `Session.make`; see the module description for each query. */
290
- export interface Session<S extends Schema.Any, Names extends string> {
493
+ export interface Session<
494
+ S extends Schema.Any,
495
+ Names extends string,
496
+ Schedules extends Readonly<Record<Names, unknown>> = Readonly<Record<Names, ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>>>
497
+ > {
291
498
  /** Ticks the named schedule frame by frame; stops at the first failure, defect, or violated invariant. */
292
499
  readonly run: (name: Names, options?: RunOptions) => Rendered.Rendered<RunResult>
500
+ /**
501
+ * Begins one frame of the named schedule, to run it a step at a time (see
502
+ * {@link SteppedFrame}). Use it when a value goes wrong between two systems
503
+ * of one frame; use `run` for whole frames.
504
+ */
505
+ readonly step: <Name extends Names>(name: Name) => SteppedFrame<StepSystem<Schedules[Name]>>
293
506
  /** What happened in the kept history, one fact per line. */
294
507
  readonly journal: (filter?: JournalFilter<S>) => Rendered.Rendered<ReadonlyArray<Format.Line>>
295
- /** Latest changes to one entity's component, and the systems whose `spawns` could have spawned it. Use `whyResource` for resources. */
296
- readonly why: (entity: number, component: Schema.ComponentDescriptor<S>, options?: { readonly limit?: number }) => Rendered.Rendered<ReadonlyArray<Format.Line>>
297
- /** Latest changes to one resource and the systems that made them. */
298
- readonly whyResource: (resource: Schema.ResourceDescriptor<S>, options?: { readonly limit?: number }) => Rendered.Rendered<ReadonlyArray<Format.Line>>
508
+ /**
509
+ * Latest changes to one entity's component, and the systems whose `spawns`
510
+ * could have spawned it; with `depth` above 1, what each writing system
511
+ * declared it reads, under each change ({@link WhyOptions}). Use
512
+ * `whyResource` for resources.
513
+ */
514
+ readonly why: (entity: number, component: Schema.ComponentDescriptor<S>, options?: WhyOptions) => Rendered.Rendered<ReadonlyArray<Format.Line>>
515
+ /** Latest changes to one resource and the systems that made them; `depth` as for `why`. */
516
+ readonly whyResource: (resource: Schema.ResourceDescriptor<S>, options?: WhyOptions) => Rendered.Rendered<ReadonlyArray<Format.Line>>
299
517
  /** One system's declared access and recent activity. */
300
518
  readonly system: (name: string, options?: { readonly limit?: number }) => Rendered.Rendered<SystemActivity>
301
519
  /** `debug.describe()`, lints first. */
@@ -315,8 +533,13 @@ export interface Session<S extends Schema.Any, Names extends string> {
315
533
  interface FrameRecord {
316
534
  readonly frame: number
317
535
  readonly events: Array<Debug.TraceEvent>
536
+ /** The labels at the end of this frame, when they were evaluated then. */
537
+ labels?: ReadonlyMap<number, string>
318
538
  }
319
539
 
540
+ /** `e12` tokens in free text (not `&e12` handles), as an invariant writes them. */
541
+ const entityToken = /(?<![\w&])e(\d+)\b/g
542
+
320
543
  const inRange = (frame: number, frames: number | readonly [number, number] | undefined): boolean =>
321
544
  frames === undefined ? true
322
545
  : typeof frames === "number" ? frame === frames
@@ -342,6 +565,16 @@ const growsSteadily = (samples: ReadonlyArray<number>): boolean => {
342
565
  return true
343
566
  }
344
567
 
568
+ /** The stop for a failed tick or step result, as `run` reports it. */
569
+ const failureStop = (failure: unknown, frame: number): Extract<Stop, { readonly reason: "failure" | "missingRequirements" | "tickOrder" }> => {
570
+ const error = describeError(failure)
571
+ return error.kind === "MissingRuntimeRequirements"
572
+ ? { reason: "missingRequirements", frame, requirements: error.requirements }
573
+ : error.kind === "TickOrderViolation"
574
+ ? { reason: "tickOrder", frame, issues: (error.issues ?? []).map((issue) => issue.message) }
575
+ : { reason: "failure", frame, system: typeof error.system === "string" ? error.system : "(unknown)", error: error.error }
576
+ }
577
+
345
578
  const describeError = (error: unknown): { readonly kind?: unknown; readonly system?: unknown; readonly error?: unknown; readonly requirements?: unknown; readonly issues?: ReadonlyArray<{ readonly message: string }> } =>
346
579
  typeof error === "object" && error !== null ? error : {}
347
580
 
@@ -358,12 +591,18 @@ export const make = <
358
591
  Resources extends object,
359
592
  Machines extends Record<string, unknown>,
360
593
  const Names extends string,
361
- const Invariants extends ReadonlyArray<Invariant<Inspector.InspectorDefinition<any, string | undefined, Root, any, any>>> = readonly []
594
+ const Schedules extends Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>,
595
+ const Invariants extends ReadonlyArray<Invariant<Inspector.InspectorDefinition<any, string | undefined, Root, any, any>>> = readonly [],
596
+ const Labels extends LabelsInspector<Root> = never
362
597
  >(
363
598
  runtime: Target<S, Root, Services, Resources, Machines>,
364
- options: Options<S, Root, Names, Invariants> & ValidateInvariants<Invariants, Services, Resources, Machines>
365
- ): Session<S, Names> => {
366
- const inspect = runtime.inspect as (inspector: Inspector.Inspector.Any) => string | undefined
599
+ options:
600
+ & Options<S, Root, Names, Invariants, Labels>
601
+ & { readonly schedules: Schedules }
602
+ & ValidateInvariants<Invariants, Services, Resources, Machines>
603
+ & ValidateLabels<Labels, Services, Resources, Machines>
604
+ ): Session<S, Names, Schedules> => {
605
+ const inspect = runtime.inspect as (inspector: Inspector.Inspector.Any) => unknown
367
606
  const debug = runtime.debug
368
607
  const capacity = options.history ?? 600
369
608
  const format = options.format ?? {}
@@ -385,8 +624,45 @@ export const make = <
385
624
  }
386
625
  return entry
387
626
  }
388
- const warnings = new Map<string, { code: Warning["code"]; message: string; count: number; firstFrame: number; lastFrame: number }>()
389
- const warn = (code: Warning["code"], key: string, message: string, frame: number) => {
627
+ const labelsInspector = options.labels as LabelsInspector | undefined
628
+ /** Each labelled entity's latest label; a despawned entity keeps its last one. */
629
+ const lastLabels = new Map<number, string>()
630
+ /** The labels of the last evaluation. */
631
+ let latestLabels: ReadonlyMap<number, string> = new Map()
632
+ /** Evaluates the labels for the frame that just ended and stamps it on its record. */
633
+ const evaluateLabels = (): void => {
634
+ if (labelsInspector === undefined) return
635
+ const labels = inspect(labelsInspector) as ReadonlyMap<number, string>
636
+ const dropped = [...latestLabels.keys()].filter((id) => !labels.has(id))
637
+ // An entity that lost its label while alive has none now; a despawned one keeps it.
638
+ if (dropped.length > 0) for (const alive of debug.dump({ entities: dropped }).entities) lastLabels.delete(alive.id)
639
+ for (const [id, label] of labels) lastLabels.set(id, label)
640
+ latestLabels = labels
641
+ current.labels = labels
642
+ }
643
+ /** Evaluates labels when frames ran outside `run` (queries print the latest world). */
644
+ const refreshLabels = (): void => {
645
+ if (labelsInspector === undefined || current.labels !== undefined) return
646
+ try {
647
+ evaluateLabels()
648
+ } catch {
649
+ // A throwing labels inspector stops `run` as `labels-threw`; queries print ids alone.
650
+ }
651
+ }
652
+ /** The labels for a line of `frame`: that frame's (or the next evaluated one's), then each entity's last. */
653
+ const labelsAt = (frame: number): Format.Labels | undefined => {
654
+ if (labelsInspector === undefined) return undefined
655
+ const own = history.find((entry) => entry.frame >= frame && entry.labels !== undefined)?.labels
656
+ return { get: (id) => own?.get(id) ?? lastLabels.get(id) }
657
+ }
658
+ const nowLabels = (): Format.Labels | undefined => {
659
+ refreshLabels()
660
+ return labelsAt(debug.frame())
661
+ }
662
+
663
+ type WarningMessage = string | ((labels: Format.Labels | undefined) => string)
664
+ const warnings = new Map<string, { code: Warning["code"]; message: WarningMessage; count: number; firstFrame: number; lastFrame: number }>()
665
+ const warn = (code: Warning["code"], key: string, message: WarningMessage, frame: number) => {
390
666
  const existing = warnings.get(key)
391
667
  if (existing) {
392
668
  existing.count += 1
@@ -428,11 +704,34 @@ export const make = <
428
704
  warn(
429
705
  "non-finite-value",
430
706
  `nonfinite:${system}:${subject}`,
431
- `${system} wrote a NaN or infinite number to ${entity === undefined ? "" : `e${entity} `}${subject}${path} (first at f${frame}; why() shows its history)`,
707
+ (labels) => `${system} wrote a NaN or infinite number to ${entity === undefined ? "" : `${Format.entity(entity, labels)} `}${subject}${path} (first at f${frame}; why() shows its history)`,
432
708
  frame
433
709
  )
434
710
  }
435
711
 
712
+ /** The declared ranges of every component and resource field, by descriptor name, read from `describe()` on the first write. */
713
+ let ranges: ReturnType<typeof rangesOf> | undefined
714
+ const checkRange = (kind: "component" | "resource", system: string, subject: string, value: unknown, frame: number, entity?: number) => {
715
+ ranges ??= rangesOf(debug.describe())
716
+ const fields = ranges[kind].get(subject)
717
+ if (fields === undefined || typeof value !== "object" || value === null) return
718
+ for (const [field, min, max] of fields) {
719
+ const written = (value as Readonly<Record<string, unknown>>)[field]
720
+ // NaN and infinities are `non-finite-value` warnings.
721
+ if (typeof written !== "number" || !Number.isFinite(written) || (written >= min && written <= max)) continue
722
+ warn(
723
+ "out-of-range",
724
+ `range:${system}:${subject}.${field}`,
725
+ (labels) => `${entity === undefined ? "" : `${Format.entity(entity, labels)} `}${subject}.${field} written as ${Format.value(written)}, declared range [${Format.value(min)}, ${Format.value(max)}] by ${system} at frame ${frame}`,
726
+ frame
727
+ )
728
+ }
729
+ }
730
+ const checkComponent = (system: string, subject: string, value: unknown, frame: number, entity: number) => {
731
+ checkFinite(system, subject, value, frame, entity)
732
+ checkRange("component", system, subject, value, frame, entity)
733
+ }
734
+
436
735
  const record = (event: Debug.TraceEvent) => {
437
736
  if (event.type === "frame") {
438
737
  checkPending(current.frame)
@@ -452,8 +751,11 @@ export const make = <
452
751
  warn("system-failed", `failed:${event.system}`, `${event.system} ${event.outcome === "defect" ? "threw" : "failed"}: ${Format.value(event.error, format)}`, event.frame)
453
752
  } else {
454
753
  if (event.commands.length > 0) pending.set(event.system, (pending.get(event.system) ?? 0) + event.commands.length)
455
- for (const write of event.writes) checkFinite(event.system, write.component, write.after, event.frame, write.entity)
456
- for (const write of event.resources) checkFinite(event.system, write.resource, write.after, event.frame)
754
+ for (const write of event.writes) checkComponent(event.system, write.component, write.after, event.frame, write.entity)
755
+ for (const write of event.resources) {
756
+ checkFinite(event.system, write.resource, write.after, event.frame)
757
+ checkRange("resource", event.system, write.resource, write.after, event.frame)
758
+ }
457
759
  for (const emit of event.events) checkFinite(event.system, emit.event, emit.values, event.frame)
458
760
  for (const next of event.nextStates) {
459
761
  if (next.value === undefined) pendingStates.delete(next.machine)
@@ -493,13 +795,13 @@ export const make = <
493
795
  for (const effect of command.effects) {
494
796
  switch (effect.kind) {
495
797
  case "spawn":
496
- for (const [component, value] of Object.entries(effect.components)) checkFinite(command.system, component, value, event.frame, effect.entity)
798
+ for (const [component, value] of Object.entries(effect.components)) checkComponent(command.system, component, value, event.frame, effect.entity)
497
799
  break
498
800
  case "insert":
499
- checkFinite(command.system, effect.component, effect.value, event.frame, effect.entity)
801
+ checkComponent(command.system, effect.component, effect.value, event.frame, effect.entity)
500
802
  break
501
803
  case "overwrite":
502
- checkFinite(command.system, effect.component, effect.after, event.frame, effect.entity)
804
+ checkComponent(command.system, effect.component, effect.after, event.frame, effect.entity)
503
805
  break
504
806
  }
505
807
  }
@@ -531,12 +833,50 @@ export const make = <
531
833
  return first === undefined ? undefined : [first.frame, history[history.length - 1]!.frame]
532
834
  }
533
835
 
836
+ /** The first invariant violated (or throwing) now, in order. */
837
+ const checkInvariants = (frame: number): CheckStop | undefined => {
838
+ for (const invariant of options.invariants ?? []) {
839
+ let message: string | undefined
840
+ try {
841
+ message = inspect(invariant.inspector) as string | undefined
842
+ } catch (error) {
843
+ return { reason: "invariant-threw", frame, invariant: invariant.name, error }
844
+ }
845
+ if (message !== undefined) return { reason: "invariant", frame, invariant: invariant.name, message }
846
+ }
847
+ return undefined
848
+ }
849
+
850
+ /** What a run compares against: taken before its first frame begins. */
851
+ const startRun = () => {
852
+ takeIgnored()
853
+ return {
854
+ started: options.hostClock.now(),
855
+ warningsBefore: new Map([...warnings].map(([key, warning]) => [key, warning.count])),
856
+ initial: debug.population()
857
+ }
858
+ }
859
+
860
+ /** The frame `session.step` has open, if any. */
861
+ let stepping: { readonly name: string; readonly frame: number } | undefined
862
+ const refuseWhileStepping = (call: string): void => {
863
+ if (stepping !== undefined) throw new Error(`${call} was called while frame f${stepping.frame} of ${stepping.name} is being stepped: call finish() on it first`)
864
+ }
865
+
534
866
  const run = (name: Names, runOptions: RunOptions = {}): Rendered.Rendered<RunResult> => {
867
+ refuseWhileStepping(`session.run(${name})`)
535
868
  const schedule = schedules[name]!
869
+ return runFrames(name, runOptions, startRun(), () => runtime.tryTick(schedule))
870
+ }
871
+
872
+ /** Ticks `frames` frames with `tickFrame` and reports them; `run` and `finish()` share it. */
873
+ const runFrames = (
874
+ name: string,
875
+ runOptions: RunOptions,
876
+ { started, warningsBefore, initial }: ReturnType<typeof startRun>,
877
+ tickFrame: () => Result.Result<void, unknown>
878
+ ): Rendered.Rendered<RunResult> => {
536
879
  const frames = runOptions.frames ?? 1
537
- const started = options.hostClock.now()
538
- const warningsBefore = new Map([...warnings].map(([key, warning]) => [key, warning.count]))
539
- const initial = debug.population()
540
880
  const entityCounts: Array<number> = []
541
881
  const componentCounts = new Map<string, Array<number>>(Object.keys(initial.components).map((name) => [name, []]))
542
882
  const sample = () => {
@@ -547,11 +887,10 @@ export const make = <
547
887
  let first: number | undefined
548
888
  let last: number | undefined
549
889
  let stop: Stop = { reason: "completed" }
550
- takeIgnored()
551
890
  for (let index = 0; index < frames; index++) {
552
891
  let result: Result.Result<void, unknown>
553
892
  try {
554
- result = runtime.tryTick(schedule)
893
+ result = tickFrame()
555
894
  } catch (defect) {
556
895
  const frame = debug.frame()
557
896
  first ??= frame
@@ -570,28 +909,16 @@ export const make = <
570
909
  break
571
910
  }
572
911
  if (!result.ok) {
573
- const error = describeError(result.error)
574
- stop = error.kind === "MissingRuntimeRequirements"
575
- ? { reason: "missingRequirements", frame, requirements: error.requirements }
576
- : error.kind === "TickOrderViolation"
577
- ? { reason: "tickOrder", frame, issues: (error.issues ?? []).map((issue) => issue.message) }
578
- : { reason: "failure", frame, system: typeof error.system === "string" ? error.system : "(unknown)", error: error.error }
912
+ stop = failureStop(result.error, frame)
579
913
  break
580
914
  }
581
- let checked: Stop | undefined
582
- for (const invariant of options.invariants ?? []) {
583
- let message: string | undefined
584
- try {
585
- message = inspect(invariant.inspector)
586
- } catch (error) {
587
- checked = { reason: "invariant-threw", frame, invariant: invariant.name, error }
588
- break
589
- }
590
- if (message !== undefined) {
591
- checked = { reason: "invariant", frame, invariant: invariant.name, message }
592
- break
593
- }
915
+ try {
916
+ evaluateLabels()
917
+ } catch (error) {
918
+ stop = { reason: "labels-threw", frame, error }
919
+ break
594
920
  }
921
+ const checked = checkInvariants(frame)
595
922
  if (checked) {
596
923
  stop = checked
597
924
  break
@@ -645,21 +972,163 @@ export const make = <
645
972
  const warningText = raisedCodes.length === 0
646
973
  ? ""
647
974
  : `\nwarnings during the run (see report()): ${raisedCodes.map(([code, count]) => `${code} x${count}`).join(", ")}`
648
- return Rendered.make(data, renderRun(data, format) + lintText + warningText)
975
+ return Rendered.make(data, renderRun(data, format, labelsAt(debug.frame())) + lintText + warningText)
976
+ }
977
+
978
+ const step = (name: Names): SteppedFrame<AnySystem> => {
979
+ refuseWhileStepping(`session.step(${name})`)
980
+ const schedule = schedules[name]!
981
+ const start = startRun()
982
+ const begun = debug.beginFrame(schedule)
983
+ const frame = debug.frame()
984
+ const cursor = begun.ok ? begun.value : undefined
985
+ /** Why the frame never began (missing requirements, `thisTick` order). */
986
+ const notBegun = begun.ok ? undefined : failureStop(begun.error, frame) as StepStop
987
+ /** How the frame ended before `finish()`: a failed system's result, or a thrown defect. */
988
+ let ended: { readonly result: Result.Result<void, unknown> } | { readonly defect: unknown } | undefined
989
+ let finished: Rendered.Rendered<RunResult> | undefined
990
+ if (cursor !== undefined && cursor.remaining().length > 0) stepping = { name, frame }
991
+
992
+ const head = notBegun === undefined ? `step ${name} f${frame}` : `step ${name}`
993
+ const stopText = (stop: StepStop): string => {
994
+ switch (stop.reason) {
995
+ case "frameEnded":
996
+ return `${head}: the frame has ended; finish() reports it`
997
+ case "notAhead":
998
+ return `${head}: ${stop.system} is not ahead (it already ran this frame, or ${name} does not run it as a step); nothing ran. Remaining: ${stop.remaining.length === 0 ? "(none)" : stop.remaining.map(Format.step).join(", ")}`
999
+ case "failure":
1000
+ return `${head}: ${stop.system} FAILED: ${Format.value(stop.error, format)}; the frame ended, finish() reports it`
1001
+ case "defect":
1002
+ return `${head}: DEFECT: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
1003
+ case "missingRequirements":
1004
+ return `${head}: NOT BEGUN: missing runtime requirements ${Format.value(stop.requirements, format)}`
1005
+ case "tickOrder":
1006
+ return `${head}: NOT BEGUN: ${stop.issues.join("; ")}`
1007
+ }
1008
+ }
1009
+ const remainingSteps = (): ReadonlyArray<Debug.StepDescription> =>
1010
+ cursor === undefined || ended !== undefined ? [] : cursor.remaining()
1011
+ const nextText = (): string => {
1012
+ const left = remainingSteps()
1013
+ return left.length === 0 ? "the frame ended, finish() reports it" : `next: ${Format.step(left[0]!)}`
1014
+ }
1015
+ const unavailable = (): StepStop | undefined =>
1016
+ notBegun ?? (remainingSteps().length === 0 ? { reason: "frameEnded", frame } : undefined)
1017
+
1018
+ /** Runs one step; a failure or defect ends the frame. */
1019
+ const advance = (): Result.Result<Debug.StepOutcome, StepStop> => {
1020
+ const stop = unavailable()
1021
+ if (stop !== undefined) return Result.failure(stop)
1022
+ let result: Result.Result<Debug.StepOutcome, unknown>
1023
+ try {
1024
+ result = cursor!.next()
1025
+ } catch (defect) {
1026
+ ended = { defect }
1027
+ stepping = undefined
1028
+ return Result.failure({ reason: "defect", frame, error: defect })
1029
+ } finally {
1030
+ // Labels evaluated mid-frame are evaluated again for the world after this step.
1031
+ if (current.frame === frame) delete current.labels
1032
+ }
1033
+ if (!result.ok) {
1034
+ ended = { result: Result.failure(result.error) }
1035
+ stepping = undefined
1036
+ return Result.failure(failureStop(result.error, frame) as StepStop)
1037
+ }
1038
+ if (result.value.ended) stepping = undefined
1039
+ return Result.success(result.value)
1040
+ }
1041
+
1042
+ const stepped: SteppedFrame<AnySystem> = {
1043
+ until: (system) => {
1044
+ const unavailableStop = unavailable()
1045
+ const left = remainingSteps()
1046
+ const offset = schedule.steps
1047
+ .slice(schedule.steps.length - left.length)
1048
+ .findIndex((entry) => "ordering" in entry && entry.ordering.key === system.ordering.key)
1049
+ const stop: StepStop | undefined = unavailableStop
1050
+ ?? (offset === -1 ? { reason: "notAhead", frame, system: system.name, remaining: left } : undefined)
1051
+ if (stop !== undefined) return Rendered.make(Result.failure(stop), stopText(stop))
1052
+ const ran: Array<Debug.StepDescription> = []
1053
+ for (let index = 0; index < offset; index++) {
1054
+ const result = advance()
1055
+ if (!result.ok) return Rendered.make(Result.failure(result.error), stopText(result.error))
1056
+ ran.push(result.value.step)
1057
+ }
1058
+ const reached: StepReached = { frame, system: system.name, ran }
1059
+ return Rendered.make(
1060
+ Result.success(reached),
1061
+ `${head}: stopped before ${system.name}; ${ran.length === 0 ? "nothing ran" : `ran ${ran.map(Format.step).join(", ")}`}`
1062
+ )
1063
+ },
1064
+ next: () => {
1065
+ const result = advance()
1066
+ if (!result.ok) return Rendered.make(Result.failure(result.error), stopText(result.error))
1067
+ const ran: StepRan = { frame, step: result.value.step, ended: result.value.ended }
1068
+ return Rendered.make(Result.success(ran), `${head}: ran ${Format.step(ran.step)}; ${nextText()}`)
1069
+ },
1070
+ remaining: () => {
1071
+ const left = remainingSteps()
1072
+ return Rendered.make(left, left.length === 0
1073
+ ? `${head}: no steps left; ${finished === undefined ? "finish() reports the frame" : "finished"}`
1074
+ : `${head}: ${left.length} steps left: ${left.map(Format.step).join(", ")}`)
1075
+ },
1076
+ check: () => {
1077
+ const at = remainingSteps()
1078
+ const where = at.length === 0 ? "at the end of the frame" : `before ${Format.step(at[0]!)}`
1079
+ const stop = checkInvariants(frame)
1080
+ if (stop === undefined) return Rendered.make(Result.success(undefined), `${head}: invariants hold ${where}`)
1081
+ const text = stop.reason === "invariant"
1082
+ ? `${head}: INVARIANT "${stop.invariant}" violated ${where}: ${stop.message.replace(entityToken, (_token, id: string) => Format.entity(Number(id), nowLabels()))} (it may hold again by the end of the frame)`
1083
+ : `${head}: INVARIANT "${stop.invariant}" threw ${where}: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
1084
+ return Rendered.make(Result.failure(stop), text)
1085
+ },
1086
+ finish: () => {
1087
+ finished ??= runFrames(name, {}, start, () => {
1088
+ if (!begun.ok) return begun
1089
+ if (ended !== undefined) {
1090
+ if ("defect" in ended) throw ended.defect
1091
+ return ended.result
1092
+ }
1093
+ try {
1094
+ while (cursor!.remaining().length > 0) {
1095
+ const result = cursor!.next()
1096
+ if (!result.ok) return result
1097
+ }
1098
+ return Result.success(undefined)
1099
+ } finally {
1100
+ stepping = undefined
1101
+ }
1102
+ })
1103
+ return finished
1104
+ }
1105
+ }
1106
+ return stepped
649
1107
  }
650
1108
 
651
1109
  /** Lines hidden by the last `collectLines` call because they record no change. */
652
1110
  let hidden = 0
653
1111
 
654
- const collectLines = (filter: JournalFilter<S>): Array<Format.Line> => {
1112
+ const collectLines = (filter: JournalFilter<S>): Array<Format.Line> => collectSourced(filter).map((entry) => entry.line)
1113
+
1114
+ /** The journal lines of `filter`, each with its event's position in {@link flatTrace}. */
1115
+ const collectSourced = (filter: JournalFilter<S>): Array<{ readonly line: Format.Line; readonly at: number }> => {
655
1116
  hidden = 0
1117
+ refreshLabels()
656
1118
  const subject = filter.component?.name ?? filter.resource?.name ?? filter.event?.name ?? filter.machine?.name
657
- const records = filter.last === undefined ? history : history.slice(-filter.last)
658
- const result: Array<Format.Line> = []
659
- for (const entry of records) {
660
- if (!inRange(entry.frame, filter.frames)) continue
1119
+ // `slice(-last)` keeps the journal's meaning of `last` (0 keeps everything).
1120
+ const first = filter.last === undefined ? 0 : history.length - history.slice(-filter.last).length
1121
+ const result: Array<{ readonly line: Format.Line; readonly at: number }> = []
1122
+ let at = 0
1123
+ for (const [index, entry] of history.entries()) {
1124
+ if (index < first || !inRange(entry.frame, filter.frames)) {
1125
+ at += entry.events.length
1126
+ continue
1127
+ }
1128
+ const labels = labelsAt(entry.frame)
661
1129
  for (const event of entry.events) {
662
- for (const line of Format.lines(event, format)) {
1130
+ const position = at++
1131
+ for (const line of Format.lines(event, format, labels)) {
663
1132
  if (filter.entity !== undefined && line.entity !== filter.entity) continue
664
1133
  if (subject !== undefined && line.subject !== subject && !(line.kind === "effect" && line.subject === undefined && filter.entity !== undefined)) continue
665
1134
  if (filter.system !== undefined && line.system !== filter.system) continue
@@ -669,7 +1138,7 @@ export const make = <
669
1138
  hidden += 1
670
1139
  continue
671
1140
  }
672
- result.push(line)
1141
+ result.push({ line, at: position })
673
1142
  }
674
1143
  }
675
1144
  }
@@ -690,21 +1159,23 @@ export const make = <
690
1159
  return Rendered.make(lines, renderLines(`journal: ${lines.length} lines (${rangeText()}${hiddenText})`, lines))
691
1160
  }
692
1161
 
693
- const why = (entity: number, component: Schema.ComponentDescriptor<S>, whyOptions: { readonly limit?: number } = {}) => {
694
- const lines = collectLines({ entity, component, kinds: ["write", "effect"], limit: whyOptions.limit ?? 5 })
1162
+ const why = (entity: number, component: Schema.ComponentDescriptor<S>, whyOptions: WhyOptions = {}) => {
1163
+ const sourced = collectSourced({ entity, component, kinds: ["write", "effect"], limit: whyOptions.limit ?? 5 })
1164
+ const lines = followReads(sourced, whyOptions)
695
1165
  const currentValue = debug.dump({ entities: [entity] }).entities[0]
1166
+ const name = Format.entity(entity, nowLabels())
696
1167
  const now = currentValue === undefined
697
- ? `e${entity} is not alive`
1168
+ ? `${name} is not alive`
698
1169
  : component.name in currentValue.components
699
- ? `e${entity} ${component.name} is now ${Format.value(currentValue.components[component.name], format)}`
700
- : `e${entity} has no ${component.name} now`
701
- const changes = lines.length === 0
1170
+ ? `${name} ${component.name} is now ${Format.value(currentValue.components[component.name], format)}`
1171
+ : `${name} has no ${component.name} now`
1172
+ const changes = sourced.length === 0
702
1173
  ? `${now}; no change to it in ${rangeText()}`
703
- : `${now}; last ${lines.length} changes (oldest first):`
1174
+ : `${now}; last ${sourced.length} changes (oldest first):`
704
1175
  const spawners = spawnersOf(currentValue === undefined ? [component.name] : Object.keys(currentValue.components), component.name)
705
1176
  const header = `${changes}\n${spawners.length === 0
706
1177
  ? `no described system declares spawns of ${component.name}`
707
- : `could have spawned it: ${spawners.join(", ")}`}`
1178
+ : `could have spawned it: ${spawners.join(", ")}`}${readsNote(lines)}`
708
1179
  return Rendered.make(lines, renderLines(header, lines))
709
1180
  }
710
1181
 
@@ -722,18 +1193,275 @@ export const make = <
722
1193
  .map((system) => system.name)
723
1194
  }
724
1195
 
725
- const whyResource = (resource: Schema.ResourceDescriptor<S>, whyOptions: { readonly limit?: number } = {}) => {
726
- const lines = collectLines({ resource, kinds: ["resource"], limit: whyOptions.limit ?? 5 })
1196
+ const whyResource = (resource: Schema.ResourceDescriptor<S>, whyOptions: WhyOptions = {}) => {
1197
+ const lines = followReads(collectSourced({ resource, kinds: ["resource"], limit: whyOptions.limit ?? 5 }), whyOptions)
727
1198
  const resources = debug.dump({ limit: 0 }).resources
728
1199
  const now = resource.name in resources
729
1200
  ? `${resource.name} is now ${Format.value(resources[resource.name], format)}`
730
1201
  : `${resource.name} has no value now`
731
- const header = lines.length === 0
1202
+ const changes = lines.filter((line) => line.depth === 0).length
1203
+ const header = changes === 0
732
1204
  ? `${now}; no change to it in ${rangeText()}`
733
- : `${now}; last ${lines.length} changes (oldest first):`
1205
+ : `${now}; last ${changes} changes (oldest first):${readsNote(lines)}`
734
1206
  return Rendered.make(lines, renderLines(header, lines))
735
1207
  }
736
1208
 
1209
+ /** The header note `why` adds when it printed declared reads. */
1210
+ const readsNote = (lines: ReadonlyArray<Format.Line>): string =>
1211
+ lines.some((line) => line.depth > 0)
1212
+ ? "\nindented: what each writing system declared it reads, and the latest fact that could have produced it (declared: possible causes, not observed reads)"
1213
+ : ""
1214
+
1215
+ /** Every kept trace event, oldest first; {@link collectSourced} positions index into it. */
1216
+ const flatTrace = (): ReadonlyArray<Debug.TraceEvent> => history.flatMap((entry) => entry.events)
1217
+
1218
+ /**
1219
+ * The changes `why` lists, each followed (with `depth` above 1) by the
1220
+ * reads its system declared, depth first. Positions are in trace order, so
1221
+ * "before the run" is what the system could have seen.
1222
+ */
1223
+ const followReads = (sourced: ReadonlyArray<{ readonly line: Format.Line; readonly at: number }>, whyOptions: WhyOptions): Array<Format.Line> => {
1224
+ const depth = whyOptions.depth ?? 1
1225
+ const limit = whyOptions.limit ?? 5
1226
+ if (depth <= 1 || sourced.length === 0) return sourced.map((entry) => entry.line)
1227
+ const trace = flatTrace()
1228
+ const systems = new Map(debug.describe().systems.map((entry) => [entry.name, entry] as const))
1229
+ let world: ReadonlyArray<Debug.EntityDump> | undefined
1230
+ const worldNow = () => (world ??= debug.dump().entities)
1231
+
1232
+ /** The latest committed run of `system` before `before`. */
1233
+ const runBefore = (system: string, before: number): { readonly at: number; readonly run: Debug.SystemEvent } | undefined => {
1234
+ for (let at = before - 1; at >= 0; at--) {
1235
+ const event = trace[at]!
1236
+ if (event.type === "system" && event.system === system && event.outcome === "ok") return { at, run: event }
1237
+ }
1238
+ return undefined
1239
+ }
1240
+ /** Where the stream reads of the run at `at` start: after the system's previous run, or the discarding skip. */
1241
+ const readsSince = (system: string, at: number): number => {
1242
+ for (let index = at - 1; index >= 0; index--) {
1243
+ const event = trace[index]!
1244
+ if ((event.type === "system" && event.system === system) || (event.type === "system.skipped" && event.system === system && !event.held)) return index + 1
1245
+ }
1246
+ return 0
1247
+ }
1248
+ const latest = <A>(before: number, find: (event: Debug.TraceEvent, at: number) => A | undefined): A | undefined => {
1249
+ for (let at = before - 1; at >= 0; at--) {
1250
+ const found = find(trace[at]!, at)
1251
+ if (found !== undefined) return found
1252
+ }
1253
+ return undefined
1254
+ }
1255
+
1256
+ /** A run whose reads can be followed: the entity and component (or resource) it wrote, which its own reads skip. */
1257
+ interface Cause {
1258
+ readonly at: number
1259
+ readonly run: Debug.SystemEvent
1260
+ readonly entity: number | undefined
1261
+ readonly subject: string | undefined
1262
+ }
1263
+ interface Read {
1264
+ readonly frame: number
1265
+ readonly schedule: string
1266
+ readonly system: string | undefined
1267
+ readonly entity: number | undefined
1268
+ readonly subject: string
1269
+ readonly text: string
1270
+ readonly next: Cause | undefined
1271
+ }
1272
+
1273
+ const readsOf = (cause: Cause): Array<Read> => {
1274
+ const { run } = cause
1275
+ const description = systems.get(run.system)
1276
+ const here = { frame: run.frame, schedule: run.schedule, system: undefined, entity: undefined, next: undefined }
1277
+ if (description === undefined) {
1278
+ return [{ ...here, subject: run.system, text: `${run.system} is in no named or described schedule: its declared reads are unknown` }]
1279
+ }
1280
+ const reads: Array<Read> = []
1281
+ const since = readsSince(run.system, cause.at)
1282
+ for (const name of description.events.reads) {
1283
+ const before = reads.length
1284
+ for (let at = since; at < cause.at; at++) {
1285
+ const event = trace[at]!
1286
+ if (event.type === "runtime.sent" && event.event === name) {
1287
+ reads.push({ ...here, frame: event.frame, schedule: "", subject: name, text: `read ${name} ${Format.value([event.value], format)} (declared), sent by runtime.send at f${event.frame}` })
1288
+ }
1289
+ if (event.type === "system" && event.outcome === "ok") {
1290
+ for (const emitted of event.events) {
1291
+ if (emitted.event !== name) continue
1292
+ reads.push({
1293
+ frame: event.frame,
1294
+ schedule: event.schedule,
1295
+ system: event.system,
1296
+ entity: undefined,
1297
+ subject: name,
1298
+ text: `read ${name} ${Format.value(emitted.values, format)} (declared), emitted by ${event.system} at f${event.frame}`,
1299
+ next: { at, run: event, entity: undefined, subject: undefined }
1300
+ })
1301
+ }
1302
+ }
1303
+ }
1304
+ if (reads.length === before) {
1305
+ reads.push({ ...here, subject: name, text: `read ${name} (declared): nothing published to it since ${run.system}'s previous run` })
1306
+ }
1307
+ }
1308
+ for (const query of description.queries) {
1309
+ const components = [...query.reads, ...query.writes, ...query.optional]
1310
+ if (cause.entity !== undefined && cause.subject !== undefined && query.writes.includes(cause.subject)) {
1311
+ const entity = cause.entity
1312
+ for (const name of components.filter((component) => component !== cause.subject)) {
1313
+ reads.push(componentRead(cause, entity, name))
1314
+ }
1315
+ } else if (components.length > 0) {
1316
+ const required = [...query.reads, ...query.writes, ...query.with]
1317
+ const count = worldNow().filter((dumped) =>
1318
+ required.every((name) => name in dumped.components) && !query.without.some((name) => name in dumped.components)).length
1319
+ reads.push({
1320
+ ...here,
1321
+ subject: components[0]!,
1322
+ text: `read ${components.join(", ")} of ${count} matching ${count === 1 ? "entity" : "entities"} now (declared; the trace does not say which it read)`
1323
+ })
1324
+ }
1325
+ }
1326
+ for (const name of new Set([...description.resources.reads, ...description.resources.writes])) {
1327
+ if (name === cause.subject && cause.entity === undefined) continue
1328
+ const found = latest(cause.at, (event, at) => {
1329
+ if (event.type !== "system" || event.outcome !== "ok") return undefined
1330
+ // An equal-value write did not produce the value; the change before it did.
1331
+ const write = event.resources.find((entry) => entry.resource === name && !Format.sameValue(entry.before, entry.after))
1332
+ return write === undefined ? undefined : { at, event, write }
1333
+ })
1334
+ reads.push(found === undefined
1335
+ ? { ...here, subject: name, text: `read resource ${name} (declared): no change to it in ${rangeText()}` }
1336
+ : {
1337
+ frame: found.event.frame,
1338
+ schedule: found.event.schedule,
1339
+ system: found.event.system,
1340
+ entity: undefined,
1341
+ subject: name,
1342
+ text: `read resource ${name} ${Format.value(found.write.after, format)} (declared), written by ${found.event.system} at f${found.event.frame}`,
1343
+ next: { at: found.at, run: found.event, entity: undefined, subject: name }
1344
+ })
1345
+ }
1346
+ for (const name of new Set([...description.machines.reads, ...description.machines.updates])) {
1347
+ const found = latest(cause.at, (event, at): Read | undefined => {
1348
+ if (event.type === "transition" && event.machine === name && (event.outcome === "applied" || event.outcome === "enterFailed")) {
1349
+ return { ...here, frame: event.frame, schedule: event.schedule, subject: name, text: `read machine ${name} (declared): transition ${Format.transition(event)} ${event.outcome} at f${event.frame}` }
1350
+ }
1351
+ if (event.type !== "system" || event.outcome !== "ok" || event.system === run.system) return undefined
1352
+ const write = event.machines.find((entry) => entry.machine === name)
1353
+ return write === undefined ? undefined : {
1354
+ frame: event.frame,
1355
+ schedule: event.schedule,
1356
+ system: event.system,
1357
+ entity: undefined,
1358
+ subject: name,
1359
+ text: `read machine ${name} ${Format.change(write.before, write.after, format)} (declared), updated by ${event.system} at f${event.frame}`,
1360
+ next: { at, run: event, entity: undefined, subject: undefined }
1361
+ }
1362
+ })
1363
+ reads.push(found ?? { ...here, subject: name, text: `read machine ${name} (declared): no transition in ${rangeText()}` })
1364
+ }
1365
+ if (reads.length === 0) reads.push({ ...here, subject: run.system, text: `${run.system} declares no other reads (declared)` })
1366
+ return reads
1367
+ }
1368
+
1369
+ /** The latest value of `component` on `entity` before the cause's run, and what produced it. */
1370
+ const componentRead = (cause: Cause, entity: number, component: string): Read => {
1371
+ const name = Format.entity(entity, labelsAt(cause.run.frame))
1372
+ const found = latest(cause.at, (event, at): Read | undefined => {
1373
+ if (event.type === "system" && event.outcome === "ok") {
1374
+ const write = event.writes.find((entry) => entry.entity === entity && entry.component === component && !Format.sameValue(entry.before, entry.after))
1375
+ return write === undefined ? undefined : {
1376
+ frame: event.frame,
1377
+ schedule: event.schedule,
1378
+ system: event.system,
1379
+ entity,
1380
+ subject: component,
1381
+ text: `read ${name} ${component} ${Format.value(write.after, format)} (declared), written by ${event.system} at f${event.frame}`,
1382
+ next: { at, run: event, entity, subject: component }
1383
+ }
1384
+ }
1385
+ if (event.type !== "deferred") return undefined
1386
+ for (const command of [...event.commands].reverse()) {
1387
+ for (const effect of [...command.effects].reverse()) {
1388
+ if (effect.entity !== entity) continue
1389
+ const value = effect.kind === "spawn" ? (component in effect.components ? { found: effect.components[component] } : undefined)
1390
+ : effect.kind === "insert" && effect.component === component ? { found: effect.value }
1391
+ : effect.kind === "overwrite" && effect.component === component ? { found: effect.after }
1392
+ : undefined
1393
+ if (value === undefined) continue
1394
+ const queued = runBefore(command.system, at)
1395
+ return {
1396
+ frame: event.frame,
1397
+ schedule: event.schedule,
1398
+ system: command.system,
1399
+ entity,
1400
+ subject: component,
1401
+ text: `read ${name} ${component} ${Format.value(value.found, format)} (declared), ${effect.kind === "spawn" ? "spawned" : "inserted"} by ${command.system} at f${event.frame}`,
1402
+ next: queued === undefined ? undefined : { ...queued, entity: undefined, subject: undefined }
1403
+ }
1404
+ }
1405
+ }
1406
+ return undefined
1407
+ })
1408
+ return found ?? { frame: cause.run.frame, schedule: cause.run.schedule, system: undefined, entity, subject: component, text: `read ${name} ${component} (declared): no change to it in ${rangeText()}`, next: undefined }
1409
+ }
1410
+
1411
+ const toLine = (read: Read, level: number, suffix: string): Format.Line => {
1412
+ const label = read.entity === undefined ? undefined : labelsAt(read.frame)?.get(read.entity)
1413
+ return {
1414
+ kind: "read",
1415
+ frame: read.frame,
1416
+ schedule: read.schedule,
1417
+ system: read.system,
1418
+ entity: read.entity,
1419
+ label: label === "" ? undefined : label,
1420
+ subject: read.subject,
1421
+ text: `${read.text}${suffix}`,
1422
+ noop: false,
1423
+ depth: level
1424
+ }
1425
+ }
1426
+
1427
+ const out: Array<Format.Line> = []
1428
+ const follow = (cause: Cause, level: number, chain: ReadonlySet<string>) => {
1429
+ const reads = readsOf(cause)
1430
+ for (const read of reads.slice(0, limit)) {
1431
+ const cycle = read.next !== undefined && chain.has(read.next.run.system)
1432
+ out.push(toLine(read, level, cycle ? " (cycle: not followed)" : ""))
1433
+ if (read.next !== undefined && !cycle && level + 1 < depth) follow(read.next, level + 1, new Set([...chain, read.next.run.system]))
1434
+ }
1435
+ if (reads.length > limit) {
1436
+ out.push({
1437
+ kind: "read",
1438
+ frame: cause.run.frame,
1439
+ schedule: cause.run.schedule,
1440
+ system: undefined,
1441
+ entity: undefined,
1442
+ label: undefined,
1443
+ subject: undefined,
1444
+ text: `…+${reads.length - limit} more declared reads of ${cause.run.system} (raise limit to see them)`,
1445
+ noop: false,
1446
+ depth: level
1447
+ })
1448
+ }
1449
+ }
1450
+ /** The run behind a listed change: the writing run, or for an applied command the run that queued it. */
1451
+ const causeOf = (line: Format.Line, at: number): Cause | undefined => {
1452
+ const event = trace[at]
1453
+ if (event?.type === "system") return { at, run: event, entity: line.entity, subject: line.subject }
1454
+ const queued = event?.type === "deferred" && line.system !== undefined ? runBefore(line.system, at) : undefined
1455
+ return queued === undefined ? undefined : { ...queued, entity: undefined, subject: undefined }
1456
+ }
1457
+ for (const { line, at } of sourced) {
1458
+ out.push(line)
1459
+ const cause = causeOf(line, at)
1460
+ if (cause !== undefined) follow(cause, 1, new Set([cause.run.system]))
1461
+ }
1462
+ return out
1463
+ }
1464
+
737
1465
  const statsFor = (system: string): SystemStats | undefined => {
738
1466
  const entry = stats.get(system)
739
1467
  return entry === undefined ? undefined : { system, ...entry }
@@ -766,7 +1494,10 @@ export const make = <
766
1494
  frames: debug.frame(),
767
1495
  history: historyRange(),
768
1496
  systems,
769
- warnings: [...warnings.values()].map((warning) => ({ ...warning })),
1497
+ warnings: [...warnings.values()].map((warning) => ({
1498
+ ...warning,
1499
+ message: typeof warning.message === "string" ? warning.message : warning.message(labelsAt(warning.firstFrame))
1500
+ })),
770
1501
  streams: debug.streams().filter((stream) => stream.heldBy !== undefined || stream.readers.some((reader) => reader.lagged)),
771
1502
  lints: debug.describe().lints,
772
1503
  population: debug.population()
@@ -790,6 +1521,7 @@ export const make = <
790
1521
 
791
1522
  return {
792
1523
  run,
1524
+ step: step as Session<S, Names, Schedules>["step"],
793
1525
  journal,
794
1526
  why,
795
1527
  whyResource,
@@ -800,7 +1532,7 @@ export const make = <
800
1532
  },
801
1533
  dump: (filter) => {
802
1534
  const dumped = debug.dump(filter)
803
- return Rendered.make(dumped, Format.dump(dumped, format))
1535
+ return Rendered.make(dumped, Format.dump(dumped, format, nowLabels()))
804
1536
  },
805
1537
  streams: () => {
806
1538
  const status = debug.streams()
@@ -815,7 +1547,7 @@ export const make = <
815
1547
  }
816
1548
  }
817
1549
 
818
- const renderRun = (result: RunResult, format: Format.ValueOptions): string => {
1550
+ const renderRun = (result: RunResult, format: Format.ValueOptions, labels: Format.Labels | undefined): string => {
819
1551
  const frames = result.range === undefined ? "no frames" : `f${result.range[0]}-f${result.range[1]}`
820
1552
  const head = `run ${result.schedule}: ${result.frames} frames (${frames}) in ${Format.value(result.ms)}ms`
821
1553
  const stop = result.stop
@@ -831,9 +1563,11 @@ const renderRun = (result: RunResult, format: Format.ValueOptions): string => {
831
1563
  case "defect":
832
1564
  return `${head}, DEFECT at f${stop.frame}: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
833
1565
  case "invariant":
834
- return `${head}, INVARIANT "${stop.invariant}" violated at f${stop.frame}: ${stop.message}`
1566
+ return `${head}, INVARIANT "${stop.invariant}" violated at f${stop.frame}: ${stop.message.replace(entityToken, (_token, id: string) => Format.entity(Number(id), labels))}`
835
1567
  case "invariant-threw":
836
1568
  return `${head}, INVARIANT "${stop.invariant}" threw at f${stop.frame}: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
1569
+ case "labels-threw":
1570
+ return `${head}, LABELS threw at f${stop.frame}: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`
837
1571
  case "tickOrder":
838
1572
  return `${head}, NOT RUN after f${stop.frame}: ${stop.issues.join("; ")}`
839
1573
  case "ignored-failure":