babavoss 0.0.1 → 0.0.2

package/src/ecs/table.ts

@@ -0,0 +1,420 @@
+// The storage under the state and under a replica: entities as a bitmask of
+// the components each has, and one store per component holding its values
+// in entity order. A query walks the smallest store of its required terms
+// and tests masks; `not(…)` is a bit test. Every value and every entity's
+// component set carries the sequence number of its last change, which is
+// what change terms (`added`, `changed`, `removed`) and deltas read. Pure
+// data structure, browser-safe: components are known by name here.
+import type { Entity } from "./state.ts";
+
+export type Mask = Uint32Array;
+const BITS = 32;
+
+/** A term's shape as the table sees it: a component by name, a not, or a change term. */
+export type Named = { kind: "component"; name: string } | { kind: "not"; components: readonly { name: string }[] } | { kind: "changed"; how: "added" | "changed" | "removed"; component: { name: string } };
+
+/** A query declared once: its terms, the predicate over the row, the order by one component's value. Its matched set is kept live by the table it runs in. */
+export interface Select<R = Record<string, unknown>> { readonly kind: "select"; readonly terms: readonly Named[]; readonly pred: ((row: R) => boolean) | null; readonly order: { component: { name: string }; cmp: (a: unknown, b: unknown) => number } | null }
+
+/**
+ * A select kept live: its plan, its matched ids in id order, and a version
+ * that moves when the set changes, and, for a select with a predicate or an
+ * order, when a value of one of its components is written on a member. A
+ * watcher compares versions; the answer is made once per version.
+ */
+interface Live { plan: Plan; ids: number[]; version: number; sensitive: boolean; keyed: Store | null; cache: { version: number; ids: readonly number[] } | null }
+
+/** A query resolved against this table: masks, the stores to walk, and the names to put in a row. */
+interface Plan {
+  required: Mask; excluded: Mask;
+  comps: { name: string; store: Store }[];
+  changes: { how: "added" | "changed" | "removed"; name: string; store: Store }[];
+}
+
+/** One component's values, in entity order, with the sequence of each one's last write and of its arrival. */
+class Store {
+  ids: number[] = [];
+  vals: unknown[] = [];
+  ticks: number[] = [];
+  arrived: number[] = [];
+  /** Entities that lost it, each with the value they had and when. */
+  removed = new Map<number, { seq: number; value: unknown }>();
+  /** The key field's values to entities, when the component has one. */
+  keys: Map<unknown, number> | null = null;
+  constructor(readonly name: string, readonly id: number, readonly keyOf: ((value: unknown) => unknown) | null) { if (keyOf) this.keys = new Map(); }
+
+  /** The position of `e`, or the bitwise complement of where it would go. */
+  at(e: number): number {
+    let lo = 0, hi = this.ids.length - 1;
+    while (lo <= hi) { const mid = (lo + hi) >>> 1; const v = this.ids[mid]!; if (v === e) return mid; if (v < e) lo = mid + 1; else hi = mid - 1; }
+    return ~lo;
+  }
+}
+
+const grow = <T extends Uint32Array | Uint8Array | Float64Array>(a: T, n: number): T => { const b = new (a.constructor as new (n: number) => T)(n); b.set(a as never); return b; };
+
+export class Table {
+  private stores = new Map<string, Store>();
+  private byId: Store[] = [];
+  private words = 1;
+  private capacity = 64;
+  private masks: Mask = new Uint32Array(this.capacity * this.words);
+  private alive = new Uint8Array(this.capacity);
+  /** When each entity's component set last changed. */
+  private etick = new Float64Array(this.capacity);
+  /** When anything on each entity was last written: a part put, taken away, the entity spawned or gone. */
+  private wtick = new Float64Array(this.capacity);
+  /** Entities despawned, and when. */
+  readonly gone = new Map<number, number>();
+  /** The sequence of the last change; every write takes the next. */
+  seq = 0;
+  private count = 0;
+  private highest = 0;
+  private live = new Map<Select, Live>();
+
+  constructor(private keyOf: (name: string) => ((value: unknown) => unknown) | null = () => null) {}
+
+  /** The table knows the component, assigning its id. */
+  register(name: string): Store {
+    let s = this.stores.get(name);
+    if (s) return s;
+    const id = this.byId.length;
+    s = new Store(name, id, this.keyOf(name));
+    this.stores.set(name, s);
+    this.byId.push(s);
+    const words = Math.ceil(this.byId.length / BITS);
+    if (words > this.words) {
+      const masks = new Uint32Array(this.capacity * words);
+      for (let e = 0; e < this.capacity; e++) for (let k = 0; k < this.words; k++) masks[e * words + k] = this.masks[e * this.words + k]!;
+      this.masks = masks; this.words = words;
+      for (const l of this.live.values()) l.plan = this.plan(this.termsOf(l.plan));
+    }
+    return s;
+  }
+
+  has(name: string): boolean { return this.stores.has(name); }
+  names(): string[] { return this.byId.map((s) => s.name); }
+
+  private room(e: number): void {
+    if (e < this.capacity) return;
+    let cap = this.capacity;
+    while (cap <= e) cap *= 2;
+    this.masks = grow(this.masks, cap * this.words);
+    this.alive = grow(this.alive, cap);
+    this.etick = grow(this.etick, cap);
+    this.wtick = grow(this.wtick, cap);
+    this.capacity = cap;
+  }
+
+  // ---- entities ------------------------------------------------------------
+
+  exists(e: number): boolean { return e < this.capacity && this.alive[e] === 1; }
+  size(): number { return this.count; }
+  /** Every entity, in id order. */
+  all(): number[] { const out: number[] = []; for (let e = 1; e <= this.highest; e++) if (this.alive[e] === 1) out.push(e); return out; }
+
+  spawn(e: number): void {
+    this.room(e);
+    if (this.alive[e] === 1) throw new Error(`entity ${e} exists`);
+    this.alive[e] = 1;
+    this.count++;
+    if (e > this.highest) this.highest = e;
+    this.etick[e] = ++this.seq;
+    this.wtick[e] = this.seq;
+    this.gone.delete(e);
+  }
+
+  /** Removes the entity and every value on it; what it carried, for an undo. */
+  despawn(e: number): Record<string, unknown> {
+    const parts = this.partsOf(e);
+    for (const name of Object.keys(parts)) this.remove(e, name);
+    this.alive[e] = 0;
+    this.count--;
+    this.gone.set(e, ++this.seq);
+    this.etick[e] = this.seq;
+    this.wtick[e] = this.seq;
+    return parts;
+  }
+
+  /** When the entity's component set last changed. */
+  tickOf(e: number): number { return this.etick[e] ?? 0; }
+  /** When anything on the entity was last written. */
+  writeTick(e: number): number { return this.wtick[e] ?? 0; }
+  /** When the entity's value of `name` was last written, or -1 without one. */
+  valueTick(e: number, name: string): number { const s = this.stores.get(name); if (!s) return -1; const i = s.at(e); return i >= 0 ? s.ticks[i]! : -1; }
+
+  // ---- values --------------------------------------------------------------
+
+  get(e: number, name: string): unknown {
+    const s = this.stores.get(name);
+    if (!s) return undefined;
+    const i = s.at(e);
+    return i >= 0 ? s.vals[i] : undefined;
+  }
+
+  hasPart(e: number, name: string): boolean {
+    const s = this.stores.get(name);
+    return !!s && this.bit(e, s.id);
+  }
+
+  private bit(e: number, id: number): boolean { return ((this.masks[e * this.words + (id >>> 5)]! >>> (id & 31)) & 1) === 1; }
+
+  /** Attaches or replaces; the value before, if any, and whether it was there. */
+  put(e: number, name: string, value: unknown): { had: boolean; was: unknown; tick: number; arrived: number } {
+    const s = this.register(name);
+    const i = s.at(e);
+    const seq = ++this.seq;
+    if (i >= 0) {
+      const was = s.vals[i], tick = s.ticks[i]!, arrived = s.arrived[i]!;
+      if (s.keys) { s.keys.delete(s.keyOf!(was)); s.keys.set(s.keyOf!(value), e); }
+      s.vals[i] = value; s.ticks[i] = seq;
+      this.wtick[e] = seq;
+      if (this.live.size) this.touched(e, s);
+      return { had: true, was, tick, arrived };
+    }
+    const at = ~i;
+    s.ids.splice(at, 0, e); s.vals.splice(at, 0, value); s.ticks.splice(at, 0, seq); s.arrived.splice(at, 0, seq);
+    s.removed.delete(e);
+    if (s.keys) s.keys.set(s.keyOf!(value), e);
+    this.setBit(e, s.id, true, seq);
+    return { had: false, was: undefined, tick: 0, arrived: 0 };
+  }
+
+  /** Puts back a value with the ticks it had: an undo. */
+  restore(e: number, name: string, value: unknown, tick: number, arrived: number): void {
+    const s = this.register(name);
+    const i = s.at(e);
+    if (i >= 0) { s.vals[i] = value; s.ticks[i] = tick; if (s.keys) s.keys.set(s.keyOf!(value), e); return; }
+    this.put(e, name, value);
+    const j = s.at(e);
+    s.ticks[j] = tick; s.arrived[j] = arrived;
+  }
+
+  /** Detaches; the value it had, or undefined when it was not there. */
+  remove(e: number, name: string): { had: boolean; was: unknown; tick: number; arrived: number } {
+    const s = this.stores.get(name);
+    if (!s) return { had: false, was: undefined, tick: 0, arrived: 0 };
+    const i = s.at(e);
+    if (i < 0) return { had: false, was: undefined, tick: 0, arrived: 0 };
+    const was = s.vals[i], tick = s.ticks[i]!, arrived = s.arrived[i]!;
+    s.ids.splice(i, 1); s.vals.splice(i, 1); s.ticks.splice(i, 1); s.arrived.splice(i, 1);
+    if (s.keys) s.keys.delete(s.keyOf!(was));
+    const seq = ++this.seq;
+    s.removed.set(e, { seq, value: was });
+    this.setBit(e, s.id, false, seq);
+    return { had: true, was, tick, arrived };
+  }
+
+  /** Records that `e` lost `name` with `value` without ever holding it here: a kept value dropped on load, so change terms see it go. */
+  forget(e: number, name: string, value: unknown): void {
+    this.register(name).removed.set(e, { seq: ++this.seq, value });
+  }
+
+  private setBit(e: number, id: number, on: boolean, seq: number): void {
+    const w = e * this.words + (id >>> 5), b = 1 << (id & 31);
+    const before = this.masks[w]!;
+    this.masks[w] = on ? before | b : before & ~b;
+    this.etick[e] = seq;
+    this.wtick[e] = seq;
+    if (this.live.size) this.relive(e);
+  }
+
+  /** A value of `s` was written on `e`: every sensitive live select `e` is in moves its version. */
+  private touched(e: number, s: Store): void {
+    for (const l of this.live.values()) {
+      if (!l.sensitive || ((l.plan.required[s.id >>> 5]! >>> (s.id & 31)) & 1) !== 1) continue;
+      if (this.matches(e, l.plan)) l.version++;
+    }
+  }
+
+  /** The entity's values by component name, in id order of the components. */
+  partsOf(e: number): Record<string, unknown> {
+    const o: Record<string, unknown> = {};
+    for (const s of this.byId) if (this.bit(e, s.id)) o[s.name] = s.vals[s.at(e)];
+    return o;
+  }
+
+  /** Makes the entity carry exactly these parts: a replica applying a delta. */
+  setParts(e: number, parts: Record<string, unknown>): void {
+    if (!this.exists(e)) this.spawn(e);
+    for (const s of this.byId) if (this.bit(e, s.id) && !(s.name in parts)) this.remove(e, s.name);
+    for (const [name, v] of Object.entries(parts)) this.put(e, name, v);
+  }
+
+  /** The entity whose `name` has the key `key`. */
+  find(name: string, key: unknown): number | undefined {
+    const s = this.stores.get(name);
+    return s?.keys?.get(key);
+  }
+
+  /** How many entities have the component. */
+  countOf(name: string): number { return this.stores.get(name)?.ids.length ?? 0; }
+  /** The entities that have the component, in id order: a copy. */
+  idsOf(name: string): number[] { return [...(this.stores.get(name)?.ids ?? [])]; }
+
+  // ---- queries -------------------------------------------------------------
+
+  private termsOf(p: Plan): Named[] {
+    const out: Named[] = p.comps.map((c) => ({ kind: "component", name: c.name }));
+    const nots: { name: string }[] = [];
+    for (const s of this.byId) if (((p.excluded[s.id >>> 5]! >>> (s.id & 31)) & 1) === 1) nots.push({ name: s.name });
+    if (nots.length) out.push({ kind: "not", components: nots });
+    for (const c of p.changes) out.push({ kind: "changed", how: c.how, component: { name: c.name } });
+    return out;
+  }
+
+  private plan(terms: readonly Named[]): Plan {
+    const required = new Uint32Array(this.words), excluded = new Uint32Array(this.words);
+    const comps: Plan["comps"] = [], changes: Plan["changes"] = [];
+    const on = (m: Mask, id: number) => { m[id >>> 5] = (m[id >>> 5]! | (1 << (id & 31))) >>> 0; };
+    for (const t of terms) {
+      if (t.kind === "component") { const s = this.register(t.name); on(required, s.id); comps.push({ name: s.name, store: s }); }
+      else if (t.kind === "not") for (const c of t.components) on(excluded, this.register(c.name).id);
+      else {
+        const s = this.register(t.component.name);
+        if (t.how !== "removed") { on(required, s.id); comps.push({ name: s.name, store: s }); }
+        changes.push({ how: t.how, name: s.name, store: s });
+      }
+    }
+    return { required, excluded, comps, changes };
+  }
+
+  private matches(e: number, p: Plan): boolean {
+    const base = e * this.words;
+    for (let k = 0; k < this.words; k++) {
+      const m = this.masks[base + k]!;
+      if (((m & p.required[k]!) >>> 0) !== p.required[k]! || (m & p.excluded[k]!) !== 0) return false;
+    }
+    return true;
+  }
+
+  /** Visits every entity matching the terms, in id order, with its values in term order; `since` is what change terms are measured from. */
+  each(terms: readonly Named[] | Select, since: number, fn: (e: number, values: unknown[]) => void): void {
+    const sel = isSelect(terms) ? terms : null;
+    const live = sel ? this.live.get(sel) : undefined;
+    const p = live ? live.plan : this.plan(sel ? sel.terms : (terms as readonly Named[]));
+    const changed = p.changes.filter((c) => c.how !== "removed");
+    const removed = p.changes.find((c) => c.how === "removed");
+    const values = new Array<unknown>(p.comps.length);
+    const row = sel?.pred ? Object.fromEntries(p.comps.map((c) => [c.name, undefined])) as Record<string, unknown> : null;
+    const visit = (e: number) => {
+      if (removed) {
+        const r = removed.store.removed.get(e);
+        if (!r || r.seq <= since) return;
+        if (!this.exists(e)) { if (p.comps.length) return; }
+      }
+      if (p.comps.length || this.exists(e)) { if (!this.exists(e) || !this.matches(e, p)) return; }
+      for (let i = 0; i < p.comps.length; i++) {
+        const s = p.comps[i]!.store, at = s.at(e);
+        values[i] = s.vals[at];
+        for (const c of changed) if (c.store === s && (c.how === "added" ? s.arrived[at]! : s.ticks[at]!) <= since) return;
+      }
+      if (row) { row.entity = e; for (let i = 0; i < p.comps.length; i++) row[p.comps[i]!.name] = values[i]; if (!sel!.pred!(row)) return; }
+      fn(e, values);
+    };
+    if (removed) { for (const e of [...removed.store.removed.keys()].sort((a, b) => a - b)) visit(e); return; }
+    if (live) { for (const e of [...live.ids]) visit(e); return; }
+    if (p.comps.length === 0) { for (let e = 1; e <= this.highest; e++) if (this.alive[e] === 1) visit(e); return; }
+    let smallest = p.comps[0]!.store;
+    for (const c of p.comps) if (c.store.ids.length < smallest.ids.length) smallest = c.store;
+    for (const e of [...smallest.ids]) visit(e);
+  }
+
+  /** The names each row's values go under, in term order. */
+  columns(terms: readonly Named[] | Select): string[] {
+    const ts = isSelect(terms) ? terms.terms : terms;
+    const out: string[] = [];
+    for (const t of ts) { if (t.kind === "component") out.push(t.name); else if (t.kind === "changed" && t.how !== "removed") out.push(t.component.name); }
+    return out;
+  }
+
+  /** The rows matching the terms: the entity, then each value under its component's name. A removed term's value is the last one it had. */
+  query(terms: readonly Named[] | Select, since: number): Record<string, unknown>[] {
+    const names = this.columns(terms);
+    const ts = isSelect(terms) ? terms.terms : terms;
+    const rem = ts.find((t): t is Extract<Named, { kind: "changed" }> => t.kind === "changed" && t.how === "removed");
+    const out: Record<string, unknown>[] = [];
+    this.each(terms, since, (e, values) => {
+      const row: Record<string, unknown> = { entity: e };
+      for (let i = 0; i < names.length; i++) row[names[i]!] = values[i];
+      if (rem) row[rem.component.name] = this.stores.get(rem.component.name)!.removed.get(e)!.value;
+      out.push(row);
+    });
+    return out;
+  }
+
+  /** Keeps the select's matched set live from now on: built once, then kept by every mask change. A select with change terms is not kept. */
+  keep(sel: Select): void {
+    if (this.live.has(sel) || sel.terms.some((t) => t.kind === "changed")) return;
+    const plan = this.plan(sel.terms);
+    const ids: number[] = [];
+    for (let e = 1; e <= this.highest; e++) if (this.alive[e] === 1 && this.matches(e, plan)) ids.push(e);
+    this.live.set(sel, { plan, ids, version: 1, sensitive: sel.pred !== null || sel.order !== null, keyed: sel.order ? this.register(sel.order.component.name) : null, cache: null });
+  }
+
+  /** The version of a kept select: another number whenever its answer may differ. 0 for one not kept. */
+  version(sel: Select): number { return this.live.get(sel)?.version ?? 0; }
+
+  /** The entities a kept select answers, its predicate applied, in its order: the same array until the version moves. */
+  kept(sel: Select): readonly number[] {
+    const l = this.live.get(sel);
+    if (!l) throw new Error("kept: the select is not kept; keep it first");
+    if (l.cache && l.cache.version === l.version) return l.cache.ids;
+    let ids: number[];
+    if (sel.pred) { ids = []; this.each(sel, 0, (e) => { ids.push(e); }); } else ids = [...l.ids];
+    if (sel.order && l.keyed) { const s = l.keyed, cmp = sel.order.cmp; ids.sort((a, b) => cmp(s.vals[s.at(a)], s.vals[s.at(b)]) || a - b); }
+    l.cache = { version: l.version, ids: Object.freeze(ids) };
+    return l.cache.ids;
+  }
+
+  private relive(e: number): void {
+    for (const l of this.live.values()) {
+      const inSet = this.matches(e, l.plan) && this.alive[e] === 1;
+      let lo = 0, hi = l.ids.length - 1, at = -1;
+      while (lo <= hi) { const mid = (lo + hi) >>> 1; const v = l.ids[mid]!; if (v === e) { at = mid; break; } if (v < e) lo = mid + 1; else hi = mid - 1; }
+      if (inSet && at < 0) { l.ids.splice(lo, 0, e); l.version++; }
+      else if (!inSet && at >= 0) { l.ids.splice(at, 1); l.version++; }
+    }
+  }
+
+  // ---- change ------------------------------------------------------------------
+
+  /**
+   * What changed after `since`, by entity: every value written, every
+   * component taken away (null), and the entities gone. Costs a walk of
+   * every store, not of every entity times every store.
+   */
+  changes(since: number): { patches: Map<number, Record<string, unknown>>; gone: number[]; added: Map<number, string[]> } {
+    const patches = new Map<number, Record<string, unknown>>();
+    const added = new Map<number, string[]>();
+    const of = (e: number) => { let p = patches.get(e); if (!p) { p = {}; patches.set(e, p); } return p; };
+    for (const s of this.byId) {
+      for (let i = 0; i < s.ids.length; i++) if (s.ticks[i]! > since) { const e = s.ids[i]!; of(e)[s.name] = s.vals[i]; if (s.arrived[i]! > since) { const a = added.get(e); if (a) a.push(s.name); else added.set(e, [s.name]); } }
+      for (const [e, r] of s.removed) if (r.seq > since && this.alive[e] === 1) of(e)[s.name] = null;
+    }
+    const gone: number[] = [];
+    for (const [e, at] of this.gone) if (at > since && this.alive[e] !== 1) { gone.push(e); patches.delete(e); added.delete(e); }
+    return { patches, gone: gone.sort((a, b) => a - b), added };
+  }
+
+  /** A delta's patch applied to the entity: each value put, each null taken away; a replica's. */
+  patch(e: number, parts: Record<string, unknown>): void {
+    if (!this.exists(e)) this.spawn(e);
+    for (const [name, v] of Object.entries(parts)) { if (v === null) this.remove(e, name); else this.put(e, name, v); }
+  }
+
+  /** Every value written after `since`, by walking the stores: the entity, the component's name, the value. */
+  changedParts(since: number): [number, string, unknown][] {
+    const out: [number, string, unknown][] = [];
+    for (const s of this.byId) for (let i = 0; i < s.ids.length; i++) if (s.ticks[i]! > since) out.push([s.ids[i]!, s.name, s.vals[i]]);
+    return out;
+  }
+
+  /** Forgets removals and despawns older than `seq`: nothing measures from before it any more. */
+  prune(seq: number): void {
+    for (const [e, at] of this.gone) if (at <= seq) this.gone.delete(e);
+    for (const s of this.byId) for (const [e, r] of s.removed) if (r.seq <= seq) s.removed.delete(e);
+  }
+}
+
+export const isSelect = (x: unknown): x is Select => typeof x === "object" && x !== null && (x as { kind?: unknown }).kind === "select";

