@irtio/schema 0.11.0 → 3.0.0

package/dist/index.d.ts

@@ -93,6 +93,7 @@ type InitFields<F extends Fields> = Simplify<{
     [K in InitOptKeys<F>]?: Infer<F[K]> | undefined;
 }>;
 declare function describeType(d: TypeDesc): string;
+declare function utf8Length(s: string): number;
 /** Entity ids are strings of at most this many UTF-8 bytes (`str(32)` on the wire). */
 declare const ID_MAX_BYTES = 32;
 /**
@@ -279,7 +280,12 @@ declare function ownershipFromCanonical(at: string, raw: unknown): OwnershipOpti
  * (ordered collection descriptors, sorted RPC table, canonical form, hash).
  */
 
-type Visibility = 'all' | 'role' | 'spatial-grid';
+/**
+ * `'server'` is the room's own private state: no client role sees it, no client may write it, and
+ * it never reaches the wire. It is the first-class spelling of what `visibility: 'role'` with an
+ * empty `roles` list has always done by accident, and it takes no `roles`.
+ */
+type Visibility = 'all' | 'role' | 'spatial-grid' | 'server';
 interface GridOptions<K extends string = string> {
     /** Numeric fields containing the entity's world position. */
     readonly x: K;
@@ -296,7 +302,10 @@ 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'` (per-client AOI). */
+    /**
+     * `'all'` (default) | `'role'` (per-role views, needs `roles`) | `'spatial-grid'` (per-client
+     * AOI) | `'server'` (room-private: no client sees or writes it).
+     */
     readonly visibility?: Visibility;
     /** With `visibility: 'role'`: the roles that see this collection. */
     readonly roles?: readonly string[];
@@ -364,6 +373,27 @@ interface EntityOptions {
      * unowned, and a leaving player's records keep their (now absent) owner.
      */
     readonly ownership?: OwnershipOptions;
+    /**
+     * Fields of a client-owned record that only the server may write.
+     *
+     * Ownership is per record, so the server's own facts about a client-owned entity — granted
+     * upgrades, a validated score, a cooldown the room controls — have had to live in a parallel
+     * collection keyed by the same id. This puts them on the record and refuses the client's writes
+     * to them by name: the leaf goes back to the value it had before any validator runs, the client
+     * is corrected, and the rest of the same write still lands.
+     *
+     * Server behaviour, so it is part of the canonical form and the hash — a client and a room that
+     * disagree about who writes `upgrades` disagree about the world. Emitted into the canonical form
+     * only when declared, so every schema written before this keeps the hash it had.
+     *
+     * Entity-only, and meaningless on a `serverOwned` collection (where every field already is);
+     * both are refused. On a `physics` collection the intent list already answers the question, so a
+     * field named by both is refused too.
+     *
+     * There is deliberately no dynamic form. A per-field *owner id* would have to ride the wire per
+     * field per record, and the case that needs one is served by a second collection.
+     */
+    readonly serverFields?: readonly string[];
 }
 interface EntityDef<F extends Fields = Fields, O extends EntityOptions = EntityOptions> {
     readonly kind: 'entity';
@@ -418,6 +448,12 @@ declare function client<P extends Fields = {}, R extends Fields = Fields>(spec:
 }): RpcDef<'client', P, R>;
 /** RPC names a builder may not declare (built-ins live in `@irtio/protocol`). */
 declare const RESERVED_RPC_NAMES: readonly string[];
+/**
+ * The prefix irtio's built-in RPC names carry (`$ownership.ask`), refused to a builder here and to
+ * a caller in `@irtio/protocol`'s `isReservedRpcName`. Stated twice because the dependency runs
+ * schema → protocol and never the other way.
+ */
+declare const RESERVED_RPC_PREFIX = "$";
 /** Collection names a builder may not declare (the runtime merges built-in state under them). */
 declare const RESERVED_COLLECTION_NAMES: readonly string[];
 interface FieldDesc {
@@ -452,10 +488,21 @@ interface CollectionDesc {
     readonly clientCreate: boolean;
     /** D77: the compiled transfer and leave rules. `undefined` when none were declared. In the hash. */
     readonly ownership: OwnershipDesc | undefined;
+    /**
+     * M7 pf3 (e): the field names only the server may write, sorted, or `undefined` when none were
+     * declared. In the hash when present. A `Set` because `writes.ts` asks the membership question
+     * once per written leaf.
+     */
+    readonly serverFields: ReadonlySet<string> | undefined;
 }
 interface RpcDesc {
     readonly name: string;
-    /** Index in `schema.rpcs` (sorted by name). Built-ins are appended by `@irtio/protocol`. */
+    /**
+     * The wire id: this RPC's position in **declaration order**, 0-based (M7 pf2). It is not a
+     * sort — the order the developer wrote the `rpc` object in is the order of the id space, and
+     * moving a declaration moves an id. `@irtio/protocol`'s built-ins live in a reserved range at
+     * the top of the u16 and never collide with these.
+     */
     readonly index: number;
     readonly direction: RpcDirection;
     readonly params: readonly FieldDesc[];
@@ -465,13 +512,13 @@ interface RpcDesc {
 /** 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`).
+ * One compiled message shape. `index` is its position in `schema.messages` in **declaration
+ * order** (M7 pf2) and is what rides the wire, so appending a message is additive and moving an
+ * existing declaration is breaking, in exactly the way it is for a collection (see `diffSchemas`).
  */
 interface MessageDesc {
     readonly name: string;
-    /** Index in `schema.messages` (sorted by name) = wire index. */
+    /** Index in `schema.messages` (declaration order) = wire index. */
     readonly index: number;
     readonly fields: readonly FieldDesc[];
 }
@@ -481,6 +528,13 @@ interface MessageDesc {
  * later is additive rather than a wire change.
  */
 declare const MAX_MESSAGES = 256;
+/**
+ * M7 pf2: the ceiling on builder-declared RPCs. `Call.rpcId` is a `u16`, and `@irtio/protocol`
+ * reserves the top of that space for irtio's built-ins (65535 downward). This cap is what keeps
+ * the two ranges from ever meeting, with thousands of ids of headroom on both sides — a schema
+ * that hits it has a problem no id scheme can fix.
+ */
+declare const MAX_USER_RPCS = 60000;
 interface SchemaOptions<Rpc extends RpcMap, Roles extends readonly string[], Msgs extends MessageMap = MessageMap> {
     readonly rpc?: Rpc;
     readonly roles?: Roles;
@@ -589,6 +643,8 @@ interface Collection<T, Init = T> extends ReadonlyCollection<T> {
     add(id: string, values: Init, options?: AddOptions): T;
     remove(id: string): boolean;
     setOwner(id: string, owner: string): void;
+    /** M7 pf3 (d): make this collection hold exactly `entries`. See {@link reconcileCollection}. */
+    reconcile(entries: Iterable<readonly [string, Init]>): void;
     [Symbol.iterator](): IterableIterator<readonly [string, T]>;
 }
 interface Record_<T> {
@@ -606,10 +662,43 @@ declare class EntityCollection<T extends object = any, Init = T> implements Coll
     has(id: string): boolean;
     setOwner(id: string, owner: string): void;
     ownerOf(id: string): string | undefined;
+    reconcile(entries: Iterable<readonly [string, Init]>): void;
     get size(): number;
     ids(): IterableIterator<string>;
     [Symbol.iterator](): IterableIterator<readonly [string, T]>;
 }
+/**
+ * M7 pf3 (d): make `coll` hold exactly the ids `entries` yields, and nothing else.
+ *
+ * The shape a transient set wants — fires, pings, scorch marks, anything recomputed wholesale
+ * every tick. What it replaces is an `add`/`remove` bookkeeping pass plus a scratch `Set`, written
+ * again in every room that has one, and got subtly wrong the first time in most of them.
+ *
+ * It is a **thin diff over the existing methods**, not a second write path:
+ *
+ * - an id in `entries` that the collection does not have is `add`ed, exactly as if you had called
+ *   `add` yourself (defaults filled, owner the server);
+ * - an id it already has keeps its record object, its owner, and its physics body: the values in
+ *   `entries` are **assigned onto the existing record**, field by field, so a value that did not
+ *   really change does not dirty and a body-backed row is not torn down and rebuilt;
+ * - an id the collection has and `entries` does not is `remove`d.
+ *
+ * That is the whole of the difference between this and a loop of `add()`s: `add` installs a *new*
+ * record object, which re-dirties every field and (on a physics collection) rebuilds the body at
+ * its spawn pose. `reconcile` is for the set that mostly stays the same.
+ *
+ * On a tracked collection every one of those steps goes through the tracking proxies, so the
+ * dirty set comes out identical to the one hand-written bookkeeping would have produced.
+ *
+ * Partial `entries` values are honoured on an existing row: a pair of `['a', { x: 3 }]` assigns
+ * `x` and leaves every other field of `a` alone. On a *new* row the same pair goes through `add`,
+ * where the collection's `.default()`/`.opt` rules fill the rest and a missing required field
+ * throws — the same asymmetry `add` has always had.
+ *
+ * Removals happen after the additions, so an id present in `entries` is never removed and
+ * re-added by one call.
+ */
+declare function reconcileCollection<T extends object, Init>(coll: Collection<T, Init>, desc: CollectionDesc, entries: Iterable<readonly [string, Init]>): void;
 /** Builds a full record from init values: every field present, defaults applied, f32 frounded. */
 declare function normalizeRecord(desc: CollectionDesc, values: Record<string, unknown>): Record<string, unknown>;
 /** A record with every field at its default. */
@@ -706,6 +795,8 @@ type RolesOf<O extends EntityOptions> = O extends {
 } ? R : never;
 /** Is collection with options `O` visible to `Role`? */
 type VisibleTo<O extends EntityOptions, Role extends string> = O extends {
+    visibility: 'server';
+} ? false : O extends {
     visibility: 'role';
 } ? [Role] extends [RolesOf<O>] ? true : false : true;
 type VisibleKeys<S, Role extends string> = {
@@ -923,6 +1014,12 @@ declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
  *
  * Encoding validates: oversize strings/lists, out-of-range or non-integer ints, wrong types,
  * missing required values and unknown enum members all throw with the field path.
+ *
+ * Decoding validates what a peer can lie about: an oversize string, an over-max list, an unknown
+ * enum index and a non-finite `f32`/`f64` all throw, which every caller of this codec already
+ * surfaces as a refused frame rather than as a value in state. The single exception is
+ * `decodeSnapshot`, which coerces a non-finite float to the field default and warns, because
+ * those bytes can be a room's own save and refusing them loses the room; see the comment there.
  */
 
 /**
@@ -943,8 +1040,22 @@ interface ValueSink {
 }
 /** Writes one value in snapshot form (presence byte first when the descriptor is `.opt`). */
 declare function writeValue(w: ValueSink, desc: TypeDesc, v: unknown, path?: string): void;
+/**
+ * How a decode answers a non-finite `f32`/`f64` it reads off the wire.
+ *
+ * The default — and the only answer on the delta/WRITE path — is to throw, which is what makes a
+ * peer-authored NaN an ordinary refused frame. {@link decodeSnapshot} passes a `coerce` reporter
+ * instead; see the comment there for why the two paths must differ.
+ */
+interface ReadOptions {
+    /**
+     * When set, a non-finite float is replaced by the field's default and reported here instead of
+     * throwing. `path` is the field path, `value` the number that was read.
+     */
+    readonly onNonFinite?: (path: string, value: number) => void;
+}
 /** Reads one value in snapshot form. */
-declare function readValue(r: ByteReader, desc: TypeDesc): unknown;
+declare function readValue(r: ByteReader, desc: TypeDesc, opts?: ReadOptions, path?: string): unknown;
 /** Snapshot-form record encoding — used for RPC params and returns. */
 declare function encodeFields(fields: readonly FieldDesc[], value: Record<string, unknown>): Uint8Array;
 /** Decodes a snapshot-form record. Accepts raw bytes or a positioned `ByteReader`. */
@@ -964,7 +1075,29 @@ interface DecodedSnapshot {
     readonly hash8: Uint8Array;
     readonly state: PlainState;
 }
-declare function decodeSnapshot(schema: AnySchema, bytes: Uint8Array): DecodedSnapshot;
+interface DecodeSnapshotOptions {
+    /**
+     * Where a non-finite float found in the snapshot is reported. Defaults to a `console.warn`.
+     * The field is restored as its declared default either way.
+     */
+    readonly onNonFinite?: (path: string, value: number) => void;
+}
+/**
+ * Decodes a whole-state snapshot: a join payload, or the codec section of a room save.
+ *
+ * **Why this path tolerates a non-finite float where the delta path refuses one.** A delta is a
+ * live frame from a peer, so a NaN in it is an attack or a bug happening *now* and refusing the
+ * frame costs one frame. A snapshot is also how a hibernated room comes back, and those bytes
+ * were written by *us* — possibly months ago, before `normalizeValue` re-checked after its
+ * fround and before `writeValue` checked at all. Applying the strict rule to them means a save
+ * containing one Infinity is a room that can never be restored again: every wake throws, and
+ * since the save is the room, the room is gone. Weighed against that, coercing the one poisoned
+ * field to its declared default and saying so loudly is plainly the better trade — the room
+ * comes back, one number is wrong in a way the operator has been told about, and room code fixes
+ * or overwrites it on the next tick. This deliberately does *not* extend to `decodeDelta` or the
+ * WRITE path, where the bytes are a peer's and refusing them is free.
+ */
+declare function decodeSnapshot(schema: AnySchema, bytes: Uint8Array, options?: DecodeSnapshotOptions): DecodedSnapshot;
 type DeltaOp = {
     readonly op: 'add';
     readonly id: string;
@@ -1110,5 +1243,19 @@ interface SchemaChange {
 }
 /** Compares two compiled schemas and returns every classified change, sorted by path then code. */
 declare function diffSchemas(oldSchema: AnySchema, newSchema: AnySchema): SchemaChange[];
+/**
+ * True when every breaking change in `changes` lives under the RPC table (`rpc` / `rpc.*`) or the
+ * message table (`message.*`), and there is at least one. Such a change breaks connected clients
+ * (the version fence reconnects them) but touches nothing a snapshot stores, so a deploy needs
+ * `--allow-breaking` and no migration: a chain step without one decodes and re-encodes losslessly.
+ *
+ * M7 pf2 added the message half. Messages are transient peer packets — the snapshot encoder has
+ * no reference to `schema.messages` at all — so a message-only break has never had anything to
+ * migrate; before pf2 nobody noticed, because a message index only moved when a name was inserted
+ * early. Declaration-order indices make moves ordinary, and the pf2 transition itself renumbers
+ * messages for every project that declares more than one. Demanding a hand-written identity
+ * migration for a packet nothing stores would be a lie about what the deploy costs.
+ */
+declare function breakingIsWireOnly(changes: readonly SchemaChange[]): boolean;
 
-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, type OwnershipDesc, type OwnershipLeave, type OwnershipLeaveAction, type OwnershipOptions, type OwnershipPosition, type OwnershipTransfer, 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, canonicalOwnership, canonicalPhysics, canonicalType, channelOf2d, client, cloneValue, collectionDirty, compileOwnership, 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, ownershipFromCanonical, parseHold, physicsFromCanonical, readValue, ref, schemaFromCanonical, server, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, validateForDeploy, validateValue, walkDelta, walkSnapshot, 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 DecodeSnapshotOptions, 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, MAX_USER_RPCS, type MessageChannels, type MessageDesc, type MessageMap, type MessageNames, type MessageValue, type MessagesOf, type OwnableKeys, type Owned, type OwnershipDesc, type OwnershipLeave, type OwnershipLeaveAction, type OwnershipOptions, type OwnershipPosition, type OwnershipTransfer, PHYSICS_BODY_CHANNELS, type PhysicsBodyChannel, type PhysicsBodyMap, type PhysicsDesc, type PhysicsKeys, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, RESERVED_RPC_PREFIX, type ReadOptions, 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, breakingIsWireOnly, bytesEqual, canonicalOwnership, canonicalPhysics, canonicalType, channelOf2d, client, cloneValue, collectionDirty, compileOwnership, 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, ownershipFromCanonical, parseHold, physicsFromCanonical, readValue, reconcileCollection, ref, schemaFromCanonical, server, sha256, sha256Hex, singleton, stableStringify, str, struct, toHex, track, u16, u32, u8, utf8Length, validateForDeploy, validateValue, walkDelta, walkSnapshot, writeValue };

package/dist/index.js

@@ -112,7 +112,8 @@ function validateValue(d, v, path = "") {
     }
     case "f32":
     case "f64":
-      return typeof v === "number" ? null : `${at} must be a number`;
+      if (typeof v !== "number") return `${at} must be a number`;
+      return Number.isFinite(v) ? null : `${at} must be a finite number (${d.kind})`;
     case "str":
     case "ref": {
       if (typeof v !== "string") return `${at} must be a string`;
@@ -187,7 +188,11 @@ function normalizeValue(d, v, path = "") {
   switch (d.kind) {
     case "f32": {
       if (typeof v !== "number") throw new Error(`${at} must be a number`);
-      return Math.fround(v);
+      if (!Number.isFinite(v)) throw new Error(`${at} must be a finite number (f32)`);
+      const f = Math.fround(v);
+      if (!Number.isFinite(f))
+        throw new Error(`${at} overflows f32 (${v} rounds to ${f > 0 ? "Infinity" : "-Infinity"})`);
+      return f;
     }
     case "list": {
       if (!Array.isArray(v)) throw new Error(`${at} must be an array`);
@@ -657,6 +662,48 @@ function singleton(fields, options) {
   checkFields(fields);
   return { kind: "singleton", fields, options: options ?? {} };
 }
+function compileServerFields(name, kind, fields, o) {
+  const declared = o.serverFields;
+  if (declared === void 0) return void 0;
+  if (!Array.isArray(declared)) {
+    throw new Error(`${name}: serverFields must be an array of field names`);
+  }
+  if (kind !== "entity") {
+    throw new Error(
+      `${name}: serverFields is entity-only \u2014 a client never writes a singleton, so every field of one is already server-only`
+    );
+  }
+  if (o.serverOwned === true) {
+    throw new Error(
+      `${name}: serverFields on a serverOwned collection says nothing \u2014 serverOwned already means no client writes any field of it`
+    );
+  }
+  if (declared.length === 0) {
+    throw new Error(`${name}: serverFields is empty; leave it off instead`);
+  }
+  const known = new Set(fields.map((f) => f.name));
+  const out = /* @__PURE__ */ new Set();
+  for (const field of declared) {
+    if (typeof field !== "string" || !known.has(field)) {
+      throw new Error(
+        `${name}: serverFields names ${JSON.stringify(field)}, which is not a field of ${name}`
+      );
+    }
+    if (out.has(field)) throw new Error(`${name}: serverFields names ${field} twice`);
+    out.add(field);
+  }
+  if (out.size === fields.length) {
+    throw new Error(
+      `${name}: serverFields names every field \u2014 that is serverOwned: true, which says it once`
+    );
+  }
+  if (o.physics) {
+    throw new Error(
+      `${name}: serverFields says nothing on a physics collection \u2014 the owner of a body-backed record writes its declared intents and nothing else. Take the field out of physics.intents instead`
+    );
+  }
+  return new Set([...out].sort());
+}
 function checkFields(fields) {
   const names = Object.keys(fields);
   if (names.length === 0) throw new Error("entity/singleton needs at least one field");
@@ -676,8 +723,10 @@ function makeRpc(direction, spec) {
   return { kind: "rpc", direction, params, returns: spec.returns };
 }
 var RESERVED_RPC_NAMES = ["requestOwnership"];
+var RESERVED_RPC_PREFIX = "$";
 var RESERVED_COLLECTION_NAMES = ["clients"];
 var MAX_MESSAGES = 256;
+var MAX_USER_RPCS = 6e4;
 function defineSchema(defs, options = {}) {
   const names = Object.keys(defs);
   for (const n of names) {
@@ -713,6 +762,7 @@ function defineSchema(defs, options = {}) {
       );
     }
     const ownership = o.ownership || perPlayer ? compileOwnership(name, def.kind, fields, o.ownership ?? {}, perPlayer) : void 0;
+    const serverFields = compileServerFields(name, def.kind, fields, o);
     return {
       name,
       index,
@@ -720,6 +770,7 @@ function defineSchema(defs, options = {}) {
       fields,
       fieldIndex: new Map(fields.map((f) => [f.name, f.index])),
       serverOwned: o.serverOwned === true,
+      serverFields,
       perPlayer,
       clientCreate: o.clientCreate === true,
       ownership,
@@ -763,13 +814,23 @@ function defineSchema(defs, options = {}) {
     }
   }
   const rpcMap = options.rpc ?? {};
+  if (Object.keys(rpcMap).length > MAX_USER_RPCS) {
+    throw new Error(
+      `at most ${MAX_USER_RPCS} RPCs per schema, got ${Object.keys(rpcMap).length} \u2014 an rpcId is a u16 and the top of that space is reserved for irtio's built-in RPCs`
+    );
+  }
   for (const n of Object.keys(rpcMap)) {
     assertFieldName(n);
     if (RESERVED_RPC_NAMES.includes(n)) {
       throw new Error(`RPC name ${JSON.stringify(n)} is reserved by irtio (built-in RPC)`);
     }
+    if (n.startsWith(RESERVED_RPC_PREFIX)) {
+      throw new Error(
+        `RPC name ${JSON.stringify(n)} starts with ${JSON.stringify(RESERVED_RPC_PREFIX)}, which is reserved for irtio's built-in RPCs \u2014 pick another name`
+      );
+    }
   }
-  const rpcs = Object.keys(rpcMap).sort().map((name, index) => {
+  const rpcs = Object.keys(rpcMap).map((name, index) => {
     const r = rpcMap[name];
     for (const f of Object.values(r.params))
       checkRefs(f.desc, entityNames, `rpc ${name} params`);
@@ -813,7 +874,7 @@ function defineSchema(defs, options = {}) {
     }
     for (const f of Object.keys(fields)) assertFieldName(f);
   }
-  const messages = [...messageNames].sort().map((name, index) => {
+  const messages = messageNames.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 };
@@ -916,6 +977,10 @@ function canonicalize(s) {
       // canonical form, and therefore the hash, it had. They are in the hash when declared because
       // they are server behaviour: a client and a room that disagree about who may take a crate
       // disagree about the world.
+      // M7 pf3 (e): the same only-when-declared rule again, for the same reason. Server
+      // behaviour, so it is in the hash when present: a client and a room that disagree about who
+      // writes `upgrades` disagree about the world.
+      serverFields: c.serverFields ? [...c.serverFields] : void 0,
       perPlayer: c.perPlayer ? true : void 0,
       clientCreate: c.clientCreate ? true : void 0,
       ownership: c.ownership ? canonicalOwnership(c.ownership) : void 0
@@ -1010,11 +1075,17 @@ function validateForDeploy(schema) {
         message: `${c.name}: grid is only valid with visibility 'spatial-grid'`
       });
     }
+    if (c.visibility === "server" && c.roles && c.roles.length > 0) {
+      issues.push({
+        level: "error",
+        message: `${c.name}: visibility 'server' takes no roles \u2014 it is visible to no client role`
+      });
+    }
     if (c.visibility === "role") {
       if (!c.roles || c.roles.length === 0) {
         issues.push({
           level: "warning",
-          message: `${c.name}: visibility 'role' without roles \u2014 visible to no client role (likely a mistake)`
+          message: `${c.name}: visibility 'role' without roles \u2014 visible to no client role (likely a mistake; say visibility: 'server' if that is what you meant)`
         });
       } else {
         for (const r of c.roles) {
@@ -1165,7 +1236,7 @@ function typeOf(t, at) {
 }
 function entityOptions(e, name) {
   const visibility = stringAt(e, "visibility");
-  if (visibility !== "all" && visibility !== "role" && visibility !== "spatial-grid") {
+  if (visibility !== "all" && visibility !== "role" && visibility !== "spatial-grid" && visibility !== "server") {
     throw new Error(
       `schemaFromCanonical: ${name}: unknown visibility ${JSON.stringify(visibility)}`
     );
@@ -1179,6 +1250,11 @@ function entityOptions(e, name) {
   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"));
   const ownership = e.ownership === void 0 || e.ownership === null ? void 0 : ownershipFromCanonical(`schemaFromCanonical: ${name}`, e.ownership);
+  const serverFields = e.serverFields === void 0 || e.serverFields === null ? void 0 : arrayAtRaw(e, "serverFields").map((f) => {
+    if (typeof f !== "string")
+      throw new Error(`schemaFromCanonical: ${name}: serverFields must be strings`);
+    return f;
+  });
   return {
     serverOwned: e.serverOwned === true,
     visibility,
@@ -1188,8 +1264,9 @@ function entityOptions(e, name) {
     // ---- M6 lane K: stateful relay ----
     ...e.perPlayer === true ? { perPlayer: true } : {},
     ...e.clientCreate === true ? { clientCreate: true } : {},
-    ...ownership !== void 0 ? { ownership } : {}
+    ...ownership !== void 0 ? { ownership } : {},
     // ---- end M6 lane K ----
+    ...serverFields !== void 0 ? { serverFields } : {}
   };
 }
 function gridFromCanonical(name, grid) {
@@ -1294,6 +1371,9 @@ var EntityCollection = class {
   ownerOf(id) {
     return this.records.get(id)?.owner;
   }
+  reconcile(entries) {
+    reconcileCollection(this, this.desc, entries);
+  }
   get size() {
     return this.records.size;
   }
@@ -1304,6 +1384,39 @@ var EntityCollection = class {
     for (const [id, r] of this.records) yield [id, r.value];
   }
 };
+function reconcileCollection(coll, desc, entries) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    if (!Array.isArray(entry) || entry.length < 2) {
+      throw new Error(
+        `${desc.name}.reconcile: entries must yield [id, values] pairs, got ${JSON.stringify(entry)}`
+      );
+    }
+    const [id, values] = entry;
+    seen.add(id);
+    const current = coll.get(id);
+    if (current === void 0) {
+      coll.add(id, values);
+      continue;
+    }
+    assignFields(desc, current, values);
+  }
+  for (const id of [...coll.ids()]) if (!seen.has(id)) coll.remove(id);
+}
+function assignFields(desc, target, values) {
+  if (typeof values !== "object" || values === null) {
+    throw new Error(`${desc.name}: values must be an object`);
+  }
+  for (const [name, raw] of Object.entries(values)) {
+    const index = desc.fieldIndex.get(name);
+    if (index === void 0) {
+      throw new Error(`${desc.name}: unknown field ${JSON.stringify(name)}`);
+    }
+    const field = desc.fields[index];
+    const next = raw === void 0 && field.type.opt ? void 0 : normalizeValue(field.type, raw, `${desc.name}.${name}`);
+    target[name] = next;
+  }
+}
 function normalizeRecord(desc, values) {
   if (typeof values !== "object" || values === null) {
     throw new Error(`${desc.name}: values must be an object`);
@@ -1543,6 +1656,13 @@ var ByteWriter = class {
     return this.buf.slice(0, this.pos);
   }
 };
+function utf82(bytes) {
+  try {
+    return decoder.decode(bytes);
+  } catch {
+    throw new Error(`invalid UTF-8 in string (${bytes.length} bytes)`);
+  }
+}
 var ByteReader = class {
   constructor(buf, offset = 0) {
     this.buf = buf;
@@ -1633,10 +1753,10 @@ var ByteReader = class {
    * decoded by every receiver).
    */
   str(max) {
-    if (max === void 0) return decoder.decode(this.blob());
+    if (max === void 0) return utf82(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));
+    return utf82(this.bytes(n));
   }
   /** The rest of the buffer (a view). */
   rest() {
@@ -1739,13 +1859,13 @@ function writeValue(w, desc, v, path = "value") {
       return;
     }
     case "f32":
+    case "f64": {
       if (typeof value !== "number") fail(path, "must be a number");
-      w.f32(value);
-      return;
-    case "f64":
-      if (typeof value !== "number") fail(path, "must be a number");
-      w.f64(value);
+      if (!Number.isFinite(value)) fail(path, `must be a finite number (${desc.kind})`);
+      if (desc.kind === "f32") w.f32(value);
+      else w.f64(value);
       return;
+    }
     case "str":
     case "ref": {
       if (typeof value !== "string") fail(path, "must be a string");
@@ -1779,7 +1899,12 @@ function writeValue(w, desc, v, path = "value") {
     }
   }
 }
-function readValue(r, desc) {
+function warnNonFinite(path, value) {
+  console.warn(
+    `irtio: snapshot field ${path} held ${value}; restored as the field's default. The value predates the finiteness checks on write and encode.`
+  );
+}
+function readValue(r, desc, opts, path = "value") {
   if (desc.opt && r.u8() === 0) return void 0;
   switch (desc.kind) {
     case "bool":
@@ -1793,9 +1918,15 @@ function readValue(r, desc) {
     case "i32":
       return r.i32();
     case "f32":
-      return r.f32();
-    case "f64":
-      return r.f64();
+    case "f64": {
+      const v = desc.kind === "f32" ? r.f32() : r.f64();
+      if (!Number.isFinite(v)) {
+        if (!opts?.onNonFinite) throw new Error(`must be a finite number (${desc.kind})`);
+        opts.onNonFinite(path, v);
+        return defaultValue(desc);
+      }
+      return v;
+    }
     case "str":
     case "ref":
       return r.str(desc.kind === "str" ? desc.max : ID_MAX_BYTES);
@@ -1810,12 +1941,13 @@ function readValue(r, desc) {
       const n = r.varint();
       if (n > desc.max) throw new Error(`list exceeds max length ${desc.max} (${n})`);
       const out = [];
-      for (let i = 0; i < n; i++) out.push(readValue(r, desc.item));
+      for (let i = 0; i < n; i++) out.push(readValue(r, desc.item, opts, `${path}[${i}]`));
       return out;
     }
     case "struct": {
       const o = {};
-      for (const [k, fd] of Object.entries(desc.fields)) o[k] = readValue(r, fd);
+      for (const [k, fd] of Object.entries(desc.fields))
+        o[k] = readValue(r, fd, opts, `${path}.${k}`);
       return o;
     }
   }
@@ -1825,9 +1957,10 @@ function writeRecord(w, fields, value, path) {
     fail(path, "must be an object");
   for (const f of fields) writeValue(w, f.type, value[f.name], `${path}.${f.name}`);
 }
-function readRecord(r, fields) {
+function readRecord(r, fields, opts, path = "") {
   const o = {};
-  for (const f of fields) o[f.name] = readValue(r, f.type);
+  for (const f of fields)
+    o[f.name] = readValue(r, f.type, opts, path ? `${path}.${f.name}` : f.name);
   return o;
 }
 function encodeFields(fields, value) {
@@ -1887,8 +2020,9 @@ function encodeSnapshot(schema, state, header, options) {
   writeSnapshot(w, schema, state, header.tick, options);
   return w.finish();
 }
-function decodeSnapshot(schema, bytes) {
+function decodeSnapshot(schema, bytes, options = {}) {
   const r = new ByteReader(bytes);
+  const opts = { onNonFinite: options.onNonFinite ?? warnNonFinite };
   const tick = r.u32();
   const hash8 = r.bytes(8).slice();
   const state = createState(schema);
@@ -1897,13 +2031,13 @@ function decodeSnapshot(schema, bytes) {
       const coll = entityOf(state, c.name);
       const n = r.varint();
       for (let i = 0; i < n; i++) {
-        const id = r.str();
-        const owner = r.str();
-        coll.add(id, readRecord(r, c.fields), { owner });
+        const id = r.str(ID_MAX_BYTES);
+        const owner = r.str(ID_MAX_BYTES);
+        coll.add(id, readRecord(r, c.fields, opts, `${c.name}.${id}`), { owner });
       }
     } else {
       const target = singletonOf(state, c.name);
-      const value = readRecord(r, c.fields);
+      const value = readRecord(r, c.fields, opts, c.name);
       for (const f of c.fields) target[f.name] = value[f.name];
     }
   }
@@ -2242,6 +2376,7 @@ function skipValue(r, desc) {
       return;
     case "list": {
       const n = r.varint();
+      if (n > desc.max) throw new Error(`list exceeds max length ${desc.max} (${n})`);
       for (let i = 0; i < n; i++) skipValue(r, desc.item);
       return;
     }
@@ -2389,6 +2524,11 @@ function objHandler(node) {
     get(target, prop, receiver) {
       if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
       const f = node.fields.get(prop);
+      if (!f && prop === "reconcile") {
+        throw new Error(
+          `${node.label}.reconcile: reconcile() diffs the ids of an entity collection; ${node.label} is a single record. Assign its fields directly.`
+        );
+      }
       if (!f) return Reflect.get(target, prop, receiver);
       const v = target[f.name];
       if (v === null || typeof v !== "object") return v;
@@ -2635,6 +2775,14 @@ var TrackedCollection = class {
   ownerOf(id) {
     return this.inner.ownerOf(id);
   }
+  /**
+   * M7 pf3 (d): the tracked half of {@link reconcileCollection}. It calls this collection's own
+   * `add`/`remove`/`get`, so every mark the hand-written bookkeeping would have made is made here
+   * — including the record-proxy invalidation an `add` over a live id does.
+   */
+  reconcile(entries) {
+    reconcileCollection(this, this.desc, entries);
+  }
   get size() {
     return this.inner.size;
   }
@@ -2784,6 +2932,12 @@ function diffSchemas(oldSchema, newSchema) {
   );
   return changes;
 }
+function breakingIsWireOnly(changes) {
+  const breaking = changes.filter((c) => c.kind === "breaking");
+  return breaking.length > 0 && breaking.every(
+    (c) => c.path === "rpc" || c.path.startsWith("rpc.") || c.path.startsWith("message.")
+  );
+}
 function diffCollections(oldCollections, newCollections, changes) {
   const oldByName = new Map(oldCollections.map((c) => [c.name, c]));
   const newByName = new Map(newCollections.map((c) => [c.name, c]));
@@ -2858,6 +3012,14 @@ function diffCollections(oldCollections, newCollections, changes) {
         message: `${oldC.name}: spatial grid contract changed \u2014 changes per-client membership`
       });
     }
+    if (!sameStringSet([...oldC.serverFields ?? []], [...newC.serverFields ?? []])) {
+      changes.push({
+        kind: "breaking",
+        code: "entity.server_fields_changed",
+        path: oldC.name,
+        message: `${oldC.name}: serverFields changed from [${[...oldC.serverFields ?? []].join(", ")}] to [${[...newC.serverFields ?? []].join(", ")}] \u2014 changes which fields a client may write`
+      });
+    }
     diffFields(oldC.fields, newC.fields, oldC.name, changes);
   }
 }
@@ -2884,14 +3046,6 @@ 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;
@@ -2900,7 +3054,7 @@ function diffRpcs(oldRpcs, newRpcs, changes) {
         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)`
+        message: `rpc ${oldR.name}: wire id changed (${oldR.index} -> ${newR.index}) \u2014 RPC ids are your declaration order, so moving a declaration moves an id and calls would reach the wrong handler (breaking)`
       });
     }
     if (oldR.direction !== newR.direction) {
@@ -2946,7 +3100,7 @@ function diffMessages(oldMessages, newMessages, changes) {
         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)`
+        message: `message ${oldM.name}: wire index changed (${oldM.index} -> ${newM.index}) \u2014 message indices are your declaration order, so peers would decode this one as another (breaking)`
       });
     }
     diffFields(oldM.fields, newM.fields, `message.${oldM.name}`, changes);
@@ -3193,15 +3347,18 @@ export {
   EntityCollection,
   ID_MAX_BYTES,
   MAX_MESSAGES,
+  MAX_USER_RPCS,
   PHYSICS_BODY_CHANNELS,
   RESERVED_COLLECTION_NAMES,
   RESERVED_RPC_NAMES,
+  RESERVED_RPC_PREFIX,
   SERVER_OWNER,
   SINGLETON_ID,
   angleFrom2d,
   applyChannel2d,
   applyDelta,
   bool,
+  breakingIsWireOnly,
   bytesEqual,
   canonicalOwnership,
   canonicalPhysics,
@@ -3252,6 +3409,7 @@ export {
   parseHold,
   physicsFromCanonical,
   readValue,
+  reconcileCollection,
   ref,
   schemaFromCanonical,
   server,
@@ -3266,6 +3424,7 @@ export {
   u16,
   u32,
   u8,
+  utf8Length,
   validateForDeploy,
   validateValue,
   walkDelta,

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@irtio/schema",
-  "version": "0.11.0",
+  "version": "3.0.0",
   "description": "irtio schema DSL, type inference, canonical hash, codec, change tracking, and schema diff",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alex-irt/irtio.git",
+    "directory": "packages/schema"
+  },
   "publishConfig": {
     "access": "public"
   },