babavoss 0.0.1 → 0.0.2

package/src/ecs/state.ts

@@ -0,0 +1,759 @@
+// The state of a baba: entities with typed components, resources that exist
+// once, and the jobs the port runs for it. Every declaration belongs to a
+// system, and a system's steps write only what the system declared. Only data:
+// a value is what its schema admits, a reference to another entity is its
+// id. Job results live one round. Pure: no IO. Values are checked at the
+// boundary, where they come from outside the type system; a system's own
+// writes are trusted unless `checking` is on, as it is in a testbed.
+import { SchemaError, type Schema, type Json } from "../kernel/schema.ts";
+import type { Context } from "../kernel/context.ts";
+import { keyField, mapEntities } from "./handles.ts";
+import { Table } from "./table.ts";
+import type { Delta } from "./snapshot.ts";
+
+export type Entity = number;
+
+/**
+ * A component: per entity. An `accept` is an ask: any system may add it to an
+ * entity, and only its owner replaces or removes it. `O` is the owning
+ * system's name, so one system's handle never passes for another's.
+ */
+export interface Component<N extends string = string, T = unknown, O extends string = string> { readonly kind: "component"; readonly name: N; readonly owner: O; readonly schema: Schema<T>; readonly accept: boolean }
+/** An ask, as a system refers to another's: addable by any system that reads its owner. */
+export interface Ask<N extends string = string, T = unknown, O extends string = string> extends Component<N, T, O> { readonly accept: true }
+/** A resource: once per baba, always present. */
+export interface Resource<N extends string = string, T = unknown, O extends string = string> { readonly kind: "resource"; readonly name: N; readonly owner: O; readonly schema: Schema<T>; readonly initial: T }
+/**
+ * An effect: the port. A request's job runs its handler outside the round
+ * once, and the result is visible for one round. A source's job keeps
+ * answering: `list` the slice of the outside as it is, `watch` its changes;
+ * a source with a `mirror` keeps that component of its system, and no system
+ * code writes it; one without lands events a step reads with `w.events`.
+ */
+export interface Effect<N extends string = string, A = unknown, R = unknown, V = unknown, O extends string = string> {
+  readonly kind: "effect";
+  readonly name: N;
+  readonly owner: O;
+  readonly args: Schema<A>;
+  readonly result: Schema<R>;
+  readonly shape: "request" | "source";
+  /** A source's: the component it keeps, that component's entity field the job's entity goes in, the schema of a stream's events. */
+  readonly mirror: string | null;
+  readonly of: string | null;
+  readonly event: Schema<V> | null;
+  list: ((args: any, ctx: Context) => Promise<unknown[]> | unknown[]) | null;
+  watch: ((args: any, ctx: Context, last: any) => AsyncIterable<unknown>) | null;
+  /** Milliseconds before a failed job runs again; null to fail once. */
+  readonly retry: number | null;
+  /** Milliseconds between runs for the system itself; null for an effect only asked for. */
+  readonly every: number | null;
+  /** Safe to run again after a crash: a job that was running when the state was kept starts again; when false it lands as failed, "interrupted", once. */
+  readonly repeat: boolean;
+  readonly summary: string;
+  run(args: A, ctx: Context): Promise<R> | R;
+}
+export type Declaration = Component | Resource | Effect;
+
+export type Value<C> = C extends Component<string, infer T> ? T : C extends Resource<string, infer T> ? T : never;
+export type Args<E> = E extends Effect<string, infer A, any> ? A : never;
+export type Result<E> = E extends Effect<string, any, infer R, any> ? R : never;
+/** What a stream yields, as `w.events` answers it. */
+export type EventOf<E> = E extends Effect<string, any, any, infer V> ? V : unknown;
+
+/** The components a query's rows carry: its component terms, and the components of its `added` and `changed` terms. */
+type Cols<Cs extends readonly Term[]> = Extract<Cs[number], Component> | Extract<Cs[number], Change<Component, "added" | "changed">>["component"];
+/** A query's rows: the entity, then each component's value under its name; a `removed` term's last value under its name too. */
+export type Row<Cs extends readonly Term[]> = Flat<{ entity: Entity } & { [C in Cols<Cs> as C["name"]]: Value<C> } & { [C in Extract<Cs[number], Change<Component, "removed">>["component"] as C["name"]]: Value<C> }>;
+type Flat<T> = { [K in keyof T]: T[K] } & {};
+/** The values `each` hands over, in term order: one per component term and per `added` or `changed` term. */
+export type Values<Cs extends readonly unknown[]> = Cs extends readonly [infer H, ...infer T]
+  ? H extends Component ? [Value<H>, ...Values<T>] : H extends Change<infer C, "added" | "changed"> ? [Value<C>, ...Values<T>] : Values<T>
+  : [];
+
+/** In a query: the entities that have none of these. `w.query(task, not(state, missing))`. */
+export interface Not { readonly kind: "not"; readonly components: readonly Component[] }
+export function not(...components: Component[]): Not { return { kind: "not", components }; }
+/**
+ * In a query: what changed since `w.since`, which the runtime sets to the
+ * moment this system's steps last ran. `added(c)`: entities that gained c;
+ * `changed(c)`: entities whose c was written, gained included; `removed(c)`:
+ * entities that lost c, despawned ones included, with the value they had.
+ */
+export interface Change<C extends Component = Component, How extends "added" | "changed" | "removed" = "added" | "changed" | "removed"> { readonly kind: "changed"; readonly how: How; readonly component: C }
+export function added<C extends Component>(component: C): Change<C, "added"> { return { kind: "changed", how: "added", component }; }
+export function changed<C extends Component>(component: C): Change<C, "changed"> { return { kind: "changed", how: "changed", component }; }
+export function removed<C extends Component>(component: C): Change<C, "removed"> { return { kind: "changed", how: "removed", component }; }
+/** A query's terms: any component of the state, since reads are open to every system, `not(…)`, and the change terms. */
+export type Term = Component | Not | Change;
+
+/**
+ * A query declared once, `select(fish, not(target)).where((r) => r.fish.hunger > 10)`,
+ * or kept in an order with `.by(fish, (a, b) => a.x - b.x)`;
+ * and run with `w.each(q, fn)` or `w.query(q)`: the state keeps its matched
+ * set live from the first run, so a step pays only the predicate. One
+ * with change terms is run like any other.
+ */
+export interface Select<Cs extends readonly Term[] = readonly Term[]> {
+  readonly kind: "select";
+  readonly terms: Cs;
+  readonly pred: ((row: Row<Cs>) => boolean) | null;
+  /** The order its entities are kept in, by one component's value; null for id order. */
+  readonly order: { component: Component; cmp: (a: any, b: any) => number } | null;
+  /** The same select with a predicate over the row. */
+  where(pred: (row: Row<Cs>) => boolean): Select<Cs>;
+  /** The same select kept in the order `cmp` gives the values of `c`, which must be one of its terms. */
+  by<K extends Component>(c: K, cmp: (a: Value<K>, b: Value<K>) => number): Select<Cs>;
+}
+export function select<const Cs extends readonly Term[]>(...terms: Cs): Select<Cs> {
+  const build = (pred: Select<Cs>["pred"], order: Select<Cs>["order"]): Select<Cs> => ({
+    kind: "select", terms, pred, order,
+    where: (p) => build(p, order),
+    by: (c: Component, cmp: (a: unknown, b: unknown) => number) => {
+      if (!terms.some((t) => (t as { kind?: string; name?: string }).kind === "component" && (t as { name: string }).name === c.name)) throw new Error(`select: ${c.name} is not one of its terms`);
+      return build(pred, { component: c, cmp });
+    },
+  }) as Select<Cs>;
+  return build(null, null);
+}
+
+/**
+ * A job: one run of an effect, for an entity or for the system. `attempt`
+ * counts its failures so far, `since` is when it was asked or last failed,
+ * `error` the last failure's message. "interrupted": it was running when the
+ * state was kept and its effect is not safe to repeat; the next round lands
+ * it as failed.
+ */
+export interface Job {
+  effect: Effect; entity: Entity | null; args: unknown; status: "waiting" | "running" | "retrying" | "interrupted"; attempt: number; since: number; error: string | null;
+  /** Which run this is: an answer from an earlier run of the same key is dropped. */
+  instance: number;
+  /** A source's: where it is, how many events it has landed, the round's time of the last. */
+  phase: "list" | "watch" | null; events: number; last: number;
+}
+/** What a mirror's watch may yield: an item of the component's shape, a key gone, or a word that the slice should be listed again. */
+export type MirrorEvent = Record<string, unknown> | { gone: string | number } | { changed: true } | { resync: true };
+export interface Done<E extends Effect = Effect> { entity: Entity | null; args: Args<E>; result: Result<E> }
+export interface Failed<E extends Effect = Effect> { entity: Entity | null; args: Args<E>; error: string }
+
+/** How a job last ended for an entity, or for a system's own job of an effect: `at` is the round's time it landed. */
+export interface Settlement { effect: string; ok: boolean; error: string | null; at: number }
+
+/**
+ * The whole state as JSON: the round, the resources, every entity, the jobs.
+ * `next` is the entity counter, so an id is never reused; `settled` each
+ * entity's last settlement by its id, a system's own jobs' by "system:<effect>";
+ * `keys` the answers remembered by idempotency key. Those three, and a job's
+ * attempt, since and error, are absent from snapshots kept before they existed.
+ */
+export interface Snapshot {
+  round: number;
+  resources: Record<string, unknown>;
+  entities: Record<string, Record<string, unknown>>;
+  jobs: { effect: string; entity: Entity | null; args: unknown; status: Job["status"]; attempt?: number; since?: number; error?: string | null; shape?: "request" | "source"; phase?: Job["phase"]; events?: number; last?: number }[];
+  next?: number;
+  settled?: Record<string, Settlement>;
+  keys?: Record<string, Remembered>;
+  /** Which system made each entity, for those a system made: the one that may despawn it whatever it carries. */
+  made?: Record<string, string>;
+  /** The round's time, as `w.now` had it: when this state is from. */
+  now?: number;
+  /** The state of `w.random()`, so a kept state draws on as it would have. */
+  rng?: number;
+}
+
+/** An action's answer, remembered under its idempotency key, with the round's time it ran. */
+export interface Remembered { value: unknown; at: number }
+
+/** How long, and how many, idempotency keys are remembered. */
+export const KEY_TTL_MS = 24 * 60 * 60 * 1000;
+export const KEY_LIMIT = 1000;
+
+/** What a baba declared, by kind, in system order. */
+export interface Model { components: Component[]; resources: Resource[]; effects: Effect[] }
+
+/** How many rounds back a delta can be measured from; a follower further behind gets the whole. */
+export const DELTA_WINDOW = 256;
+
+export class StateError extends Error {
+  constructor(readonly code: "entity" | "value" | "name" | "owner", msg: string) { super(msg); }
+}
+
+export const jobKey = (effect: Effect, entity: Entity | null) => `${effect.name}#${entity ?? ""}`;
+/** Where a settlement is kept: the entity's id, or "system:<effect>" for a system's own job. */
+export const settledKey = (effect: Effect | string, entity: Entity | null) => entity === null ? `system:${typeof effect === "string" ? effect : effect.name}` : String(entity);
+
+/** The references of a system, or of every system of a baba, as the union of their values. */
+type RefsOf<X> = X extends { kind: "baba"; systems: infer Cs extends readonly unknown[] } ? Cs[number] : X;
+type ValuesOf<T> = T extends unknown ? T[keyof T] : never;
+/** The components, resources and effects of a system or baba `X`, from its references; any of them for an untyped state. */
+export type Comps<X> = unknown extends X ? Component : Extract<ValuesOf<RefsOf<X>>, Component>;
+export type Ress<X> = unknown extends X ? Resource : Extract<ValuesOf<RefsOf<X>>, Resource>;
+export type Effs<X> = unknown extends X ? Effect : Extract<ValuesOf<RefsOf<X>>, Effect>;
+
+/**
+ * The state as a step sees it, typed by the system or baba `X` it belongs
+ * to. `writer` is the system whose code is running; null is the runtime
+ * itself, which may write anything. Checked at runtime for every caller.
+ */
+export class State<X = any> {
+  /** The round's time, milliseconds since the epoch; set by the runtime before each round. */
+  now = 0;
+  /** Milliseconds since the previous round's time; 0 in the first. */
+  elapsed = 0;
+  /** The round running, or the last run. */
+  round = 0;
+  /** What change terms measure from: the moment this system's steps last ran, as the runtime sets it; 0 is ever. */
+  since = 0;
+  /** The system writing now, or null for the runtime and the shell. */
+  writer: string | null = null;
+  /** Every write checked against its schema, as a testbed wants; off, the system's code is trusted and only the boundary checks. */
+  checking = false;
+  /** The runtime's, while a source keeps its mirror: the one way a mirrored component is written. */
+  sourcing = false;
+  private readonly mirrored = new Map<string, Effect>();
+  /** The system that made each entity, when a system did. */
+  private made = new Map<Entity, string>();
+  private instances = 0;
+  private rng = 1;
+  /** The events landed this round, by effect name: what `w.events` answers. */
+  private landed = new Map<string, { entity: Entity | null; event: unknown }[]>();
+  private next: Entity = 1;
+  private readonly table: Table;
+  private values = new Map<Resource, unknown>();
+  private rtick = new Map<Resource, number>();
+  private byName = new Map<string, Declaration>();
+  private lastNow: number | null = null;
+  /** The sequence at the end of each recent round, for deltas. */
+  private ends = new Map<number, number>();
+  /** When the jobs, the settlements and the remembered answers last changed, as seen at a round's end: a delta carries each only when it did. */
+  private jobsTick = 0; private settledTick = 0; private keysTick = 0;
+  private jobsText = "[]";
+  readonly jobs = new Map<string, Job>();
+  private settledDone: Done[] = [];
+  private settledFailed: Failed[] = [];
+  private effectOf = new WeakMap<object, string>();
+  /** The jobs answered this round: asking for one again, this round, is nothing, whatever the order of steps. */
+  private answered = new Set<string>();
+  /** Each entity's last settlement, and each system job's under "system:<effect>". */
+  private settledLast = new Map<string, Settlement>();
+  /** Answers remembered by idempotency key, oldest first. */
+  private keys = new Map<string, Remembered>();
+  /** The undo list of the transaction open, if any. */
+  private journal: (() => void)[] | null = null;
+
+  constructor(readonly model: Model = { components: [], resources: [], effects: [] }) {
+    for (const d of [...model.components, ...model.resources, ...model.effects]) {
+      if (this.byName.has(d.name)) throw new StateError("name", `two declarations are named ${d.name}`);
+      this.byName.set(d.name, d);
+    }
+    this.table = new Table((name) => {
+      const c = this.byName.get(name);
+      const field = c?.kind === "component" ? keyField(c.schema.json) : null;
+      return field === null ? null : field === "" ? (v) => v : (v) => (v as Record<string, unknown>)[field];
+    });
+    for (const c of model.components) this.table.register(c.name);
+    for (const r of model.resources) this.values.set(r, r.schema.check(r.initial, r.name));
+    for (const e of model.effects) if (e.mirror) this.mirrored.set(e.mirror, e);
+  }
+
+  /** The source that keeps `c`, if one does. */
+  sourceOf(c: Component): Effect | undefined { return this.mirrored.get(c.name); }
+
+  /** The declaration of a name, if any. */
+  declaration(name: string): Declaration | undefined { return this.byName.get(name); }
+
+  private declared(d: Declaration): void {
+    if (this.byName.get(d.name) !== d) throw new StateError("name", `${d.kind} ${d.name} is not one of this state's`);
+  }
+
+  private owned(d: Declaration): void {
+    this.declared(d);
+    if (this.writer !== null && d.owner !== this.writer) throw new StateError("owner", `${d.kind} ${d.name} belongs to ${d.owner}; ${this.writer} may read it, not write it`);
+    this.kept(d);
+  }
+
+  /** The part of `owned` that holds for the owner too: a mirrored component is the source's. */
+  private kept(d: Declaration): void {
+    if (this.writer !== null && !this.sourcing && d.kind === "component" && this.mirrored.has(d.name)) throw new StateError("owner", `component ${d.name} is kept by the source ${this.mirrored.get(d.name)!.name}; ${this.writer} reads it, the outside writes it`);
+  }
+
+  /**
+   * Runs `fn` all-or-nothing: if it throws, every spawn, add, remove,
+   * despawn, set, run and cancel it made is undone, in reverse, and the
+   * error rethrown. A transaction inside another joins it.
+   */
+  transaction<T>(fn: () => T): T {
+    if (this.journal) return fn();
+    const undo: (() => void)[] = [];
+    this.journal = undo;
+    try { return fn(); } catch (err) {
+      this.journal = null;
+      for (let i = undo.length - 1; i >= 0; i--) undo[i]!();
+      throw err;
+    } finally { this.journal = null; }
+  }
+
+  private undo(f: () => void): void { this.journal?.push(f); }
+
+  // ---- entities and components ----------------------------------------
+
+  spawn(): Entity;
+  spawn<K extends Comps<X> | Ask>(c: K, value: Value<K>): Entity;
+  spawn(c?: Component, value?: unknown): Entity {
+    const e = this.next++;
+    this.table.spawn(e);
+    if (this.writer !== null) this.made.set(e, this.writer);
+    this.undo(() => { this.table.despawn(e); this.table.gone.delete(e); this.made.delete(e); this.next = e; });
+    if (c) this.add(e, c as never, value as never);
+    return e;
+  }
+
+  /** The system that made `e`, if a system did. */
+  maker(e: Entity): string | undefined { return this.made.get(e); }
+
+  /** A number in [0, 1) from the state's own generator: the same state, the same draws, so a round can be reproduced. Seed it with `seed()`. */
+  random(): number {
+    let x = this.rng >>> 0 || 1;
+    x ^= x << 13; x >>>= 0; x ^= x >>> 17; x ^= x << 5; x >>>= 0;
+    this.rng = x;
+    return x / 4294967296;
+  }
+  /** Seeds `random()`; the runtime seeds a fresh state from its clock, a testbed from 1. */
+  seed(n: number): void { this.rng = (n >>> 0) || 1; }
+
+  alive(e: Entity): boolean { return this.table.exists(e); }
+
+  /**
+   * Removes the entity, everything on it, and cancels its jobs. The system
+   * that made the entity despawns it whatever it carries: the asks it put
+   * there and the answers they drew go with it. Another system despawns only
+   * an entity carrying nothing but its own.
+   */
+  despawn(e: Entity): void {
+    this.exists(e);
+    const parts = this.table.partsOf(e);
+    if (this.writer !== null) for (const n of Object.keys(parts)) {
+      const c = this.byName.get(n)!;
+      if (!this.sourcing && this.mirrored.has(n)) throw new StateError("owner", `entity ${e} carries ${n}, kept by the source ${this.mirrored.get(n)!.name}; ${this.writer} may not despawn it`);
+      if (c.owner !== this.writer && this.made.get(e) !== this.writer) throw new StateError("owner", `entity ${e} carries ${n} of ${c.owner}; ${this.writer} did not make it and may not despawn it`);
+    }
+    const maker = this.made.get(e);
+    this.made.delete(e);
+    this.undo(() => { if (maker !== undefined) this.made.set(e, maker); });
+    const jobs = [...this.jobs].filter(([, j]) => j.entity === e);
+    const settled = this.settledLast.get(String(e));
+    this.table.despawn(e);
+    for (const [k] of jobs) this.jobs.delete(k);
+    if (this.settledLast.delete(String(e))) this.settledTick = ++this.table.seq;
+    this.undo(() => {
+      this.table.spawn(e);
+      for (const [n, v] of Object.entries(parts)) this.table.put(e, n, v);
+      for (const [k, j] of jobs) this.jobs.set(k, j);
+      if (settled) this.settledLast.set(String(e), settled);
+    });
+  }
+
+  /** Attaches or replaces `c` on `e`; a tag needs no value. Checked against its schema when `checking`. */
+  add<K extends (Comps<X> | Ask) & Component<string, true>>(e: Entity, c: K): void;
+  add<K extends Comps<X> | Ask>(e: Entity, c: K, value: Value<K>): void;
+  add(e: Entity, c: Component, value: unknown = true): void {
+    this.exists(e);
+    // An ask is anyone's to add once; replacing it is the owner's.
+    if (c.accept && this.writer !== null && c.owner !== this.writer) { this.declared(c); if (this.table.hasPart(e, c.name)) throw new StateError("owner", `entity ${e} already asks ${c.name}; an ask is not changed, the owner ${c.owner} answers it`); }
+    else this.owned(c);
+    this.put(e, c, this.checking ? this.check(c, value) : value);
+  }
+
+  /** A value checked against a declaration's schema, as the boundary does. */
+  check(d: Component | Resource, value: unknown): unknown {
+    try { return d.schema.check(value, d.name); } catch (err) { throw new StateError("value", err instanceof SchemaError ? err.message : String(err)); }
+  }
+
+  private put(e: Entity, c: Component, value: unknown): void {
+    const r = this.table.put(e, c.name, value);
+    if (this.journal) this.undo(() => { if (r.had) this.table.restore(e, c.name, r.was, r.tick, r.arrived); else this.table.remove(e, c.name); });
+  }
+
+  /** `c` on `e` replaced by what `fn` makes of it: a new value, never a change to the one stored. */
+  update<K extends Comps<X>>(e: Entity, c: K, fn: (value: Value<K>) => Value<K>): void;
+  update<K extends Ress<X>>(r: K, fn: (value: Value<K>) => Value<K>): void;
+  update(a: Entity | Resource, b: Component | ((v: never) => unknown), fn?: (v: never) => unknown): void {
+    if (typeof a === "number") {
+      const c = b as Component;
+      const v = this.get(a, c);
+      if (v === undefined) throw new StateError("entity", `entity ${a} has no ${c.name}`);
+      this.add(a, c as never, fn!(v as never) as never);
+    } else this.set(a as never, (b as (v: never) => unknown)(this.get(a) as never) as never);
+  }
+
+  get<K extends Component>(e: Entity, c: K): Value<K> | undefined;
+  get<K extends Resource>(r: K): Value<K>;
+  get(a: Entity | Resource, c?: Component): unknown {
+    if (typeof a === "number") return this.table.get(a, c!.name);
+    this.declared(a);
+    return this.values.get(a);
+  }
+
+  set<K extends Ress<X>>(r: K, value: Value<K>): void {
+    this.owned(r);
+    const was = this.values.get(r), tick = this.rtick.get(r) ?? 0;
+    this.values.set(r, this.checking ? this.check(r, value) : value);
+    this.rtick.set(r, ++this.table.seq);
+    this.undo(() => { this.values.set(r, was); this.rtick.set(r, tick); });
+  }
+
+  has(e: Entity, c: Component): boolean { return this.table.hasPart(e, c.name); }
+
+  remove(e: Entity, ...cs: Comps<X>[]): void {
+    this.exists(e);
+    for (const c of cs) {
+      this.owned(c);
+      const r = this.table.remove(e, c.name);
+      if (r.had && this.journal) this.undo(() => this.table.restore(e, c.name, r.was, r.tick, r.arrived));
+    }
+  }
+
+  /** The entity whose `c` has the key field equal to `key`, if any. */
+  find<K extends Comps<X>>(c: K, key: string | number): Entity | undefined {
+    this.declared(c);
+    if (keyField(c.schema.json) === null) throw new StateError("name", `component ${c.name} has no key field`);
+    return this.table.find(c.name, key);
+  }
+
+  /** Every entity matching the terms, in spawn order, each row keyed by component name. */
+  query<const Cs extends readonly Term[]>(...terms: Cs): Row<Cs>[];
+  query<Cs extends readonly Term[]>(sel: Select<Cs>): Row<Cs>[];
+  query(...terms: unknown[]): unknown[] {
+    const t = terms[0];
+    if (isSel(t)) { this.table.keep(t as never); return this.table.query(t as never, this.since); }
+    return this.table.query(terms as Term[], this.since);
+  }
+
+  /** Visits every entity matching the terms, in spawn order, with its values in term order; no rows are made. */
+  each<const Cs extends readonly Term[]>(terms: Cs, fn: (e: Entity, ...values: Values<Cs>) => void): void;
+  each<Cs extends readonly Term[]>(sel: Select<Cs>, fn: (e: Entity, ...values: Values<Cs>) => void): void;
+  each(terms: unknown, fn: (e: Entity, ...values: never[]) => void): void {
+    if (isSel(terms)) { this.table.keep(terms as never); this.table.each(terms as never, this.since, (e, v) => fn(e, ...(v as never[]))); return; }
+    this.table.each(terms as Term[], this.since, (e, v) => fn(e, ...(v as never[])));
+  }
+
+  /** How many entities have `c`. */
+  count(c: Component): number { return this.table.countOf(c.name); }
+  /** The entities that have `c`, in id order. */
+  idsOf(c: Component): Entity[] { return this.table.idsOf(c.name); }
+
+  /** Every component on `e`, by name. */
+  of(e: Entity): Record<string, unknown> { this.exists(e); return this.table.partsOf(e); }
+
+  /** Every entity, in order. */
+  all(): Entity[] { return this.table.all(); }
+
+  // ---- jobs --------------------------------------------------------------
+
+  /** Asks for a run of `effect`, for `entity` or for the system. Asking while one runs, or in the round its answer landed, is nothing. */
+  run<K extends Effs<X>>(effect: K, args?: Args<K>, entity?: Entity): void {
+    this.owned(effect);
+    if (entity !== undefined && !this.table.exists(entity)) throw new StateError("entity", `no entity ${entity}`);
+    const key = jobKey(effect, entity ?? null);
+    if (this.jobs.has(key) || this.answered.has(key)) return;
+    let checked: unknown;
+    try { checked = effect.args.check(args ?? {}, effect.name); } catch (err) { throw new StateError("value", err instanceof SchemaError ? err.message : String(err)); }
+    this.jobs.set(key, { effect, entity: entity ?? null, args: checked, status: "waiting", attempt: 0, since: this.now, error: null, instance: ++this.instances, phase: null, events: 0, last: 0 });
+    this.undo(() => this.jobs.delete(key));
+  }
+
+  /** What `effect`'s sources landed this round, in order: for a step to read. A mirror's events too, after they were kept. */
+  events<E extends Effect>(effect: E): { entity: Entity | null; event: EventOf<E> }[] {
+    this.declared(effect);
+    return (this.landed.get(effect.name) ?? []) as never;
+  }
+
+  /**
+   * The runtime's: a source's batch lands as the owner. A listing keeps the
+   * mirror as the slice says: every item put by its key, with the job's
+   * entity in `of`, unchanged values left alone, rows the listing did not
+   * name taken away; events put, take away, or ask to list again. Items the
+   * schema refuses are dropped and told. Answers whether to list again.
+   */
+  land(effect: Effect, entity: Entity | null, batch: { listed: unknown[] } | { events: unknown[] }, dropped: (what: string) => void): { relist: boolean } {
+    const c = effect.mirror ? this.byName.get(effect.mirror) as Component : null;
+    const events = "listed" in batch ? batch.listed : batch.events;
+    if (!this.landed.has(effect.name)) this.landed.set(effect.name, []);
+    const seen = this.landed.get(effect.name)!;
+    for (const event of events) seen.push({ entity, event });
+    if (!c) {
+      if (effect.event) for (const [i, ev] of events.entries()) { try { effect.event.check(ev, effect.name); } catch (err) { dropped(`${effect.name}: event ${i}: ${err instanceof Error ? err.message : String(err)}`); seen.splice(seen.findIndex((s) => s.event === ev), 1); } }
+      return { relist: false };
+    }
+    const field = keyField(c.schema.json)!;
+    const keyOf = (v: unknown) => field === "" ? v : (v as Record<string, unknown>)[field];
+    if (entity !== null && !effect.of) { dropped(`${effect.name}: a mirror kept for an entity needs an entity field on ${c.name} for the job's entity`); return { relist: false }; }
+    const was = this.sourcing; this.sourcing = true;
+    let relist = false;
+    try {
+      const touched = new Set<Entity>();
+      const put = (item: unknown) => {
+        const value = effect.of && typeof item === "object" && item !== null ? { ...(item as Record<string, unknown>), [effect.of]: entity } : item;
+        let checked: unknown;
+        try { checked = c.schema.check(value, c.name); } catch (err) { dropped(`${effect.name}: ${err instanceof Error ? err.message : String(err)}`); return; }
+        const key = keyOf(checked);
+        let e = this.table.find(c.name, key as never);
+        if (e === undefined) { e = this.spawn(); this.add(e, c as never, checked as never); }
+        else if (JSON.stringify(this.get(e, c)) !== JSON.stringify(checked)) this.add(e, c as never, checked as never);
+        touched.add(e);
+      };
+      const take = (e: Entity) => { this.remove(e, c as never); if (Object.keys(this.table.partsOf(e)).length === 0) this.despawn(e); };
+      if ("listed" in batch) {
+        for (const item of batch.listed) put(item);
+        const mine = this.query(c).filter((r) => !touched.has(r.entity) && (effect.of ? (r as Record<string, Record<string, unknown>>)[c.name]![effect.of] === entity : true));
+        for (const r of mine) take(r.entity);
+      } else {
+        for (const ev of batch.events) {
+          if (typeof ev !== "object" || ev === null) { dropped(`${effect.name}: an event that is not an object`); continue; }
+          const o = ev as Record<string, unknown>;
+          if (o.changed === true || o.resync === true) { relist = true; continue; }
+          if ("gone" in o && Object.keys(o).length === 1) { const e = this.table.find(c.name, o.gone as never); if (e !== undefined) take(e); continue; }
+          put(o);
+        }
+      }
+    } finally { this.sourcing = was; }
+    return { relist };
+  }
+
+  running(effect: Effect, entity?: Entity): boolean { return this.jobs.has(jobKey(effect, entity ?? null)); }
+
+  cancel(effect: Effs<X>, entity?: Entity): void {
+    this.owned(effect);
+    const key = jobKey(effect, entity ?? null);
+    const job = this.jobs.get(key);
+    if (!job) return;
+    this.jobs.delete(key);
+    this.undo(() => this.jobs.set(key, job));
+  }
+
+  /** How the last job for `entity` ended, or the system's own last job of `effect`; kept until the next one lands, dropped with the entity. */
+  settlement(of: Entity | Effect): Settlement | undefined {
+    return this.settledLast.get(typeof of === "number" ? String(of) : settledKey(of, null));
+  }
+
+  /** What `effect` answered since the last round: for this round only. */
+  done<K extends Effect>(effect: K): Done<K>[] { return this.settledDone.filter((d) => this.effectOf.get(d) === effect.name) as Done<K>[]; }
+  failed<K extends Effect>(effect: K): Failed<K>[] { return this.settledFailed.filter((d) => this.effectOf.get(d) === effect.name) as Failed<K>[]; }
+
+  /** The runtime's: a job's answer, applied before a round. A late answer to a gone entity or a cancelled job is dropped. `retry` false lands a failure once, whatever the effect says. */
+  settle(effect: Effect, entity: Entity | null, ok: boolean, value: unknown, retry = true): "kept" | "dropped" | "retry" {
+    const key = jobKey(effect, entity);
+    const job = this.jobs.get(key);
+    if (!job || (entity !== null && !this.table.exists(entity))) return "dropped";
+    if (ok) {
+      let checked: unknown;
+      try { checked = effect.result.check(value, effect.name); } catch (err) { ok = false; value = `${effect.name} returned a bad result: ${err instanceof Error ? err.message : String(err)}`; }
+      if (ok) {
+        this.jobs.delete(key);
+        this.answered.add(key);
+        const d: Done = { entity, args: job.args, result: checked };
+        this.effectOf.set(d, effect.name);
+        this.settledDone.push(d);
+        this.settledLast.set(settledKey(effect, entity), { effect: effect.name, ok: true, error: null, at: this.now });
+        this.settledTick = ++this.table.seq;
+        return "kept";
+      }
+    }
+    const f: Failed = { entity, args: job.args, error: String(value) };
+    this.effectOf.set(f, effect.name);
+    this.settledFailed.push(f);
+    this.settledLast.set(settledKey(effect, entity), { effect: effect.name, ok: false, error: f.error, at: this.now });
+    this.settledTick = ++this.table.seq;
+    job.error = f.error;
+    if (effect.retry === null || !retry) { this.jobs.delete(key); this.answered.add(key); return "kept"; }
+    job.status = "retrying";
+    job.attempt++;
+    job.since = this.now;
+    return "retry";
+  }
+
+  /** The runtime's: round `round` begins at `now`; the last round's answers are gone. */
+  begin(now: number, round = this.round + 1): void {
+    this.elapsed = this.lastNow === null ? 0 : Math.max(0, now - this.lastNow);
+    this.lastNow = now;
+    this.now = now;
+    this.round = round;
+    this.settledDone = [];
+    this.settledFailed = [];
+    this.landed.clear();
+    this.answered.clear();
+    for (const [k, r] of this.keys) if (r.at < now - KEY_TTL_MS) { this.keys.delete(k); this.keysTick = ++this.table.seq; }
+    const old = round - DELTA_WINDOW;
+    const at = this.ends.get(old);
+    for (const r of this.ends.keys()) if (r < old) this.ends.delete(r);
+    if (at !== undefined) this.table.prune(at);
+  }
+
+  /**
+   * The runtime's, at the round's end: every value written since `since`
+   * checked against its schema, so the state holds only what the model
+   * admits whatever a trusted write did. A component that fails is dropped,
+   * which the next round sees as a removal; a resource that fails returns
+   * to its initial value. Each is told through `dropped`. Costs what
+   * changed, not what exists.
+   */
+  audit(since: number, dropped: (what: string) => void): void {
+    for (const [e, name, v] of this.table.changedParts(since)) {
+      const c = this.byName.get(name) as Component;
+      try { c.schema.check(v, name); } catch (err) {
+        this.table.remove(e, name);
+        dropped(`entity ${e}: ${err instanceof SchemaError ? err.message : String(err)}; ${name} dropped`);
+      }
+    }
+    for (const [r, tick] of this.rtick) {
+      if (tick <= since) continue;
+      try { r.schema.check(this.values.get(r), r.name); } catch (err) {
+        this.values.set(r, r.schema.check(r.initial, r.name));
+        this.rtick.set(r, ++this.table.seq);
+        dropped(`resource ${r.name}: ${err instanceof SchemaError ? err.message : String(err)}; its initial value stands`);
+      }
+    }
+  }
+
+  /** The runtime's: the round is over; what a delta since it measures from is remembered, and whether the jobs, settlements and keys moved. */
+  end(): void {
+    const jobs = JSON.stringify(this.jobsOf());
+    if (jobs !== this.jobsText) { this.jobsText = jobs; this.jobsTick = ++this.table.seq; }
+    this.ends.set(this.round, this.table.seq);
+  }
+
+  /** The sequence now: what `since` is set to for a system whose steps just ran. */
+  get seq(): number { return this.table.seq; }
+
+  /**
+   * What changed since round `since` ended, or null when that is too long
+   * ago or never, so the whole is sent instead: per entity the components
+   * written and the ones taken away, the resources written, and the jobs,
+   * settlements and remembered answers each only when it moved. Since the
+   * round that just ended, it is empty.
+   */
+  delta(since: number): Delta | null {
+    const from = this.ends.get(since);
+    if (from === undefined) return null;
+    const { patches, gone, added } = this.table.changes(from);
+    const entities: Delta["entities"] = {};
+    const made: Record<string, string> = {};
+    for (const [e, patch] of patches) { entities[String(e)] = patch; const c = this.made.get(e); if (c !== undefined) made[String(e)] = c; }
+    for (const e of gone) entities[String(e)] = null;
+    const resources: Record<string, unknown> = {};
+    for (const [r, v] of this.values) if ((this.rtick.get(r) ?? 0) > from) resources[r.name] = v;
+    const d: Delta = { kind: "delta", round: this.round, since, entities, resources, next: this.next, made, now: this.now, rng: this.rng };
+    if (added.size) d.added = Object.fromEntries([...added].map(([e, names]) => [String(e), names]));
+    if (this.jobsTick > from) d.jobs = this.jobsOf();
+    if (this.settledTick > from) d.settled = Object.fromEntries(this.settledLast);
+    if (this.keysTick > from) d.keys = Object.fromEntries(this.keys);
+    return d;
+  }
+
+  private jobsOf(): Snapshot["jobs"] {
+    return [...this.jobs.values()].map((j) => ({ effect: j.effect.name, entity: j.entity, args: j.args, status: j.status, attempt: j.attempt, since: j.since, error: j.error, ...(j.effect.shape === "source" ? { shape: "source" as const, phase: j.phase, events: j.events, last: j.last } : {}) }));
+  }
+
+  // ---- idempotency keys ----------------------------------------------------
+
+  /** The answer remembered under `key`, if any. */
+  recall(key: string): Remembered | undefined { return this.keys.get(key); }
+
+  /** Remembers `value` under `key` at the round's time; the oldest go past KEY_LIMIT. */
+  remember(key: string, value: unknown): void {
+    this.keys.delete(key);
+    this.keys.set(key, { value, at: this.now });
+    this.keysTick = ++this.table.seq;
+    for (const k of this.keys.keys()) { if (this.keys.size <= KEY_LIMIT) break; this.keys.delete(k); }
+  }
+
+  /** The jobs that were running when the state was kept, of effects not safe to repeat: the runtime lands each as failed. */
+  interrupted(): Job[] { return [...this.jobs.values()].filter((j) => j.status === "interrupted"); }
+
+  snapshot(): Snapshot {
+    const entities: Snapshot["entities"] = {};
+    for (const e of this.table.all()) entities[String(e)] = this.table.partsOf(e);
+    const resources: Record<string, unknown> = {};
+    for (const [r, v] of this.values) resources[r.name] = v;
+    return {
+      round: this.round, resources, entities,
+      jobs: this.jobsOf(),
+      next: this.next,
+      settled: Object.fromEntries(this.settledLast),
+      keys: Object.fromEntries(this.keys),
+      made: Object.fromEntries([...this.made].map(([e, c]) => [String(e), c])),
+      now: this.now,
+      rng: this.rng,
+    };
+  }
+
+  /**
+   * A state from a snapshot, fitted to the model: what the model no longer
+   * declares, or a value its schema no longer admits, is dropped and told
+   * through `dropped`, never refused, so the state never holds the code
+   * back. An entity left with nothing stays only while a kept value still
+   * points at it. A value dropped shows to `removed(c)` in the first round,
+   * as a write would. Jobs come back waiting, to run again, keeping their
+   * attempt and last error; a job that was running, of an effect not safe
+   * to repeat, comes back interrupted instead.
+   */
+  static restore(snap: Snapshot, model: Model, dropped: (what: string) => void = () => {}): State {
+    const w = new State(model);
+    w.round = snap.round ?? 0;
+    for (const [name, v] of Object.entries(snap.resources ?? {})) {
+      const r = w.byName.get(name);
+      if (!r || r.kind !== "resource") { dropped(`resource ${name}: no longer declared`); continue; }
+      try { w.set(r as never, w.check(r, v) as never); } catch (err) { dropped(`resource ${name}: ${err instanceof Error ? err.message : String(err)}; its initial value stands`); }
+    }
+    const ids = Object.keys(snap.entities ?? {}).map(Number).filter((e) => Number.isInteger(e) && e >= 1).sort((a, b) => a - b);
+    const kept = new Map<Entity, [Component, unknown][]>();
+    for (const e of ids) {
+      const parts: [Component, unknown][] = [];
+      for (const [name, v] of Object.entries(snap.entities[String(e)]!)) {
+        const c = w.byName.get(name);
+        if (!c || c.kind !== "component") { dropped(`entity ${e}: ${name} is no longer declared`); continue; }
+        try { parts.push([c, w.check(c, v)]); } catch (err) { dropped(`entity ${e}: ${err instanceof Error ? err.message : String(err)}`); w.table.forget(e, c.name, v); }
+      }
+      kept.set(e, parts);
+    }
+    // What a kept value points at: those entities stay even when nothing is left on them.
+    const referenced = new Set<Entity>();
+    const note = (json: Json, v: unknown) => { mapEntities(json, v, (_, id) => { if (typeof id === "number") referenced.add(id); return id; }); };
+    for (const parts of kept.values()) for (const [c, v] of parts) note(c.schema.json, v);
+    for (const [r, v] of w.values) note(r.schema.json, v);
+    for (const [e, parts] of kept) {
+      if (parts.length === 0 && !referenced.has(e)) { if (Object.keys(snap.entities[String(e)]!).length) dropped(`entity ${e}: nothing left on it and nothing points at it`); continue; }
+      w.table.spawn(e);
+      for (const [c, v] of parts) w.put(e, c, v);
+    }
+    // The counter as kept; a snapshot from before it was kept falls back to past the highest id.
+    w.next = Math.max(...ids.map((e) => e + 1), Number.isInteger(snap.next) ? snap.next! : 1, 1);
+    for (const j of snap.jobs ?? []) {
+      const eff = w.byName.get(j.effect);
+      if (!eff || eff.kind !== "effect") { dropped(`job of ${j.effect}: no longer declared`); continue; }
+      if (j.entity !== null && !w.table.exists(j.entity)) continue;
+      let args: unknown;
+      try { args = eff.args.check(j.args, eff.name); } catch (err) { dropped(`job of ${j.effect}: ${err instanceof Error ? err.message : String(err)}`); continue; }
+      const interrupted = j.status === "interrupted" || (j.status === "running" && !eff.repeat);
+      w.jobs.set(jobKey(eff, j.entity), { effect: eff, entity: j.entity, args, status: interrupted ? "interrupted" : "waiting", attempt: j.attempt ?? 0, since: j.since ?? 0, error: j.error ?? null, instance: ++w.instances, phase: null, events: j.events ?? 0, last: j.last ?? 0 });
+    }
+    for (const [k, s] of Object.entries(snap.settled ?? {})) {
+      if (w.byName.get(s.effect)?.kind !== "effect") { dropped(`settlement of ${s.effect}: no longer declared`); continue; }
+      // "cell:<effect>" is how a state kept before systems were named so keyed a system's own job.
+      if (k.startsWith("system:") || k.startsWith("cell:")) w.settledLast.set(settledKey(s.effect, null), s);
+      else if (w.table.exists(Number(k))) w.settledLast.set(k, s);
+    }
+    for (const [k, r] of Object.entries(snap.keys ?? {}).sort((a, b) => a[1].at - b[1].at)) w.keys.set(k, r);
+    for (const [id, c] of Object.entries(snap.made ?? {})) if (w.table.exists(Number(id)) && w.byName.size) w.made.set(Number(id), c);
+    if (typeof snap.rng === "number") w.rng = snap.rng >>> 0 || 1;
+    return w;
+  }
+
+  private exists(e: Entity): void {
+    if (!this.table.exists(e)) throw new StateError("entity", `no entity ${e}`);
+  }
+}
+
+const isSel = (x: unknown): x is Select => typeof x === "object" && x !== null && (x as { kind?: unknown }).kind === "select";
+
+export type { Schema, Json };