@irtio/schema 3.1.1 → 4.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @irtio/schema
+
+Define shared multiplayer state, typed RPCs, and messages. The same schema supplies TypeScript
+types and binary encoding for your room and its clients.
+
+```bash
+npm install @irtio/schema
+```
+
+## Define state and an RPC
+
+Create `irtio/schema.ts`:
+
+```ts
+import { defineSchema, entity, f32, server, singleton, u32 } from '@irtio/schema';
+
+export const schema = defineSchema(
+  {
+    players: entity({ x: f32, y: f32 }),
+    match: singleton({ round: u32 }),
+  },
+  {
+    roles: ['player'] as const,
+    rpc: {
+      nextRound: server({}),
+    },
+  },
+);
+```
+
+`players` contains records addressed by id. `match` is one server-owned object. `nextRound`
+declares a client-to-server call; implement it with `defineRoom` from `@irtio/server`.
+For a deployed project, use the project id generated by `irtio init` in the schema options.
+
+## Choose a schema primitive
+
+| Export | Use |
+| --- | --- |
+| `entity(fields, options?)` | Records with ids, ownership, and optional visibility rules |
+| `singleton(fields, options?)` | One object, written by the server |
+| `bool`, `u8`, `u16`, `u32`, `i32`, `f32`, `f64` | Boolean and numeric fields |
+| `str(maxBytes)` | A UTF-8 string with a byte limit |
+| `enumOf(...)`, `struct(...)`, `list(...)`, `ref(...)` | Enums, nested values, bounded lists, and references |
+| `server(spec)`, `client(spec)` | RPC declarations in either direction |
+| `State<typeof schema>` | The inferred server state type |
+
+A schema validates shape and bounds. Authorize actions and validate gameplay in room handlers.
+Append new RPCs and messages to their declaration maps to preserve existing wire ids.
+
+For codec and tooling integrations, the package also exports state creation, snapshot and delta
+codecs, change tracking, canonical schema reconstruction, and schema diffing. Use the client SDK
+and room API to manage these during normal gameplay.
+
+See the [schema reference](https://irt.io/docs/reference/schema) for field signatures, collection
+options, defaults, and migration rules, or start with the
+[quickstart](https://irt.io/docs/getting-started).

package/dist/index.d.ts

@@ -123,6 +123,11 @@ declare function normalizeValue(d: TypeDesc, v: unknown, path?: string): unknown
  * 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.
  *
+ * That makes `intents` the owner-write list rather than a force list, which surprises people: a
+ * field the owner writes and the step never reads — a cosmetic `yaw`, a held emote — still goes
+ * in `intents`, because that is the only way to make a field of a body-backed collection writable
+ * at all. Listing a non-force there is correct, not a misuse.
+ *
  * 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
@@ -143,7 +148,12 @@ type PhysicsBodyMap = {
 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. */
+    /**
+     * The owner-write list: every field the owning client may write. Usually inputs the step
+     * consumes, but not only — a purely cosmetic owned field (a `yaw` nothing simulates, a chosen
+     * colour) belongs here too, because this list *is* how a field on a body-backed collection
+     * becomes writable. Declaration order is the canonical order.
+     */
     readonly intents?: readonly string[];
 }
 /** Compiled form on `CollectionDesc.physics`. */
@@ -282,10 +292,22 @@ declare function ownershipFromCanonical(at: string, raw: unknown): OwnershipOpti
 
 /**
  * `'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`.
+ * its rows are never encoded into a snapshot or a delta. The collection's definition — its name
+ * and field names — is still part of the schema the server and every client share, so the names
+ * are public and only the values are private. 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';
+/**
+ * `'owner'` is per-record, not per-role: an entity record is visible to the one client that owns
+ * it — the first-class ownership every entity record already carries, the thing `perPlayer`,
+ * `requestOwnership` and `ctx.owner` all speak about — and to the server. Its adds and removes are
+ * scoped the same way, so a client never learns another client's record exists, and a transfer of
+ * ownership reaches the old owner as a `remove` and the new one as an `add`. A record left
+ * server-owned (`SERVER_OWNER`, the empty string) is owned by no client and is therefore visible
+ * to none. It is entity-only — a singleton has no owner — and takes no `roles` and no `grid`.
+ */
+type Visibility = 'all' | 'role' | 'spatial-grid' | 'server' | 'owner';
 interface GridOptions<K extends string = string> {
     /** Numeric fields containing the entity's world position. */
     readonly x: K;
@@ -304,7 +326,8 @@ interface EntityOptions {
     readonly serverOwned?: boolean;
     /**
      * `'all'` (default) | `'role'` (per-role views, needs `roles`) | `'spatial-grid'` (per-client
-     * AOI) | `'server'` (room-private: no client sees or writes it).
+     * AOI) | `'server'` (room-private: no client sees or writes it) | `'owner'` (per-record: the
+     * client that owns the record, and the server).
      */
     readonly visibility?: Visibility;
     /** With `visibility: 'role'`: the roles that see this collection. */
@@ -361,6 +384,17 @@ interface EntityOptions {
      * Server behaviour, so it is part of the canonical form and the hash — unlike `predicted`.
      */
     readonly perPlayer?: boolean;
+    /**
+     * M8 proposal 13: the fields of this per-player record that outlive the room.
+     *
+     * On a relay-with-state project a client that joins with a verified identity assertion has these
+     * fields hydrated from a per-(project, subject) blob, and they are written back when the player
+     * leaves. Anonymous joins get schema defaults and write nothing. Requires `perPlayer: true`, the
+     * named fields must exist, and their worst-case encoded size must fit `PERSIST_BLOB_BYTES`.
+     *
+     * Server behaviour — hydration shape — so it is part of the canonical form and the hash.
+     */
+    readonly persist?: readonly string[];
     /**
      * D77: clients may `add` records to this collection (the adder becomes the owner, with the id
      * it chose) and the owner may `remove` one. Off by default, which is what every collection
@@ -387,8 +421,10 @@ interface EntityOptions {
      * 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.
+     * both are refused. Refused on a `physics` collection too, and for the same reason: the owner
+     * writes only the fields in `physics.intents`, so every other field is already server-only.
+     * (`physics.intents` is the owner-write list, not a force list — an owned field the step never
+     * reads, a cosmetic `yaw` say, goes in `intents` too. That is how it becomes writable.)
      *
      * 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.
@@ -413,6 +449,21 @@ declare function entity<F extends Fields, const O extends EntityOptions>(fields:
 /** Exactly one instance; same `serverOwned`/`visibility` options. */
 declare function singleton<F extends Fields>(fields: F): SingletonDef<F, {}>;
 declare function singleton<F extends Fields, const O extends EntityOptions>(fields: F, options: O): SingletonDef<F, O>;
+/**
+ * The hard cap on one player's persistence blob, in encoded bytes.
+ *
+ * A compile that could exceed it is refused here rather than at the first leave that would have
+ * written an oversize blob: a cap discovered in production is a cap nobody can act on.
+ */
+declare const PERSIST_BLOB_BYTES: number;
+/**
+ * The worst-case encoded size of `names` out of `fields`, in bytes.
+ *
+ * Static and deliberately pessimistic: every bound is the largest value the declared type can
+ * hold, so a schema that compiles can never write a blob over the cap. Mirrors `codec.ts`'s
+ * writers — LEB128 varints for list and string lengths, one presence byte for `.opt`.
+ */
+declare function maxEncodedBytes(fields: readonly FieldDesc[], names: readonly string[]): number;
 type RpcDirection = 'server' | 'client';
 interface RpcDef<Dir extends RpcDirection = RpcDirection, P extends Fields = Fields, R extends Fields | undefined = Fields | undefined> {
     readonly kind: 'rpc';
@@ -484,6 +535,11 @@ interface CollectionDesc {
     readonly physics: PhysicsDesc | undefined;
     /** D77: one record per joined client, owned by them. In the hash. */
     readonly perPlayer: boolean;
+    /**
+     * M8 proposal 13: the per-player fields that outlive the room, sorted, or `undefined` when none
+     * were declared. In the hash when present.
+     */
+    readonly persist: readonly string[] | undefined;
     /** D77: clients may add records here and their owner may remove them. In the hash. */
     readonly clientCreate: boolean;
     /** D77: the compiled transfer and leave rules. `undefined` when none were declared. In the hash. */
@@ -793,12 +849,30 @@ type State<S> = {
 type RolesOf<O extends EntityOptions> = O extends {
     roles: readonly (infer R)[];
 } ? R : never;
-/** Is collection with options `O` visible to `Role`? */
+/**
+ * Is a collection with options `O` visible to `Role`?
+ *
+ * `server` is never visible. A `role` collection is visible when `Role` **overlaps** its roles,
+ * not when `Role` is wholly contained in them — and that distinction is the whole point.
+ *
+ * The default `Role` on {@link ClientState} is the union of every role the schema declares. Under
+ * containment, `['host' | 'guest'] extends ['host']` is false, so a bare `ClientState<S>` dropped
+ * *every* role-visible collection and reading one needed a cast — even though a hidden collection
+ * is present at runtime (the wire has a slot for every collection; a client without the role just
+ * receives it empty or default-valued). Overlap gives the bare default all of them, which is what
+ * the runtime hands you, while `ClientState<S, 'hunter'>` still excludes anything scoped only to
+ * other roles, which is what a role-narrowed view is for.
+ *
+ * `spatial-grid` and `owner` are `true` for every role, for the same reason: they scope *entities*,
+ * not collections. The collection is present in every client's state — empty, or holding only the
+ * ids that client's AOI or ownership entitles it to — and the filtering happens at runtime, which
+ * no role-indexed type can express.
+ */
 type VisibleTo<O extends EntityOptions, Role extends string> = O extends {
     visibility: 'server';
 } ? false : O extends {
     visibility: 'role';
-} ? [Role] extends [RolesOf<O>] ? true : false : true;
+} ? [Extract<Role, RolesOf<O>>] extends [never] ? false : true : true;
 type VisibleKeys<S, Role extends string> = {
     [K in keyof SchemaDefs<S>]: VisibleTo<DefOptions<SchemaDefs<S>[K]>, Role> extends true ? K : never;
 }[keyof SchemaDefs<S>];
@@ -1258,4 +1332,4 @@ declare function diffSchemas(oldSchema: AnySchema, newSchema: AnySchema): Schema
  */
 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 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 };
+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, PERSIST_BLOB_BYTES, 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, maxEncodedBytes, 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

@@ -699,11 +699,95 @@ function compileServerFields(name, kind, fields, o) {
   }
   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`
+      `${name}: serverFields is redundant on a physics collection \u2014 the owner writes only the fields in physics.intents, so every other field is already server-only. Remove serverFields`
     );
   }
   return new Set([...out].sort());
 }
+var PERSIST_BLOB_BYTES = 4 * 1024;
+function maxEncodedBytes(fields, names) {
+  const byName = new Map(fields.map((f) => [f.name, f]));
+  let total = 0;
+  for (const n of names) {
+    const f = byName.get(n);
+    if (f) total += worstCase(f.type);
+  }
+  return total;
+}
+function varintBytes(max) {
+  let bytes = 1;
+  let v = Math.max(0, Math.floor(max));
+  while (v > 127) {
+    v = Math.floor(v / 128);
+    bytes++;
+  }
+  return bytes;
+}
+function worstCase(d) {
+  const presence = d.opt ? 1 : 0;
+  switch (d.kind) {
+    case "bool":
+    case "u8":
+    case "enum":
+      return presence + 1;
+    case "u16":
+      return presence + 2;
+    case "u32":
+    case "i32":
+    case "f32":
+      return presence + 4;
+    case "f64":
+      return presence + 8;
+    case "str":
+      return presence + varintBytes(d.max) + d.max;
+    case "ref":
+      return presence + varintBytes(ID_MAX_BYTES) + ID_MAX_BYTES;
+    case "list":
+      return presence + varintBytes(d.max) + d.max * worstCase(d.item);
+    case "struct": {
+      let n = presence;
+      for (const fd of Object.values(d.fields)) n += worstCase(fd);
+      return n;
+    }
+  }
+}
+function compilePersist(name, fields, perPlayer, declared) {
+  if (declared === void 0) return void 0;
+  if (!Array.isArray(declared)) {
+    throw new Error(`${name}: persist must be an array of field names`);
+  }
+  if (!perPlayer) {
+    throw new Error(
+      `${name}: persist requires perPlayer \u2014 only a per-player record has a player to follow`
+    );
+  }
+  if (declared.length === 0) {
+    throw new Error(`${name}: persist is empty; leave it off instead`);
+  }
+  const known = new Map(fields.map((f) => [f.name, f]));
+  const out = [];
+  for (const field of declared) {
+    if (typeof field !== "string" || !known.has(field)) {
+      throw new Error(
+        `${name}: persist names ${JSON.stringify(field)}, which is not a field of ${name}`
+      );
+    }
+    if (out.includes(field)) throw new Error(`${name}: persist names ${field} twice`);
+    if (known.get(field).type.kind === "ref") {
+      throw new Error(
+        `${name}: persist names ${field}, an entity ref \u2014 a ref is an id inside one room and means nothing in the next one`
+      );
+    }
+    out.push(field);
+  }
+  const bytes = maxEncodedBytes(fields, out);
+  if (bytes > PERSIST_BLOB_BYTES) {
+    throw new Error(
+      `${name}: persist fields can encode up to ${bytes} bytes, over the 4 KB persistence cap`
+    );
+  }
+  return out.sort();
+}
 function checkFields(fields) {
   const names = Object.keys(fields);
   if (names.length === 0) throw new Error("entity/singleton needs at least one field");
@@ -762,6 +846,7 @@ function defineSchema(defs, options = {}) {
       );
     }
     const ownership = o.ownership || perPlayer ? compileOwnership(name, def.kind, fields, o.ownership ?? {}, perPlayer) : void 0;
+    const persist = compilePersist(name, fields, perPlayer, o.persist);
     const serverFields = compileServerFields(name, def.kind, fields, o);
     return {
       name,
@@ -772,6 +857,7 @@ function defineSchema(defs, options = {}) {
       serverOwned: o.serverOwned === true,
       serverFields,
       perPlayer,
+      persist,
       clientCreate: o.clientCreate === true,
       ownership,
       visibility: o.visibility ?? "all",
@@ -982,6 +1068,10 @@ function canonicalize(s) {
       // writes `upgrades` disagree about the world.
       serverFields: c.serverFields ? [...c.serverFields] : void 0,
       perPlayer: c.perPlayer ? true : void 0,
+      // M8 proposal 13: the same only-when-declared rule again. In the hash when present because
+      // it is hydration shape: a room that fills a field from a blob and a client that does not
+      // expect it to be filled disagree about the world.
+      persist: c.persist ? [...c.persist] : void 0,
       clientCreate: c.clientCreate ? true : void 0,
       ownership: c.ownership ? canonicalOwnership(c.ownership) : void 0
       // ---- end M6 lane K ----
@@ -1075,6 +1165,26 @@ function validateForDeploy(schema) {
         message: `${c.name}: grid is only valid with visibility 'spatial-grid'`
       });
     }
+    if (c.visibility === "owner") {
+      if (c.kind !== "entity") {
+        issues.push({
+          level: "error",
+          message: `${c.name}: owner visibility is entity-only \u2014 a singleton has no owner`
+        });
+      }
+      if (c.roles && c.roles.length > 0) {
+        issues.push({
+          level: "error",
+          message: `${c.name}: visibility 'owner' takes no roles \u2014 it is scoped by record ownership, not by role`
+        });
+      }
+      if (c.serverOwned) {
+        issues.push({
+          level: "warning",
+          message: `${c.name}: visibility 'owner' on a serverOwned collection \u2014 every record stays server-owned, so no client ever sees one`
+        });
+      }
+    }
     if (c.visibility === "server" && c.roles && c.roles.length > 0) {
       issues.push({
         level: "error",
@@ -1236,7 +1346,7 @@ function typeOf(t, at) {
 }
 function entityOptions(e, name) {
   const visibility = stringAt(e, "visibility");
-  if (visibility !== "all" && visibility !== "role" && visibility !== "spatial-grid" && visibility !== "server") {
+  if (visibility !== "all" && visibility !== "role" && visibility !== "spatial-grid" && visibility !== "server" && visibility !== "owner") {
     throw new Error(
       `schemaFromCanonical: ${name}: unknown visibility ${JSON.stringify(visibility)}`
     );
@@ -1250,6 +1360,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 persist = e.persist === void 0 || e.persist === null ? void 0 : arrayAtRaw(e, "persist").map((f) => {
+    if (typeof f !== "string")
+      throw new Error(`schemaFromCanonical: ${name}: persist must be strings`);
+    return f;
+  });
   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`);
@@ -1263,6 +1378,7 @@ function entityOptions(e, name) {
     ...physics !== void 0 ? { physics } : {},
     // ---- M6 lane K: stateful relay ----
     ...e.perPlayer === true ? { perPlayer: true } : {},
+    ...persist !== void 0 ? { persist } : {},
     ...e.clientCreate === true ? { clientCreate: true } : {},
     ...ownership !== void 0 ? { ownership } : {},
     // ---- end M6 lane K ----
@@ -3348,6 +3464,7 @@ export {
   ID_MAX_BYTES,
   MAX_MESSAGES,
   MAX_USER_RPCS,
+  PERSIST_BLOB_BYTES,
   PHYSICS_BODY_CHANNELS,
   RESERVED_COLLECTION_NAMES,
   RESERVED_RPC_NAMES,
@@ -3401,6 +3518,7 @@ export {
   markOwner,
   markPath,
   markRemove,
+  maxEncodedBytes,
   mergeDirty,
   mergeMask,
   normalizeRecord,

package/package.json

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