@irtio/schema 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -200,6 +200,80 @@ declare function applyChannel2d(channel: PhysicsBodyChannel, value: number, targ
     wz: number;
 }): void;
 
+/**
+ * M6 lane K (D77): the declarative ownership policies a collection may declare.
+ *
+ * A relay room with state has no room file, so the three things a rung-1 room file exists for —
+ * add one record per player, remove it when they go, and decide contested handovers — have to be
+ * declarations instead. These are those declarations, compiled the way `physics` is compiled: a
+ * literal in the schema, a descriptor on the collection, and a canonical fragment that is emitted
+ * **only when declared**, so every schema written before this keeps the hash it had.
+ *
+ * They are server behaviour, not rendering behaviour, which is why they join the hash at all: a
+ * client and a room that disagree about who may take a crate disagree about the world, the way
+ * they would about `physics`, and not the way they would about `interpolate`.
+ *
+ * Nothing here reads state. Compilation is pure and the descriptors are plain data, so the same
+ * declaration means the same thing in a coded room, in the relay host, and in a test.
+ */
+
+/** How a contested record changes hands. `free | closer | ask | never` (D77). */
+type OwnershipTransfer = 'free' | 'closer' | 'ask' | 'never';
+/** What happens to a held record when its hold runs out. */
+type OwnershipLeaveAction = 'release' | 'nearest' | 'random' | 'remove';
+/** The fields `closer` and `nearest` read positions from. Same shape `spatial-grid` uses. */
+interface OwnershipPosition {
+    /** A numeric field of this collection: the object's x. */
+    readonly x: string;
+    /** A numeric field of this collection: the object's y. */
+    readonly y: string;
+    /** The entity collection holding one record per player, keyed by client id. */
+    readonly players: string;
+}
+/**
+ * Hold, then act. When a player's presence is removed, every record they own is held for `hold`
+ * (still theirs, still visible, unwritable and untakeable by anyone else); when the hold expires,
+ * `then` fires. `hold: 0` — the default — makes `then` fire at once.
+ */
+interface OwnershipLeave {
+    /** `'5m'`, `'30s'`, `'2h'`, or milliseconds as a number. Default `0`. */
+    readonly hold?: string | number;
+    /** Default `'release'`, except on a `perPlayer` collection where it is `'remove'`. */
+    readonly then?: OwnershipLeaveAction;
+}
+interface OwnershipOptions {
+    /** Default `'free'`'s opposite: with no `ownership` declared at all the old rule applies. */
+    readonly transfer?: OwnershipTransfer;
+    /** `closer`'s flap guard: the requester must be nearer by at least this many world units. */
+    readonly by?: number;
+    /** Required by `transfer: 'closer'` and by `onLeave.then: 'nearest'`. */
+    readonly position?: OwnershipPosition;
+    readonly onLeave?: OwnershipLeave;
+}
+/** The compiled form. `holdMs` is milliseconds, always; `then` is always resolved. */
+interface OwnershipDesc {
+    readonly transfer: OwnershipTransfer;
+    readonly by: number;
+    readonly position: OwnershipPosition | undefined;
+    readonly holdMs: number;
+    readonly then: OwnershipLeaveAction;
+}
+/** A hold window, in milliseconds. Accepts `'5m'`-style strings and plain millisecond numbers. */
+declare function parseHold(at: string, raw: string | number | undefined): number;
+/**
+ * Compiles one collection's `ownership` declaration, refusing the combinations that cannot mean
+ * anything. Cross-collection checks (does `position.players` name an entity?) happen in
+ * `defineSchema`, once every collection is compiled.
+ */
+declare function compileOwnership(name: string, kind: 'entity' | 'singleton', fields: readonly FieldDesc[], options: OwnershipOptions, perPlayer: boolean): OwnershipDesc;
+/**
+ * The canonical fragment. `hold` is emitted in milliseconds so the round trip through
+ * `schemaFromCanonical` is exact whichever spelling the author used.
+ */
+declare function canonicalOwnership(o: OwnershipDesc): Record<string, unknown>;
+/** Reads a canonical ownership fragment back (`schemaFromCanonical`). */
+declare function ownershipFromCanonical(at: string, raw: unknown): OwnershipOptions;
+
 /**
  * `entity`, `singleton`, `server`, `client`, `defineSchema`, and the compiled schema
  * (ordered collection descriptors, sorted RPC table, canonical form, hash).
@@ -269,6 +343,27 @@ interface EntityOptions {
      * world. Requires `physics:` on the room config; the runtime rejects the pairing otherwise.
      */
     readonly physics?: EntityPhysics;
