babavoss 0.0.1 → 0.0.2

package/src/ecs/codec.ts

@@ -0,0 +1,334 @@
+// A frame: a round's state as bytes, for the wire between the runtime and a
+// window. Values are laid out by their schema, which both ends hold, so a
+// number is eight bytes, an integer a varint, a tag nothing; what the schema
+// cannot type travels as JSON text inside. Component and resource ids are
+// their positions in the model, the same order the manifest lists them in.
+// Pure, browser-safe.
+import type { Json } from "../kernel/schema.ts";
+import type { Snapshot } from "./state.ts";
+import { isDelta, PRESENT, type Delta, type StateAnswer } from "./snapshot.ts";
+import type { Interest, Declared } from "../server/protocol.ts";
+export type { Declared };
+
+/** The table both ends agree on: names in id order, with the schema each value is laid out by. */
+export interface Codec {
+  components: Declared[];
+  resources: Declared[];
+  componentId: Map<string, number>;
+  resourceId: Map<string, number>;
+}
+
+export function codecOf(components: Declared[], resources: Declared[]): Codec {
+  return { components, resources, componentId: new Map(components.map((c, i) => [c.name, i])), resourceId: new Map(resources.map((r, i) => [r.name, i])) };
+}
+
+export const FRAME_VERSION = 2;
+const MAGIC = 0x42;
+const WHOLE = 1, DELTA = 2;
+/** A part's tag: how its value follows. TYPED and TEXT are followed by the payload's byte length, so a reader can skip without a schema. The NEW bit says the part arrived since: what a follower of presence alone takes. */
+const REMOVED = 0, TYPED = 1, TEXT = 2, HELD = 3;
+const NEW = 8, KIND = 7;
+/** The blocks a state carries beside its entities and resources, as JSON text, each when present. */
+const BLOCKS = ["jobs", "next", "settled", "keys", "made"] as const;
+
+const utf8 = new TextEncoder();
+const utf8d = new TextDecoder();
+
+class Writer {
+  private buf = new Uint8Array(1024);
+  private view = new DataView(this.buf.buffer);
+  at = 0;
+  private room(n: number): void {
+    if (this.at + n <= this.buf.length) return;
+    let size = this.buf.length * 2;
+    while (size < this.at + n) size *= 2;
+    const next = new Uint8Array(size);
+    next.set(this.buf);
+    this.buf = next; this.view = new DataView(next.buffer);
+  }
+  u8(n: number): void { this.room(1); this.buf[this.at++] = n; }
+  /** An unsigned integer up to 2^53, seven bits at a time. */
+  varint(n: number): void { while (n >= 128) { this.u8((n % 128) | 128); n = Math.floor(n / 128); } this.u8(n); }
+  /** A signed integer, zigzagged. */
+  int(n: number): void { this.varint(n >= 0 ? n * 2 : -n * 2 - 1); }
+  f64(n: number): void { this.room(8); this.view.setFloat64(this.at, n, true); this.at += 8; }
+  str(s: string): void { const b = utf8.encode(s); this.varint(b.length); this.raw(b); }
+  bytes(): Uint8Array { return this.buf.slice(0, this.at); }
+  /** Writes what `fn` writes behind its byte length. */
+  withLength(fn: () => void): void {
+    this.room(5);
+    const mark = this.at;
+    this.at += 5;
+    const start = this.at;
+    fn();
+    const len = this.at - start;
+    let k = 1; for (let n = len; n >= 128; n = Math.floor(n / 128)) k++;
+    this.buf.copyWithin(mark + k, start, this.at);
+    this.at = mark;
+    this.varint(len);
+    this.at = mark + k + len;
+  }
+  raw(bytes: Uint8Array): void { this.room(bytes.length); this.buf.set(bytes, this.at); this.at += bytes.length; }
+}
+
+class Reader {
+  private view: DataView;
+  at = 0;
+  constructor(private buf: Uint8Array) { this.view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength); }
+  u8(): number { if (this.at >= this.buf.length) throw new Error("frame: cut short"); return this.buf[this.at++]!; }
+  varint(): number { let n = 0, mul = 1; for (;;) { const b = this.u8(); n += (b & 127) * mul; if (b < 128) return n; mul *= 128; } }
+  int(): number { const z = this.varint(); return z % 2 === 0 ? z / 2 : -(z + 1) / 2; }
+  f64(): number { if (this.at + 8 > this.buf.length) throw new Error("frame: cut short"); const n = this.view.getFloat64(this.at, true); this.at += 8; return n; }
+  str(): string { const len = this.varint(); if (this.at + len > this.buf.length) throw new Error("frame: cut short"); const s = utf8d.decode(this.buf.subarray(this.at, this.at + len)); this.at += len; return s; }
+  /** The next `len` bytes, as a view. */
+  take(len: number): Uint8Array { if (this.at + len > this.buf.length) throw new Error("frame: cut short"); const v = this.buf.subarray(this.at, this.at + len); this.at += len; return v; }
+  done(): boolean { return this.at >= this.buf.length; }
+}
+
+class Untyped extends Error {}
+
+/** Writes `v` as `json` lays it out; throws Untyped where the value is not what the schema says, so the caller falls back to text. */
+function writeValue(w: Writer, j: Json, v: unknown): void {
+  if (j.const !== undefined) { if (v !== j.const) throw new Untyped(); return; }
+  if (Array.isArray(j.type)) {
+    if (v === null) { w.u8(0); return; }
+    w.u8(1);
+    writeValue(w, { ...j, type: j.type.find((t) => t !== "null") }, v);
+    return;
+  }
+  switch (j.type) {
+    case "string": if (typeof v !== "string") throw new Untyped(); w.str(v); return;
+    case "number": if (typeof v !== "number" || !Number.isFinite(v)) throw new Untyped(); w.f64(v); return;
+    case "integer": if (typeof v !== "number" || !Number.isSafeInteger(v)) throw new Untyped(); w.int(v); return;
+    case "boolean": if (typeof v !== "boolean") throw new Untyped(); w.u8(v ? 1 : 0); return;
+    case "null": if (v !== null) throw new Untyped(); return;
+    case "array": {
+      if (!Array.isArray(v) || typeof j.items !== "object" || j.items === null) throw new Untyped();
+      w.varint(v.length);
+      for (const x of v) writeValue(w, j.items as Json, x);
+      return;
+    }
+    case "object": {
+      const props = j.properties as Record<string, Json> | undefined;
+      if (!props || typeof v !== "object" || v === null || Array.isArray(v)) throw new Untyped();
+      const o = v as Record<string, unknown>;
+      for (const k in o) if (!(k in props)) throw new Untyped();
+      const required = (j.required as string[] | undefined) ?? [];
+      for (const [k, p] of Object.entries(props)) {
+        const x = o[k];
+        if (!required.includes(k)) { if (x === undefined) { w.u8(0); continue; } w.u8(1); }
+        else if (x === undefined) throw new Untyped();
+        writeValue(w, p, x);
+      }
+      return;
+    }
+    default: throw new Untyped();
+  }
+}
+
+function readValue(r: Reader, j: Json): unknown {
+  if (j.const !== undefined) return j.const;
+  if (Array.isArray(j.type)) return r.u8() === 0 ? null : readValue(r, { ...j, type: j.type.find((t) => t !== "null") });
+  switch (j.type) {
+    case "string": return r.str();
+    case "number": return r.f64();
+    case "integer": return r.int();
+    case "boolean": return r.u8() === 1;
+    case "null": return null;
+    case "array": { const n = r.varint(); const out = new Array(n); for (let i = 0; i < n; i++) out[i] = readValue(r, j.items as Json); return out; }
+    case "object": {
+      const props = j.properties as Record<string, Json>;
+      const required = (j.required as string[] | undefined) ?? [];
+      const out: Record<string, unknown> = {};
+      for (const [k, p] of Object.entries(props)) {
+        if (!required.includes(k) && r.u8() === 0) continue;
+        out[k] = readValue(r, p);
+      }
+      return out;
+    }
+    default: throw new Error(`frame: a value of an untyped schema was laid out as typed`);
+  }
+}
+
+/** A value typed by its schema when it fits, else as text; one byte says which, and the payload's length follows it. */
+function writeTagged(w: Writer, j: Json, v: unknown, fresh: boolean): void {
+  const mark = w.at;
+  const bit = fresh ? NEW : 0;
+  w.u8(TYPED | bit);
+  try { w.withLength(() => writeValue(w, j, v)); }
+  catch (err) { if (!(err instanceof Untyped)) throw err; w.at = mark; w.u8(TEXT | bit); w.withLength(() => w.str(JSON.stringify(v))); }
+}
+
+function readTagged(r: Reader, j: Json, tag: number): unknown {
+  const kind = tag & KIND;
+  if (kind === HELD) return PRESENT;
+  const len = r.varint();
+  if (kind === TEXT) return JSON.parse(r.str());
+  if (kind === TYPED) { const end = r.at + len; const v = readValue(r, j); r.at = end; return v; }
+  throw new Error(`frame: a value tagged ${tag}`);
+}
+
+/** The state as bytes. A component or resource the codec does not know is refused: the codec is the model's. */
+export function encodeFrame(c: Codec, s: StateAnswer): Uint8Array {
+  const w = new Writer();
+  const delta = isDelta(s);
+  w.u8(MAGIC); w.u8(FRAME_VERSION); w.u8(delta ? DELTA : WHOLE);
+  w.varint(s.round); w.varint(delta ? s.since : 0);
+  if (s.now === undefined) w.u8(0); else { w.u8(1); w.f64(s.now); }
+  const ids = Object.keys(s.entities);
+  const added = delta ? s.added : undefined;
+  w.varint(ids.length);
+  for (const id of ids) {
+    const parts = s.entities[id]!;
+    w.varint(Number(id));
+    if (parts === null) { w.u8(0); continue; }
+    w.u8(1);
+    const names = Object.keys(parts);
+    const fresh = added?.[id];
+    w.varint(names.length);
+    for (const name of names) {
+      const cid = c.componentId.get(name);
+      if (cid === undefined) throw new Error(`frame: no component ${name} in the codec`);
+      w.varint(cid);
+      const v = parts[name];
+      // In a whole every part is new to the follower; in a delta the ones that arrived since.
+      const isNew = !delta || fresh?.includes(name) === true;
+      if (v === null) w.u8(REMOVED);
+      else if (v === PRESENT) w.u8(HELD | (isNew ? NEW : 0));
+      else writeTagged(w, c.components[cid]!.json, v, isNew);
+    }
+  }
+  const rnames = Object.keys(s.resources);
+  w.varint(rnames.length);
+  for (const name of rnames) {
+    const rid = c.resourceId.get(name);
+    if (rid === undefined) throw new Error(`frame: no resource ${name} in the codec`);
+    w.varint(rid);
+    writeTagged(w, c.resources[rid]!.json, s.resources[name], false);
+  }
+  const blocks = BLOCKS.filter((b) => s[b] !== undefined);
+  w.varint(blocks.length);
+  for (const b of blocks) { w.str(b); w.str(JSON.stringify(s[b])); }
+  return w.bytes();
+}
+
+/** The first words of a frame, without reading the rest: whole or delta, the round, since. */
+export function frameHeader(bytes: Uint8Array): { whole: boolean; round: number; since: number } {
+  const r = new Reader(bytes);
+  if (r.u8() !== MAGIC) throw new Error("frame: not a frame");
+  r.u8();
+  const whole = r.u8() === WHOLE;
+  return { whole, round: r.varint(), since: r.varint() };
+}
+
+/** A window's interest with the names resolved to the frame's ids: what the edge cuts frames by. */
+export interface Resolved { all: boolean; presence: Set<number>; values: Set<number>; parts: Map<number, Set<number>>; resources: Set<number> }
+
+export function resolveInterest(i: Interest, cid: Map<string, number>, rid: Map<string, number>): Resolved {
+  const ids = (names: string[] | undefined, m: Map<string, number>) => new Set((names ?? []).map((n) => m.get(n)).filter((x): x is number => x !== undefined));
+  const parts = new Map<number, Set<number>>();
+  for (const [name, es] of Object.entries(i.parts ?? {})) { const c = cid.get(name); if (c === undefined) continue; for (const e of es) { let s = parts.get(e); if (!s) { s = new Set(); parts.set(e, s); } s.add(c); } }
+  return { all: i.all === true, presence: ids(i.presence, cid), values: ids(i.values, cid), parts, resources: ids(i.resources, rid) };
+}
+
+/**
+ * The frame cut to an interest, without a schema: a part is kept whole when
+ * its value is wanted, kept as held when only its presence is and it is new,
+ * dropped otherwise; an entity left with nothing goes unless it is gone,
+ * and a gone entity goes to every window, an id each; the blocks go to no
+ * window but one that wants everything, which is not cut. A delta's `since`
+ * is rewritten to `since`, the round the window holds, since frames it was
+ * not sent leave it there. Null when a delta has nothing left to say.
+ */
+export function sliceFrame(bytes: Uint8Array, want: Resolved, since: number): Uint8Array | null {
+  const r = new Reader(bytes);
+  if (r.u8() !== MAGIC) throw new Error("frame: not a frame");
+  if (r.u8() !== FRAME_VERSION) throw new Error("frame: another version");
+  const kind = r.u8();
+  const round = r.varint(); r.varint();
+  const now = r.u8() === 1 ? r.f64() : undefined;
+  const w = new Writer();
+  w.u8(MAGIC); w.u8(FRAME_VERSION); w.u8(kind);
+  w.varint(round); w.varint(kind === DELTA ? since : 0);
+  if (now === undefined) w.u8(0); else { w.u8(1); w.f64(now); }
+  const body = new Writer();
+  let entities = 0;
+  const n = r.varint();
+  for (let i = 0; i < n; i++) {
+    const e = r.varint();
+    if (r.u8() === 0) { body.varint(e); body.u8(0); entities++; continue; }
+    const m = r.varint();
+    const kept = new Writer();
+    let parts = 0;
+    const mine = want.parts.get(e);
+    for (let k = 0; k < m; k++) {
+      const cid = r.varint();
+      const tag = r.u8();
+      const t = tag & KIND;
+      const payload = t === TYPED || t === TEXT ? r.take(r.varint()) : null;
+      const value = want.values.has(cid) || mine?.has(cid) === true;
+      const presence = value || want.presence.has(cid);
+      if (!presence) continue;
+      if (t === REMOVED || t === HELD) { kept.varint(cid); kept.u8(tag); parts++; continue; }
+      if (value) { kept.varint(cid); kept.u8(tag); kept.withLength(() => kept.raw(payload!)); parts++; continue; }
+      if (tag & NEW) { kept.varint(cid); kept.u8(HELD | NEW); parts++; }
+    }
+    if (parts === 0) continue;
+    body.varint(e); body.u8(1); body.varint(parts); body.raw(kept.bytes()); entities++;
+  }
+  w.varint(entities); w.raw(body.bytes());
+  const rbody = new Writer();
+  let resources = 0;
+  const rn = r.varint();
+  for (let i = 0; i < rn; i++) {
+    const rid = r.varint();
+    const tag = r.u8();
+    const payload = r.take(r.varint());
+    if (!want.resources.has(rid)) continue;
+    rbody.varint(rid); rbody.u8(tag); rbody.withLength(() => rbody.raw(payload)); resources++;
+  }
+  w.varint(resources); w.raw(rbody.bytes());
+  w.varint(0);
+  if (kind === DELTA && entities === 0 && resources === 0) return null;
+  return w.bytes();
+}
+
+/** The state a frame carries, in the shape the replica and the doors apply. */
+export function decodeFrame(c: Codec, bytes: Uint8Array): StateAnswer {
+  const r = new Reader(bytes);
+  if (r.u8() !== MAGIC) throw new Error("frame: not a frame");
+  const version = r.u8();
+  if (version !== FRAME_VERSION) throw new Error(`frame: version ${version}, this end reads ${FRAME_VERSION}`);
+  const kind = r.u8();
+  const round = r.varint(), since = r.varint();
+  const now = r.u8() === 1 ? r.f64() : undefined;
+  const entities: Record<string, Record<string, unknown> | null> = {};
+  const n = r.varint();
+  for (let i = 0; i < n; i++) {
+    const id = String(r.varint());
+    if (r.u8() === 0) { entities[id] = null; continue; }
+    const parts: Record<string, unknown> = {};
+    const m = r.varint();
+    for (let k = 0; k < m; k++) {
+      const cid = r.varint();
+      const d = c.components[cid];
+      if (!d) throw new Error(`frame: component ${cid} is not in the codec`);
+      const tag = r.u8();
+      parts[d.name] = (tag & KIND) === REMOVED ? null : readTagged(r, d.json, tag);
+    }
+    entities[id] = parts;
+  }
+  const resources: Record<string, unknown> = {};
+  const rn = r.varint();
+  for (let i = 0; i < rn; i++) {
+    const rid = r.varint();
+    const d = c.resources[rid];
+    if (!d) throw new Error(`frame: resource ${rid} is not in the codec`);
+    resources[d.name] = readTagged(r, d.json, r.u8());
+  }
+  const blocks: Record<string, unknown> = {};
+  const bn = r.varint();
+  for (let i = 0; i < bn; i++) { const name = r.str(); blocks[name] = JSON.parse(r.str()); }
+  if (kind === DELTA) return { kind: "delta", round, since, ...(now !== undefined ? { now } : {}), entities, resources, ...blocks } as Delta;
+  return { round, ...(now !== undefined ? { now } : {}), entities: entities as Snapshot["entities"], resources, jobs: [], ...blocks } as Snapshot;
+}

