@irtio/schema 0.1.0

package/dist/index.js

@@ -0,0 +1,2524 @@
+// src/types.ts
+var TypeImpl = class _TypeImpl {
+  constructor(desc) {
+    this.desc = desc;
+  }
+  desc;
+  get opt() {
+    return new _TypeImpl({ ...this.desc, opt: true });
+  }
+  default(value) {
+    if (value === void 0) {
+      throw new Error(".default(undefined) is not a default \u2014 use .opt on its own");
+    }
+    const err = validateValue(this.desc, value);
+    if (err) throw new Error(`invalid default for ${describeType(this.desc)}: ${err}`);
+    return new _TypeImpl({ ...this.desc, hasDefault: true, default: value });
+  }
+};
+function make(desc) {
+  return new TypeImpl({ ...desc, opt: false, hasDefault: false });
+}
+var bool = make({ kind: "bool" });
+var u8 = make({ kind: "u8" });
+var u16 = make({ kind: "u16" });
+var u32 = make({ kind: "u32" });
+var i32 = make({ kind: "i32" });
+var f32 = make({ kind: "f32" });
+var f64 = make({ kind: "f64" });
+function str(max) {
+  assertMax(max, "str");
+  return make({ kind: "str", max });
+}
+function enumOf(...values) {
+  if (values.length === 0) throw new Error("enumOf needs at least one value");
+  if (values.length > 256) throw new Error("enumOf supports at most 256 values");
+  if (new Set(values).size !== values.length) throw new Error("enumOf values must be unique");
+  return make({ kind: "enum", values: [...values] });
+}
+function ref(entity2) {
+  return make({ kind: "ref", entity: entity2 });
+}
+function list(item, max) {
+  assertMax(max, "list");
+  return make({ kind: "list", item: item.desc, max });
+}
+function struct(fields) {
+  const descs = {};
+  for (const [k, t] of Object.entries(fields)) {
+    assertFieldName(k);
+    descs[k] = t.desc;
+  }
+  return make({ kind: "struct", fields: descs });
+}
+function assertMax(max, what) {
+  if (!Number.isInteger(max) || max < 0 || max > 4294967295) {
+    throw new Error(`${what}(max): max must be a non-negative integer, got ${String(max)}`);
+  }
+}
+function assertFieldName(name) {
+  if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) {
+    throw new Error(`invalid field name ${JSON.stringify(name)}: must be an identifier`);
+  }
+}
+function describeType(d) {
+  let s;
+  switch (d.kind) {
+    case "str":
+      s = `str(${d.max})`;
+      break;
+    case "enum":
+      s = `enumOf(${d.values.map((v) => JSON.stringify(v)).join(", ")})`;
+      break;
+    case "ref":
+      s = `ref(${JSON.stringify(d.entity)})`;
+      break;
+    case "list":
+      s = `list(${describeType(d.item)}, ${d.max})`;
+      break;
+    case "struct":
+      s = `struct({ ${Object.entries(d.fields).map(([k, v]) => `${k}: ${describeType(v)}`).join(", ")} })`;
+      break;
+    default:
+      s = d.kind;
+  }
+  return d.opt ? `${s}.opt` : s;
+}
+var utf8 = new TextEncoder();
+function utf8Length(s) {
+  return utf8.encode(s).length;
+}
+var INT_RANGE = {
+  u8: [0, 255],
+  u16: [0, 65535],
+  u32: [0, 4294967295],
+  i32: [-2147483648, 2147483647]
+};
+var ID_MAX_BYTES = 32;
+function validateValue(d, v, path = "") {
+  if (v === void 0) return d.opt ? null : `${path || "value"} is required`;
+  const at = path || "value";
+  switch (d.kind) {
+    case "bool":
+      return typeof v === "boolean" ? null : `${at} must be a boolean`;
+    case "u8":
+    case "u16":
+    case "u32":
+    case "i32": {
+      if (typeof v !== "number" || !Number.isInteger(v))
+        return `${at} must be an integer (${d.kind})`;
+      const [lo, hi] = INT_RANGE[d.kind];
+      return v < lo || v > hi ? `${at} out of range for ${d.kind}: ${v}` : null;
+    }
+    case "f32":
+    case "f64":
+      return typeof v === "number" ? null : `${at} must be a number`;
+    case "str":
+    case "ref": {
+      if (typeof v !== "string") return `${at} must be a string`;
+      const max = d.kind === "str" ? d.max : ID_MAX_BYTES;
+      const n = utf8Length(v);
+      return n > max ? `${at} exceeds ${max} UTF-8 bytes (${n})` : null;
+    }
+    case "enum":
+      return typeof v === "string" && d.values.includes(v) ? null : `${at} must be one of ${d.values.join("|")}`;
+    case "list": {
+      if (!Array.isArray(v)) return `${at} must be an array`;
+      if (v.length > d.max) return `${at} exceeds max length ${d.max} (${v.length})`;
+      for (let i = 0; i < v.length; i++) {
+        const e = validateValue(d.item, v[i], `${at}[${i}]`);
+        if (e) return e;
+      }
+      return null;
+    }
+    case "struct": {
+      if (typeof v !== "object" || v === null || Array.isArray(v)) return `${at} must be an object`;
+      for (const [k, fd] of Object.entries(d.fields)) {
+        const e = validateValue(fd, v[k], `${at}.${k}`);
+        if (e) return e;
+      }
+      return null;
+    }
+  }
+}
+function defaultValue(d) {
+  if (d.hasDefault) return cloneValue(d.default);
+  if (d.opt) return void 0;
+  switch (d.kind) {
+    case "bool":
+      return false;
+    case "u8":
+    case "u16":
+    case "u32":
+    case "i32":
+    case "f32":
+    case "f64":
+      return 0;
+    case "str":
+    case "ref":
+      return "";
+    case "enum":
+      return d.values[0];
+    case "list":
+      return [];
+    case "struct": {
+      const o = {};
+      for (const [k, fd] of Object.entries(d.fields)) o[k] = defaultValue(fd);
+      return o;
+    }
+  }
+}
+function cloneValue(v) {
+  if (Array.isArray(v)) return v.map(cloneValue);
+  if (v !== null && typeof v === "object") {
+    const o = {};
+    for (const k of Object.keys(v)) o[k] = cloneValue(v[k]);
+    return o;
+  }
+  return v;
+}
+function normalizeValue(d, v, path = "") {
+  const at = path || "value";
+  if (v === void 0) {
+    if (d.hasDefault) return cloneValue(d.default);
+    if (d.opt) return void 0;
+    throw new Error(`${at} is required`);
+  }
+  switch (d.kind) {
+    case "f32": {
+      if (typeof v !== "number") throw new Error(`${at} must be a number`);
+      return Math.fround(v);
+    }
+    case "list": {
+      if (!Array.isArray(v)) throw new Error(`${at} must be an array`);
+      if (v.length > d.max) throw new Error(`${at} exceeds max length ${d.max} (${v.length})`);
+      return v.map((x, i) => normalizeValue(d.item, x, `${at}[${i}]`));
+    }
+    case "struct": {
+      if (typeof v !== "object" || v === null || Array.isArray(v))
+        throw new Error(`${at} must be an object`);
+      const o = {};
+      for (const [k, fd] of Object.entries(d.fields)) {
+        o[k] = normalizeValue(fd, v[k], `${at}.${k}`);
+      }
+      return o;
+    }
+    default: {
+      const err = validateValue(d, v, path);
+      if (err) throw new Error(err);
+      return v;
+    }
+  }
+}
+
+// src/sha256.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function sha256(data) {
+  const len = data.length;
+  const bitLenHi = Math.floor(len * 8 / 4294967296);
+  const bitLenLo = len * 8 >>> 0;
+  const padded = new Uint8Array(len + 9 + 63 >> 6 << 6);
+  padded.set(data);
+  padded[len] = 128;
+  const dv = new DataView(padded.buffer);
+  dv.setUint32(padded.length - 8, bitLenHi);
+  dv.setUint32(padded.length - 4, bitLenLo);
+  const h = new Uint32Array([
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ]);
+  const w = new Uint32Array(64);
+  for (let off = 0; off < padded.length; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = dv.getUint32(off + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const w15 = w[i - 15];
+      const w2 = w[i - 2];
+      const s0 = (w15 >>> 7 | w15 << 25) ^ (w15 >>> 18 | w15 << 14) ^ w15 >>> 3;
+      const s1 = (w2 >>> 17 | w2 << 15) ^ (w2 >>> 19 | w2 << 13) ^ w2 >>> 10;
+      w[i] = w[i - 16] + s0 + w[i - 7] + s1 >>> 0;
+    }
+    let a = h[0];
+    let b = h[1];
+    let c = h[2];
+    let d = h[3];
+    let e = h[4];
+    let f = h[5];
+    let g = h[6];
+    let hh = h[7];
+    for (let i = 0; i < 64; i++) {
+      const S1 = (e >>> 6 | e << 26) ^ (e >>> 11 | e << 21) ^ (e >>> 25 | e << 7);
+      const ch = e & f ^ ~e & g;
+      const t1 = hh + S1 + ch + K[i] + w[i] >>> 0;
+      const S0 = (a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10);
+      const maj = a & b ^ a & c ^ b & c;
+      const t2 = S0 + maj >>> 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = d + t1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 >>> 0;
+    }
+    h[0] = h[0] + a >>> 0;
+    h[1] = h[1] + b >>> 0;
+    h[2] = h[2] + c >>> 0;
+    h[3] = h[3] + d >>> 0;
+    h[4] = h[4] + e >>> 0;
+    h[5] = h[5] + f >>> 0;
+    h[6] = h[6] + g >>> 0;
+    h[7] = h[7] + hh >>> 0;
+  }
+  const out = new Uint8Array(32);
+  const odv = new DataView(out.buffer);
+  for (let i = 0; i < 8; i++) odv.setUint32(i * 4, h[i]);
+  return out;
+}
+function sha256Hex(data) {
+  return toHex(sha256(data));
+}
+function toHex(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += bytes[i].toString(16).padStart(2, "0");
+  return s;
+}
+
+// src/schema.ts
+function entity(fields, options) {
+  checkFields(fields);
+  return { kind: "entity", fields, options: options ?? {} };
+}
+function singleton(fields, options) {
+  checkFields(fields);
+  return { kind: "singleton", fields, options: options ?? {} };
+}
+function checkFields(fields) {
+  const names = Object.keys(fields);
+  if (names.length === 0) throw new Error("entity/singleton needs at least one field");
+  if (names.length > 255) throw new Error("at most 255 fields per entity/singleton");
+  for (const n of names) assertFieldName(n);
+}
+function server(spec = {}) {
+  return makeRpc("server", spec);
+}
+function client(spec = {}) {
+  return makeRpc("client", spec);
+}
+function makeRpc(direction, spec) {
+  const params = spec.params ?? {};
+  for (const n of Object.keys(params)) assertFieldName(n);
+  if (spec.returns) for (const n of Object.keys(spec.returns)) assertFieldName(n);
+  return { kind: "rpc", direction, params, returns: spec.returns };
+}
+var RESERVED_RPC_NAMES = ["requestOwnership"];
+var RESERVED_COLLECTION_NAMES = ["clients"];
+function defineSchema(defs, options = {}) {
+  const names = Object.keys(defs);
+  for (const n of names) {
+    assertFieldName(n);
+    if (RESERVED_COLLECTION_NAMES.includes(n) && !options.allowReservedNames) {
+      throw new Error(`collection name ${JSON.stringify(n)} is reserved by irtio (built-in state)`);
+    }
+  }
+  const collections = [...names].sort().map((name, index) => {
+    const def = defs[name];
+    const fields = compileFields(def.fields);
+    const o = def.options;
+    return {
+      name,
+      index,
+      kind: def.kind,
+      fields,
+      fieldIndex: new Map(fields.map((f) => [f.name, f.index])),
+      serverOwned: o.serverOwned === true,
+      visibility: o.visibility ?? "all",
+      roles: o.roles ? [...o.roles] : void 0
+    };
+  });
+  const entityNames = new Set(collections.filter((c) => c.kind === "entity").map((c) => c.name));
+  for (const c of collections) {
+    for (const f of c.fields) checkRefs(f.type, entityNames, `${c.name}.${f.name}`);
+  }
+  const rpcMap = options.rpc ?? {};
+  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)`);
+    }
+  }
+  const rpcs = Object.keys(rpcMap).sort().map((name, index) => {
+    const r = rpcMap[name];
+    for (const f of Object.values(r.params))
+      checkRefs(f.desc, entityNames, `rpc ${name} params`);
+    if (r.returns)
+      for (const f of Object.values(r.returns))
+        checkRefs(f.desc, entityNames, `rpc ${name} returns`);
+    return {
+      name,
+      index,
+      direction: r.direction,
+      params: compileFields(r.params),
+      returns: r.returns ? compileFields(r.returns) : void 0
+    };
+  });
+  const roles = options.roles ?? [];
+  if (new Set(roles).size !== roles.length) throw new Error("roles must be unique");
+  const canonical = canonicalize({ collections, rpcs, roles });
+  const hashBytes = sha256(new TextEncoder().encode(canonical));
+  const byName = new Map(collections.map((c) => [c.name, c]));
+  return {
+    defs,
+    rpc: rpcMap,
+    roles,
+    project: options.project,
+    collections,
+    collection: (name) => {
+      const c = byName.get(name);
+      if (!c) throw new Error(`unknown collection ${JSON.stringify(name)}`);
+      return c;
+    },
+    rpcs,
+    canonical,
+    hash: toHex(hashBytes),
+    hash8: hashBytes.slice(0, 8)
+  };
+}
+function compileFields(fields) {
+  return Object.entries(fields).map(([name, t], index) => ({ name, index, type: t.desc }));
+}
+function checkRefs(d, entities, at) {
+  switch (d.kind) {
+    case "ref":
+      if (!entities.has(d.entity))
+        throw new Error(`${at}: ref(${JSON.stringify(d.entity)}) does not name an entity`);
+      return;
+    case "list":
+      checkRefs(d.item, entities, at);
+      return;
+    case "struct":
+      for (const [k, fd] of Object.entries(d.fields)) checkRefs(fd, entities, `${at}.${k}`);
+      return;
+    default:
+      return;
+  }
+}
+var CANONICAL_VERSION = 1;
+function canonicalType(d) {
+  const o = { kind: d.kind };
+  if (d.opt) o.opt = true;
+  if (d.hasDefault) o.default = d.default;
+  switch (d.kind) {
+    case "str":
+      o.max = d.max;
+      break;
+    case "enum":
+      o.values = [...d.values];
+      break;
+    case "ref":
+      o.entity = d.entity;
+      break;
+    case "list":
+      o.item = canonicalType(d.item);
+      o.max = d.max;
+      break;
+    case "struct":
+      o.fields = Object.entries(d.fields).map(([name, t]) => ({ name, type: canonicalType(t) }));
+      break;
+    default:
+      break;
+  }
+  return o;
+}
+function canonicalFields(fields) {
+  return fields.map((f) => ({ name: f.name, type: canonicalType(f.type) }));
+}
+function canonicalize(s) {
+  const doc = {
+    canonicalVersion: CANONICAL_VERSION,
+    entities: s.collections.map((c) => ({
+      name: c.name,
+      kind: c.kind,
+      fields: canonicalFields(c.fields),
+      serverOwned: c.serverOwned,
+      visibility: c.visibility,
+      roles: c.roles ? [...c.roles] : null
+    })),
+    rpcs: s.rpcs.map((r) => ({
+      name: r.name,
+      direction: r.direction,
+      params: canonicalFields(r.params),
+      returns: r.returns ? canonicalFields(r.returns) : null
+    })),
+    roles: [...s.roles]
+  };
+  return stableStringify(doc);
+}
+function stableStringify(v) {
+  return stringifyValue(v) ?? "null";
+}
+function stringifyValue(v) {
+  if (Array.isArray(v)) return `[${v.map((x) => stringifyValue(x) ?? "null").join(",")}]`;
+  if (v !== null && typeof v === "object") {
+    const keys = Object.keys(v).sort();
+    const parts = [];
+    for (const k of keys) {
+      const s = stringifyValue(v[k]);
+      if (s !== void 0) parts.push(`${JSON.stringify(k)}:${s}`);
+    }
+    return `{${parts.join(",")}}`;
+  }
+  return JSON.stringify(v);
+}
+function validateForDeploy(schema) {
+  const issues = [];
+  for (const c of schema.collections) {
+    if (c.visibility === "spatial-grid") {
+      issues.push({
+        level: "error",
+        message: `${c.name}: visibility 'spatial-grid' is not yet supported; use 'all' or '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)`
+        });
+      } else {
+        for (const r of c.roles) {
+          if (!schema.roles.includes(r)) {
+            issues.push({
+              level: "error",
+              message: `${c.name}: visibility role ${JSON.stringify(r)} is not in schema roles`
+            });
+          }
+        }
+      }
+    }
+  }
+  return issues;
+}
+
+// src/from-canonical.ts
+var SCALARS = {
+  bool,
+  u8,
+  u16,
+  u32,
+  i32,
+  f32,
+  f64
+};
+function schemaFromCanonical(json, options = {}) {
+  let doc;
+  try {
+    doc = JSON.parse(json);
+  } catch (err) {
+    throw new Error(`schemaFromCanonical: not JSON: ${String(err)}`);
+  }
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+    throw new Error("schemaFromCanonical: canonical form must be a JSON object");
+  }
+  const d = doc;
+  const version = d.canonicalVersion;
+  if (version !== CANONICAL_VERSION) {
+    throw new Error(
+      `schemaFromCanonical: canonicalVersion ${String(version)} is not supported (this build reads ${CANONICAL_VERSION})`
+    );
+  }
+  const defs = {};
+  for (const e of arrayAt(d, "entities")) {
+    const name = stringAt(e, "name");
+    const kind = stringAt(e, "kind");
+    const fields = fieldsOf(arrayAt(e, "fields"), `${name}`);
+    const optionsForDef = entityOptions(e, name);
+    if (kind === "entity") defs[name] = entity(fields, optionsForDef);
+    else if (kind === "singleton") defs[name] = singleton(fields, optionsForDef);
+    else throw new Error(`schemaFromCanonical: ${name}: unknown collection kind ${kind}`);
+  }
+  const rpc = {};
+  for (const r of arrayAt(d, "rpcs")) {
+    const name = stringAt(r, "name");
+    const direction = stringAt(r, "direction");
+    if (direction !== "server" && direction !== "client") {
+      throw new Error(`schemaFromCanonical: rpc ${name}: unknown direction ${direction}`);
+    }
+    const params = fieldsOf(arrayAt(r, "params"), `rpc ${name} params`);
+    const returnsRaw = r.returns;
+    const returns = returnsRaw === null || returnsRaw === void 0 ? void 0 : fieldsOf(arrayAt(r, "returns"), `rpc ${name} returns`);
+    rpc[name] = {
+      kind: "rpc",
+      direction,
+      params,
+      returns
+    };
+  }
+  const roles = [];
+  for (const role of arrayAtRaw(d, "roles")) {
+    if (typeof role !== "string") throw new Error("schemaFromCanonical: roles must be strings");
+    roles.push(role);
+  }
+  const schema = defineSchema(defs, {
+    rpc,
+    roles,
+    // A canonical form produced by `withBuiltins` names the reserved `clients` collection; a
+    // reader must be able to replay whatever it is handed.
+    allowReservedNames: true,
+    ...options.project !== void 0 ? { project: options.project } : {}
+  });
+  const expected = stableStringify(doc);
+  if (schema.canonical !== expected) {
+    throw new Error(
+      "schemaFromCanonical: reconstructed schema does not match its canonical form \u2014 the deployment record is corrupt or was written by a newer irtio"
+    );
+  }
+  return schema;
+}
+function fieldsOf(entries, at) {
+  const out = {};
+  for (const f of entries) {
+    const name = stringAt(f, "name");
+    out[name] = typeOf(objectAt(f, "type"), `${at}.${name}`);
+  }
+  return out;
+}
+function typeOf(t, at) {
+  const kind = stringAt(t, "kind");
+  let base;
+  switch (kind) {
+    case "bool":
+    case "u8":
+    case "u16":
+    case "u32":
+    case "i32":
+    case "f32":
+    case "f64":
+      base = SCALARS[kind];
+      break;
+    case "str":
+      base = str(numberAt(t, "max"));
+      break;
+    case "enum": {
+      const values = arrayAtRaw(t, "values").map((v) => {
+        if (typeof v !== "string") throw new Error(`${at}: enum values must be strings`);
+        return v;
+      });
+      if (values.length === 0) throw new Error(`${at}: enum has no values`);
+      base = enumOf(...values);
+      break;
+    }
+    case "ref":
+      base = ref(stringAt(t, "entity"));
+      break;
+    case "list":
+      base = list(typeOf(objectAt(t, "item"), `${at}[]`), numberAt(t, "max"));
+      break;
+    case "struct":
+      base = struct(fieldsOf(arrayAt(t, "fields"), at));
+      break;
+    default:
+      throw new Error(`${at}: unknown type kind ${JSON.stringify(kind)}`);
+  }
+  if (t.opt === true) base = base.opt;
+  if (Object.hasOwn(t, "default")) base = base.default(t.default);
+  return base;
+}
+function entityOptions(e, name) {
+  const visibility = stringAt(e, "visibility");
+  if (visibility !== "all" && visibility !== "role" && visibility !== "spatial-grid") {
+    throw new Error(
+      `schemaFromCanonical: ${name}: unknown visibility ${JSON.stringify(visibility)}`
+    );
+  }
+  const rolesRaw = e.roles;
+  const roles = rolesRaw === null || rolesRaw === void 0 ? void 0 : arrayAtRaw(e, "roles").map((r) => {
+    if (typeof r !== "string")
+      throw new Error(`schemaFromCanonical: ${name}: roles must be strings`);
+    return r;
+  });
+  return {
+    serverOwned: e.serverOwned === true,
+    visibility,
+    ...roles !== void 0 ? { roles } : {}
+  };
+}
+function stringAt(o, key) {
+  const v = o[key];
+  if (typeof v !== "string") throw new Error(`schemaFromCanonical: ${key} must be a string`);
+  return v;
+}
+function numberAt(o, key) {
+  const v = o[key];
+  if (typeof v !== "number" || !Number.isInteger(v)) {
+    throw new Error(`schemaFromCanonical: ${key} must be an integer`);
+  }
+  return v;
+}
+function objectAt(o, key) {
+  const v = o[key];
+  if (typeof v !== "object" || v === null || Array.isArray(v)) {
+    throw new Error(`schemaFromCanonical: ${key} must be an object`);
+  }
+  return v;
+}
+function arrayAtRaw(o, key) {
+  const v = o[key];
+  if (!Array.isArray(v)) throw new Error(`schemaFromCanonical: ${key} must be an array`);
+  return v;
+}
+function arrayAt(o, key) {
+  return arrayAtRaw(o, key).map((v) => {
+    if (typeof v !== "object" || v === null || Array.isArray(v)) {
+      throw new Error(`schemaFromCanonical: ${key} entries must be objects`);
+    }
+    return v;
+  });
+}
+
+// src/collection.ts
+var SERVER_OWNER = "";
+var SINGLETON_ID = "";
+function assertId(id) {
+  if (typeof id !== "string") throw new Error("entity id must be a string");
+  if (utf8Length(id) > ID_MAX_BYTES)
+    throw new Error(`entity id exceeds ${ID_MAX_BYTES} UTF-8 bytes: ${JSON.stringify(id)}`);
+}
+function assertOwner(owner) {
+  if (typeof owner !== "string")
+    throw new Error("owner must be a client id string or SERVER_OWNER");
+  if (utf8Length(owner) > ID_MAX_BYTES)
+    throw new Error(`owner id exceeds ${ID_MAX_BYTES} UTF-8 bytes: ${JSON.stringify(owner)}`);
+}
+var EntityCollection = class {
+  constructor(desc) {
+    this.desc = desc;
+  }
+  desc;
+  records = /* @__PURE__ */ new Map();
+  add(id, values, options) {
+    assertId(id);
+    const owner = options?.owner ?? SERVER_OWNER;
+    assertOwner(owner);
+    const value = normalizeRecord(this.desc, values);
+    this.records.set(id, { owner, value });
+    return value;
+  }
+  remove(id) {
+    return this.records.delete(id);
+  }
+  get(id) {
+    return this.records.get(id)?.value;
+  }
+  has(id) {
+    return this.records.has(id);
+  }
+  setOwner(id, owner) {
+    const r = this.records.get(id);
+    if (!r) throw new Error(`setOwner: no instance ${JSON.stringify(id)} in ${this.desc.name}`);
+    assertOwner(owner);
+    r.owner = owner;
+  }
+  ownerOf(id) {
+    return this.records.get(id)?.owner;
+  }
+  get size() {
+    return this.records.size;
+  }
+  ids() {
+    return this.records.keys();
+  }
+  *[Symbol.iterator]() {
+    for (const [id, r] of this.records) yield [id, r.value];
+  }
+};
+function normalizeRecord(desc, values) {
+  if (typeof values !== "object" || values === null) {
+    throw new Error(`${desc.name}: values must be an object`);
+  }
+  for (const k of Object.keys(values)) {
+    if (!desc.fieldIndex.has(k))
+      throw new Error(`${desc.name}: unknown field ${JSON.stringify(k)}`);
+  }
+  const out = {};
+  for (const f of desc.fields)
+    out[f.name] = normalizeValue(f.type, values[f.name], `${desc.name}.${f.name}`);
+  return out;
+}
+function defaultRecord(desc) {
+  const out = {};
+  for (const f of desc.fields) out[f.name] = defaultValue(f.type);
+  return out;
+}
+function createState(schema, init) {
+  const state = {};
+  for (const c of schema.collections) {
+    if (c.kind === "entity") state[c.name] = new EntityCollection(c);
+    else {
+      const given = init?.[c.name];
+      state[c.name] = given ? normalizeRecord(c, given) : defaultRecord(c);
+    }
+  }
+  return state;
+}
+
+// src/dirty.ts
+function createDirtySet() {
+  return /* @__PURE__ */ new Map();
+}
+function createFieldMask() {
+  return { fields: /* @__PURE__ */ new Set(), nested: /* @__PURE__ */ new Map() };
+}
+function collectionDirty(dirty, collection) {
+  let c = dirty.get(collection);
+  if (!c) {
+    c = { added: /* @__PURE__ */ new Set(), removed: /* @__PURE__ */ new Set(), updated: /* @__PURE__ */ new Map() };
+    dirty.set(collection, c);
+  }
+  return c;
+}
+function recordDirty(dirty, collection, id) {
+  const c = collectionDirty(dirty, collection);
+  if (c.added.has(id)) return void 0;
+  let r = c.updated.get(id);
+  if (!r) {
+    r = { mask: createFieldMask(), owner: false };
+    c.updated.set(id, r);
+  }
+  return r;
+}
+function markField(dirty, collection, id, path) {
+  const r = recordDirty(dirty, collection, id);
+  if (r) markPath(r.mask, path);
+}
+function markPath(mask, path) {
+  if (path.length === 0) return;
+  let m = mask;
+  for (let i = 0; i < path.length - 1; i++) {
+    const idx = path[i];
+    if (isWhole(m, idx)) return;
+    m.fields.add(idx);
+    let n = m.nested.get(idx);
+    if (!n) {
+      n = createFieldMask();
+      m.nested.set(idx, n);
+    }
+    m = n;
+  }
+  const last = path[path.length - 1];
+  m.fields.add(last);
+  m.nested.delete(last);
+}
+function markOwner(dirty, collection, id) {
+  const r = recordDirty(dirty, collection, id);
+  if (r) r.owner = true;
+}
+function markAdd(dirty, collection, id) {
+  const c = collectionDirty(dirty, collection);
+  c.removed.delete(id);
+  c.updated.delete(id);
+  c.added.add(id);
+}
+function markRemove(dirty, collection, id) {
+  const c = collectionDirty(dirty, collection);
+  c.added.delete(id);
+  c.updated.delete(id);
+  c.removed.add(id);
+}
+function isDirtyEmpty(dirty) {
+  for (const c of dirty.values()) {
+    if (c.added.size || c.removed.size || c.updated.size) return false;
+  }
+  return true;
+}
+function isWhole(mask, idx) {
+  return mask.fields.has(idx) && !mask.nested.has(idx);
+}
+function mergeDirty(dst, src) {
+  for (const [name, sc] of src) {
+    for (const id of sc.removed) markRemove(dst, name, id);
+    for (const id of sc.added) markAdd(dst, name, id);
+    for (const [id, rd] of sc.updated) {
+      const r = recordDirty(dst, name, id);
+      if (!r) continue;
+      if (rd.owner) r.owner = true;
+      mergeMask(r.mask, rd.mask);
+    }
+  }
+}
+function mergeMask(dst, src) {
+  for (const idx of src.fields) {
+    const n = src.nested.get(idx);
+    if (!n) {
+      dst.fields.add(idx);
+      dst.nested.delete(idx);
+    } else if (!isWhole(dst, idx)) {
+      dst.fields.add(idx);
+      let dn = dst.nested.get(idx);
+      if (!dn) {
+        dn = createFieldMask();
+        dst.nested.set(idx, dn);
+      }
+      mergeMask(dn, n);
+    }
+  }
+}
+function filterDirty(dirty, keep) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [name, cd] of dirty) if (keep(name)) out.set(name, cd);
+  return out;
+}
+
+// src/bytes.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder("utf-8", { fatal: true });
+var ByteWriter = class {
+  buf;
+  view;
+  pos = 0;
+  constructor(initialCapacity = 256) {
+    this.buf = new Uint8Array(initialCapacity);
+    this.view = new DataView(this.buf.buffer);
+  }
+  get length() {
+    return this.pos;
+  }
+  ensure(n) {
+    if (this.pos + n <= this.buf.length) return;
+    let cap = this.buf.length * 2;
+    while (cap < this.pos + n) cap *= 2;
+    const next = new Uint8Array(cap);
+    next.set(this.buf.subarray(0, this.pos));
+    this.buf = next;
+    this.view = new DataView(next.buffer);
+  }
+  u8(v) {
+    this.ensure(1);
+    this.buf[this.pos++] = v;
+  }
+  bool(v) {
+    this.u8(v ? 1 : 0);
+  }
+  u16(v) {
+    this.ensure(2);
+    this.view.setUint16(this.pos, v, true);
+    this.pos += 2;
+  }
+  u32(v) {
+    this.ensure(4);
+    this.view.setUint32(this.pos, v, true);
+    this.pos += 4;
+  }
+  i32(v) {
+    this.ensure(4);
+    this.view.setInt32(this.pos, v, true);
+    this.pos += 4;
+  }
+  f32(v) {
+    this.ensure(4);
+    this.view.setFloat32(this.pos, v, true);
+    this.pos += 4;
+  }
+  f64(v) {
+    this.ensure(8);
+    this.view.setFloat64(this.pos, v, true);
+    this.pos += 8;
+  }
+  /** LEB128 unsigned varint (0 .. 2^32-1). */
+  varint(v) {
+    if (!Number.isInteger(v) || v < 0 || v > 4294967295)
+      throw new Error(`varint out of range: ${v}`);
+    this.ensure(5);
+    while (v >= 128) {
+      this.buf[this.pos++] = v & 127 | 128;
+      v >>>= 7;
+    }
+    this.buf[this.pos++] = v;
+  }
+  /** Raw bytes, no length prefix. */
+  bytes(b) {
+    this.ensure(b.length);
+    this.buf.set(b, this.pos);
+    this.pos += b.length;
+  }
+  /** varint length + raw bytes. */
+  blob(b) {
+    this.varint(b.length);
+    this.bytes(b);
+  }
+  /** varint UTF-8 byte length + bytes. Returns the byte length written. */
+  str(s) {
+    const b = encoder.encode(s);
+    this.blob(b);
+    return b.length;
+  }
+  /** Reserves `n` bytes and returns their offset (for masks filled in later). */
+  reserve(n) {
+    this.ensure(n);
+    const at = this.pos;
+    this.buf.fill(0, at, at + n);
+    this.pos += n;
+    return at;
+  }
+  setU8(at, v) {
+    this.buf[at] = v;
+  }
+  orU8(at, v) {
+    this.buf[at] |= v;
+  }
+  /** A copy of the written bytes. */
+  finish() {
+    return this.buf.slice(0, this.pos);
+  }
+};
+var ByteReader = class {
+  constructor(buf, offset = 0) {
+    this.buf = buf;
+    this.view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    this.pos = offset;
+  }
+  buf;
+  view;
+  pos;
+  get remaining() {
+    return this.buf.length - this.pos;
+  }
+  get eof() {
+    return this.pos >= this.buf.length;
+  }
+  need(n) {
+    if (this.pos + n > this.buf.length) throw new Error("unexpected end of buffer");
+  }
+  u8() {
+    this.need(1);
+    return this.buf[this.pos++];
+  }
+  bool() {
+    return this.u8() !== 0;
+  }
+  u16() {
+    this.need(2);
+    const v = this.view.getUint16(this.pos, true);
+    this.pos += 2;
+    return v;
+  }
+  u32() {
+    this.need(4);
+    const v = this.view.getUint32(this.pos, true);
+    this.pos += 4;
+    return v;
+  }
+  i32() {
+    this.need(4);
+    const v = this.view.getInt32(this.pos, true);
+    this.pos += 4;
+    return v;
+  }
+  f32() {
+    this.need(4);
+    const v = this.view.getFloat32(this.pos, true);
+    this.pos += 4;
+    return v;
+  }
+  f64() {
+    this.need(8);
+    const v = this.view.getFloat64(this.pos, true);
+    this.pos += 8;
+    return v;
+  }
+  varint() {
+    let result = 0;
+    let shift = 0;
+    for (; ; ) {
+      const b = this.u8();
+      result += (b & 127) * 2 ** shift;
+      if ((b & 128) === 0) break;
+      shift += 7;
+      if (shift > 35) throw new Error("varint too long");
+    }
+    if (result > 4294967295) throw new Error("varint out of range");
+    return result;
+  }
+  /** `n` raw bytes (a view, not a copy). */
+  bytes(n) {
+    this.need(n);
+    const v = this.buf.subarray(this.pos, this.pos + n);
+    this.pos += n;
+    return v;
+  }
+  /** varint length + raw bytes (a view). */
+  blob() {
+    return this.bytes(this.varint());
+  }
+  str() {
+    return decoder.decode(this.blob());
+  }
+  /** The rest of the buffer (a view). */
+  rest() {
+    const v = this.buf.subarray(this.pos);
+    this.pos = this.buf.length;
+    return v;
+  }
+};
+function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+// src/codec.ts
+function varintSize(v) {
+  let n = 1;
+  let x = v;
+  while (x >= 128) {
+    x = Math.floor(x / 128);
+    n++;
+  }
+  return n;
+}
+var CountingSink = class {
+  length = 0;
+  u8() {
+    this.length += 1;
+  }
+  bool() {
+    this.length += 1;
+  }
+  u16() {
+    this.length += 2;
+  }
+  u32() {
+    this.length += 4;
+  }
+  i32() {
+    this.length += 4;
+  }
+  f32() {
+    this.length += 4;
+  }
+  f64() {
+    this.length += 8;
+  }
+  varint(v) {
+    if (!Number.isInteger(v) || v < 0 || v > 4294967295)
+      throw new Error(`varint out of range: ${v}`);
+    this.length += varintSize(v);
+  }
+  bytes(b) {
+    this.length += b.length;
+  }
+  str(s) {
+    const n = utf8Length(s);
+    this.length += varintSize(n) + n;
+    return n;
+  }
+};
+var OP_ADD = 0;
+var OP_UPDATE = 1;
+var OP_REMOVE = 2;
+function fail(path, message) {
+  throw new Error(`${path || "value"}: ${message}`);
+}
+function structNames(d) {
+  return Object.keys(d.fields);
+}
+function writeValue(w, desc, v, path = "value") {
+  let value = v;
+  if (value === void 0 && desc.hasDefault && desc.default !== void 0) value = desc.default;
+  if (desc.opt) {
+    if (value === void 0) {
+      w.u8(0);
+      return;
+    }
+    w.u8(1);
+  } else if (value === void 0) {
+    fail(path, "is required");
+  }
+  switch (desc.kind) {
+    case "bool":
+      if (typeof value !== "boolean") fail(path, "must be a boolean");
+      w.bool(value);
+      return;
+    case "u8":
+    case "u16":
+    case "u32":
+    case "i32": {
+      if (typeof value !== "number" || !Number.isInteger(value))
+        fail(path, `must be an integer (${desc.kind})`);
+      const [lo, hi] = INT_RANGE[desc.kind];
+      if (value < lo || value > hi) fail(path, `out of range for ${desc.kind}: ${value}`);
+      if (desc.kind === "u8") w.u8(value);
+      else if (desc.kind === "u16") w.u16(value);
+      else if (desc.kind === "u32") w.u32(value);
+      else w.i32(value);
+      return;
+    }
+    case "f32":
+      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);
+      return;
+    case "str":
+    case "ref": {
+      if (typeof value !== "string") fail(path, "must be a string");
+      const max = desc.kind === "str" ? desc.max : ID_MAX_BYTES;
+      const n = utf8Length(value);
+      if (n > max) fail(path, `exceeds ${max} UTF-8 bytes (${n})`);
+      w.str(value);
+      return;
+    }
+    case "enum": {
+      if (typeof value !== "string") fail(path, "must be a string");
+      const i = desc.values.indexOf(value);
+      if (i < 0)
+        fail(path, `must be one of ${desc.values.join("|")} (got ${JSON.stringify(value)})`);
+      w.u8(i);
+      return;
+    }
+    case "list": {
+      if (!Array.isArray(value)) fail(path, "must be an array");
+      if (value.length > desc.max) fail(path, `exceeds max length ${desc.max} (${value.length})`);
+      w.varint(value.length);
+      for (let i = 0; i < value.length; i++) writeValue(w, desc.item, value[i], `${path}[${i}]`);
+      return;
+    }
+    case "struct": {
+      if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail(path, "must be an object");
+      const o = value;
+      for (const [k, fd] of Object.entries(desc.fields)) writeValue(w, fd, o[k], `${path}.${k}`);
+      return;
+    }
+  }
+}
+function readValue(r, desc) {
+  if (desc.opt && r.u8() === 0) return void 0;
+  switch (desc.kind) {
+    case "bool":
+      return r.bool();
+    case "u8":
+      return r.u8();
+    case "u16":
+      return r.u16();
+    case "u32":
+      return r.u32();
+    case "i32":
+      return r.i32();
+    case "f32":
+      return r.f32();
+    case "f64":
+      return r.f64();
+    case "str":
+    case "ref":
+      return r.str();
+    case "enum": {
+      const i = r.u8();
+      const v = desc.values[i];
+      if (v === void 0)
+        throw new Error(`unknown enum index ${i} (${desc.values.length} values)`);
+      return v;
+    }
+    case "list": {
+      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));
+      return out;
+    }
+    case "struct": {
+      const o = {};
+      for (const [k, fd] of Object.entries(desc.fields)) o[k] = readValue(r, fd);
+      return o;
+    }
+  }
+}
+function writeRecord(w, fields, value, path) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    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) {
+  const o = {};
+  for (const f of fields) o[f.name] = readValue(r, f.type);
+  return o;
+}
+function encodeFields(fields, value) {
+  const w = new ByteWriter(64);
+  writeRecord(w, fields, value, "fields");
+  return w.finish();
+}
+function decodeFields(fields, bytes) {
+  const r = bytes instanceof ByteReader ? bytes : new ByteReader(bytes);
+  return readRecord(r, fields);
+}
+function entityOf(state, name) {
+  const c = state[name];
+  if (!c || typeof c.get !== "function")
+    throw new Error(`state is missing entity collection ${JSON.stringify(name)}`);
+  return c;
+}
+function singletonOf(state, name) {
+  const s = state[name];
+  if (!s || typeof s !== "object")
+    throw new Error(`state is missing singleton ${JSON.stringify(name)}`);
+  return s;
+}
+function writeSnapshot(w, schema, state, tick, options) {
+  w.u32(tick);
+  w.bytes(schema.hash8);
+  for (const c of schema.collections) {
+    const visible = options?.collections ? options.collections(c) : true;
+    if (c.kind === "entity") {
+      if (!visible) {
+        w.varint(0);
+        continue;
+      }
+      const coll = entityOf(state, c.name);
+      w.varint(coll.size);
+      for (const id of coll.ids()) {
+        const value = coll.get(id);
+        if (value === void 0) throw new Error(`${c.name}: id ${JSON.stringify(id)} vanished`);
+        w.str(id);
+        w.str(coll.ownerOf(id) ?? "");
+        writeRecord(w, c.fields, value, `${c.name}[${id}]`);
+      }
+    } else {
+      writeRecord(w, c.fields, visible ? singletonOf(state, c.name) : defaultRecord(c), c.name);
+    }
+  }
+}
+function encodeSnapshot(schema, state, header, options) {
+  const w = new ByteWriter(1024);
+  writeSnapshot(w, schema, state, header.tick, options);
+  return w.finish();
+}
+function decodeSnapshot(schema, bytes) {
+  const r = new ByteReader(bytes);
+  const tick = r.u32();
+  const hash8 = r.bytes(8).slice();
+  const state = createState(schema);
+  for (const c of schema.collections) {
+    if (c.kind === "entity") {
+      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 });
+      }
+    } else {
+      const target = singletonOf(state, c.name);
+      const value = readRecord(r, c.fields);
+      for (const f of c.fields) target[f.name] = value[f.name];
+    }
+  }
+  return { tick, hash8, state };
+}
+function planCollection(c, state, dirty) {
+  const cd = dirty.get(c.name);
+  if (!cd) return void 0;
+  const ops = [];
+  if (c.kind === "entity") {
+    const coll = entityOf(state, c.name);
+    for (const id of cd.added) if (coll.has(id)) ops.push({ kind: "add", id });
+    for (const [id, rd] of cd.updated) {
+      if (!rd.owner && rd.mask.fields.size === 0) continue;
+      if (!coll.has(id)) continue;
+      ops.push({ kind: "update", id, mask: rd.mask, owner: rd.owner });
+    }
+    for (const id of cd.removed) ops.push({ kind: "remove", id });
+  } else {
+    for (const [id, rd] of cd.updated) {
+      if (rd.mask.fields.size === 0) continue;
+      ops.push({ kind: "update", id, mask: rd.mask, owner: false });
+    }
+  }
+  return ops.length > 0 ? ops : void 0;
+}
+function maskBytesFor(indices, bits) {
+  const bytes = new Uint8Array(bits + 7 >> 3);
+  for (const i of indices) bytes[i >> 3] |= 1 << (i & 7);
+  return bytes;
+}
+function sortedIndices(mask, limit) {
+  return [...mask.fields].filter((i) => i >= 0 && i < limit).sort((a, b) => a - b);
+}
+function writeDirtyField(w, desc, v, nested, path) {
+  if (desc.kind !== "struct") {
+    writeValue(w, desc, v, path);
+    return;
+  }
+  let value = v;
+  if (value === void 0 && desc.hasDefault && desc.default !== void 0) value = desc.default;
+  if (desc.opt) {
+    if (value === void 0) {
+      w.u8(0);
+      return;
+    }
+    w.u8(1);
+  } else if (value === void 0) {
+    fail(path, "is required");
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    fail(path, "must be an object");
+  const o = value;
+  const names = structNames(desc);
+  const indices = nested ? sortedIndices(nested, names.length) : names.map((_, i) => i);
+  w.bytes(maskBytesFor(indices, names.length));
+  for (const i of indices) {
+    const name = names[i];
+    const fd = desc.fields[name];
+    writeDirtyField(w, fd, o[name], nested?.nested.get(i), `${path}.${name}`);
+  }
+}
+function writeDelta(w, schema, state, dirty, tick) {
+  w.u32(tick);
+  w.bytes(schema.hash8);
+  const planned = [];
+  for (const c of schema.collections) {
+    const ops = planCollection(c, state, dirty);
+    if (ops) planned.push({ c, ops });
+  }
+  w.varint(planned.length);
+  for (const { c, ops } of planned) {
+    w.varint(c.index);
+    w.varint(ops.length);
+    const coll = c.kind === "entity" ? entityOf(state, c.name) : void 0;
+    for (const op of ops) {
+      if (op.kind === "remove") {
+        w.u8(OP_REMOVE);
+        w.str(op.id);
+        continue;
+      }
+      const value = coll === void 0 ? singletonOf(state, c.name) : coll.get(op.id);
+      if (op.kind === "add") {
+        w.u8(OP_ADD);
+        w.str(op.id);
+        w.str(coll.ownerOf(op.id) ?? "");
+        writeRecord(w, c.fields, value, `${c.name}[${op.id}]`);
+        continue;
+      }
+      w.u8(OP_UPDATE);
+      w.str(op.id);
+      const n = c.fields.length;
+      const indices = sortedIndices(op.mask, n);
+      const bits = op.owner ? [...indices, n] : indices;
+      w.bytes(maskBytesFor(bits, n + 1));
+      if (op.owner) w.str(coll.ownerOf(op.id) ?? "");
+      for (const i of indices) {
+        const f = c.fields[i];
+        writeDirtyField(
+          w,
+          f.type,
+          value[f.name],
+          op.mask.nested.get(i),
+          `${c.name}[${op.id}].${f.name}`
+        );
+      }
+    }
+  }
+}
+function encodeDelta(schema, state, dirty, header) {
+  const w = new ByteWriter(512);
+  writeDelta(w, schema, state, dirty, header.tick);
+  return w.finish();
+}
+function estimateSize(schema, state, dirty) {
+  const w = new CountingSink();
+  writeDelta(w, schema, state, dirty, 0);
+  return w.length;
+}
+function readBit(mask, i) {
+  return ((mask[i >> 3] ?? 0) & 1 << (i & 7)) !== 0;
+}
+function readDirtyField(r, desc) {
+  if (desc.kind !== "struct") return { value: readValue(r, desc) };
+  if (desc.opt && r.u8() === 0) return { value: void 0 };
+  const names = structNames(desc);
+  const maskBytes = r.bytes(names.length + 7 >> 3);
+  const out = {};
+  const mask = createFieldMask();
+  for (let i = 0; i < names.length; i++) {
+    if (!readBit(maskBytes, i)) continue;
+    const name = names[i];
+    const fd = desc.fields[name];
+    const got = readDirtyField(r, fd);
+    out[name] = got.value;
+    mask.fields.add(i);
+    if (got.nested) mask.nested.set(i, got.nested);
+  }
+  return { value: out, nested: mask };
+}
+function decodeDelta(schema, bytes) {
+  return decodeDeltaFrom(schema, new ByteReader(bytes));
+}
+function decodeDeltaFrom(schema, r) {
+  const tick = r.u32();
+  const hash8 = r.bytes(8).slice();
+  const collections = [];
+  const count = r.varint();
+  for (let ci = 0; ci < count; ci++) {
+    const index = r.varint();
+    const c = schema.collections[index];
+    if (!c) throw new Error(`delta references unknown collection index ${index}`);
+    const opCount = r.varint();
+    const ops = [];
+    for (let oi = 0; oi < opCount; oi++) {
+      const op = r.u8();
+      if (op === OP_REMOVE) {
+        ops.push({ op: "remove", id: r.str() });
+        continue;
+      }
+      if (op === OP_ADD) {
+        const id2 = r.str();
+        const owner2 = r.str();
+        ops.push({ op: "add", id: id2, owner: owner2, value: readRecord(r, c.fields) });
+        continue;
+      }
+      if (op !== OP_UPDATE) throw new Error(`unknown delta op byte ${op} in ${c.name}`);
+      const id = r.str();
+      const n = c.fields.length;
+      const maskBytes = r.bytes(n + 1 + 7 >> 3);
+      const ownerDirty = readBit(maskBytes, n);
+      const owner = ownerDirty ? r.str() : void 0;
+      const mask = createFieldMask();
+      const patch = {};
+      for (let i = 0; i < n; i++) {
+        if (!readBit(maskBytes, i)) continue;
+        const f = c.fields[i];
+        const got = readDirtyField(r, f.type);
+        patch[f.name] = got.value;
+        mask.fields.add(i);
+        if (got.nested) mask.nested.set(i, got.nested);
+      }
+      ops.push(
+        owner === void 0 ? { op: "update", id, mask, patch } : { op: "update", id, owner, mask, patch }
+      );
+    }
+    collections.push({ name: c.name, ops });
+  }
+  return { tick, hash8, collections };
+}
+function applyPatch(fieldTypes, target, patch, mask) {
+  for (const i of sortedIndices(mask, fieldTypes.length)) {
+    const f = fieldTypes[i];
+    const value = patch[f.name];
+    const nested = mask.nested.get(i);
+    if (nested && f.type.kind === "struct" && value !== void 0) {
+      const current = target[f.name];
+      if (typeof current === "object" && current !== null && !Array.isArray(current)) {
+        const names = structNames(f.type);
+        applyPatch(
+          names.map((name) => ({
+            name,
+            type: f.type.fields[name]
+          })),
+          current,
+          value,
+          nested
+        );
+        continue;
+      }
+    }
+    target[f.name] = value;
+  }
+}
+function applyDelta(schema, state, delta) {
+  for (const dc of delta.collections) {
+    const c = schema.collection(dc.name);
+    if (c.kind === "entity") {
+      const coll = entityOf(state, c.name);
+      for (const op of dc.ops) {
+        if (op.op === "add") {
+          coll.add(op.id, op.value, { owner: op.owner });
+        } else if (op.op === "remove") {
+          coll.remove(op.id);
+        } else {
+          if (!coll.has(op.id)) continue;
+          const rec = coll.get(op.id);
+          if (rec) applyPatch(c.fields, rec, op.patch, op.mask);
+          if (op.owner !== void 0) coll.setOwner(op.id, op.owner);
+        }
+      }
+    } else {
+      const target = singletonOf(state, c.name);
+      for (const op of dc.ops) {
+        if (op.op !== "update") continue;
+        applyPatch(c.fields, target, op.patch, op.mask);
+      }
+    }
+  }
+}
+function valueEquals(a, b) {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) if (!valueEquals(a[i], b[i])) return false;
+    return true;
+  }
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  const ao = a;
+  const bo = b;
+  const keys = /* @__PURE__ */ new Set([...Object.keys(ao), ...Object.keys(bo)]);
+  for (const k of keys) if (!valueEquals(ao[k], bo[k])) return false;
+  return true;
+}
+function diffField(desc, a, b, mask, idx) {
+  if (desc.kind === "struct" && typeof a === "object" && a !== null && !Array.isArray(a) && typeof b === "object" && b !== null && !Array.isArray(b)) {
+    const nested = createFieldMask();
+    const names = structNames(desc);
+    for (let i = 0; i < names.length; i++) {
+      const name = names[i];
+      diffField(desc.fields[name], a[name], b[name], nested, i);
+    }
+    if (nested.fields.size === 0) return;
+    mask.fields.add(idx);
+    mask.nested.set(idx, nested);
+    return;
+  }
+  if (!valueEquals(a, b)) mask.fields.add(idx);
+}
+function diffRecord(c, a, b, mask) {
+  for (const f of c.fields) diffField(f.type, a[f.name], b[f.name], mask, f.index);
+}
+function computeDirty(schema, from, to) {
+  const dirty = createDirtySet();
+  for (const c of schema.collections) {
+    if (c.kind === "entity") {
+      const a = entityOf(from, c.name);
+      const b = entityOf(to, c.name);
+      let cd;
+      const ensure = () => {
+        cd ??= collectionDirty(dirty, c.name);
+        return cd;
+      };
+      for (const id of b.ids()) {
+        if (!a.has(id)) {
+          ensure().added.add(id);
+          continue;
+        }
+        const mask = createFieldMask();
+        diffRecord(c, a.get(id), b.get(id), mask);
+        const owner = a.ownerOf(id) !== b.ownerOf(id);
+        if (mask.fields.size > 0 || owner) ensure().updated.set(id, { mask, owner });
+      }
+      for (const id of a.ids()) if (!b.has(id)) ensure().removed.add(id);
+    } else {
+      const mask = createFieldMask();
+      diffRecord(c, singletonOf(from, c.name), singletonOf(to, c.name), mask);
+      if (mask.fields.size > 0) {
+        collectionDirty(dirty, c.name).updated.set(SINGLETON_ID, { mask, owner: false });
+      }
+    }
+  }
+  return dirty;
+}
+
+// src/track.ts
+var fieldTables = /* @__PURE__ */ new WeakMap();
+function structFields(d) {
+  let t = fieldTables.get(d);
+  if (!t) {
+    const m = /* @__PURE__ */ new Map();
+    const names = Object.keys(d.fields);
+    names.forEach((name, index) => m.set(name, { name, index, type: d.fields[name] }));
+    fieldTables.set(d, m);
+    t = m;
+  }
+  return t;
+}
+function collectionFields(c) {
+  let t = fieldTables.get(c);
+  if (!t) {
+    t = new Map(c.fields.map((f) => [f.name, f]));
+    fieldTables.set(c, t);
+  }
+  return t;
+}
+function childPath(path, whole, idx) {
+  return whole ? path : [...path, idx];
+}
+function mark(root, path) {
+  markField(root.ctx.dirty, root.collection, root.id, path);
+}
+function assertLive(root) {
+  if (!root.live) {
+    throw new Error(
+      `${root.collection}: instance ${JSON.stringify(root.id)} was removed; its proxy is stale`
+    );
+  }
+}
+function objHandler(node) {
+  return {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      const f = node.fields.get(prop);
+      if (!f) return Reflect.get(target, prop, receiver);
+      const v = target[f.name];
+      if (v === null || typeof v !== "object") return v;
+      if (f.type.kind === "struct") {
+        return structProxy(node, f, v);
+      }
+      if (f.type.kind === "list") return listProxy(node, f, v);
+      return v;
+    },
+    set(target, prop, value) {
+      if (typeof prop !== "string") {
+        throw new Error(`${node.label}: cannot set ${String(prop)}`);
+      }
+      const f = node.fields.get(prop);
+      if (!f) throw new Error(`${node.label}: unknown field ${JSON.stringify(prop)}`);
+      assertLive(node.root);
+      const at = `${node.label}.${f.name}`;
+      const next = value === void 0 && f.type.opt ? void 0 : normalizeValue(f.type, value, at);
+      if ((next === null || typeof next !== "object") && Object.is(target[f.name], next))
+        return true;
+      target[f.name] = next;
+      mark(node.root, childPath(node.path, node.whole, f.index));
+      return true;
+    },
+    deleteProperty(_target, prop) {
+      throw new Error(
+        `${node.label}: cannot delete ${String(prop)}; set an .opt field to undefined instead`
+      );
+    },
+    defineProperty(_target, prop) {
+      throw new Error(`${node.label}: cannot defineProperty ${String(prop)}; assign instead`);
+    }
+  };
+}
+function makeObjProxy(node) {
+  const p = new Proxy(node.target, objHandler(node));
+  node.root.ctx.proxies.set(node.target, p);
+  return p;
+}
+function structProxy(parent, f, value) {
+  const cached = parent.root.ctx.proxies.get(value);
+  if (cached) return cached;
+  return makeObjProxy({
+    root: parent.root,
+    target: value,
+    fields: structFields(f.type),
+    path: childPath(parent.path, parent.whole, f.index),
+    whole: parent.whole,
+    label: `${parent.label}.${f.name}`
+  });
+}
+var MUTATORS = /* @__PURE__ */ new Set([
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+  "sort",
+  "reverse",
+  "fill",
+  "copyWithin"
+]);
+function isIndexProp(prop) {
+  const c = prop.charCodeAt(0);
+  return c >= 48 && c <= 57 && String(Number(prop)) === prop;
+}
+function restoreArray(t, snap) {
+  t.length = snap.length;
+  for (let i = 0; i < snap.length; i++) t[i] = snap[i];
+}
+function finishList(node, snap) {
+  const t = node.target;
+  const err = validateValue(node.desc, t, node.label);
+  if (err) {
+    restoreArray(t, snap);
+    throw new Error(err);
+  }
+  const item = node.desc.item;
+  if (item.kind === "struct" || item.kind === "list") {
+    const norm = normalizeValue(node.desc, t, node.label);
+    restoreArray(t, norm);
+  } else if (item.kind === "f32") {
+    for (let i = 0; i < t.length; i++) {
+      if (t[i] !== void 0) t[i] = Math.fround(t[i]);
+    }
+  }
+  mark(node.root, node.path);
+}
+function listMethod(node, name) {
+  let fn = node.methods.get(name);
+  if (!fn) {
+    fn = (...args) => {
+      assertLive(node.root);
+      const t = node.target;
+      const snap = t.slice();
+      let result;
+      try {
+        result = Array.prototype[name].apply(t, args);
+      } catch (e) {
+        restoreArray(t, snap);
+        throw e;
+      }
+      finishList(node, snap);
+      return result;
+    };
+    node.methods.set(name, fn);
+  }
+  return fn;
+}
+function listHandler(node) {
+  return {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      if (MUTATORS.has(prop)) return listMethod(node, prop);
+      const v = target[prop];
+      if (v !== null && typeof v === "object" && isIndexProp(prop)) {
+        const item = node.desc.item;
+        if (item.kind === "struct") return listElemProxy(node, prop, v);
+        if (item.kind === "list") return nestedListProxy(node, prop, v);
+      }
+      return v;
+    },
+    set(target, prop, value) {
+      if (typeof prop === "string" && (prop === "length" || isIndexProp(prop))) {
+        assertLive(node.root);
+        const snap = target.slice();
+        try {
+          target[prop] = value;
+        } catch (e) {
+          restoreArray(target, snap);
+          throw e;
+        }
+        finishList(node, snap);
+        return true;
+      }
+      throw new Error(`${node.label}: cannot set ${String(prop)}`);
+    },
+    deleteProperty(_target, prop) {
+      throw new Error(`${node.label}: cannot delete ${String(prop)}; use splice()`);
+    }
+  };
+}
+function makeListProxy(node) {
+  const p = new Proxy(node.target, listHandler(node));
+  node.root.ctx.proxies.set(node.target, p);
+  return p;
+}
+function listProxy(parent, f, value) {
+  const cached = parent.root.ctx.proxies.get(value);
+  if (cached) return cached;
+  return makeListProxy({
+    root: parent.root,
+    target: value,
+    desc: f.type,
+    path: childPath(parent.path, parent.whole, f.index),
+    label: `${parent.label}.${f.name}`,
+    methods: /* @__PURE__ */ new Map()
+  });
+}
+function nestedListProxy(parent, prop, value) {
+  const cached = parent.root.ctx.proxies.get(value);
+  if (cached) return cached;
+  return makeListProxy({
+    root: parent.root,
+    target: value,
+    desc: parent.desc.item,
+    path: parent.path,
+    label: `${parent.label}[${prop}]`,
+    methods: /* @__PURE__ */ new Map()
+  });
+}
+function listElemProxy(parent, prop, value) {
+  const cached = parent.root.ctx.proxies.get(value);
+  if (cached) return cached;
+  return makeObjProxy({
+    root: parent.root,
+    target: value,
+    fields: structFields(parent.desc.item),
+    path: parent.path,
+    whole: true,
+    label: `${parent.label}[${prop}]`
+  });
+}
+var TrackedCollection = class {
+  constructor(ctx, desc, inner) {
+    this.ctx = ctx;
+    this.desc = desc;
+    this.inner = inner;
+  }
+  ctx;
+  desc;
+  inner;
+  roots = /* @__PURE__ */ new Map();
+  invalidate(id) {
+    const root = this.roots.get(id);
+    if (root) {
+      root.live = false;
+      this.roots.delete(id);
+    }
+  }
+  proxyFor(id, value) {
+    const cached = this.ctx.proxies.get(value);
+    if (cached) return cached;
+    let root = this.roots.get(id);
+    if (!root || root.target !== value) {
+      if (root) root.live = false;
+      root = { ctx: this.ctx, collection: this.desc.name, id, target: value, live: true };
+      this.roots.set(id, root);
+    }
+    return makeObjProxy({
+      root,
+      target: value,
+      fields: collectionFields(this.desc),
+      path: [],
+      whole: false,
+      label: `${this.desc.name}[${id}]`
+    });
+  }
+  add(id, values, options) {
+    this.invalidate(id);
+    const value = this.inner.add(id, values, options);
+    markAdd(this.ctx.dirty, this.desc.name, id);
+    return this.proxyFor(id, value);
+  }
+  remove(id) {
+    const had = this.inner.remove(id);
+    if (had) {
+      this.invalidate(id);
+      markRemove(this.ctx.dirty, this.desc.name, id);
+    }
+    return had;
+  }
+  get(id) {
+    const v = this.inner.get(id);
+    return v === void 0 ? void 0 : this.proxyFor(id, v);
+  }
+  has(id) {
+    return this.inner.has(id);
+  }
+  setOwner(id, owner) {
+    this.inner.setOwner(id, owner);
+    markOwner(this.ctx.dirty, this.desc.name, id);
+  }
+  ownerOf(id) {
+    return this.inner.ownerOf(id);
+  }
+  get size() {
+    return this.inner.size;
+  }
+  ids() {
+    return this.inner.ids();
+  }
+  *[Symbol.iterator]() {
+    for (const [id, value] of this.inner) {
+      yield [id, this.proxyFor(id, value)];
+    }
+  }
+};
+function track(schema, state) {
+  const ctx = { dirty: createDirtySet(), proxies: /* @__PURE__ */ new WeakMap() };
+  const descs = /* @__PURE__ */ new Map();
+  for (const c of schema.collections) descs.set(c.name, c);
+  const cache = /* @__PURE__ */ new Map();
+  const proxy = new Proxy(state, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      const desc = descs.get(prop);
+      if (!desc) return Reflect.get(target, prop, receiver);
+      let node = cache.get(prop);
+      if (node === void 0) {
+        const raw = target[prop];
+        if (desc.kind === "entity") {
+          if (!(raw instanceof EntityCollection)) {
+            throw new Error(`track: state.${prop} must be an EntityCollection`);
+          }
+          node = new TrackedCollection(ctx, desc, raw);
+        } else {
+          if (raw === null || typeof raw !== "object") {
+            throw new Error(`track: state.${prop} must be an object`);
+          }
+          const value = raw;
+          node = makeObjProxy({
+            root: {
+              ctx,
+              collection: desc.name,
+              id: SINGLETON_ID,
+              target: value,
+              live: true
+            },
+            target: value,
+            fields: collectionFields(desc),
+            path: [],
+            whole: false,
+            label: desc.name
+          });
+        }
+        cache.set(prop, node);
+      }
+      return node;
+    },
+    set(target, prop, value) {
+      if (typeof prop !== "string") throw new Error(`track: cannot set ${String(prop)}`);
+      const desc = descs.get(prop);
+      if (!desc) throw new Error(`track: unknown collection ${JSON.stringify(prop)}`);
+      if (desc.kind === "entity") {
+        throw new Error(`track: cannot replace entity collection ${JSON.stringify(prop)}`);
+      }
+      const next = normalizeRecord(desc, value);
+      const current = target[prop];
+      for (const f of desc.fields) {
+        current[f.name] = next[f.name];
+        markField(ctx.dirty, desc.name, SINGLETON_ID, [f.index]);
+      }
+      return true;
+    },
+    deleteProperty(_target, prop) {
+      throw new Error(`track: cannot delete ${String(prop)}`);
+    }
+  });
+  return {
+    state: proxy,
+    get dirty() {
+      return ctx.dirty;
+    },
+    flush() {
+      const out = ctx.dirty;
+      ctx.dirty = createDirtySet();
+      return out;
+    }
+  };
+}
+function frozenProxy(value, ownershipHint) {
+  if (value === null || typeof value !== "object") return value;
+  return freeze(
+    value,
+    ownershipHint,
+    "",
+    /* @__PURE__ */ new Set(),
+    /* @__PURE__ */ new WeakMap()
+  );
+}
+function freeze(target, hint, prefix, warned, cache) {
+  const cached = cache.get(target);
+  if (cached) return cached;
+  const p = new Proxy(target, {
+    get(t, prop, receiver) {
+      const v = Reflect.get(t, prop, receiver);
+      if (v !== null && typeof v === "object" && typeof prop === "string") {
+        return freeze(v, hint, prefix ? `${prefix}.${prop}` : prop, warned, cache);
+      }
+      return v;
+    },
+    set(_t, prop) {
+      warnFrozen(hint, prefix, String(prop), warned);
+      return true;
+    },
+    deleteProperty(_t, prop) {
+      warnFrozen(hint, prefix, String(prop), warned);
+      return true;
+    },
+    defineProperty(_t, prop) {
+      warnFrozen(hint, prefix, String(prop), warned);
+      return true;
+    }
+  });
+  cache.set(target, p);
+  return p;
+}
+function warnFrozen(hint, prefix, prop, warned) {
+  const path = prefix ? `${prefix}.${prop}` : prop;
+  if (warned.has(path)) return;
+  warned.add(path);
+  console.warn(`irtio: ignoring write to ${path} \u2014 ${hint}`);
+}
+
+// src/diff.ts
+function diffSchemas(oldSchema, newSchema) {
+  const changes = [];
+  diffCollections(
+    oldSchema.collections,
+    newSchema.collections,
+    changes
+  );
+  diffRpcs(oldSchema.rpcs, newSchema.rpcs, changes);
+  diffRoles(oldSchema.roles, newSchema.roles, changes);
+  changes.sort(
+    (a, b) => a.path === b.path ? a.code.localeCompare(b.code) : a.path.localeCompare(b.path)
+  );
+  return changes;
+}
+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]));
+  for (const c of oldCollections) {
+    if (!newByName.has(c.name)) {
+      changes.push({
+        kind: "breaking",
+        code: `${c.kind}.removed`,
+        path: c.name,
+        message: `${c.name}: ${c.kind} was removed \u2014 clients/servers referencing it will break`
+      });
+    }
+  }
+  for (const c of newCollections) {
+    if (!oldByName.has(c.name)) {
+      changes.push({
+        kind: "additive",
+        code: `${c.kind}.added`,
+        path: c.name,
+        message: `${c.name}: new ${c.kind} added`
+      });
+    }
+  }
+  for (const oldC of oldCollections) {
+    const newC = newByName.get(oldC.name);
+    if (!newC) continue;
+    if (oldC.kind !== newC.kind) {
+      changes.push({
+        kind: "breaking",
+        code: "entity.kind_changed",
+        path: oldC.name,
+        message: `${oldC.name}: changed from ${oldC.kind} to ${newC.kind} \u2014 this is a breaking shape change`
+      });
+    }
+    if (oldC.serverOwned !== newC.serverOwned) {
+      changes.push({
+        kind: "breaking",
+        code: "entity.server_owned_changed",
+        path: oldC.name,
+        message: `${oldC.name}: serverOwned changed from ${oldC.serverOwned} to ${newC.serverOwned}`
+      });
+    }
+    if (oldC.visibility !== newC.visibility) {
+      changes.push({
+        kind: "breaking",
+        code: "entity.visibility_changed",
+        path: oldC.name,
+        message: `${oldC.name}: visibility changed from ${JSON.stringify(oldC.visibility)} to ${JSON.stringify(newC.visibility)}`
+      });
+    }
+    if (!sameStringSet(oldC.roles ?? [], newC.roles ?? [])) {
+      changes.push({
+        kind: "breaking",
+        code: "entity.roles_changed",
+        path: oldC.name,
+        message: `${oldC.name}: visible roles changed from [${(oldC.roles ?? []).join(", ")}] to [${(newC.roles ?? []).join(", ")}] \u2014 changes who sees this collection`
+      });
+    }
+    diffFields(oldC.fields, newC.fields, oldC.name, changes);
+  }
+}
+function diffRpcs(oldRpcs, newRpcs, changes) {
+  const oldByName = new Map(oldRpcs.map((r) => [r.name, r]));
+  const newByName = new Map(newRpcs.map((r) => [r.name, r]));
+  for (const r of oldRpcs) {
+    if (!newByName.has(r.name)) {
+      changes.push({
+        kind: "breaking",
+        code: "rpc.removed",
+        path: `rpc.${r.name}`,
+        message: `rpc ${r.name}: was removed`
+      });
+    }
+  }
+  for (const r of newRpcs) {
+    if (!oldByName.has(r.name)) {
+      changes.push({
+        kind: "additive",
+        code: "rpc.added",
+        path: `rpc.${r.name}`,
+        message: `rpc ${r.name}: new ${r.direction} RPC added`
+      });
+    }
+  }
+  for (const oldR of oldRpcs) {
+    const newR = newByName.get(oldR.name);
+    if (!newR) continue;
+    if (oldR.direction !== newR.direction) {
+      changes.push({
+        kind: "breaking",
+        code: "rpc.direction_changed",
+        path: `rpc.${oldR.name}`,
+        message: `rpc ${oldR.name}: direction changed from ${oldR.direction} to ${newR.direction}`
+      });
+    }
+    diffFields(oldR.params, newR.params, `rpc.${oldR.name}.params`, changes);
+    diffFields(oldR.returns ?? [], newR.returns ?? [], `rpc.${oldR.name}.returns`, changes);
+  }
+}
+function diffRoles(oldRoles, newRoles, changes) {
+  const oldSet = new Set(oldRoles);
+  const newSet = new Set(newRoles);
+  for (const r of oldRoles) {
+    if (!newSet.has(r)) {
+      changes.push({
+        kind: "breaking",
+        code: "role.removed",
+        path: "roles",
+        message: `roles: role ${JSON.stringify(r)} was removed`
+      });
+    }
+  }
+  for (const r of newRoles) {
+    if (!oldSet.has(r)) {
+      changes.push({
+        kind: "additive",
+        code: "role.added",
+        path: "roles",
+        message: `roles: new role ${JSON.stringify(r)} added`
+      });
+    }
+  }
+}
+function diffFields(oldFields, newFields, basePath, changes) {
+  const oldByName = new Map(oldFields.map((f) => [f.name, f]));
+  const newByName = new Map(newFields.map((f) => [f.name, f]));
+  const removedNames = oldFields.filter((f) => !newByName.has(f.name)).map((f) => f.name);
+  const addedNames = newFields.filter((f) => !oldByName.has(f.name)).map((f) => f.name);
+  for (const name of removedNames) {
+    changes.push({
+      kind: "breaking",
+      code: "field.removed",
+      path: `${basePath}.${name}`,
+      message: `${basePath}.${name}: field was removed (breaking)`
+    });
+  }
+  for (const name of addedNames) {
+    const f = newByName.get(name);
+    const additive = f.type.hasDefault || f.type.opt;
+    changes.push({
+      kind: additive ? "additive" : "breaking",
+      code: "field.added",
+      path: `${basePath}.${name}`,
+      message: additive ? `${basePath}.${name}: new field added (has a default/opt, safe for existing snapshots)` : `${basePath}.${name}: new required field without a default (breaking) \u2014 add .default(...) or make it .opt`
+    });
+  }
+  if (removedNames.length === 1 && addedNames.length === 1) {
+    const removedName = removedNames[0];
+    const addedName = addedNames[0];
+    const oldF = oldByName.get(removedName);
+    const newF = newByName.get(addedName);
+    if (oldF.index === newF.index && typeSignature(oldF.type) === typeSignature(newF.type)) {
+      changes.push({
+        kind: "breaking",
+        code: "field.renamed",
+        path: `${basePath}.${addedName}`,
+        message: `${basePath}.${removedName} -> ${basePath}.${addedName}: looks like a rename; write a transform`
+      });
+    }
+  }
+  for (const oldF of oldFields) {
+    const newF = newByName.get(oldF.name);
+    if (!newF) continue;
+    const path = `${basePath}.${oldF.name}`;
+    if (oldF.index !== newF.index) {
+      changes.push({
+        kind: "breaking",
+        code: "field.reordered",
+        path,
+        message: `${path}: declaration order changed (wire index ${oldF.index} -> ${newF.index}) \u2014 breaking`
+      });
+    }
+    diffType(oldF.type, newF.type, path, changes);
+  }
+}
+function diffType(oldT, newT, path, changes) {
+  if (oldT.kind !== newT.kind) {
+    changes.push({
+      kind: "breaking",
+      code: "field.type_changed",
+      path,
+      message: `${path}: type changed from ${describeType(oldT)} to ${describeType(newT)} (breaking)`
+    });
+    return;
+  }
+  if (!oldT.opt && newT.opt) {
+    changes.push({
+      kind: "additive",
+      code: "field.opt_added",
+      path,
+      message: `${path}: became .opt (required -> optional), safe for existing clients`
+    });
+  } else if (oldT.opt && !newT.opt) {
+    changes.push({
+      kind: "breaking",
+      code: "field.opt_removed",
+      path,
+      message: `${path}: no longer .opt (optional -> required) \u2014 breaking`
+    });
+  }
+  diffDefault(oldT, newT, path, changes);
+  switch (oldT.kind) {
+    case "str":
+      diffMax(oldT.max, newT.max, path, changes);
+      break;
+    case "ref": {
+      const newRef = newT;
+      if (oldT.entity !== newRef.entity) {
+        changes.push({
+          kind: "breaking",
+          code: "field.ref_target_changed",
+          path,
+          message: `${path}: ref target changed from ${JSON.stringify(oldT.entity)} to ${JSON.stringify(newRef.entity)} (breaking)`
+        });
+      }
+      break;
+    }
+    case "enum":
+      diffEnum(oldT.values, newT.values, path, changes);
+      break;
+    case "list": {
+      const newList = newT;
+      diffMax(oldT.max, newList.max, path, changes);
+      diffType(oldT.item, newList.item, `${path}[]`, changes);
+      break;
+    }
+    case "struct": {
+      const newStruct = newT;
+      diffFields(structFieldDescs(oldT.fields), structFieldDescs(newStruct.fields), path, changes);
+      break;
+    }
+    default:
+      break;
+  }
+}
+function diffMax(oldMax, newMax, path, changes) {
+  if (newMax > oldMax) {
+    changes.push({
+      kind: "additive",
+      code: "field.max_increased",
+      path,
+      message: `${path}: max increased from ${oldMax} to ${newMax}, safe for existing values`
+    });
+  } else if (newMax < oldMax) {
+    changes.push({
+      kind: "breaking",
+      code: "field.max_decreased",
+      path,
+      message: `${path}: max decreased from ${oldMax} to ${newMax} \u2014 existing values may no longer fit (breaking)`
+    });
+  }
+}
+function diffEnum(oldValues, newValues, path, changes) {
+  if (arraysEqual(oldValues, newValues)) return;
+  const isPureAppend = oldValues.length < newValues.length && oldValues.every((v, i) => newValues[i] === v);
+  if (isPureAppend) {
+    changes.push({
+      kind: "additive",
+      code: "enum.appended",
+      path,
+      message: `${path}: enum values appended (${newValues.slice(oldValues.length).join(", ")}), old values unchanged`
+    });
+  } else {
+    changes.push({
+      kind: "breaking",
+      code: "enum.reordered",
+      path,
+      message: `${path}: enum values changed from [${oldValues.join(", ")}] to [${newValues.join(", ")}] \u2014 reorder/rename/remove breaks the wire index (breaking)`
+    });
+  }
+}
+function diffDefault(oldT, newT, path, changes) {
+  if (!oldT.hasDefault && newT.hasDefault) {
+    changes.push({
+      kind: "additive",
+      code: "field.default_added",
+      path,
+      message: `${path}: gained a .default(...), existing snapshots keep their current values`
+    });
+  } else if (oldT.hasDefault && !newT.hasDefault) {
+    changes.push({
+      kind: "additive",
+      code: "field.default_removed",
+      path,
+      message: `${path}: .default(...) removed; existing snapshots already have values, so this is safe`
+    });
+  } else if (oldT.hasDefault && newT.hasDefault && stableStringify(oldT.default) !== stableStringify(newT.default)) {
+    changes.push({
+      kind: "additive",
+      code: "field.default_changed",
+      path,
+      message: `${path}: .default(...) value changed; clients with old snapshots keep their existing values`
+    });
+  }
+}
+function structFieldDescs(fields) {
+  return Object.entries(fields).map(([name, type], index) => ({ name, index, type }));
+}
+function sameStringSet(a, b) {
+  if (a.length !== b.length) return false;
+  const setA = new Set(a);
+  for (const v of b) if (!setA.has(v)) return false;
+  return true;
+}
+function arraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+function typeSignature(d) {
+  const o = { kind: d.kind, opt: d.opt };
+  switch (d.kind) {
+    case "str":
+      o.max = d.max;
+      break;
+    case "enum":
+      o.values = [...d.values];
+      break;
+    case "ref":
+      o.entity = d.entity;
+      break;
+    case "list":
+      o.max = d.max;
+      o.item = typeSignature(d.item);
+      break;
+    case "struct":
+      o.fields = Object.entries(d.fields).map(([k, v]) => [k, typeSignature(v)]);
+      break;
+    default:
+      break;
+  }
+  return stableStringify(o);
+}
+export {
+  ByteReader,
+  ByteWriter,
+  CANONICAL_VERSION,
+  EntityCollection,
+  ID_MAX_BYTES,
+  RESERVED_COLLECTION_NAMES,
+  RESERVED_RPC_NAMES,
+  SERVER_OWNER,
+  SINGLETON_ID,
+  applyDelta,
+  bool,
+  bytesEqual,
+  canonicalType,
+  client,
+  cloneValue,
+  collectionDirty,
+  computeDirty,
+  createDirtySet,
+  createFieldMask,
+  createState,
+  decodeDelta,
+  decodeDeltaFrom,
+  decodeFields,
+  decodeSnapshot,
+  defaultRecord,
+  defaultValue,
+  defineSchema,
+  describeType,
+  diffSchemas,
+  encodeDelta,
+  encodeFields,
+  encodeSnapshot,
+  entity,
+  enumOf,
+  estimateSize,
+  f32,
+  f64,
+  filterDirty,
+  frozenProxy,
+  i32,
+  isDirtyEmpty,
+  isWhole,
+  list,
+  markAdd,
+  markField,
+  markOwner,
+  markPath,
+  markRemove,
+  mergeDirty,
+  mergeMask,
+  normalizeRecord,
+  normalizeValue,
+  readValue,
+  ref,
+  schemaFromCanonical,
+  server,
+  sha256,
+  sha256Hex,
+  singleton,
+  stableStringify,
+  str,
+  struct,
+  toHex,
+  track,
+  u16,
+  u32,
+  u8,
+  validateForDeploy,
+  validateValue,
+  writeValue
+};