+    /**
+     * D77: one record per joined client, id = the client id, owned by them. The runtime adds it on
+     * join and applies `ownership.onLeave` when the player goes, which is what replaces a room
+     * file's `onJoin`/`onLeave` pair. Defaults its leave rule to `{ hold: 0, then: 'remove' }` and
+     * accepts no other `then`, because a per-player record cannot belong to someone else.
+     *
+     * Server behaviour, so it is part of the canonical form and the hash — unlike `predicted`.
+     */
+    readonly perPlayer?: boolean;
+    /**
+     * 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
+     * written before this is: `add` and `remove` from a client are refused by name.
+     */
+    readonly clientCreate?: boolean;
+    /**
+     * D77: how a contested record changes hands, and what happens to it when its owner leaves.
+     * Absent means the old rule and nothing else: `requestOwnership` grants only when the record is
+     * unowned, and a leaving player's records keep their (now absent) owner.
+     */
+    readonly ownership?: OwnershipOptions;
 }
 interface EntityDef<F extends Fields = Fields, O extends EntityOptions = EntityOptions> {
     readonly kind: 'entity';
@@ -351,6 +446,12 @@ interface CollectionDesc {
     readonly proxy: boolean;
     /** D22 body/intent field split, compiled. `undefined` for ordinary collections. In the hash. */
     readonly physics: PhysicsDesc | undefined;
+    /** D77: one record per joined client, owned by them. In the hash. */
+    readonly perPlayer: boolean;
+    /** 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. */
+    readonly ownership: OwnershipDesc | undefined;
 }
 interface RpcDesc {
     readonly name: string;
@@ -1010,4 +1111,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 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 };
+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 };

package/dist/index.js

@@ -369,6 +369,141 @@ function applyChannel2d(channel, value, target) {
   }
 }
 
