babavoss 0.0.1 → 0.12.0

package/src/ecs/runtime.ts

@@ -0,0 +1,603 @@
+// The baba running: one state, one inbox, rounds. A round is synchronous:
+// begin, apply the inbox (actions run as their system, raw writes, answers
+// land), then for each system in order land its effects' answers, run its
+// steps, ask for its jobs; start the jobs. Time is the round's. One
+// timer waits for the earliest due moment; nothing runs while nothing is due.
+import { SchemaError, type Json } from "../kernel/schema.ts";
+import type { Context } from "../kernel/context.ts";
+import { hasSecret, mapEntities, redact } from "./handles.ts";
+import { State, StateError, jobKey, type Component, type Resource, type Effect, type Entity, type Job, type Snapshot, type Declaration } from "./state.ts";
+import { isDelta, mergeDeltas, type StateAnswer, type Delta } from "./snapshot.ts";
+import { codecOf, encodeFrame, type Codec } from "./codec.ts";
+import { PRESENT } from "./snapshot.ts";
+import type { Interest } from "../server/protocol.ts";
+import { realScheduler, type Handle, type Scheduler } from "./scheduler.ts";
+import type { Adapter } from "../spec/adapters.ts";
+import { ofSystem, isSystem, dataOf, type Baba, type System, type SystemData } from "./baba.ts";
+
+export class ContractError extends Error {
+  constructor(readonly code: "noaction" | "noquery" | "args" | "result" | "failed" | "entity" | "name" | "owner", msg: string) { super(msg); }
+}
+
+/** How the runtime reaches the port for its jobs: a context per run, named for the effect, with the run's cancel. */
+export type Port = (system: string, effect: string, job: number, signal: AbortSignal, entity?: Entity | null) => Context;
+
+/** A write at layer zero: the state's own operations, as the shell and the inspector use them. */
+export type Raw =
+  | { op: "spawn"; parts: Record<string, unknown> }
+  | { op: "add"; entity: Entity; component: string; value?: unknown }
+  | { op: "remove"; entity: Entity; components: string[] }
+  | { op: "despawn"; entity: Entity }
+  | { op: "set"; resource: string; value: unknown };
+
+type Input =
+  | { kind: "fire"; name: string; args: unknown; key?: string; resolve: (v: unknown) => void; reject: (err: Error) => void }
+  | { kind: "raw"; raw: Raw; resolve: (v: unknown) => void; reject: (err: Error) => void }
+  | { kind: "settled"; effect: Effect; entity: Entity | null; instance: number; ok: boolean; value: unknown }
+  | { kind: "batch"; effect: Effect; entity: Entity | null; instance: number; batch: Batch };
+
+/** What a source delivers: the slice listed, or events watched. */
+export type Batch = { listed: unknown[] } | { events: unknown[] };
+
+/** How long a mirror waits after a "changed" before listing again, so a burst becomes one listing. */
+const RELIST_MS = 100;
+/** How many rounds' deltas the runtime keeps made and redacted: a follower within them is answered from the log, one further back from the table. */
+const LOG_ROUNDS = 4;
+
+export interface RuntimeOptions {
+  port?: Port;
+  /** Ticks on its own: a microtask after a fire, a timer for the earliest due moment. A testbed turns it off. */
+  auto?: boolean;
+  /** A state to continue from. */
+  snapshot?: Snapshot;
+  /** The time of the first round; the scheduler's clock by default. */
+  now?: () => number;
+  /** The clock and the timers: the machine's by default; a virtual one a driver advances for a testbed or a simulation. */
+  scheduler?: Scheduler;
+  /** The outside as a model: an effect's adapter answers its jobs instead of the port, on the scheduler. An effect with none waits for the port, or for a testbed's answer. */
+  adapters?: (effect: Effect) => Adapter | undefined;
+  /** Every value written in a round checked at its end, so the state holds only what the model admits; on by default. */
+  audit?: boolean;
+  /** The seed of `w.random()` for a fresh state; the clock by default. A kept state keeps its own. */
+  seed?: number;
+  /** Hears each round's end: what the round changed, as a delta since the one before, or the whole when there is no before. */
+  onRound?: (state: StateAnswer) => void;
+  log?: (line: string) => void;
+}
+
+export class Runtime {
+  readonly baba: Baba;
+  readonly w: State;
+  private rounds: number;
+  private inbox: Input[] = [];
+  private scheduled = false;
+  private timer: Handle | null = null;
+  /** The runs under way, by instance: a job asked again is a new instance, and the old run's answers are dropped. */
+  private started = new Map<number, { key: string; ctl: AbortController }>();
+  /** How to ask a running source to list again, by its run: what a mirror's landing calls when the slice said "changed". */
+  private relisters = new Map<number, () => void>();
+  /** The last event each source job landed, by key: what its watch resumes from after a failure. */
+  private lastEvent = new Map<string, unknown>();
+  /** The batches landed this round, by owning system, waiting for the system's slot. */
+  private batches = new Map<string, Extract<Input, { kind: "batch" }>[]>();
+  private soon: Handle | null = null;
+  private due_ = new Map<string, number>();       // jobs retrying: when they may start again
+  private everyDue = new Map<Effect, number>();   // scheduled effects: when they run next
+  private tickDue: number | null;
+  private waiters: { since: number; resolve: () => void }[] = [];
+  private jobs = 1;
+  private stopped = false;
+  private readonly port: Port | null;
+  private readonly adapters: ((effect: Effect) => Adapter | undefined) | null;
+  /** Each adapter's state in this state, by effect: what `model` keeps, what the shell shows as the outside. */
+  readonly outside = new Map<Effect, Map<string, unknown>>();
+  private readonly auto: boolean;
+  private readonly sched: Scheduler;
+  private readonly audit: boolean;
+  private readonly onRound: (state: StateAnswer) => void;
+  /** The sequence at which each system's steps last ran: what its change terms measure from. */
+  private ran = new Map<string, number>();
+  /** The sequence at the last round's end: what the audit and the next round's inbox phase measure from. */
+  private ended = 0;
+  /** The last rounds' deltas, made once each, redacted once each, laid out as a frame on first demand: what every follower is answered from. */
+  private deltas = new Map<number, { delta: Delta; redacted: Delta; frame: Uint8Array | null }>();
+  /** The whole as a frame, for the round it was made at. */
+  private whole: { round: number; frame: Uint8Array } | null = null;
+  /** The frame layout: the model's components and resources, in order. */
+  readonly codec: Codec;
+  /** Whether any declaration has a secret field: without one, nothing leaves redacted, so nothing is copied. */
+  private readonly secrets: boolean;
+  private readonly log: (line: string) => void;
+
+  constructor(v: Baba | System, o: RuntimeOptions = {}) {
+    this.baba = isSystem(v) ? ofSystem(v) : v;
+    this.port = o.port ?? null;
+    this.adapters = o.adapters ?? null;
+    this.auto = o.auto ?? true;
+    this.sched = o.scheduler ?? (o.now ? { ...realScheduler(), now: o.now } : realScheduler());
+    this.audit = o.audit ?? true;
+    this.onRound = o.onRound ?? (() => {});
+    this.log = o.log ?? (() => {});
+    this.w = o.snapshot ? State.restore(o.snapshot, this.baba.model, (what) => this.log(`the kept state was fitted to the code: ${what}`)) : new State(this.baba.model);
+    if (!o.snapshot) this.w.seed(o.seed ?? (this.sched.now() ^ (Math.random() * 2 ** 31)) >>> 0);
+    this.rounds = o.snapshot?.round ?? 0;
+    this.w.round = this.rounds;
+    this.w.end();
+    this.ended = this.w.seq;
+    this.tickDue = this.baba.tick === null ? null : 0;
+    for (const e of this.baba.model.effects) if (e.every !== null) this.everyDue.set(e, 0);
+    this.codec = codecOf(this.baba.model.components.map((c) => ({ name: c.name, json: c.schema.json })), this.baba.model.resources.map((r) => ({ name: r.name, json: r.schema.json })));
+    this.secrets = [...this.baba.model.components, ...this.baba.model.resources].some((d) => hasSecret(d.schema.json)) || this.baba.model.effects.some((e) => hasSecret(e.args.json));
+    if (this.auto) this.schedule();
+  }
+
+  get round(): number { return this.rounds; }
+
+  /** What `name` is: an action, a query, or nothing. */
+  kind(name: string): "action" | "query" | null {
+    return name in this.baba.actions ? "action" : name in this.baba.queries ? "query" : null;
+  }
+
+  /**
+   * Fires an action: it runs at the start of the next round, as its system; the
+   * answer is what it returned. With an idempotency `key` the state has seen,
+   * the answer is the one remembered, and the action does not run again.
+   */
+  fire(name: string, args: unknown = {}, coerce = false, key?: string): Promise<unknown> {
+    const d = this.baba.actions[name];
+    if (!d) return Promise.reject(new ContractError("noaction", `no action ${name}; actions: ${Object.keys(this.baba.actions).join(", ")}`));
+    let checked: unknown;
+    try { checked = d.args.check(args ?? {}, "", coerce); } catch (e) { return Promise.reject(new ContractError("args", e instanceof SchemaError ? e.message : String(e))); }
+    return new Promise((resolve, reject) => { this.inbox.push({ kind: "fire", name, args: checked, ...(key !== undefined ? { key } : {}), resolve, reject }); this.schedule(); });
+  }
+
+  /**
+   * Runs an action now, as its system, over the state as it is: the round's and
+   * the testbed's. `args` are already checked; an `s.entity(component)` field
+   * is resolved from a key and checked to carry its component first. All or
+   * nothing: a throw or a bad result undoes every write it made.
+   */
+  act(name: string, args: unknown): unknown {
+    const d = this.baba.actions[name];
+    if (!d) throw new ContractError("noaction", `no action ${name}; actions: ${Object.keys(this.baba.actions).join(", ")}`);
+    const w = this.w;
+    args = this.entities(d.args.json, args);
+    return w.transaction(() => {
+      const was = w.writer;
+      w.writer = d.owner;
+      let r: unknown;
+      try { r = d.run(w, args); } catch (e) {
+        if (e instanceof StateError) throw new ContractError(e.code === "value" ? "args" : e.code, `${name}: ${e.message}`);
+        throw new ContractError("failed", `${name}: ${e instanceof Error ? e.message : String(e)}`);
+      } finally { w.writer = was; }
+      if (r === undefined) r = null;
+      try { return d.result.check(r); } catch (e) { throw new ContractError("result", `${name} returned a bad result: ${e instanceof SchemaError ? e.message : String(e)}`); }
+    });
+  }
+
+  /** The args with every `s.entity(component)` field an entity carrying it: a key resolved by `w.find`, an id checked. */
+  private entities(json: Json, args: unknown): unknown {
+    const w = this.w;
+    return mapEntities(json, args, (name, v, path) => {
+      const c = w.declaration(name);
+      if (!c || c.kind !== "component") throw new ContractError("entity", `${path}: no component ${name}`);
+      let e = v;
+      if (typeof v === "string") {
+        let found: number | undefined;
+        try { found = w.find(c as Component, v); } catch { throw new ContractError("entity", `${path}: ${name} has no key field; pass the entity id`); }
+        if (found === undefined) throw new ContractError("entity", `${path}: no ${name} ${JSON.stringify(v)}`);
+        e = found;
+      }
+      if (typeof e !== "number" || !w.has(e, c as Component)) throw new ContractError("entity", `${path}: entity ${String(e)} has no ${name}`);
+      return e;
+    });
+  }
+
+  /** Reads a query, now, between rounds. */
+  read(name: string, args: unknown = {}, coerce = false): unknown {
+    const q = this.baba.queries[name];
+    if (!q) throw new ContractError("noquery", `no query ${name}; queries: ${Object.keys(this.baba.queries).join(", ")}`);
+    let checked: unknown;
+    try { checked = q.args.check(args ?? {}, "", coerce); } catch (e) { throw new ContractError("args", e instanceof SchemaError ? e.message : String(e)); }
+    let r: unknown;
+    try { r = q.read(this.w, checked); } catch (e) { throw new ContractError("failed", `${name}: ${e instanceof Error ? e.message : String(e)}`); }
+    try { return q.result.check(r); } catch (e) { throw new ContractError("result", `${name} read a bad result: ${e instanceof SchemaError ? e.message : String(e)}`); }
+  }
+
+  /** A write at layer zero, applied at the next round: spawn answers the entity, the rest what the entity or resource holds. */
+  raw(raw: Raw): Promise<unknown> {
+    return new Promise((resolve, reject) => { this.inbox.push({ kind: "raw", raw, resolve, reject }); this.schedule(); });
+  }
+
+  /**
+   * The state as kept, with the round. `redacted`: every secret field of a
+   * component, a resource or a job's args replaced by •••, and no remembered
+   * answers: what leaves the runtime toward a window, the inspector or `state`.
+   */
+  snapshot(o: { redacted?: boolean } = {}): Snapshot {
+    const snap = { ...this.w.snapshot(), round: this.rounds };
+    return o.redacted ? this.redacted(snap) as Snapshot : snap;
+  }
+
+  /**
+   * The state since round `since`: a delta when the state remembers that
+   * round, else the whole; `redacted` as `snapshot`. A follower a few rounds
+   * behind is answered from the log of deltas made at each round's end, so
+   * what following costs is paid once per round, not once per follower.
+   */
+  state(since: number, o: { redacted?: boolean } = {}): StateAnswer {
+    if (since > this.rounds) since = 0;
+    // Since the round just ended: the empty delta the state answers, without a walk.
+    if (since > 0 && since === this.rounds) return this.w.delta(since) ?? this.snapshot(o);
+    const d = since > 0 ? this.since(since, o.redacted === true) : null;
+    return d ?? this.snapshot(o);
+  }
+
+  /** The deltas since `since` as one, from the log when it holds them all, else measured from the table; null when the whole must go. */
+  private since(since: number, redacted: boolean): Delta | null {
+    if (this.rounds - since <= LOG_ROUNDS) {
+      const parts: Delta[] = [];
+      for (let r = since + 1; r <= this.rounds; r++) { const l = this.deltas.get(r); if (!l) break; parts.push(redacted ? l.redacted : l.delta); }
+      if (parts.length === this.rounds - since) return parts.length === 1 ? parts[0]! : mergeDeltas(parts);
+    }
+    const d = this.w.delta(since);
+    if (!d) return null;
+    return redacted ? this.redacted(d) : d;
+  }
+
+  /** The state since `since` as a frame, redacted: the round just ended is laid out once and shared by every follower. */
+  frame(since: number): Uint8Array {
+    if (since > 0 && since === this.rounds - 1) {
+      const l = this.deltas.get(this.rounds);
+      if (l) { if (!l.frame) l.frame = encodeFrame(this.codec, l.redacted); return l.frame; }
+    }
+    const s = this.state(since, { redacted: true });
+    if (isDelta(s)) return encodeFrame(this.codec, s);
+    if (this.whole?.round !== this.rounds) this.whole = { round: this.rounds, frame: encodeFrame(this.codec, s) };
+    return this.whole.frame;
+  }
+
+  /**
+   * The parts of the state a window began to ask for, as a frame since the
+   * round just ended: the presence of some components on every entity that
+   * has them, the values of others, some parts, some resources. Every part
+   * is marked as arrived, so a follower of presence alone takes it.
+   */
+  parts(interest: Interest): Uint8Array {
+    const w = this.w;
+    const entities: Delta["entities"] = {};
+    const added: Record<string, string[]> = {};
+    const put = (e: Entity, name: string, v: unknown) => { (entities[String(e)] ??= {})![name] = v; (added[String(e)] ??= []).push(name); };
+    const comp = (name: string) => { const c = w.declaration(name); return c?.kind === "component" ? c as Component : null; };
+    for (const name of interest.presence ?? []) { const c = comp(name); if (c) for (const e of w.idsOf(c)) put(e, name, PRESENT); }
+    for (const name of interest.values ?? []) { const c = comp(name); if (c) for (const e of w.idsOf(c)) put(e, name, w.get(e, c)); }
+    for (const [name, es] of Object.entries(interest.parts ?? {})) { const c = comp(name); if (c) for (const e of es) if (w.alive(e) && w.has(e, c)) put(e, name, w.get(e, c)); }
+    const resources: Record<string, unknown> = {};
+    for (const name of interest.resources ?? []) { const r = w.declaration(name); if (r?.kind === "resource") resources[name] = w.get(r as never); }
+    const d: Delta = { kind: "delta", round: this.rounds, since: this.rounds, entities, resources, now: w.now, added };
+    return encodeFrame(this.codec, this.redacted(d));
+  }
+
+  private redacted<S extends Snapshot | Delta>(s: S): S {
+    if (!this.secrets) { if (isDelta(s) ? s.keys === undefined : s.keys === undefined || Object.keys(s.keys).length === 0) return s; return { ...s, keys: {} }; }
+    const decl = (n: string) => this.w.declaration(n);
+    const entities: Record<string, Record<string, unknown> | null> = {};
+    for (const [id, parts] of Object.entries(s.entities)) entities[id] = parts === null ? null : Object.fromEntries(Object.entries(parts).map(([n, v]) => [n, v === null || v === PRESENT ? v : redact((decl(n) as Component).schema.json, v)]));
+    const resources = Object.fromEntries(Object.entries(s.resources).map(([n, v]) => [n, redact((decl(n) as Resource).schema.json, v)]));
+    const out = { ...s, entities, resources } as S;
+    if (s.jobs !== undefined) out.jobs = s.jobs.map((j) => ({ ...j, args: redact((decl(j.effect) as Effect).args.json, j.args) }));
+    if (s.keys !== undefined || !isDelta(s)) out.keys = {};
+    return out;
+  }
+
+  /** Resolves once a round past `since` has run, or after `ms`. */
+  waitRound(since: number, ms: number): Promise<void> {
+    if (this.rounds > since || this.stopped) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      const w = { since, resolve: () => { clearTimeout(timer); resolve(); } };
+      const timer = setTimeout(() => { this.waiters = this.waiters.filter((x) => x !== w); resolve(); }, ms);
+      (timer as unknown as { unref?: () => void }).unref?.();
+      this.waiters.push(w);
+    });
+  }
+
+  /** Cancels every job and timer; the state is left as it is, for the snapshot. */
+  stop(): Snapshot {
+    this.stopped = true;
+    this.timer?.cancel(); this.timer = null;
+    this.soon?.cancel(); this.soon = null;
+    for (const s of this.started.values()) s.ctl.abort();
+    this.started.clear();
+    for (const i of this.inbox.splice(0)) if (i.kind === "fire" || i.kind === "raw") i.reject(new ContractError("failed", "the baba stopped"));
+    for (const w of this.waiters.splice(0)) w.resolve();
+    return this.snapshot();
+  }
+
+  /** The jobs not yet started, as a testbed sees them. */
+  pending(effect?: Effect): Job[] {
+    return [...this.w.jobs.values()].filter((j) => (!effect || j.effect === effect) && !this.started.has(j.instance));
+  }
+
+  /** A job's answer, as the port or a testbed gives it: applied at the next round. `instance` says which run answers; another's is dropped. */
+  answer(effect: Effect, entity: Entity | null, instance: number, ok: boolean, value: unknown): void {
+    this.inbox.push({ kind: "settled", effect, entity, instance, ok, value });
+    this.schedule();
+  }
+
+  /** A source's batch, as the driver or a testbed gives it: lands at the next round, in the owner's slot. Every batch in flight lands in the same round. */
+  private queuedBytes = new Map<number, number>();
+
+  deliver(effect: Effect, entity: Entity | null, instance: number, batch: Batch): void {
+    const bytes = (this.queuedBytes.get(instance) ?? 0) + (effect.mirror ? 0 : JSON.stringify(batch).length * 2);
+    if (bytes > 1024 * 1024) throw new Error(`${effect.name}: source events exceed 1 MiB before a round; reduce or coalesce events`);
+    this.queuedBytes.set(instance, bytes);
+    this.inbox.push({ kind: "batch", effect, entity, instance, batch });
+    this.scheduleSoon();
+  }
+
+  /** The earliest moment a round is due on its own: a retry, a scheduled effect, the tick; null when nothing is. */
+  due(): number | null {
+    let earliest: number | null = null;
+    const consider = (at: number | null | undefined) => { if (at !== null && at !== undefined && (earliest === null || at < earliest)) earliest = at; };
+    for (const at of this.due_.values()) consider(at);
+    for (const [e, at] of this.everyDue) if (!this.w.running(e)) consider(at);
+    consider(this.tickDue);
+    return earliest;
+  }
+
+  /** The time, as the scheduler has it. */
+  now(): number { return this.sched.now(); }
+
+  /** One round, at `now`. */
+  step(now = this.sched.now()): void {
+    if (this.stopped) return;
+    this.scheduled = false;
+    this.timer?.cancel(); this.timer = null;
+    this.soon?.cancel(); this.soon = null;
+    this.rounds++;
+    const w = this.w;
+    w.begin(now, this.rounds);
+    w.writer = null;
+    const before = this.ended;   // the previous round's end: what the inbox phase, and reads between rounds, measure from
+    w.since = before;
+    // Jobs cut off by a crash, of effects not safe to repeat: failed, once, never retried.
+    for (const j of w.interrupted()) {
+      w.settle(j.effect, j.entity, false, "interrupted", false);
+      if (j.effect.every !== null) this.everyDue.set(j.effect, now + j.effect.every);
+    }
+    this.queuedBytes.clear();
+    // The inbox: actions run as their system, raw writes happen, answers land.
+    for (const i of this.inbox.splice(0)) {
+      if (i.kind === "fire") {
+        const kept = i.key === undefined ? undefined : w.recall(i.key);
+        if (kept) { i.resolve(kept.value); continue; }
+        try {
+          const v = this.act(i.name, i.args);
+          if (i.key !== undefined) w.remember(i.key, v);
+          i.resolve(v);
+        } catch (err) { i.reject(err instanceof Error ? err : new Error(String(err))); }
+      } else if (i.kind === "raw") {
+        try { i.resolve(w.transaction(() => this.apply(i.raw))); } catch (err) { i.reject(err instanceof Error ? err : new Error(String(err))); }
+      } else if (i.kind === "batch") {
+        const job = w.jobs.get(jobKey(i.effect, i.entity));
+        if (!job || job.instance !== i.instance) continue;   // a run that was cancelled or asked again: its batches are not news
+        if (!this.batches.has(i.effect.owner)) this.batches.set(i.effect.owner, []);
+        this.batches.get(i.effect.owner)!.push(i);
+      } else {
+        const key = jobKey(i.effect, i.entity);
+        const job = w.jobs.get(key);
+        if (!job || job.instance !== i.instance) continue;
+        this.started.get(i.instance)?.ctl.abort();
+        this.started.delete(i.instance);
+        const r = w.settle(i.effect, i.entity, i.ok, i.value);
+        if (r === "retry") this.due_.set(key, now + i.effect.retry!);
+        if (i.effect.every !== null && r !== "retry") this.everyDue.set(i.effect, now + i.effect.every);
+        if (r !== "retry") this.lastEvent.delete(key);
+      }
+    }
+    for (const [key, at] of [...this.due_]) if (at <= now) { this.due_.delete(key); const j = w.jobs.get(key); if (j) j.status = "waiting"; }
+    if (this.tickDue !== null && this.tickDue <= now) this.tickDue = now + this.baba.tick!;
+    // The systems, in order: answers land, steps run, jobs are asked for.
+    for (const c of this.baba.systems.map(dataOf)) {
+      w.writer = c.name;
+      w.since = this.ran.get(c.name) ?? 0;
+      // The sources' batches land first, as the owner: a mirror is kept, a stream's events are readable this round.
+      for (const b of this.batches.get(c.name) ?? []) {
+        // Vetted in the inbox phase, when its run was the job's: a poll's listing lands even when this same round settled its run as done.
+        const job = w.jobs.get(jobKey(b.effect, b.entity));
+        const { relist } = w.land(b.effect, b.entity, b.batch, (what) => this.log(`${c.name}: ${what}`));
+        if (job && job.instance === b.instance) { job.events += "listed" in b.batch ? b.batch.listed.length : b.batch.events.length; job.last = now; }
+        if (relist) this.relisters.get(b.instance)?.();
+      }
+      this.batches.delete(c.name);
+      for (const [effect, b] of c.bindings) {
+        if (b.done) for (const d of w.done(effect)) this.guard(c, `${effect.name}.done`, () => b.done!(w, d.entity, d.result));
+        if (b.failed) for (const f of w.failed(effect)) this.guard(c, `${effect.name}.failed`, () => b.failed!(w, f.entity, f.error));
+      }
+      for (const st of c.steps) this.guard(c, st.name, () => st.run(w));
+      for (const [effect, b] of c.bindings) {
+        if (!b.for) continue;
+        if (effect.shape !== "source") { this.guard(c, `${effect.name}.for`, () => { for (const [entity, args] of b.for!(w)) w.run(effect, args, entity); }); continue; }
+        // A source's `for` is the set wanted: an entity no longer in it loses its job, one whose args changed gets a new one.
+        this.guard(c, `${effect.name}.for`, () => {
+          const wanted = new Map<Entity, unknown>();
+          for (const [entity, args] of b.for!(w)) wanted.set(entity, args ?? {});
+          for (const job of [...w.jobs.values()]) {
+            if (job.effect !== effect || job.entity === null) continue;
+            const args = wanted.get(job.entity);
+            if (args === undefined || JSON.stringify(args) !== JSON.stringify(job.args)) w.cancel(effect, job.entity);
+          }
+          for (const [entity, args] of wanted) w.run(effect, args as never, entity);
+        });
+      }
+      for (const effect of c.model.effects) {
+        const at = this.everyDue.get(effect);
+        if (at !== undefined && at <= now && !w.running(effect)) w.run(effect);
+      }
+      this.ran.set(c.name, w.seq);
+    }
+    w.writer = null;
+    if (this.audit && !w.checking) w.audit(this.ended, (what) => this.log(`a write the model refuses: ${what}`));
+    this.start();
+    w.end();
+    this.ended = w.seq;
+    w.since = before;   // between rounds, change terms answer what the last round changed
+    for (const x of this.waiters.splice(0)) if (this.rounds > x.since) x.resolve(); else this.waiters.push(x);
+    const d = this.w.delta(this.rounds - 1);
+    if (d) {
+      this.deltas.set(this.rounds, { delta: d, redacted: this.redacted(d), frame: null });
+      for (const r of this.deltas.keys()) if (r <= this.rounds - LOG_ROUNDS) this.deltas.delete(r);
+    }
+    this.onRound(d ?? this.snapshot());
+    this.arm(now);
+  }
+
+  private guard(c: SystemData, what: string, f: () => void): void {
+    try { f(); } catch (err) { this.log(`${c.name} ${what}: ${err instanceof Error ? err.message : String(err)}`); }
+  }
+
+  private apply(raw: Raw): unknown {
+    const w = this.w;
+    const need = (name: string, kind: Declaration["kind"]): Declaration => {
+      const d = w.declaration(name);
+      if (!d || d.kind !== kind) throw new ContractError("name", `no ${kind} ${name}`);
+      return d;
+    };
+    const alive = (e: Entity) => { if (!w.alive(e)) throw new ContractError("entity", `no entity ${e}`); return e; };
+    try {
+      switch (raw.op) {
+        case "spawn": { const e = w.spawn(); for (const [n, v] of Object.entries(raw.parts)) { const c = need(n, "component") as Component; w.add(e, c as never, w.check(c, v) as never); } return e; }
+        case "add": { const c = need(raw.component, "component") as Component; w.add(alive(raw.entity), c as never, w.check(c, raw.value ?? true) as never); return w.of(raw.entity); }
+        case "remove": w.remove(alive(raw.entity), ...raw.components.map((n) => need(n, "component") as never)); return w.of(raw.entity);
+        case "despawn": w.despawn(alive(raw.entity)); return null;
+        case "set": { const r = need(raw.resource, "resource") as Resource; w.set(r as never, w.check(r, raw.value) as never); return w.get(r as never); }
+      }
+    } catch (err) {
+      if (err instanceof StateError) throw new ContractError(err.code === "value" ? "args" : err.code, err.message);
+      throw err;
+    }
+  }
+
+  /** Starts every job waiting; cancels every run whose job the state no longer has, or has again as a new instance. */
+  private start(): void {
+    for (const [instance, s] of [...this.started]) if (this.w.jobs.get(s.key)?.instance !== instance) { s.ctl.abort(); this.started.delete(instance); }
+    for (const key of [...this.due_.keys()]) if (!this.w.jobs.has(key)) this.due_.delete(key);
+    if (!this.port && !this.adapters) return;
+    for (const job of this.w.jobs.values()) {
+      const key = jobKey(job.effect, job.entity);
+      if (this.started.has(job.instance) || job.status === "retrying" || job.status === "interrupted") continue;
+      const adapter = this.adapters?.(job.effect);
+      if (!adapter && !this.port) continue;
+      const ctl = new AbortController();
+      this.started.set(job.instance, { key, ctl });
+      job.status = "running";
+      const { effect, entity, args, instance } = job;
+      if (adapter) { this.adapt(job, adapter, ctl); continue; }
+      const ctx = this.port!(effect.owner, effect.name, instance, ctl.signal, entity);
+      if (effect.shape === "source") { void this.drive(job, key, ctx, ctl); continue; }
+      Promise.resolve().then(() => effect.run(args, ctx)).then(
+        (v) => { if (!ctl.signal.aborted) this.answer(effect, entity, instance, true, v); },
+        (err) => { if (!ctl.signal.aborted) this.answer(effect, entity, instance, false, err instanceof Error ? err.message : String(err)); },
+      );
+    }
+  }
+
+  /** Runs a job against its adapter: a request's reply lands after its delay; a source's listing at once, its events at their moments, listed again every `relist`. */
+  private adapt(job: Job, adapter: Adapter, ctl: AbortController): void {
+    const { effect, entity, args, instance } = job;
+    const signal = ctl.signal;
+    if (!this.outside.has(effect)) this.outside.set(effect, new Map());
+    const ctx = { now: this.sched.now(), entity, state: this.outside.get(effect)! };
+    // What the outside sends is news: a round follows it, as one follows the port's answers, whether or not the runtime ticks on its own.
+    const at = (ms: number, fn: () => void) => { const h = this.sched.at(this.sched.now() + ms, () => { if (signal.aborted) return; fn(); this.roundSoon(); }); signal.addEventListener("abort", () => h.cancel(), { once: true }); };
+    try {
+      if (adapter.kind === "request") {
+        const r = adapter.reply(args, ctx);
+        if (r.answer) { const a = r.answer; at(r.after, () => this.answer(effect, entity, instance, a.ok, a.ok ? a.value : a.error)); }
+        return;
+      }
+      if (effect.shape !== "source") { this.answer(effect, entity, instance, false, `${effect.name} is a request; its adapter is a source`); return; }
+      job.phase = "list";
+      const list = () => { try { this.deliver(effect, entity, instance, { listed: adapter.listing(args, { ...ctx, now: this.sched.now() }) }); } catch (e) { this.answer(effect, entity, instance, false, e instanceof Error ? e.message : String(e)); } };
+      if (effect.list) { at(0, list); this.relisters.set(instance, () => at(0, list)); }
+      if (adapter.relist !== null && effect.list) { const again = () => at(adapter.relist!, () => { list(); again(); }); again(); }
+      if (effect.watch) { job.phase = "watch"; for (const ev of adapter.events(args, ctx)) at(ev.at, () => { this.lastEvent.set(jobKey(effect, entity), ev.event); this.deliver(effect, entity, instance, { events: [ev.event] }); }); }
+    } catch (e) { this.answer(effect, entity, instance, false, e instanceof Error ? e.message : String(e)); }
+  }
+
+  /**
+   * Drives a source's run: list, then watch, delivering batches; a "changed"
+   * from the watch or from the mirror's landing lists again after a short
+   * quiet; `every` lists again on a schedule. Ends as a request does: done
+   * when the watch ends, failed when anything throws, retried per the effect.
+   */
+  private async drive(job: Job, key: string, ctx: Context, ctl: AbortController): Promise<void> {
+    const { effect, entity, args, instance } = job;
+    const signal = ctl.signal;
+    const deliver = (batch: Batch) => { if (!signal.aborted) this.deliver(effect, entity, instance, batch); };
+    let listing: Promise<void> | null = null;
+    const list = () => {
+      if (!effect.list || signal.aborted) return Promise.resolve();
+      if (!listing) listing = Promise.resolve().then(() => effect.list!(args, ctx)).then((items) => deliver({ listed: items })).finally(() => { listing = null; });
+      return listing;
+    };
+    const timers = new Map<"relist" | "every", Handle>();
+    const stop = (k: "relist" | "every") => { timers.get(k)?.cancel(); timers.delete(k); };
+    const relistSoon = () => { stop("relist"); timers.set("relist", this.sched.at(this.sched.now() + RELIST_MS, () => { timers.delete("relist"); void list().catch(() => {}); })); };
+    this.relisters.set(instance, relistSoon);
+    // `every` on a watched source: list again on a schedule, as long as the run lives.
+    if (effect.every !== null && effect.watch) { const again = () => { timers.set("every", this.sched.at(this.sched.now() + effect.every!, () => { void list().catch(() => {}); again(); })); }; again(); }
+    try {
+      job.phase = "list";
+      await list();
+      if (effect.watch) {
+        job.phase = "watch";
+        let buffer: unknown[] = [];
+        let flushing = false;
+        const flush = () => { flushing = false; if (buffer.length) { const b = buffer; buffer = []; try { deliver({ events: b }); } catch (e) { this.answer(effect, entity, instance, false, String(e)); ctl.abort(); } } };
+        for await (const ev of effect.watch(args, ctx, this.lastEvent.get(key))) {
+          if (signal.aborted) break;
+          this.lastEvent.set(key, ev);
+          const o = ev as { changed?: unknown; resync?: unknown } | null;
+          if (effect.mirror && o && typeof o === "object" && (o.changed === true || o.resync === true)) { relistSoon(); continue; }
+          buffer.push(ev);
+          if (!flushing) { flushing = true; queueMicrotask(flush); }
+        }
+        flush();
+      }
+      if (!signal.aborted) this.answer(effect, entity, instance, true, undefined);
+    } catch (err) {
+      if (!signal.aborted) this.answer(effect, entity, instance, false, err instanceof Error ? err.message : String(err));
+    } finally {
+      this.relisters.delete(instance);
+      stop("relist");
+      stop("every");
+    }
+  }
+
+  /** The earliest due moment, if any, as a timer on the scheduler: a round then. With `auto` off the timer is still set, so a driver that advances a virtual clock gets the round at its moment. */
+  private arm(_now: number): void {
+    if (this.stopped) return;
+    const earliest = this.due();
+    if (earliest === null) return;
+    this.timer = this.sched.at(earliest, () => { this.timer = null; this.step(); });
+  }
+
+  private schedule(): void {
+    if (!this.auto || this.scheduled || this.stopped) return;
+    this.scheduled = true;
+    queueMicrotask(() => { if (this.scheduled) this.step(); });
+  }
+
+  /** A round on the next turn of the event loop, not this one: every message already queued lands in it. */
+  private scheduleSoon(): void {
+    if (!this.auto) return;
+    this.roundSoon();
+  }
+
+  /** A round soon, auto or not: what an adapter's answer asks for, so a simulated state moves when its outside speaks. */
+  private roundSoon(): void {
+    if (this.soon || this.stopped) return;
+    this.soon = this.sched.soon(() => { this.soon = null; this.step(); });
+  }
+}