package/src/ecs/testbed.ts

@@ -0,0 +1,97 @@
+// State in, state out: a baba or a system driven by hand, on a virtual clock.
+// `fire` runs the action now, as its system; `tick` advances the clock to the
+// time given, running every round due on the way (a retry, a scheduled
+// effect, the baba's tick) and one round at that time; jobs wait until
+// `done` or `failed` answers them, unless a port is given. The same driver
+// serves the headless runner and a live simulation: both only advance.
+import { Runtime, type Port } from "./runtime.ts";
+import type { Baba, System } from "./baba.ts";
+import type { State, Effect, Entity, Args, Result, Job, Snapshot } from "./state.ts";
+import { virtualScheduler } from "./scheduler.ts";
+import type { ActOf as ContractActs, ReadOf as ContractReads } from "./baba.ts";
+import type { Adapter } from "../spec/adapters.ts";
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** An untyped testbed (a scenario in a file of its own) fires and reads anything. */
+type ActOf<V> = IsAny<V> extends true ? Record<string, { args: any; result: any }> : ContractActs<V>;
+type ReadOf<V> = IsAny<V> extends true ? Record<string, { args: any; result: any }> : ContractReads<V>;
+type ArgsOf<D> = D extends { args: infer A } ? ({} extends A ? [args?: A] : [args: A]) : [];
+type ResultOf<D> = D extends { result: infer R } ? R : never;
+
+export interface Testbed<V> {
+  readonly w: State<V>;
+  /** Runs the action now, as its system, over the state as it is; what it returned. */
+  fire<K extends keyof ActOf<V> & string>(name: K, ...args: ArgsOf<ActOf<V>[K]>): ResultOf<ActOf<V>[K]>;
+  /** The clock to `now` (the last time plus one by default), every round due on the way, then one round at `now`. */
+  tick(at?: { now: number }): void;
+  /** The clock to `to`: every round due on the way, and nothing more. What a live driver calls as real time passes. */
+  advance(to: number): void;
+  /** The time, as the clock has it. */
+  readonly now: number;
+  /** The earliest moment a round is due on its own, or null. */
+  readonly due: number | null;
+  /** The jobs of `effect` waiting for an answer. */
+  pending<E extends Effect>(effect: E): { entity: Entity | null; args: Args<E> }[];
+  /** Answers the jobs of `effect` whose args match `where` (every one by default), at the next tick. */
+  done<E extends Effect>(effect: E, result: Result<E>, where?: Partial<Args<E>> | { entity: Entity | null }): void;
+  failed<E extends Effect>(effect: E, error: string, where?: Partial<Args<E>> | { entity: Entity | null }): void;
+  /** A source's listing, as its `list` would answer: lands at the next tick for the jobs matching `where`. */
+  list<E extends Effect>(effect: E, items: unknown[], where?: Partial<Args<E>> | { entity: Entity | null }): void;
+  /** A source's events, as its `watch` would yield them. */
+  watch<E extends Effect>(effect: E, events: unknown[], where?: Partial<Args<E>> | { entity: Entity | null }): void;
+  read<K extends keyof ReadOf<V> & string>(name: K, ...args: ArgsOf<ReadOf<V>[K]>): ResultOf<ReadOf<V>[K]>;
+  readonly round: number;
+  readonly jobs: Job[];
+  /** Each adapter's state, by effect: the outside as the state's models hold it. */
+  readonly outside: ReadonlyMap<Effect, Map<string, unknown>>;
+}
+
+export function testbed<V extends Baba | System>(v: V, at: { now?: number; seed?: number; snapshot?: Snapshot; port?: Port; adapters?: (effect: Effect) => Adapter | undefined; log?: (line: string) => void } = {}): Testbed<V> {
+  const clock = virtualScheduler(at.now ?? 0);
+  const rt = new Runtime(v, { auto: false, scheduler: clock, seed: at.seed ?? 1, ...(at.snapshot ? { snapshot: at.snapshot } : {}), ...(at.port ? { port: at.port } : {}), ...(at.adapters ? { adapters: at.adapters } : {}), ...(at.log ? { log: at.log } : {}) });
+  rt.w.checking = true;
+  rt.w.begin(clock.now(), 0);
+  const matching = (effect: Effect, where?: Record<string, unknown>) => [...rt.w.jobs.values()].filter((j) => j.effect === effect).filter((j) => {
+    if (!where) return true;
+    if ("entity" in where && Object.keys(where).length === 1) return j.entity === where.entity;
+    return Object.entries(where).every(([k, val]) => JSON.stringify((j.args as Record<string, unknown>)[k]) === JSON.stringify(val));
+  });
+  return {
+    w: rt.w as State<V>,
+    fire: ((name: string, args?: unknown) => {
+      const d = rt.baba.actions[name];
+      if (!d) throw new Error(`no action ${name}`);
+      return rt.act(name, d.args.check(args ?? {}));
+    }) as never,
+    // The clock to `to`, the round, then whatever the round's jobs answered at once: an adapter's reply with no delay lands before the hand looks.
+    tick(t) { const to = t?.now ?? clock.now() + 1; clock.advance(to); rt.step(to); clock.flush(); },
+    advance(to) { clock.advance(to); },
+    get now() { return clock.now(); },
+    get due() { return rt.due(); },
+    pending: (effect) => rt.pending(effect).map((j) => ({ entity: j.entity, args: j.args as never })),
+    done(effect, result, where) {
+      const jobs = matching(effect, where as Record<string, unknown> | undefined);
+      if (jobs.length === 0) throw new Error(`no job of ${effect.name} is waiting${where ? " for those args" : ""}`);
+      for (const j of jobs) rt.answer(effect, j.entity, j.instance, true, result);
+    },
+    failed(effect, error, where) {
+      const jobs = matching(effect, where as Record<string, unknown> | undefined);
+      if (jobs.length === 0) throw new Error(`no job of ${effect.name} is waiting${where ? " for those args" : ""}`);
+      for (const j of jobs) rt.answer(effect, j.entity, j.instance, false, error);
+    },
+    list(effect, items, where) {
+      const jobs = matching(effect, where as Record<string, unknown> | undefined);
+      if (jobs.length === 0) throw new Error(`no job of ${effect.name} is running${where ? " for those args" : ""}`);
+      for (const j of jobs) rt.deliver(effect, j.entity, j.instance, { listed: items });
+    },
+    watch(effect, events, where) {
+      const jobs = matching(effect, where as Record<string, unknown> | undefined);
+      if (jobs.length === 0) throw new Error(`no job of ${effect.name} is running${where ? " for those args" : ""}`);
+      for (const j of jobs) rt.deliver(effect, j.entity, j.instance, { events });
+    },
+    read: ((name: string, args?: unknown) => rt.read(name, args ?? {})) as never,
+    get round() { return rt.round; },
+    get jobs() { return [...rt.w.jobs.values()]; },
+    get outside() { return rt.outside; },
+  };
+}