+// src/policy.ts
+var DURATION_RE = /^(\d+)(ms|s|m|h|d)$/;
+var UNIT_MS = {
+  ms: 1,
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5
+};
+function parseHold(at, raw) {
+  if (raw === void 0) return 0;
+  if (typeof raw === "number") {
+    if (!Number.isFinite(raw) || raw < 0 || !Number.isInteger(raw)) {
+      throw new Error(`${at}: ownership.onLeave.hold must be a non-negative whole ms, got ${raw}`);
+    }
+    return raw;
+  }
+  const m = DURATION_RE.exec(raw);
+  if (!m) {
+    throw new Error(
+      `${at}: ownership.onLeave.hold must be a duration like '30s', '5m', '2h' or milliseconds, got ${JSON.stringify(raw)}`
+    );
+  }
+  return Number(m[1]) * UNIT_MS[m[2]];
+}
+var NUMERIC = /* @__PURE__ */ new Set(["u8", "u16", "u32", "i32", "f32", "f64"]);
+function compileOwnership(name, kind, fields, options, perPlayer) {
+  const at = name;
+  if (kind !== "entity") {
+    throw new Error(`${at}: ownership is entity-only \u2014 a singleton has no per-record owner`);
+  }
+  const transfer = options.transfer ?? (perPlayer ? "never" : "free");
+  if (!["free", "closer", "ask", "never"].includes(transfer)) {
+    throw new Error(
+      `${at}: ownership.transfer must be 'free', 'closer', 'ask' or 'never', got ${JSON.stringify(
+        transfer
+      )}`
+    );
+  }
+  const then = options.onLeave?.then ?? (perPlayer ? "remove" : "release");
+  if (!["release", "nearest", "random", "remove"].includes(then)) {
+    throw new Error(
+      `${at}: ownership.onLeave.then must be 'release', 'nearest', 'random' or 'remove', got ` + JSON.stringify(then)
+    );
+  }
+  if (perPlayer && then !== "remove") {
+    throw new Error(
+      `${at}: a perPlayer collection only accepts onLeave.then: 'remove' \u2014 a per-player record cannot belong to someone else`
+    );
+  }
+  const holdMs = parseHold(at, options.onLeave?.hold);
+  const position = options.position;
+  if ((transfer === "closer" || then === "nearest") && position === void 0) {
+    throw new Error(
+      `${at}: ownership.position: { x, y, players } is required by transfer: 'closer' and by onLeave.then: 'nearest' \u2014 there is no other way to know who is nearer`
+    );
+  }
+  if (options.by !== void 0) {
+    if (transfer !== "closer") {
+      throw new Error(
+        `${at}: ownership.by is the 'closer' flap guard and means nothing without it`
+      );
+    }
+    if (!Number.isFinite(options.by) || options.by < 0) {
+      throw new Error(`${at}: ownership.by must be a non-negative finite number`);
+    }
+  }
+  if (position !== void 0) {
+    for (const axis of ["x", "y"]) {
+      const field = fields.find((f) => f.name === position[axis]);
+      if (!field || !NUMERIC.has(field.type.kind)) {
+        throw new Error(`${at}: ownership.position.${axis} must name a numeric field of ${at}`);
+      }
+    }
+    if (typeof position.players !== "string" || position.players === "") {
+      throw new Error(`${at}: ownership.position.players must name an entity collection`);
+    }
+  }
+  return {
+    transfer,
+    by: options.by ?? 0,
+    position: position ? { x: position.x, y: position.y, players: position.players } : void 0,
+    holdMs,
+    then
+  };
+}
+function canonicalOwnership(o) {
+  return {
+    transfer: o.transfer,
+    ...o.by !== 0 ? { by: o.by } : {},
+    ...o.position ? { position: { x: o.position.x, y: o.position.y, players: o.position.players } } : {},
+    // `then` is the owner-decided name for the leave action in the D77 spec, and this is plain
+    // data that is never awaited.
+    // biome-ignore lint/suspicious/noThenProperty: see above
+    onLeave: { hold: o.holdMs, then: o.then }
+  };
+}
+function ownershipFromCanonical(at, raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`${at}: ownership must be an object`);
+  }
+  const o = raw;
+  const transfer = o.transfer;
+  if (typeof transfer !== "string") throw new Error(`${at}: ownership.transfer must be a string`);
+  const leaveRaw = o.onLeave;
+  if (typeof leaveRaw !== "object" || leaveRaw === null || Array.isArray(leaveRaw)) {
+    throw new Error(`${at}: ownership.onLeave must be an object`);
+  }
+  const leave = leaveRaw;
+  if (typeof leave.hold !== "number")
+    throw new Error(`${at}: ownership.onLeave.hold must be a ms number`);
+  if (typeof leave.then !== "string")
+    throw new Error(`${at}: ownership.onLeave.then must be a string`);
+  let position;
+  if (o.position !== void 0 && o.position !== null) {
+    const p = o.position;
+    if (typeof p.x !== "string" || typeof p.y !== "string" || typeof p.players !== "string") {
+      throw new Error(`${at}: ownership.position needs string x, y and players`);
+    }
+    position = { x: p.x, y: p.y, players: p.players };
+  }
+  const by = o.by;
+  if (by !== void 0 && typeof by !== "number")
+    throw new Error(`${at}: ownership.by must be a number`);
+  return {
+    transfer,
+    ...by !== void 0 ? { by } : {},
+    ...position !== void 0 ? { position } : {},
+    // `then` is the owner-decided name for the leave action in the D77 spec, and this is plain
+    // data that is never awaited.
+    // biome-ignore lint/suspicious/noThenProperty: see above
+    onLeave: { hold: leave.hold, then: leave.then }
+  };
+}
+
 // src/sha256.ts
 var K = new Uint32Array([
   1116352408,
@@ -565,6 +700,19 @@ function defineSchema(defs, options = {}) {
         `${name}: proxy needs physics \u2014 only body-backed collections get a body in a client's local world`
       );
     }
+    const perPlayer = o.perPlayer === true;
+    if (perPlayer && def.kind !== "entity") {
+      throw new Error(`${name}: perPlayer is entity-only \u2014 a singleton has no per-player record`);
+    }
+    if (o.clientCreate === true && def.kind !== "entity") {
+      throw new Error(`${name}: clientCreate is entity-only \u2014 a singleton is never added`);
+    }
+    if ((perPlayer || o.clientCreate === true || o.ownership) && o.serverOwned === true) {
+      throw new Error(
+        `${name}: perPlayer, clientCreate and ownership all describe client ownership, which a serverOwned collection does not have`
+      );
+    }
+    const ownership = o.ownership || perPlayer ? compileOwnership(name, def.kind, fields, o.ownership ?? {}, perPlayer) : void 0;
     return {
       name,
       index,
@@ -572,6 +720,9 @@ function defineSchema(defs, options = {}) {
       fields,
       fieldIndex: new Map(fields.map((f) => [f.name, f.index])),
       serverOwned: o.serverOwned === true,
+      perPlayer,
+      clientCreate: o.clientCreate === true,
+      ownership,
       visibility: o.visibility ?? "all",
       roles: o.roles ? [...o.roles] : void 0,
       grid: o.grid ? {
@@ -591,6 +742,26 @@ function defineSchema(defs, options = {}) {
   for (const c of collections) {
     for (const f of c.fields) checkRefs(f.type, entityNames, `${c.name}.${f.name}`);
   }
+  for (const c of collections) {
+    const players = c.ownership?.position?.players;
+    if (players === void 0) continue;
+    const target = collections.find((o) => o.name === players);
+    if (!target || target.kind !== "entity") {
+      throw new Error(
+        `${c.name}: ownership.position.players ${JSON.stringify(players)} does not name an entity collection in this schema`
+      );
+    }
+    const position = c.ownership?.position;
+    if (!position) continue;
+    for (const axis of ["x", "y"]) {
+      const field = target.fields.find((f) => f.name === position[axis]);
+      if (!field || !["u8", "u16", "u32", "i32", "f32", "f64"].includes(field.type.kind)) {
+        throw new Error(
+          `${c.name}: ownership.position.${axis} must name a numeric field of BOTH ${c.name} and ${players} \u2014 the comparison is between an object and a player`
+        );
+      }
+    }
+  }
   const rpcMap = options.rpc ?? {};
   for (const n of Object.keys(rpcMap)) {
     assertFieldName(n);
@@ -738,7 +909,17 @@ function canonicalize(s) {
       } : void 0,
       // Emitted only when declared: `stableStringify` drops `undefined`, so every schema written
       // before D22 keeps the byte-identical canonical form — and therefore the hash — it had.
-      physics: c.physics ? canonicalPhysics(c.physics) : void 0
+      physics: c.physics ? canonicalPhysics(c.physics) : void 0,
+      // ---- M6 lane K: stateful relay ----
+      // D77: the same only-when-declared rule as `grid`, `physics` and `messages`, for the same
+      // reason — every schema written before ownership policies existed keeps the byte-identical
+      // 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.
+      perPlayer: c.perPlayer ? true : void 0,
+      clientCreate: c.clientCreate ? true : void 0,
+      ownership: c.ownership ? canonicalOwnership(c.ownership) : void 0
+      // ---- end M6 lane K ----
       // 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
@@ -997,12 +1178,18 @@ 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);
   return {
     serverOwned: e.serverOwned === true,
     visibility,
     ...roles !== void 0 ? { roles } : {},
     ...grid !== void 0 ? { grid } : {},
-    ...physics !== void 0 ? { physics } : {}
+    ...physics !== void 0 ? { physics } : {},
+    // ---- M6 lane K: stateful relay ----
+    ...e.perPlayer === true ? { perPlayer: true } : {},
+    ...e.clientCreate === true ? { clientCreate: true } : {},
+    ...ownership !== void 0 ? { ownership } : {}
+    // ---- end M6 lane K ----
   };
 }
 function gridFromCanonical(name, grid) {
@@ -3016,12 +3203,14 @@ export {
   applyDelta,
   bool,
   bytesEqual,
+  canonicalOwnership,
   canonicalPhysics,
   canonicalType,
   channelOf2d,
   client,
   cloneValue,
   collectionDirty,
+  compileOwnership,
   compilePhysics,
   computeDirty,
   createDirtySet,
@@ -3059,6 +3248,8 @@ export {
   mergeMask,
   normalizeRecord,
   normalizeValue,
+  ownershipFromCanonical,
+  parseHold,
   physicsFromCanonical,
   readValue,
   ref,

package/package.json

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