@irtio/schema 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -111,19 +111,107 @@ declare function cloneValue<T>(v: T): T;
  */
 declare function normalizeValue(d: TypeDesc, v: unknown, path?: string): unknown;
 
+/**
+ * The `physics` entity option (D22): which of an entity's fields the simulation owns, and which
+ * are intents the owner writes for the step to consume.
+ *
+ * The split is the whole idea. **Body fields** are written by the physics step and are read-only
+ * to everyone else — room code (a compile error), and clients (a `WRITE` touching one is
+ * corrected back). **Intent fields** are ordinary owned fields: the client writes them, the
+ * validator judges them, and room code turns them into forces during `tick()`. Nothing else on a
+ * physics entity is client-writable, so a client's write history for one of these entities is
+ * exactly its intent frames — which is what week 10's client-side re-stepping replays.
+ *
+ * Unlike week 8's `interpolate` (a client-side rendering choice, deliberately outside the schema
+ * hash), physics options are **server shape**: a room and a client that disagree about which
+ * fields the simulation owns disagree about the world. They go in the canonical form and
+ * therefore in the hash.
+ *
+ * The channel names are 3D because `@dimforge/rapier3d-compat` is the blessed engine (D22). A 2D
+ * game maps only the channels it uses (`x`, `y`, and `qz`/`qw` for a locked-axis rotation) and
+ * locks the remaining axis on the body — the schema surface never picks a dimensionality.
+ */
+
+/** Body state channels the runtime syncs, in canonical order. */
+declare const PHYSICS_BODY_CHANNELS: readonly ["x", "y", "z", "qx", "qy", "qz", "qw", "vx", "vy", "vz", "wx", "wy", "wz"];
+type PhysicsBodyChannel = (typeof PHYSICS_BODY_CHANNELS)[number];
+/** Channel → the entity field that mirrors it. Every channel is optional; at least one required. */
+type PhysicsBodyMap = {
+    readonly [C in PhysicsBodyChannel]?: string;
+};
+interface EntityPhysics {
+    /** Fields the simulation owns: translation (`x`/`y`/`z`), rotation quaternion (`q*`), velocities (`v*`/`w*`). */
+    readonly body: PhysicsBodyMap;
+    /** Owner-written input fields the step consumes. Declaration order is the canonical order. */
+    readonly intents?: readonly string[];
+}
+/** Compiled form on `CollectionDesc.physics`. */
+interface PhysicsDesc {
+    readonly body: PhysicsBodyMap;
+    /** `[channel, field]` in `PHYSICS_BODY_CHANNELS` order — the sync loop's iteration order. */
+    readonly channels: readonly (readonly [PhysicsBodyChannel, string])[];
+    readonly intents: readonly string[];
+    /** Every field named by `body`, for the read-only checks. */
+    readonly bodyFields: ReadonlySet<string>;
+}
+declare function compilePhysics(at: string, kind: 'entity' | 'singleton', fields: readonly FieldDesc[], physics: EntityPhysics): PhysicsDesc;
+/** The canonical fragment for one collection's physics (omitted entirely when there is none). */
+declare function canonicalPhysics(p: PhysicsDesc): Record<string, unknown>;
+/** Reads a canonical physics fragment back (`schemaFromCanonical`). */
+declare function physicsFromCanonical(at: string, raw: unknown): EntityPhysics;
+
 /**
  * `entity`, `singleton`, `server`, `client`, `defineSchema`, and the compiled schema
  * (ordered collection descriptors, sorted RPC table, canonical form, hash).
  */
 
 type Visibility = 'all' | 'role' | 'spatial-grid';