package/src/ecs/handles.ts

@@ -0,0 +1,91 @@
+// What a schema's JSON says about a value's fields beyond their type: which
+// field is a component's key (`x-key`), which names an entity carrying a
+// component (`x-entity`), which is a secret (`format: "secret"`). Pure: the
+// walkers read the JSON only, so the runtime, the shell and a window share them.
+import type { Json } from "../kernel/schema.ts";
+
+/** What redaction puts in place of a secret. */
+export const REDACTED = "•••";
+
+type Leaf = (json: Json, value: unknown, path: string) => unknown;
+
+/**
+ * Rebuilds `value` along `json`: at every field whose JSON `match` admits,
+ * the value is what `leaf` answers; objects and arrays are walked through
+ * their properties and items. Undefined and null are left as they are.
+ */
+function walk(json: Json, value: unknown, match: (json: Json) => boolean, leaf: Leaf, path: string): unknown {
+  if (value === undefined || value === null) return value;
+  if (match(json)) return leaf(json, value, path);
+  if (Array.isArray(value) && json.items && typeof json.items === "object") {
+    return value.map((x, i) => walk(json.items as Json, x, match, leaf, `${path}[${i}]`));
+  }
+  const props = json.properties as Record<string, Json> | undefined;
+  if (props && typeof value === "object" && !Array.isArray(value)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      const p = props[k];
+      out[k] = p ? walk(p, v, match, leaf, path ? `${path}.${k}` : k) : v;
+    }
+    return out;
+  }
+  return value;
+}
+
+/** The field of a component's schema marked as its key: a property name, "" for a component that is its key, or null for none. */
+export function keyField(json: Json): string | null {
+  if (json["x-key"] === true) return "";
+  const keys = keyFields(json);
+  return keys[0] ?? null;
+}
+
+/** Every top-level property marked `x-key`, in order: a component may have at most one. */
+export function keyFields(json: Json): string[] {
+  const props = json.properties as Record<string, Json> | undefined;
+  return props ? Object.entries(props).filter(([, p]) => p["x-key"] === true).map(([k]) => k) : [];
+}
+
+/**
+ * Every field of `value` whose schema names an entity of a component
+ * (`x-entity`), replaced by what `visit` answers for it: the runtime resolves
+ * a key to its entity there, and checks the entity carries the component.
+ */
+export function mapEntities(json: Json, value: unknown, visit: (component: string, value: unknown, path: string) => unknown): unknown {
+  return walk(json, value, (j) => typeof j["x-entity"] === "string", (j, v, p) => visit(j["x-entity"] as string, v, p), "");
+}
+
+/** Whether the schema has a secret field anywhere in it. */
+export function hasSecret(json: Json): boolean {
+  if (json.format === "secret") return true;
+  const props = json.properties as Record<string, Json> | undefined;
+  if (props && Object.values(props).some(hasSecret)) return true;
+  return typeof json.items === "object" && json.items !== null && hasSecret(json.items as Json);
+}
+
+/** `value` with every field its schema says is a secret replaced by •••. */
+export function redact(json: Json, value: unknown): unknown {
+  return walk(json, value, (j) => j.format === "secret", () => REDACTED, "");
+}
+
+/**
+ * A literal example of a value the schema admits, for an agent to copy: every
+ * property, a string empty, an enum its first member, an entity 1, an array
+ * one item, a secret the redaction mark.
+ */
+export function exampleOf(json: Json): unknown {
+  if (typeof json !== "object" || json === null || Array.isArray(json)) return null;
+  const j = json as Record<string, unknown>;
+  if (Array.isArray(j.enum) && j.enum.length) return j.enum[0];
+  if (j.const !== undefined) return j.const;
+  const type = Array.isArray(j.type) ? j.type.find((t) => t !== "null") : j.type;
+  switch (type) {
+    case "object": return Object.fromEntries(Object.entries((j.properties as Record<string, Json> | undefined) ?? {}).map(([k, p]) => [k, exampleOf(p)]));
+    case "array": return [exampleOf(j.items as Json)];
+    case "string": return j.format === "secret" ? REDACTED : "";
+    case "integer": return j["x-entity"] !== undefined || j.description === "an entity" ? 1 : 0;
+    case "number": return 0;
+    case "boolean": return j.const === true ? true : false;
+    case "null": return null;
+    default: return Array.isArray(j.anyOf) && j.anyOf.length ? exampleOf(j.anyOf[0] as Json) : null;
+  }
+}

