@irtio/schema 0.5.2 → 0.7.0

package/dist/index.d.ts

@@ -159,6 +159,46 @@ declare function compilePhysics(at: string, kind: 'entity' | 'singleton', fields
 declare function canonicalPhysics(p: PhysicsDesc): Record<string, unknown>;
 /** Reads a canonical physics fragment back (`schemaFromCanonical`). */
 declare function physicsFromCanonical(at: string, raw: unknown): EntityPhysics;
+/**
+ * One planar body's state, in the vocabulary a 2D engine speaks. This is the only place the
+ * mapping from two dimensions onto the thirteen 3D channels is written down, and it lives in the
+ * schema package precisely because two sides have to agree about it: the room's server-side world
+ * writes through it, and anything reading those channels back (a renderer deriving the angle, a
+ * client-side world) reverses it. A second copy of these six lines somewhere else would be a
+ * silent way for the two to disagree by a sign.
+ *
+ * `angle` rides the quaternion about Z, which is what a rotation in the xy plane *is*:
+ * `qz = sin(a/2)`, `qw = cos(a/2)`, and back out with `2 * atan2(qz, qw)`. Channels a plane has no
+ * use for (`z`, `qx`, `qy`, `vz`, `wx`, `wy`) read as constant zero rather than being omitted, so a
+ * schema written for one engine still decodes under the other.
+ */
+interface Body2dState {
+    readonly x: number;
+    readonly y: number;
+    /** Radians, counter-clockwise. */
+    readonly angle: number;
+    readonly vx: number;
+    readonly vy: number;
+    /** Radians per second about Z. */
+    readonly angularVelocity: number;
+}
+/** The value a planar body puts on one 3D channel. */
+declare function channelOf2d(channel: PhysicsBodyChannel, b: Body2dState): number;
+/** Reads the angle back out of the two quaternion channels a plane uses. */
+declare function angleFrom2d(qz: number, qw: number): number;
+/**
+ * The reverse of {@link channelOf2d}: folds one channel's value into a mutable planar state.
+ * `qz`/`qw` are accumulated and the angle recomputed, so either order of arrival works.
+ */
+declare function applyChannel2d(channel: PhysicsBodyChannel, value: number, target: {
+    x: number;
+    y: number;
+    qz: number;
+    qw: number;
+    vx: number;
+    vy: number;
+    wz: number;
+}): void;
 
 /**
  * `entity`, `singleton`, `server`, `client`, `defineSchema`, and the compiled schema
@@ -204,6 +244,23 @@ interface EntityOptions {
      * the schema hash, and `schemaFromCanonical` does not round-trip it. Requires `physics`.
      */
     readonly predicted?: boolean;
+    /**
+     * D71: `false` → instances of this collection the client does not predict get **no body** in the
+     * client's local world, which is what every unpredicted body had before proxies existed.
+     *
+     * The default is `true`. An instance the predictor skips — one past `maxPredictedBodies` in a
+     * `predicted` collection, or any instance of a collection that is not `predicted` — is given a
+     * **kinematic proxy**: the same collider, built by the same body factory, moved each local step
+     * to the pose the renderer draws for it and never simulated forward. Predicted bodies collide
+     * with it; local forces never move it. So a player stands on a crate instead of falling through
+     * it. Turn it off for decoration nothing collides with, and for anything whose collider is
+     * expensive and whose contacts do not matter.
+     *
+     * Like `interpolate` and `predicted`, 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`, and does nothing without a client-side body factory.
+     */
+    readonly proxy?: 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
@@ -290,6 +347,8 @@ interface CollectionDesc {
     readonly interpolate: boolean;
     /** D21: clients simulate non-owned bodies ahead. Client-side only — not in the hash. */
     readonly predicted: boolean;
+    /** D71: unpredicted instances get a kinematic proxy locally. Client-side only — not in the hash. */
+    readonly proxy: boolean;
     /** D22 body/intent field split, compiled. `undefined` for ordinary collections. In the hash. */
     readonly physics: PhysicsDesc | undefined;
 }
@@ -302,24 +361,56 @@ interface RpcDesc {
     /** `undefined` = void. */
     readonly returns: readonly FieldDesc[] | undefined;
 }
-interface SchemaOptions<Rpc extends RpcMap, Roles extends readonly string[]> {
+/** Declared message shapes: name → the fields one message of that name carries. */
+type MessageMap = Readonly<Record<string, Fields>>;
+/**
+ * One compiled message shape. `index` is its position in `schema.messages` (sorted by name) and
+ * is what rides the wire, so adding a message whose name sorts early is a breaking change in
+ * exactly the way adding an early-sorting collection is (see `diffSchemas`).
+ */
+interface MessageDesc {
+    readonly name: string;
+    /** Index in `schema.messages` (sorted by name) = wire index. */
+    readonly index: number;
+    readonly fields: readonly FieldDesc[];
+}
+/**
+ * D70: the declared ceiling on message shapes. The wire index is a `u16` — this is the number a
+ * schema is refused at, deliberately far below what the encoding could carry, so that raising it
+ * later is additive rather than a wire change.
+ */
+declare const MAX_MESSAGES = 256;
+interface SchemaOptions<Rpc extends RpcMap, Roles extends readonly string[], Msgs extends MessageMap = MessageMap> {
     readonly rpc?: Rpc;
     readonly roles?: Roles;
+    /**
+     * D70: peer message shapes. `messages: { emote: { kind: enumOf('wave', 'laugh'), x: f32 } }`
+     * gives the client `room.messages.emote.send(target, value)` / `.on(cb)` and the room the same
+     * `send` plus a decoded sixth argument on `onMessage`. Part of the hash — a client and a room
+     * that disagree about a message shape disagree about the bytes — but emitted into the canonical
+     * form only when at least one is declared, so every schema written before this feature keeps
+     * the hash it had.
+     */
+    readonly messages?: Msgs;
     /** The public project id, written by `irtio init`. Identity, not shape: not part of the hash. */
     readonly project?: string;
     /** Internal: lets `@irtio/protocol` build the runtime-extended schema with built-in collections. */
     readonly allowReservedNames?: boolean;
 }
-interface Schema<Defs extends DefMap = DefMap, Rpc extends RpcMap = RpcMap, Roles extends readonly string[] = readonly string[]> {
+interface Schema<Defs extends DefMap = DefMap, Rpc extends RpcMap = RpcMap, Roles extends readonly string[] = readonly string[], Msgs extends MessageMap = MessageMap> {
     readonly defs: Defs;
     readonly rpc: Rpc;
     readonly roles: Roles;
+    /** D70: the declared message map, as written. */
+    readonly messageDefs: Msgs;
     readonly project: string | undefined;
     /** Collections sorted by name; index = wire index. */
     readonly collections: readonly CollectionDesc[];
     readonly collection: (name: string) => CollectionDesc;
     /** Builder RPCs sorted by name; index = wire `rpcId` (protocol appends built-ins after). */
     readonly rpcs: readonly RpcDesc[];
+    /** D70: declared messages sorted by name; index = wire index. Empty when none are declared. */
+    readonly messages: readonly MessageDesc[];
     /** Canonical JSON (sorted keys, `canonicalVersion: 1`). */
     readonly canonical: string;
     /** SHA-256 of the canonical form, hex. */
@@ -327,8 +418,8 @@ interface Schema<Defs extends DefMap = DefMap, Rpc extends RpcMap = RpcMap, Role
     /** First 8 bytes of the hash (HELLO / snapshot / delta header). */
     readonly hash8: Uint8Array;
 }
-type AnySchema = Schema<any, any, any>;
-declare function defineSchema<const Defs extends DefMap, const Rpc extends RpcMap = {}, const Roles extends readonly string[] = readonly string[]>(defs: Defs, options?: SchemaOptions<Rpc, Roles>): Schema<Defs, Rpc, Roles>;
+type AnySchema = Schema<any, any, any, any>;
+declare function defineSchema<const Defs extends DefMap, const Rpc extends RpcMap = {}, const Roles extends readonly string[] = readonly string[], const Msgs extends MessageMap = {}>(defs: Defs, options?: SchemaOptions<Rpc, Roles, Msgs>): Schema<Defs, Rpc, Roles, Msgs>;
 declare const CANONICAL_VERSION = 1;
 declare function canonicalType(d: TypeDesc): Record<string, unknown>;
 /**
@@ -445,10 +536,42 @@ type DeepWritable<T> = T extends readonly (infer U)[] ? DeepWritable<U>[] : T ex
 } : T;
 /** The writable view of an instance the client owns (the client SDK hands these out). */
 type Owned<T> = DeepWritable<T>;
-type SchemaDefs<S> = S extends Schema<infer D, any, any> ? D : never;
-type SchemaRpc<S> = S extends Schema<any, infer R, any> ? R : never;
-type SchemaRoles<S> = S extends Schema<any, any, infer R> ? R : never;
+type SchemaDefs<S> = S extends Schema<infer D, any, any, any> ? D : never;
+type SchemaRpc<S> = S extends Schema<any, infer R, any, any> ? R : never;
+type SchemaRoles<S> = S extends Schema<any, any, infer R, any> ? R : never;
 type RoleOf<S> = SchemaRoles<S>[number];
+/** The declared message map of a schema (`{}` for a schema that declares none). */
+type SchemaMessages<S> = S extends Schema<any, any, any, infer M> ? M : never;
+/** Alias reading the way call sites do: `MessagesOf<typeof schema>`. */
+type MessagesOf<S> = SchemaMessages<S>;
+/** Every declared message name, as a union of string literals. */
+type MessageNames<S> = keyof SchemaMessages<S> & string;
+/**
+ * The plain TS value one message of name `N` carries — exactly what `send` takes and exactly
+ * what `on` hands back, `.opt` fields included.
+ */
+type MessageValue<S, N extends MessageNames<S>> = SchemaMessages<S>[N] extends infer F ? F extends Fields ? InferFields<F> : never : never;
+/**
+ * `room.messages` on both sides, given the target and sender types each side uses.
+ *
+ * The two sides differ only in those two: a client sends to a `MessageTarget` and hears from
+ * `'server' | clientId`; a room sends to its own `MessageTarget` and observes through
+ * `onMessage`. Sharing the mapped type is what keeps `send` and `on` agreeing about the shape.
+ */
+type MessageChannels<S, Target, From, Unsub> = {
+    [K in MessageNames<S>]: {
+        send(target: Target, value: MessageValue<S, K>): void;
+        on(cb: (from: From, value: MessageValue<S, K>) => void): Unsub;
+    };
+};
+/** The server half: `send` only (a room observes through `onMessage`, never through `on`). */
+type ServerMessageChannels<S, Target> = {
+    [K in MessageNames<S>]: {
+        send(target: Target, value: MessageValue<S, K>): void;
+    };
+};
+/** Guard for `MessageMap`-shaped generics at declaration sites. */
+type AnyMessageMap = MessageMap;
 /** Plain instance type of an entity/singleton definition. */
 type InstanceOf<D> = D extends EntityDef<infer F, any> ? InferFields<F> : D extends SingletonDef<infer F, any> ? InferFields<F> : never;
 /** Init type (`add()` values) of an entity definition. */
@@ -662,7 +785,17 @@ declare class ByteReader {
     bytes(n: number): Uint8Array;
     /** varint length + raw bytes (a view). */
     blob(): Uint8Array;
-    str(): string;
+    /**
+     * varint length + UTF-8 bytes.
+     *
+     * `max` is the declared byte ceiling for this string (`str(max)`, or `ID_MAX_BYTES` for a
+     * `ref`). Checked against the length prefix **before** the bytes are read, so a hostile length
+     * costs a comparison rather than a read — and so a decoder is as strict as the encoder, which
+     * has always refused an oversize value. The encoder's guarantee only ever covered our own
+     * encoders; this covers bytes that arrived from somewhere else (D70: a peer's typed message is
+     * decoded by every receiver).
+     */
+    str(max?: number): string;
     /** The rest of the buffer (a view). */
     rest(): Uint8Array;
 }
@@ -774,6 +907,59 @@ declare function applyDelta(schema: AnySchema, state: PlainState, delta: Delta):
 /** Field-level diff between two plain states: what would have to be sent to turn `from` into `to`. */
 declare function computeDirty(schema: AnySchema, from: PlainState, to: PlainState): DirtySet;
 
+/**
+ * The measurement walker: a reader's-eye pass over *encoded* delta and snapshot bytes that
+ * reports where each byte went, keyed by collection and field.
+ *
+ * This is deliberately a second reader of the wire format rather than an instrumented writer.
+ * The encoders and `ValueSink` are untouched, so the hot path stays byte-identical and
+ * cost-identical whether or not anything is profiling; and because the walker reads exactly what
+ * `decodeDeltaFrom`/`decodeSnapshot` read, it works on the server after an encode and on the
+ * client before a decode, from the same code.
+ *
+ * The copy is kept honest by conservation: the spans it reports partition the bytes it consumed,
+ * with nothing counted twice and nothing left over (`walk.test.ts` proves it against
+ * `encodeDelta(...).length` over random schemas). If the format changes here without changing
+ * `codec.ts`, or the other way round, that property test fails.
+ *
+ * Nothing here allocates a decoded value: it skips values by width, so a profiled room pays for
+ * a second pass over the bytes and not for a second decode.
+ */
+
+/**
+ * Where the bytes went. Every callback reports a byte count, and for one walk the counts sum to
+ * the number of bytes the walk consumed.
+ */
+interface WalkEvents {
+    /**
+     * Framing that belongs to no single field: `tick`, `hash8`, the dirty-collection count, and
+     * each collection's index and op count (snapshot: the header and each entity count).
+     */
+    header(bytes: number): void;
+    /**
+     * One op's own framing: the tag byte, the id string, the owner string (add), the dirty mask
+     * and the owner string when the owner bit is set (update). Always called before that op's
+     * fields, so a consumer can route a whole op somewhere else by latching on this call.
+     *
+     * A snapshot's records report as `add` ops whose framing is the id and owner strings; a
+     * snapshot singleton has no op framing at all, only fields.
+     */
+    op(collection: CollectionDesc, kind: 'add' | 'update' | 'remove', id: string, bytes: number): void;
+    /** One field value, nested struct masks and presence bytes included. */
+    field(collection: CollectionDesc, field: FieldDesc, bytes: number): void;
+}
+/**
+ * Walks one delta body, reporting spans through `events`. Accepts raw bytes or a positioned
+ * reader, which it leaves at the first byte after the body exactly as `decodeDeltaFrom` does
+ * (the `CORRECT` frame's tick suffix is the caller's). Returns the number of bytes consumed.
+ */
+declare function walkDelta(schema: AnySchema, bytes: Uint8Array | ByteReader, events: WalkEvents): number;
+/**
+ * Walks one snapshot body, reporting spans through `events`. Entity records report as `add` ops;
+ * a singleton reports only its fields. Returns the number of bytes consumed.
+ */
+declare function walkSnapshot(schema: AnySchema, bytes: Uint8Array | ByteReader, events: WalkEvents): number;
+
 /**
  * `track()` — a proxy tree over a plain state that records every write into a `DirtySet`.
  *
@@ -824,4 +1010,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 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 };
+export { type AddOptions, type AnyDef, type AnyMessageMap, type AnyRpc, type AnySchema, type AnyType, type Body2dState, 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, MAX_MESSAGES, type MessageChannels, type MessageDesc, type MessageMap, type MessageNames, type MessageValue, type MessagesOf, 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 SchemaMessages, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerMessageChannels, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, type WalkEvents, angleFrom2d, applyChannel2d, applyDelta, bool, bytesEqual, canonicalPhysics, canonicalType, channelOf2d, 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, walkDelta, walkSnapshot, writeValue };

package/dist/index.js

@@ -318,6 +318,56 @@ function physicsFromCanonical(at, raw) {
   }
   return { body, intents };
 }
+function channelOf2d(channel, b) {
+  switch (channel) {
+    case "x":
+      return b.x;
+    case "y":
+      return b.y;
+    case "qz":
+      return Math.sin(b.angle / 2);
+    case "qw":
+      return Math.cos(b.angle / 2);
+    case "vx":
+      return b.vx;
+    case "vy":
+      return b.vy;
+    case "wz":
+      return b.angularVelocity;
+    default:
+      return 0;
+  }
+}
+function angleFrom2d(qz, qw) {
+  return 2 * Math.atan2(qz, qw);
+}
+function applyChannel2d(channel, value, target) {
+  switch (channel) {
+    case "x":
+      target.x = value;
+      return;
+    case "y":
+      target.y = value;
+      return;
+    case "qz":
+      target.qz = value;
+      return;
+    case "qw":
+      target.qw = value;
+      return;
+    case "vx":
+      target.vx = value;
+      return;
+    case "vy":
+      target.vy = value;
+      return;
+    case "wz":
+      target.wz = value;
+      return;
+    default:
+      return;
+  }
+}
 
 // src/sha256.ts
 var K = new Uint32Array([
@@ -492,6 +542,7 @@ function makeRpc(direction, spec) {
 }
 var RESERVED_RPC_NAMES = ["requestOwnership"];
 var RESERVED_COLLECTION_NAMES = ["clients"];
+var MAX_MESSAGES = 256;
 function defineSchema(defs, options = {}) {
   const names = Object.keys(defs);
   for (const n of names) {
@@ -509,6 +560,11 @@ function defineSchema(defs, options = {}) {
         `${name}: predicted: true needs physics \u2014 only body-backed collections can be simulated ahead`
       );
     }
+    if (o.proxy !== void 0 && !o.physics) {
+      throw new Error(
+        `${name}: proxy needs physics \u2014 only body-backed collections get a body in a client's local world`
+      );
+    }
     return {
       name,
       index,
@@ -527,6 +583,7 @@ function defineSchema(defs, options = {}) {
       } : void 0,
       interpolate: o.interpolate !== false,
       predicted: o.predicted === true,
+      proxy: o.proxy !== false,
       physics: o.physics ? compilePhysics(name, def.kind, fields, o.physics) : void 0
     };
   });
@@ -558,13 +615,46 @@ function defineSchema(defs, options = {}) {
   });
   const roles = options.roles ?? [];
   if (new Set(roles).size !== roles.length) throw new Error("roles must be unique");
-  const canonical = canonicalize({ collections, rpcs, roles });
+  const messageMap = options.messages ?? {};
+  const messageNames = Object.keys(messageMap);
+  if (messageNames.length > MAX_MESSAGES) {
+    throw new Error(
+      `at most ${MAX_MESSAGES} messages per schema, got ${messageNames.length} \u2014 a message index rides the wire, and this ceiling is what a client can be sure of`
+    );
+  }
+  const rpcNameSet = new Set(Object.keys(rpcMap));
+  const collectionNameSet = new Set(names);
+  for (const n of messageNames) {
+    assertFieldName(n);
+    if (collectionNameSet.has(n)) {
+      throw new Error(
+        `message name ${JSON.stringify(n)} is already a collection in this schema \u2014 pick another`
+      );
+    }
+    if (rpcNameSet.has(n)) {
+      throw new Error(
+        `message name ${JSON.stringify(n)} is already an RPC in this schema \u2014 pick another`
+      );
+    }
+    const fields = messageMap[n];
+    if (Object.keys(fields).length > 255) {
+      throw new Error(`message ${JSON.stringify(n)}: at most 255 fields`);
+    }
+    for (const f of Object.keys(fields)) assertFieldName(f);
+  }
+  const messages = [...messageNames].sort().map((name, index) => {
+    const fields = compileFields(messageMap[name]);
+    for (const f of fields) checkRefs(f.type, entityNames, `message ${name}.${f.name}`);
+    return { name, index, fields };
+  });
+  const canonical = canonicalize({ collections, rpcs, roles, messages });
   const hashBytes = sha256(new TextEncoder().encode(canonical));
   const byName = new Map(collections.map((c) => [c.name, c]));
   return {
     defs,
     rpc: rpcMap,
     roles,
+    messageDefs: messageMap,
     project: options.project,
     collections,
     collection: (name) => {
@@ -573,6 +663,7 @@ function defineSchema(defs, options = {}) {
       return c;
     },
     rpcs,
+    messages,
     canonical,
     hash: toHex(hashBytes),
     hash8: hashBytes.slice(0, 8)
@@ -648,6 +739,10 @@ function canonicalize(s) {
       // 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
+      // Deliberately absent, and this is the list: `interpolate` (D20), `predicted` (D21) and
+      // `proxy` (D71) are all decisions about what one client does with a body it was sent, not
+      // about the shape of the world. A room and a client that disagree about any of them still
+      // agree about every byte on the wire, so none of them may move the hash.
     })),
     rpcs: s.rpcs.map((r) => ({
       name: r.name,
@@ -655,7 +750,12 @@ function canonicalize(s) {
       params: canonicalFields(r.params),
       returns: r.returns ? canonicalFields(r.returns) : null
     })),
-    roles: [...s.roles]
+    roles: [...s.roles],
+    // D70: emitted only when at least one message is declared. `stableStringify` drops
+    // `undefined`, so every schema written before typed messages keeps the byte-identical
+    // canonical form — and therefore the hash — it had, and no deployed project is reclassified.
+    // Same rule as `grid` and `physics` above, and for the same reason.
+    messages: s.messages.length > 0 ? s.messages.map((m) => ({ name: m.name, fields: canonicalFields(m.fields) })) : void 0
   };
   return stableStringify(doc);
 }
@@ -809,9 +909,17 @@ function schemaFromCanonical(json, options = {}) {
     if (typeof role !== "string") throw new Error("schemaFromCanonical: roles must be strings");
     roles.push(role);
   }
+  const messages = {};
+  if (d.messages !== void 0 && d.messages !== null) {
+    for (const m of arrayAt(d, "messages")) {
+      const name = stringAt(m, "name");
+      messages[name] = fieldsOf(arrayAt(m, "fields"), `message ${name}`);
+    }
+  }
   const schema = defineSchema(defs, {
     rpc,
     roles,
+    ...Object.keys(messages).length > 0 ? { messages } : {},
     // A canonical form produced by `withBuiltins` names the reserved `clients` collection; a
     // reader must be able to replay whatever it is handed.
     allowReservedNames: true,
@@ -1327,8 +1435,21 @@ var ByteReader = class {
   blob() {
     return this.bytes(this.varint());
   }
-  str() {
-    return decoder.decode(this.blob());
+  /**
+   * varint length + UTF-8 bytes.
+   *
+   * `max` is the declared byte ceiling for this string (`str(max)`, or `ID_MAX_BYTES` for a
+   * `ref`). Checked against the length prefix **before** the bytes are read, so a hostile length
+   * costs a comparison rather than a read — and so a decoder is as strict as the encoder, which
+   * has always refused an oversize value. The encoder's guarantee only ever covered our own
+   * encoders; this covers bytes that arrived from somewhere else (D70: a peer's typed message is
+   * decoded by every receiver).
+   */
+  str(max) {
+    if (max === void 0) return decoder.decode(this.blob());
+    const n = this.varint();
+    if (n > max) throw new Error(`string exceeds ${max} UTF-8 bytes (${n})`);
+    return decoder.decode(this.bytes(n));
   }
   /** The rest of the buffer (a view). */
   rest() {
@@ -1490,7 +1611,7 @@ function readValue(r, desc) {
       return r.f64();
     case "str":
     case "ref":
-      return r.str();
+      return r.str(desc.kind === "str" ? desc.max : ID_MAX_BYTES);
     case "enum": {
       const i = r.u8();
       const v = desc.values[i];
@@ -1901,6 +2022,147 @@ function computeDirty(schema, from, to) {
   return dirty;
 }
 
+// src/walk.ts
+function skip(r, n) {
+  if (n < 0 || r.remaining < n) throw new Error("unexpected end of buffer");
+  r.pos += n;
+}
+function structNames2(d) {
+  return Object.keys(d.fields);
+}
+function skipValue(r, desc) {
+  if (desc.opt && r.u8() === 0) return;
+  switch (desc.kind) {
+    case "bool":
+    case "u8":
+    case "enum":
+      skip(r, 1);
+      return;
+    case "u16":
+      skip(r, 2);
+      return;
+    case "u32":
+    case "i32":
+    case "f32":
+      skip(r, 4);
+      return;
+    case "f64":
+      skip(r, 8);
+      return;
+    case "str":
+    case "ref":
+      skip(r, r.varint());
+      return;
+    case "list": {
+      const n = r.varint();
+      for (let i = 0; i < n; i++) skipValue(r, desc.item);
+      return;
+    }
+    case "struct": {
+      for (const fd of Object.values(desc.fields)) skipValue(r, fd);
+      return;
+    }
+  }
+}
+function readBit2(mask, i) {
+  return ((mask[i >> 3] ?? 0) & 1 << (i & 7)) !== 0;
+}
+function skipDirtyField(r, desc) {
+  if (desc.kind !== "struct") {
+    skipValue(r, desc);
+    return;
+  }
+  if (desc.opt && r.u8() === 0) return;
+  const names = structNames2(desc);
+  const maskBytes = r.bytes(names.length + 7 >> 3);
+  for (let i = 0; i < names.length; i++) {
+    if (!readBit2(maskBytes, i)) continue;
+    skipDirtyField(r, desc.fields[names[i]]);
+  }
+}
+function readerFor(bytes) {
+  return bytes instanceof ByteReader ? bytes : new ByteReader(bytes);
+}
+function walkDelta(schema, bytes, events) {
+  const r = readerFor(bytes);
+  const from = r.pos;
+  let at = r.pos;
+  skip(r, 12);
+  const count = r.varint();
+  events.header(r.pos - at);
+  for (let ci = 0; ci < count; ci++) {
+    at = r.pos;
+    const index = r.varint();
+    const c = schema.collections[index];
+    if (!c) throw new Error(`delta references unknown collection index ${index}`);
+    const opCount = r.varint();
+    events.header(r.pos - at);
+    for (let oi = 0; oi < opCount; oi++) {
+      at = r.pos;
+      const tag = r.u8();
+      const id = r.str();
+      if (tag === 2) {
+        events.op(c, "remove", id, r.pos - at);
+        continue;
+      }
+      if (tag === 0) {
+        skip(r, r.varint());
+        events.op(c, "add", id, r.pos - at);
+        for (const f of c.fields) {
+          const start = r.pos;
+          skipValue(r, f.type);
+          events.field(c, f, r.pos - start);
+        }
+        continue;
+      }
+      if (tag !== 1) throw new Error(`unknown delta op byte ${tag} in ${c.name}`);
+      const n = c.fields.length;
+      const maskBytes = r.bytes(n + 1 + 7 >> 3).slice();
+      if (readBit2(maskBytes, n)) skip(r, r.varint());
+      events.op(c, "update", id, r.pos - at);
+      for (let i = 0; i < n; i++) {
+        if (!readBit2(maskBytes, i)) continue;
+        const f = c.fields[i];
+        const start = r.pos;
+        skipDirtyField(r, f.type);
+        events.field(c, f, r.pos - start);
+      }
+    }
+  }
+  return r.pos - from;
+}
+function walkSnapshot(schema, bytes, events) {
+  const r = readerFor(bytes);
+  const from = r.pos;
+  skip(r, 12);
+  events.header(12);
+  for (const c of schema.collections) {
+    if (c.kind === "entity") {
+      let at = r.pos;
+      const n = r.varint();
+      events.header(r.pos - at);
+      for (let i = 0; i < n; i++) {
+        at = r.pos;
+        const id = r.str();
+        skip(r, r.varint());
+        events.op(c, "add", id, r.pos - at);
+        for (const f of c.fields) {
+          const start = r.pos;
+          skipValue(r, f.type);
+          events.field(c, f, r.pos - start);
+        }
+      }
+    } else {
+      for (const f of c.fields) {
+        const start = r.pos;
+        skipValue(r, f.type);
+        events.field(c, f, r.pos - start);
+      }
+    }
+  }
+  return r.pos - from;
+}
+
 // src/track.ts
 var fieldTables = /* @__PURE__ */ new WeakMap();
 function structFields(d) {
@@ -2325,6 +2587,11 @@ function diffSchemas(oldSchema, newSchema) {
   );
   diffRpcs(oldSchema.rpcs, newSchema.rpcs, changes);
   diffRoles(oldSchema.roles, newSchema.roles, changes);
+  diffMessages(
+    oldSchema.messages ?? [],
+    newSchema.messages ?? [],
+    changes
+  );
   changes.sort(
     (a, b) => a.path === b.path ? a.code.localeCompare(b.code) : a.path.localeCompare(b.path)
   );
@@ -2388,6 +2655,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 (oldC.index !== newC.index) {
+      changes.push({
+        kind: "breaking",
+        code: `${oldC.kind}.reordered`,
+        path: oldC.name,
+        message: `${oldC.name}: wire index changed (${oldC.index} -> ${newC.index}) \u2014 collections are addressed positionally, so every delta and snapshot for this collection would be misread (breaking)`
+      });
+    }
     if (stableStringify(oldC.grid) !== stableStringify(newC.grid)) {
       changes.push({
         kind: "breaking",
@@ -2422,9 +2697,25 @@ function diffRpcs(oldRpcs, newRpcs, changes) {
       });
     }
   }
+  if (oldRpcs.length !== newRpcs.length) {
+    changes.push({
+      kind: "breaking",
+      code: "rpc.builtin_reordered",
+      path: "rpc",
+      message: `rpc: the number of RPCs changed from ${oldRpcs.length} to ${newRpcs.length}, which shifts the ids of irtio's built-in RPCs (they are numbered after yours) \u2014 connected clients would call the wrong one (breaking)`
+    });
+  }
   for (const oldR of oldRpcs) {
     const newR = newByName.get(oldR.name);
     if (!newR) continue;
+    if (oldR.index !== newR.index) {
+      changes.push({
+        kind: "breaking",
+        code: "rpc.reordered",
+        path: `rpc.${oldR.name}`,
+        message: `rpc ${oldR.name}: wire id changed (${oldR.index} -> ${newR.index}) \u2014 RPCs are addressed by a positional id, so calls would reach the wrong handler (breaking)`
+      });
+    }
     if (oldR.direction !== newR.direction) {
       changes.push({
         kind: "breaking",
@@ -2437,6 +2728,43 @@ function diffRpcs(oldRpcs, newRpcs, changes) {
     diffFields(oldR.returns ?? [], newR.returns ?? [], `rpc.${oldR.name}.returns`, changes);
   }
 }
+function diffMessages(oldMessages, newMessages, changes) {
+  const oldByName = new Map(oldMessages.map((m) => [m.name, m]));
+  const newByName = new Map(newMessages.map((m) => [m.name, m]));
+  for (const m of oldMessages) {
+    if (!newByName.has(m.name)) {
+      changes.push({
+        kind: "breaking",
+        code: "message.removed",
+        path: `message.${m.name}`,
+        message: `message ${m.name}: was removed \u2014 peers still sending it would be dropped`
+      });
+    }
+  }
+  for (const m of newMessages) {
+    if (!oldByName.has(m.name)) {
+      changes.push({
+        kind: "additive",
+        code: "message.added",
+        path: `message.${m.name}`,
+        message: `message ${m.name}: new message shape added`
+      });
+    }
+  }
+  for (const oldM of oldMessages) {
+    const newM = newByName.get(oldM.name);
+    if (!newM) continue;
+    if (oldM.index !== newM.index) {
+      changes.push({
+        kind: "breaking",
+        code: "message.reordered",
+        path: `message.${oldM.name}`,
+        message: `message ${oldM.name}: wire index changed (${oldM.index} -> ${newM.index}) \u2014 messages are addressed positionally, so peers would decode this one as another (breaking)`
+      });
+    }
+    diffFields(oldM.fields, newM.fields, `message.${oldM.name}`, changes);
+  }
+}
 function diffRoles(oldRoles, newRoles, changes) {
   const oldSet = new Set(oldRoles);
   const newSet = new Set(newRoles);
@@ -2677,16 +3005,20 @@ export {
   CANONICAL_VERSION,
   EntityCollection,
   ID_MAX_BYTES,
+  MAX_MESSAGES,
   PHYSICS_BODY_CHANNELS,
   RESERVED_COLLECTION_NAMES,
   RESERVED_RPC_NAMES,
   SERVER_OWNER,
   SINGLETON_ID,
+  angleFrom2d,
+  applyChannel2d,
   applyDelta,
   bool,
   bytesEqual,
   canonicalPhysics,
   canonicalType,
+  channelOf2d,
   client,
   cloneValue,
   collectionDirty,
@@ -2745,5 +3077,7 @@ export {
   u8,
   validateForDeploy,
   validateValue,
+  walkDelta,
+  walkSnapshot,
   writeValue
 };

package/package.json

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