+interface GridOptions<K extends string = string> {
+    /** Numeric fields containing the entity's world position. */
+    readonly x: K;
+    readonly y: K;
+    /** Positive, finite world units per cell. */
+    readonly cell: number;
+    /** Non-negative integer number of cells in the square AOI radius. */
+    readonly radius: number;
+    /** Declared roles which see the complete collection without an anchor. */
+    readonly wideRoles?: readonly string[];
+}
+interface GridDesc extends GridOptions<string> {
+}
 interface EntityOptions {
     /** `true` → never client-owned; `DeepReadonly` on the client at compile time. */
     readonly serverOwned?: boolean;
-    /** `'all'` (default) | `'role'` (per-role views, needs `roles`) | `'spatial-grid'` (accepted by the types, rejected at deploy — not yet supported). */
+    /** `'all'` (default) | `'role'` (per-role views, needs `roles`) | `'spatial-grid'` (per-client AOI). */
     readonly visibility?: Visibility;
     /** With `visibility: 'role'`: the roles that see this collection. */
     readonly roles?: readonly string[];
+    /** Required with `visibility: 'spatial-grid'`; invalid on every other visibility mode. */
+    readonly grid?: GridOptions;
+    /**
+     * `false` → the client's `room.render` read path snaps this collection to the authoritative
+     * value on arrival instead of interpolating it (D20, week 8). Rendering behavior only —
+     * identity, not shape: like `project`, it is not part of the schema hash, and
+     * `schemaFromCanonical` does not round-trip it (the canonical form has no rendering options).
+     */
+    readonly interpolate?: boolean;
+    /**
+     * D21: the client simulates this collection's bodies ahead for instances it does **not** own
+     * (owned bodies are always predicted when prediction is active). Capped per client (default 64
+     * non-owned bodies; over-cap instances render by interpolation but have no body in the client's
+     * local world, so predicted bodies pass through them). Like `interpolate`, this is
+     * client-side simulation behavior, not server shape — it is not part of the canonical form or
+     * the schema hash, and `schemaFromCanonical` does not round-trip it. Requires `physics`.
+     */
+    readonly predicted?: boolean;
+    /**
+     * D22: this collection's instances are backed by rigid bodies. `body` names the fields the
+     * simulation owns (read-only everywhere else), `intents` the owner-written inputs the step
+     * consumes. Unlike `interpolate`, this is **server shape** — it is part of the canonical form
+     * and the schema hash, because a client and a room that disagree about it disagree about the
+     * world. Requires `physics:` on the room config; the runtime rejects the pairing otherwise.
+     */
+    readonly physics?: EntityPhysics;
 }
 interface EntityDef<F extends Fields = Fields, O extends EntityOptions = EntityOptions> {
     readonly kind: 'entity';
@@ -196,6 +284,14 @@ interface CollectionDesc {
     readonly serverOwned: boolean;
     readonly visibility: Visibility;
     readonly roles: readonly string[] | undefined;
+    /** D23 spatial AOI contract, present only when declared. */
+    readonly grid: GridDesc | undefined;
+    /** `false` → `room.render` steps this collection (D20). Not part of the canonical form/hash. */
+    readonly interpolate: boolean;
+    /** D21: clients simulate non-owned bodies ahead. Client-side only — not in the hash. */
+    readonly predicted: boolean;
+    /** D22 body/intent field split, compiled. `undefined` for ordinary collections. In the hash. */
+    readonly physics: PhysicsDesc | undefined;
 }
 interface RpcDesc {
     readonly name: string;
@@ -358,8 +454,28 @@ type InstanceOf<D> = D extends EntityDef<infer F, any> ? InferFields<F> : D exte
 /** Init type (`add()` values) of an entity definition. */
 type InitOf<D> = D extends EntityDef<infer F, any> ? InitFields<F> : D extends SingletonDef<infer F, any> ? InitFields<F> : never;
 type DefOptions<D> = D extends EntityDef<any, infer O> ? O : D extends SingletonDef<any, infer O> ? O : never;
+/**
+ * The field names `physics.body` maps for a def (D22), as a union of string literals — `never`
+ * for an ordinary collection. Needs `entity(fields, { ... } as const)`, which the `const O`
+ * type parameter on `entity()`/`singleton()` already gives every call site.
+ */
+type BodyFieldsOf<D> = DefOptions<D> extends {
+    physics: {
+        body: infer B;
+    };
+} ? B[keyof B] & string : never;
+/**
+ * `T` with the keys in `Names` marked `readonly`. The simulation owns those fields between
+ * steps, so a handler assigning one is a compile error — the intent fields are where input goes.
+ * `add()` still takes them (`InitFields` is untouched): that is how a body's initial pose is set.
+ */
+type ReadonlyBodyFields<T, Names extends string> = [Names] extends [never] ? T : Simplify<{
+    readonly [K in keyof T as K extends Names ? K : never]: T[K];
+} & {
+    [K in keyof T as K extends Names ? never : K]: T[K];
+}>;
 type State<S> = {
-    [K in keyof SchemaDefs<S>]: SchemaDefs<S>[K] extends EntityDef<infer F, any> ? Collection<InferFields<F>, InitFields<F>> : SchemaDefs<S>[K] extends SingletonDef<infer F, any> ? InferFields<F> : never;
+    [K in keyof SchemaDefs<S>]: SchemaDefs<S>[K] extends EntityDef<infer F, any> ? Collection<ReadonlyBodyFields<InferFields<F>, BodyFieldsOf<SchemaDefs<S>[K]>>, InitFields<F>> : SchemaDefs<S>[K] extends SingletonDef<infer F, any> ? InferFields<F> : never;
 };
 type RolesOf<O extends EntityOptions> = O extends {
     roles: readonly (infer R)[];
@@ -385,6 +501,12 @@ type ServerOwnedKeys<S> = {
         serverOwned: true;
     } ? K : never;
 }[keyof SchemaDefs<S>];
+/** Entity collections backed by rigid bodies (D22). */
+type PhysicsKeys<S> = {
+    [K in keyof SchemaDefs<S>]: DefOptions<SchemaDefs<S>[K]> extends {
+        physics: object;
+    } ? K : never;
+}[keyof SchemaDefs<S>];
 /** Entity collections whose instances a client may own. */
 type OwnableKeys<S> = {
     [K in keyof SchemaDefs<S>]: SchemaDefs<S>[K] extends EntityDef<any, infer O> ? O extends {
@@ -597,9 +719,10 @@ type PlainRecord = Record<string, unknown>;
 interface Header {
     readonly tick: number;
 }
-/** Snapshot options: `collections` limits which collections carry data (others are encoded empty/default). */
+/** Snapshot options limit collections and, for entities, individual ids. */
 interface SnapshotOptions {
     readonly collections?: (c: CollectionDesc) => boolean;
+    readonly entities?: (c: CollectionDesc, id: string) => boolean;
 }
 declare function encodeSnapshot(schema: AnySchema, state: PlainState, header: Header, options?: SnapshotOptions): Uint8Array;
 interface DecodedSnapshot {
@@ -701,4 +824,4 @@ interface SchemaChange {
 /** Compares two compiled schemas and returns every classified change, sorted by path then code. */
 declare function diffSchemas(oldSchema: AnySchema, newSchema: AnySchema): SchemaChange[];
 
-export { type AddOptions, type AnyDef, type AnyRpc, type AnySchema, type AnyType, type BroadcastProxy, ByteReader, ByteWriter, CANONICAL_VERSION, type ClientCallProxy, type ClientImplementations, type ClientRpcs, type ClientState, type Collection, type CollectionDesc, type CollectionDirty, type DecodedSnapshot, type DeepReadonly, type DeepWritable, type DefMap, type Delta, type DeltaCollection, type DeltaOp, type DirtySet, EntityCollection, type EntityDef, type EntityOptions, type FieldDesc, type FieldMask, type Fields, type FromCanonicalOptions, type Header, ID_MAX_BYTES, type Implementations, type Infer, type InferFields, type InitFields, type InitOf, type InstanceOf, type Kind, type OwnableKeys, type Owned, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, type ReadonlyCollection, type RecordDirty, type RoleOf, type RpcDef, type RpcDesc, type RpcDirection, type RpcMap, type RpcParams, type RpcReturns, type RpcSpec, SERVER_OWNER, SINGLETON_ID, type Schema, type SchemaChange, type SchemaDefs, type SchemaIssue, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, applyDelta, bool, bytesEqual, canonicalType, client, cloneValue, collectionDirty, computeDirty, createDirtySet, createFieldMask, createState, decodeDelta, decodeDeltaFrom, decodeFields, decodeSnapshot, defaultRecord, defaultValue, defineSchema, describeType, diffSchemas, encodeDelta, encodeFields, encodeSnapshot, entity, enumOf, estimateSize, f32, f64, filterDirty, frozenProxy, i32, isDirtyEmpty, isWhole, list, markAdd, markField, markOwner, markPath, markRemove, mergeDirty, mergeMask, normalizeRecord, normalizeValue, readValue, ref, schemaFromCanonical, server, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, validateForDeploy, validateValue, writeValue };
+export { type AddOptions, type AnyDef, type AnyRpc, type AnySchema, type AnyType, type BodyFieldsOf, type BroadcastProxy, ByteReader, ByteWriter, CANONICAL_VERSION, type ClientCallProxy, type ClientImplementations, type ClientRpcs, type ClientState, type Collection, type CollectionDesc, type CollectionDirty, type DecodedSnapshot, type DeepReadonly, type DeepWritable, type DefMap, type Delta, type DeltaCollection, type DeltaOp, type DirtySet, EntityCollection, type EntityDef, type EntityOptions, type EntityPhysics, type FieldDesc, type FieldMask, type Fields, type FromCanonicalOptions, type GridDesc, type GridOptions, type Header, ID_MAX_BYTES, type Implementations, type Infer, type InferFields, type InitFields, type InitOf, type InstanceOf, type Kind, type OwnableKeys, type Owned, PHYSICS_BODY_CHANNELS, type PhysicsBodyChannel, type PhysicsBodyMap, type PhysicsDesc, type PhysicsKeys, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, type ReadonlyBodyFields, type ReadonlyCollection, type RecordDirty, type RoleOf, type RpcDef, type RpcDesc, type RpcDirection, type RpcMap, type RpcParams, type RpcReturns, type RpcSpec, SERVER_OWNER, SINGLETON_ID, type Schema, type SchemaChange, type SchemaDefs, type SchemaIssue, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, applyDelta, bool, bytesEqual, canonicalPhysics, canonicalType, client, cloneValue, collectionDirty, compilePhysics, computeDirty, createDirtySet, createFieldMask, createState, decodeDelta, decodeDeltaFrom, decodeFields, decodeSnapshot, defaultRecord, defaultValue, defineSchema, describeType, diffSchemas, encodeDelta, encodeFields, encodeSnapshot, entity, enumOf, estimateSize, f32, f64, filterDirty, frozenProxy, i32, isDirtyEmpty, isWhole, list, markAdd, markField, markOwner, markPath, markRemove, mergeDirty, mergeMask, normalizeRecord, normalizeValue, physicsFromCanonical, readValue, ref, schemaFromCanonical, server, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, validateForDeploy, validateValue, writeValue };

package/dist/index.js

@@ -211,6 +211,114 @@ function normalizeValue(d, v, path = "") {
   }
 }
 
+// src/physics.ts
+var PHYSICS_BODY_CHANNELS = [
+  "x",
+  "y",
+  "z",
+  "qx",
+  "qy",
+  "qz",
+  "qw",
+  "vx",
+  "vy",
+  "vz",
+  "wx",
+  "wy",
+  "wz"
+];
+var CHANNEL_SET = new Set(PHYSICS_BODY_CHANNELS);
+var NUMERIC_KINDS = /* @__PURE__ */ new Set(["f32", "f64"]);
+function compilePhysics(at, kind, fields, physics) {
+  if (kind !== "entity") {
+    throw new Error(`${at}: physics is only available on entity collections, not singletons`);
+  }
+  const byName = new Map(fields.map((f) => [f.name, f]));
+  const channels = [];
+  const bodyFields = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Map();
+  for (const key of Object.keys(physics.body)) {
+    if (!CHANNEL_SET.has(key)) {
+      throw new Error(
+        `${at}: physics.body has unknown channel ${JSON.stringify(key)} (one of ${PHYSICS_BODY_CHANNELS.join(", ")})`
+      );
+    }
+  }
+  for (const channel of PHYSICS_BODY_CHANNELS) {
+    const field = physics.body[channel];
+    if (field === void 0) continue;
+    const desc = byName.get(field);
+    if (!desc) {
+      throw new Error(
+        `${at}: physics.body.${channel} names ${JSON.stringify(field)}, which is not a field of this entity`
+      );
+    }
+    if (!NUMERIC_KINDS.has(desc.type.kind)) {
+      throw new Error(
+        `${at}: physics.body.${channel} \u2192 ${JSON.stringify(field)} must be f32 or f64, got ${desc.type.kind}`
+      );
+    }
+    const already = seen.get(field);
+    if (already !== void 0) {
+      throw new Error(
+        `${at}: physics.body.${channel} and physics.body.${already} both map ${JSON.stringify(field)}`
+      );
+    }
+    seen.set(field, channel);
+    channels.push([channel, field]);
+    bodyFields.add(field);
+  }
+  if (channels.length === 0) {
+    throw new Error(`${at}: physics.body must map at least one channel to a field`);
+  }
+  const intents = [];
+  for (const name of physics.intents ?? []) {
+    if (!byName.has(name)) {
+      throw new Error(
+        `${at}: physics.intents names ${JSON.stringify(name)}, which is not a field of this entity`
+      );
+    }
+    if (bodyFields.has(name)) {
+      throw new Error(
+        `${at}: ${JSON.stringify(name)} is both a body field and an intent \u2014 pick one`
+      );
+    }
+    if (intents.includes(name)) {
+      throw new Error(`${at}: physics.intents lists ${JSON.stringify(name)} twice`);
+    }
+    intents.push(name);
+  }
+  return { body: { ...physics.body }, channels, intents, bodyFields };
+}
+function canonicalPhysics(p) {
+  const body = {};
+  for (const [channel, field] of p.channels) body[channel] = field;
+  return { body, intents: [...p.intents] };
+}
+function physicsFromCanonical(at, raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`${at}: physics must be an object`);
+  }
+  const o = raw;
+  const bodyRaw = o.body;
+  if (typeof bodyRaw !== "object" || bodyRaw === null || Array.isArray(bodyRaw)) {
+    throw new Error(`${at}: physics.body must be an object`);
+  }
+  const body = {};
+  for (const [k, v] of Object.entries(bodyRaw)) {
+    if (typeof v !== "string") throw new Error(`${at}: physics.body.${k} must be a field name`);
+    body[k] = v;
+  }
+  const intentsRaw = o.intents ?? [];
+  if (!Array.isArray(intentsRaw)) throw new Error(`${at}: physics.intents must be an array`);
+  const intents = [];
+  for (const v of intentsRaw) {
+    if (typeof v !== "string") throw new Error(`${at}: physics.intents must be field names`);
+    intents.push(v);
+  }
+  return { body, intents };
+}
+
 // src/sha256.ts
 var K = new Uint32Array([
   1116352408,
@@ -396,6 +504,11 @@ function defineSchema(defs, options = {}) {
     const def = defs[name];
     const fields = compileFields(def.fields);
     const o = def.options;
+    if (o.predicted === true && !o.physics) {
+      throw new Error(
+        `${name}: predicted: true needs physics \u2014 only body-backed collections can be simulated ahead`
+      );
+    }
     return {
       name,
       index,
@@ -404,7 +517,17 @@ function defineSchema(defs, options = {}) {
       fieldIndex: new Map(fields.map((f) => [f.name, f.index])),
       serverOwned: o.serverOwned === true,
       visibility: o.visibility ?? "all",
-      roles: o.roles ? [...o.roles] : void 0
+      roles: o.roles ? [...o.roles] : void 0,
+      grid: o.grid ? {
+        x: o.grid.x,
+        y: o.grid.y,
+        cell: o.grid.cell,
+        radius: o.grid.radius,
+        ...o.grid.wideRoles ? { wideRoles: [...o.grid.wideRoles] } : {}
+      } : void 0,
+      interpolate: o.interpolate !== false,
+      predicted: o.predicted === true,
+      physics: o.physics ? compilePhysics(name, def.kind, fields, o.physics) : void 0
     };
   });
   const entityNames = new Set(collections.filter((c) => c.kind === "entity").map((c) => c.name));
@@ -513,7 +636,18 @@ function canonicalize(s) {
       fields: canonicalFields(c.fields),
       serverOwned: c.serverOwned,
       visibility: c.visibility,
-      roles: c.roles ? [...c.roles] : null
+      roles: c.roles ? [...c.roles] : null,
+      // D23 is emitted only when declared so pre-AOI schemas retain byte-identical hashes.
+      grid: c.grid ? {
+        x: c.grid.x,
+        y: c.grid.y,
+        cell: c.grid.cell,
+        radius: c.grid.radius,
+        ...c.grid.wideRoles ? { wideRoles: [...c.grid.wideRoles] } : {}
+      } : void 0,
+      // Emitted only when declared: `stableStringify` drops `undefined`, so every schema written
+      // before D22 keeps the byte-identical canonical form — and therefore the hash — it had.
+      physics: c.physics ? canonicalPhysics(c.physics) : void 0
     })),
     rpcs: s.rpcs.map((r) => ({
       name: r.name,
@@ -545,9 +679,54 @@ function validateForDeploy(schema) {
   const issues = [];
   for (const c of schema.collections) {
     if (c.visibility === "spatial-grid") {
+      const grid = c.grid;
+      if (c.kind !== "entity") {
+        issues.push({
+          level: "error",
+          message: `${c.name}: spatial-grid visibility is entity-only`
+        });
+      }
+      if (!grid) {
+        issues.push({
+          level: "error",
+          message: `${c.name}: spatial-grid visibility requires grid: { x, y, cell, radius }`
+        });
+      } else {
+        const numeric = /* @__PURE__ */ new Set(["u8", "u16", "u32", "i32", "f32", "f64"]);
+        for (const axis of ["x", "y"]) {
+          const field = c.fields.find((f) => f.name === grid[axis]);
+          if (!field || !numeric.has(field.type.kind)) {
+            issues.push({
+              level: "error",
+              message: `${c.name}: grid.${axis} must name a numeric scalar field`
+            });
+          }
+        }
+        if (!Number.isFinite(grid.cell) || grid.cell <= 0) {
+          issues.push({
+            level: "error",
+            message: `${c.name}: grid.cell must be a positive finite number`
+          });
+        }
+        if (!Number.isInteger(grid.radius) || grid.radius < 0) {
+          issues.push({
+            level: "error",
+            message: `${c.name}: grid.radius must be a non-negative integer`
+          });
+        }
+        for (const role of grid.wideRoles ?? []) {
+          if (!schema.roles.includes(role)) {
+            issues.push({
+              level: "error",
+              message: `${c.name}: grid wide role ${JSON.stringify(role)} is not in schema roles`
+            });
+          }
+        }
+      }
+    } else if (c.grid) {
       issues.push({
         level: "error",
-        message: `${c.name}: visibility 'spatial-grid' is not yet supported; use 'all' or 'role'`
+        message: `${c.name}: grid is only valid with visibility 'spatial-grid'`
       });
     }
     if (c.visibility === "role") {
@@ -708,10 +887,30 @@ function entityOptions(e, name) {
       throw new Error(`schemaFromCanonical: ${name}: roles must be strings`);
     return r;
   });
+  const physics = e.physics === void 0 || e.physics === null ? void 0 : physicsFromCanonical(`schemaFromCanonical: ${name}`, e.physics);
+  const grid = e.grid === void 0 || e.grid === null ? void 0 : gridFromCanonical(name, objectAt(e, "grid"));
   return {
     serverOwned: e.serverOwned === true,
     visibility,
-    ...roles !== void 0 ? { roles } : {}
+    ...roles !== void 0 ? { roles } : {},
+    ...grid !== void 0 ? { grid } : {},
+    ...physics !== void 0 ? { physics } : {}
+  };
+}
+function gridFromCanonical(name, grid) {
+  const wideRolesRaw = grid.wideRoles;
+  const wideRoles = wideRolesRaw === void 0 ? void 0 : arrayAtRaw(grid, "wideRoles").map((role) => {
+    if (typeof role !== "string") {
+      throw new Error(`schemaFromCanonical: ${name}: grid.wideRoles must be strings`);
+    }
+    return role;
+  });
+  return {
+    x: stringAt(grid, "x"),
+    y: stringAt(grid, "y"),
+    cell: finiteNumberAt(grid, "cell"),
+    radius: numberAt(grid, "radius"),
+    ...wideRoles !== void 0 ? { wideRoles } : {}
   };
 }
 function stringAt(o, key) {
@@ -726,6 +925,13 @@ function numberAt(o, key) {
   }
   return v;
 }
+function finiteNumberAt(o, key) {
+  const v = o[key];
+  if (typeof v !== "number" || !Number.isFinite(v)) {
+    throw new Error(`schemaFromCanonical: ${key} must be a finite number`);
+  }
+  return v;
+}
 function objectAt(o, key) {
   const v = o[key];
   if (typeof v !== "object" || v === null || Array.isArray(v)) {
@@ -1348,8 +1554,15 @@ function writeSnapshot(w, schema, state, tick, options) {
         continue;
       }
       const coll = entityOf(state, c.name);
-      w.varint(coll.size);
+      let count = 0;
+      if (options?.entities) {
+        for (const id of coll.ids()) if (options.entities(c, id)) count++;
+      } else {
+        count = coll.size;
+      }
+      w.varint(count);
       for (const id of coll.ids()) {
+        if (options?.entities && !options.entities(c, id)) continue;
         const value = coll.get(id);
         if (value === void 0) throw new Error(`${c.name}: id ${JSON.stringify(id)} vanished`);
         w.str(id);
@@ -2175,6 +2388,14 @@ function diffCollections(oldCollections, newCollections, changes) {
         message: `${oldC.name}: visible roles changed from [${(oldC.roles ?? []).join(", ")}] to [${(newC.roles ?? []).join(", ")}] \u2014 changes who sees this collection`
       });
     }
+    if (stableStringify(oldC.grid) !== stableStringify(newC.grid)) {
+      changes.push({
+        kind: "breaking",
+        code: "entity.grid_changed",
+        path: oldC.name,
+        message: `${oldC.name}: spatial grid contract changed \u2014 changes per-client membership`
+      });
+    }
     diffFields(oldC.fields, newC.fields, oldC.name, changes);
   }
 }
@@ -2456,6 +2677,7 @@ export {
   CANONICAL_VERSION,
   EntityCollection,
   ID_MAX_BYTES,
+  PHYSICS_BODY_CHANNELS,
   RESERVED_COLLECTION_NAMES,
   RESERVED_RPC_NAMES,
   SERVER_OWNER,
@@ -2463,10 +2685,12 @@ export {
   applyDelta,
   bool,
   bytesEqual,
+  canonicalPhysics,
   canonicalType,
   client,
   cloneValue,
   collectionDirty,
+  compilePhysics,
   computeDirty,
   createDirtySet,
   createFieldMask,
@@ -2503,6 +2727,7 @@ export {
   mergeMask,
   normalizeRecord,
   normalizeValue,
+  physicsFromCanonical,
   readValue,
   ref,
   schemaFromCanonical,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/schema",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "irtio schema DSL, type inference, canonical hash, codec, change tracking, and schema diff",
   "license": "MIT",
   "publishConfig": {