package/src/ecs/replica.ts

@@ -0,0 +1,150 @@
+// A read-only copy of the state, from a whole snapshot and the deltas after
+// it: what a window queries. The same storage and the same query code as the
+// state's, so a view's `w.query` costs what a step's does. Declarations are
+// matched by name, so the window imports the baba's own. A delta is applied
+// as a patch: the parts it names put or taken away, the rest left alone.
+// Change terms measure from the delta before the last one applied: what the
+// last round changed.
+// Pure, browser-safe.
+import type { Component, Resource, Effect, Entity, Row, Snapshot, Value, Term, Values, Select } from "./state.ts";
+import { Table } from "./table.ts";
+import { isDelta, PRESENT, type StateAnswer } from "./snapshot.ts";
+
+export class Replica<_X = any> {
+  round = 0;
+  private table = new Table();
+  private resources: Record<string, unknown> = {};
+  jobs: Snapshot["jobs"] = [];
+  /** What `added`, `changed` and `removed` terms measure from: the state before the last answer applied. */
+  private since = 0;
+  /** The round each resource was last written in, as far as the answers said. */
+  private rticks = new Map<string, number>();
+  /** What a select with change terms answered this round. */
+  private changed = new Map<Select, { round: number; ids: readonly Entity[] }>();
+  /** A column read once per version: the select made sensitive to its values, and the last answer. */
+  private columns = new Map<Select, Map<string, { sensitive: Select; version: number; map: ReadonlyMap<Entity, unknown> }>>();
+
+  constructor(snap?: Snapshot) { if (snap) this.apply(snap); }
+
+  /**
+   * A whole replaces everything; a delta since this round moves it forward.
+   * Answers the replica as of that round: a new object over the same
+   * storage, so a renderer that memoizes on it sees the change. The one
+   * applied to shares the storage and is not to be read after.
+   */
+  apply(answer: StateAnswer): Replica<_X> {
+    this.since = this.table.seq;
+    if (isDelta(answer)) {
+      if (answer.since !== this.round) throw new Error(`a delta since round ${answer.since} does not apply to round ${this.round}`);
+      for (const [id, patch] of Object.entries(answer.entities)) {
+        const e = Number(id);
+        if (patch === null) { if (this.table.exists(e)) this.table.despawn(e); } else this.table.patch(e, patch);
+      }
+      Object.assign(this.resources, answer.resources);
+      for (const n of Object.keys(answer.resources)) this.rticks.set(n, answer.round);
+      if (answer.jobs !== undefined) this.jobs = answer.jobs;
+    } else {
+      for (const e of this.table.all()) if (!(String(e) in answer.entities)) this.table.despawn(e);
+      for (const [id, parts] of Object.entries(answer.entities)) this.table.setParts(Number(id), parts);
+      this.resources = { ...answer.resources };
+      for (const n of Object.keys(answer.resources)) this.rticks.set(n, answer.round);
+      this.jobs = answer.jobs;
+    }
+    this.round = answer.round;
+    return Object.assign(Object.create(Replica.prototype) as Replica<_X>, this);
+  }
+
+  alive(e: Entity): boolean { return this.table.exists(e); }
+  has(e: Entity, c: Component): boolean { return this.table.hasPart(e, c.name); }
+  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") { const v = this.table.get(a, c!.name); return v === PRESENT ? undefined : v; }
+    return this.resources[a.name];
+  }
+  /** The components any entity carries, by name. */
+  components(): Set<string> { return new Set(this.table.names()); }
+  /** Whether the value of `c` on `e` is held, not only its presence. */
+  known(e: Entity, c: Component): boolean { const v = this.table.get(e, c.name); return v !== undefined && v !== PRESENT; }
+  of(e: Entity): Record<string, unknown> { return this.table.partsOf(e); }
+  all(): Entity[] { return this.table.all(); }
+  count(c: Component): number { return this.table.countOf(c.name); }
+  running(effect: Effect, entity?: Entity): boolean { return this.jobs.some((j) => j.effect === effect.name && j.entity === (entity ?? null)); }
+
+  // ---- what a watcher compares ------------------------------------------------
+
+  /** The entities a select answers, in its order: the same array until something it depends on moves. A select with change terms answers what the last round changed. */
+  ids<Cs extends readonly Term[]>(sel: Select<Cs>): readonly Entity[] {
+    if (sel.terms.some((t) => (t as { kind: string }).kind === "changed")) {
+      const have = this.changed.get(sel as never);
+      if (have && have.round === this.round) return have.ids;
+      const ids: Entity[] = [];
+      this.table.each(sel as never, this.since, (e) => { ids.push(e); });
+      const frozen = ids.length ? Object.freeze(ids) : NONE;
+      this.changed.set(sel as never, { round: this.round, ids: frozen });
+      return frozen;
+    }
+    this.table.keep(sel as never);
+    return this.table.kept(sel as never);
+  }
+  /**
+   * One column of a select: every member's value of `c`, as one map, the
+   * same until a member comes, goes or is written. What a component that
+   * draws a whole layer reads, instead of a hook per row.
+   */
+  column<K extends Component>(sel: Select, c: K): ReadonlyMap<Entity, Value<K>> {
+    let per = this.columns.get(sel);
+    if (!per) { per = new Map(); this.columns.set(sel, per); }
+    let col = per.get(c.name);
+    // A select with a predicate or an order is sensitive already; a plain one gets a twin that is, so the list's own version stays quiet on writes.
+    if (!col) { col = { sensitive: sel.pred !== null || sel.order !== null ? sel : sel.where(() => true), version: -1, map: new Map() }; per.set(c.name, col); }
+    this.table.keep(col.sensitive as never);
+    const version = this.table.version(col.sensitive as never);
+    if (version !== col.version) {
+      const map = new Map<Entity, Value<K>>();
+      for (const e of this.table.kept(col.sensitive as never)) { const v = this.table.get(e, c.name); if (v !== undefined && v !== PRESENT) map.set(e, v as Value<K>); }
+      col.version = version; col.map = map;
+    }
+    return col.map as ReadonlyMap<Entity, Value<K>>;
+  }
+  /** Another number whenever the select's answer may differ. */
+  version(sel: Select): number { this.table.keep(sel as never); return this.table.version(sel as never); }
+  /** When the value of `c` on `e` was last written, or -1 without one. */
+  tick(e: Entity, c: Component): number { return this.table.valueTick(e, c.name); }
+  /** When anything on `e` was last written. */
+  writeTick(e: Entity): number { return this.table.writeTick(e); }
+  /** The round the resource was last written in. */
+  resourceTick(r: Resource): number { return this.rticks.get(r.name) ?? 0; }
+
+  /**
+   * Lets go of what a follower no longer asks for of component `name`: the
+   * values of every entity but those in `values` become held presences when
+   * `presence` is kept, else the parts go. A held part is written anew, so
+   * `changed(c)` lists it once; that is what letting go looks like.
+   */
+  forget(name: string, keep: { presence: boolean; values: ReadonlySet<Entity> }): void {
+    for (const e of this.table.idsOf(name)) {
+      if (keep.values.has(e)) continue;
+      if (!keep.presence) { this.table.remove(e, name); continue; }
+      if (this.table.get(e, name) !== PRESENT) this.table.put(e, name, PRESENT);
+    }
+  }
+
+  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);
+  }
+
+  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[])));
+  }
+}
+
+const NONE: readonly Entity[] = Object.freeze([]);
+const isSel = (x: unknown): x is Select => typeof x === "object" && x !== null && (x as { kind?: unknown }).kind === "select";