@irtio/schema 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,704 @@
+/**
+ * Type builders and runtime type descriptors.
+ *
+ * The type menu is exactly: bool u8 u16 u32 i32 f32 f64 str(max) enumOf(...) ref(entity)
+ * list(T, max) struct({...}) plus `.opt` and `.default(v)` chainable on any of them.
+ * Nothing else — the menu is deliberately closed.
+ */
+type ScalarKind = 'bool' | 'u8' | 'u16' | 'u32' | 'i32' | 'f32' | 'f64';
+/** Common flags on every descriptor. */
+interface DescBase {
+    /** `.opt` — value may be `undefined`; encoded with a presence bit. */
+    readonly opt: boolean;
+    /** `.default(v)` was called. */
+    readonly hasDefault: boolean;
+    readonly default?: unknown;
+}
+type TypeDesc = (DescBase & {
+    readonly kind: ScalarKind;
+}) | (DescBase & {
+    readonly kind: 'str';
+    readonly max: number;
+}) | (DescBase & {
+    readonly kind: 'enum';
+    readonly values: readonly string[];
+}) | (DescBase & {
+    readonly kind: 'ref';
+    readonly entity: string;
+}) | (DescBase & {
+    readonly kind: 'list';
+    readonly item: TypeDesc;
+    readonly max: number;
+}) | (DescBase & {
+    readonly kind: 'struct';
+    readonly fields: StructFieldDescs;
+});
+/** Struct fields keep declaration order (field index on the wire). */
+type StructFieldDescs = Readonly<Record<string, TypeDesc>>;
+type Kind = TypeDesc['kind'];
+/**
+ * A schema type. `T` is the inferred plain TS type; `D` is `true` once `.default()` was called
+ * (it makes the field optional at `add()`/init time).
+ */
+interface Type<T, D extends boolean = false> {
+    readonly desc: TypeDesc;
+    /** Makes the value optional (`T | undefined`). */
+    readonly opt: Type<T | undefined, D>;
+    /** Declares a default; used by migrations (additive new field) and by `add()`/init. */
+    default(value: T): Type<T, true>;
+    /** Phantom; never set at runtime. */
+    readonly __type?: T;
+    readonly __hasDefault?: D;
+}
+type AnyType = Type<any, boolean>;
+type Fields = Readonly<Record<string, AnyType>>;
+declare const bool: Type<boolean>;
+declare const u8: Type<number>;
+declare const u16: Type<number>;
+declare const u32: Type<number>;
+declare const i32: Type<number>;
+declare const f32: Type<number>;
+declare const f64: Type<number>;
+/** String with a maximum length in UTF-8 bytes. Oversize values throw on encode. */
+declare function str(max: number): Type<string>;
+/** Enum encoded as a u8 index in declaration order (appending is additive; reordering is breaking). */
+declare function enumOf<const V extends readonly [string, ...string[]]>(...values: V): Type<V[number]>;
+/** Reference to an entity instance by id; encoded as the id string. */
+declare function ref<E extends string>(entity: E): Type<string>;
+/** Bounded list, whole-replace on the wire. */
+declare function list<T, D extends boolean>(item: Type<T, D>, max: number): Type<T[]>;
+/** Nested object; fields are tracked and encoded individually. */
+declare function struct<F extends Fields>(fields: F): Type<InferFields<F>>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** Plain TS type for a builder type or a record of fields. */
+type Infer<X> = X extends Type<infer T, any> ? T : X extends Fields ? InferFields<X> : never;
+type OptKeys<F extends Fields> = {
+    [K in keyof F]: undefined extends Infer<F[K]> ? K : never;
+}[keyof F];
+/** Plain object type for a record of fields: `.opt` fields become `k?: T | undefined`. */
+type InferFields<F extends Fields> = Simplify<{
+    [K in Exclude<keyof F, OptKeys<F>>]: Infer<F[K]>;
+} & {
+    [K in OptKeys<F>]?: Infer<F[K]> | undefined;
+}>;
+type InitOptKeys<F extends Fields> = {
+    [K in keyof F]: undefined extends Infer<F[K]> ? K : F[K] extends Type<any, true> ? K : never;
+}[keyof F];
+/** Init shape for `add()` / singleton init: `.opt` and `.default()` fields may be omitted. */
+type InitFields<F extends Fields> = Simplify<{
+    [K in Exclude<keyof F, InitOptKeys<F>>]: Infer<F[K]>;
+} & {
+    [K in InitOptKeys<F>]?: Infer<F[K]> | undefined;
+}>;
+declare function describeType(d: TypeDesc): string;
+/** Entity ids are strings of at most this many UTF-8 bytes (`str(32)` on the wire). */
+declare const ID_MAX_BYTES = 32;
+/**
+ * Validates a plain value against a descriptor. Returns an error message or `null`.
+ * Used by `.default()`, by the codec on encode (throws), and later by RPC param validation.
+ */
+declare function validateValue(d: TypeDesc, v: unknown, path?: string): string | null;
+/** Zero/default value for a descriptor (after `.default`, else the type's zero; `.opt` → undefined). */
+declare function defaultValue(d: TypeDesc): unknown;
+/** Deep-clones a plain value (arrays + plain objects + primitives). */
+declare function cloneValue<T>(v: T): T;
+/**
+ * Normalizes a plain value to what it will look like after a wire round-trip: fills missing
+ * defaulted fields, applies `Math.fround` to f32, validates integers/sizes. Throws on invalid input.
+ * Returns a fresh value (never aliases `v` for lists/structs).
+ */
+declare function normalizeValue(d: TypeDesc, v: unknown, path?: string): unknown;
+
+/**
+ * `entity`, `singleton`, `server`, `client`, `defineSchema`, and the compiled schema
+ * (ordered collection descriptors, sorted RPC table, canonical form, hash).
+ */
+
+type Visibility = 'all' | 'role' | 'spatial-grid';
+interface EntityOptions {
+    /** `true` → never client-owned; `DeepReadonly` on the client at compile time. */
+    readonly serverOwned?: boolean;
+    /** `'all'` (default) | `'role'` (per-role views, needs `roles`) | `'spatial-grid'` (accepted by the types, rejected at deploy — not yet supported). */
+    readonly visibility?: Visibility;
+    /** With `visibility: 'role'`: the roles that see this collection. */
+    readonly roles?: readonly string[];
+}
+interface EntityDef<F extends Fields = Fields, O extends EntityOptions = EntityOptions> {
+    readonly kind: 'entity';
+    readonly fields: F;
+    readonly options: O;
+}
+interface SingletonDef<F extends Fields = Fields, O extends EntityOptions = EntityOptions> {
+    readonly kind: 'singleton';
+    readonly fields: F;
+    readonly options: O;
+}
+type AnyDef = EntityDef<any, any> | SingletonDef<any, any>;
+type DefMap = Readonly<Record<string, AnyDef>>;
+/** A keyed collection of instances, each with an owner (client id or the server). */
+declare function entity<F extends Fields>(fields: F): EntityDef<F, {}>;
+declare function entity<F extends Fields, const O extends EntityOptions>(fields: F, options: O): EntityDef<F, O>;
+/** Exactly one instance; same `serverOwned`/`visibility` options. */
+declare function singleton<F extends Fields>(fields: F): SingletonDef<F, {}>;
+declare function singleton<F extends Fields, const O extends EntityOptions>(fields: F, options: O): SingletonDef<F, O>;
+type RpcDirection = 'server' | 'client';
+interface RpcDef<Dir extends RpcDirection = RpcDirection, P extends Fields = Fields, R extends Fields | undefined = Fields | undefined> {
+    readonly kind: 'rpc';
+    readonly direction: Dir;
+    readonly params: P;
+    readonly returns: R;
+}
+type AnyRpc = RpcDef<RpcDirection, any, any>;
+type RpcMap = Readonly<Record<string, AnyRpc>>;
+interface RpcSpec<P extends Fields, R extends Fields | undefined> {
+    readonly params?: P;
+    readonly returns?: R;
+}
+/** Client → server call, implemented in the room file. */
+declare function server(): RpcDef<'server', {}, undefined>;
+declare function server<P extends Fields = {}>(spec: {
+    readonly params?: P;
+    readonly returns?: undefined;
+}): RpcDef<'server', P, undefined>;
+declare function server<P extends Fields = {}, R extends Fields = Fields>(spec: {
+    readonly params?: P;
+    readonly returns: R;
+}): RpcDef<'server', P, R>;
+/** Server → client call, implemented in the game client. */
+declare function client(): RpcDef<'client', {}, undefined>;
+declare function client<P extends Fields = {}>(spec: {
+    readonly params?: P;
+    readonly returns?: undefined;
+}): RpcDef<'client', P, undefined>;
+declare function client<P extends Fields = {}, R extends Fields = Fields>(spec: {
+    readonly params?: P;
+    readonly returns: R;
+}): RpcDef<'client', P, R>;
+/** RPC names a builder may not declare (built-ins live in `@irtio/protocol`). */
+declare const RESERVED_RPC_NAMES: readonly string[];
+/** Collection names a builder may not declare (the runtime merges built-in state under them). */
+declare const RESERVED_COLLECTION_NAMES: readonly string[];
+interface FieldDesc {
+    readonly name: string;
+    /** Declaration index = wire index. */
+    readonly index: number;
+    readonly type: TypeDesc;
+}
+interface CollectionDesc {
+    readonly name: string;
+    /** Index in `schema.collections` (sorted by name) = wire index. */
+    readonly index: number;
+    readonly kind: 'entity' | 'singleton';
+    readonly fields: readonly FieldDesc[];
+    readonly fieldIndex: ReadonlyMap<string, number>;
+    readonly serverOwned: boolean;
+    readonly visibility: Visibility;
+    readonly roles: readonly string[] | undefined;
+}
+interface RpcDesc {
+    readonly name: string;
+    /** Index in `schema.rpcs` (sorted by name). Built-ins are appended by `@irtio/protocol`. */
+    readonly index: number;
+    readonly direction: RpcDirection;
+    readonly params: readonly FieldDesc[];
+    /** `undefined` = void. */
+    readonly returns: readonly FieldDesc[] | undefined;
+}
+interface SchemaOptions<Rpc extends RpcMap, Roles extends readonly string[]> {
+    readonly rpc?: Rpc;
+    readonly roles?: Roles;
+    /** The public project id, written by `irtio init`. Identity, not shape: not part of the hash. */
+    readonly project?: string;
+    /** Internal: lets `@irtio/protocol` build the runtime-extended schema with built-in collections. */
+    readonly allowReservedNames?: boolean;
+}
+interface Schema<Defs extends DefMap = DefMap, Rpc extends RpcMap = RpcMap, Roles extends readonly string[] = readonly string[]> {
+    readonly defs: Defs;
+    readonly rpc: Rpc;
+    readonly roles: Roles;
+    readonly project: string | undefined;
+    /** Collections sorted by name; index = wire index. */
+    readonly collections: readonly CollectionDesc[];
+    readonly collection: (name: string) => CollectionDesc;
+    /** Builder RPCs sorted by name; index = wire `rpcId` (protocol appends built-ins after). */
+    readonly rpcs: readonly RpcDesc[];
+    /** Canonical JSON (sorted keys, `canonicalVersion: 1`). */
+    readonly canonical: string;
+    /** SHA-256 of the canonical form, hex. */
+    readonly hash: string;
+    /** First 8 bytes of the hash (HELLO / snapshot / delta header). */
+    readonly hash8: Uint8Array;
+}
+type AnySchema = Schema<any, any, any>;
+declare function defineSchema<const Defs extends DefMap, const Rpc extends RpcMap = {}, const Roles extends readonly string[] = readonly string[]>(defs: Defs, options?: SchemaOptions<Rpc, Roles>): Schema<Defs, Rpc, Roles>;
+declare const CANONICAL_VERSION = 1;
+declare function canonicalType(d: TypeDesc): Record<string, unknown>;
+/**
+ * JSON.stringify with object keys sorted at every level (arrays keep order). Keys whose value is
+ * `undefined` are dropped, exactly as `JSON.stringify` drops them — without that the canonical
+ * form can come out as text that `JSON.parse` rejects.
+ */
+declare function stableStringify(v: unknown): string;
+interface SchemaIssue {
+    readonly level: 'error' | 'warning';
+    readonly message: string;
+}
+/** Checks a schema for things accepted by the types/hash but not currently deployable. */
+declare function validateForDeploy(schema: AnySchema): SchemaIssue[];
+
+/**
+ * `schemaFromCanonical` — rebuild a runnable schema from its canonical JSON.
+ *
+ * A deployment stores `schema.canonical`. Waking a room that was hibernated under an older
+ * deployment means decoding its snapshot with *that* deployment's schema — and the old
+ * TypeScript source is long gone. The canonical form is complete by construction
+ * (`canonicalVersion: 1` carries every collection, field descriptor, rpc and role that feeds
+ * the hash), so it can be replayed back through the same builders the DSL uses.
+ *
+ * The invariant that makes this trustworthy: `schemaFromCanonical(s.canonical).canonical === s.canonical`
+ * (and therefore the same hash, the same wire indices, and byte-identical codecs). It is checked
+ * here on every call — a mismatch is a bug in this file, not a caller error, and failing loudly
+ * beats decoding a snapshot with a subtly wrong schema.
+ */
+
+interface FromCanonicalOptions {
+    /**
+     * The public project id. Identity, not shape — it is deliberately not part of the canonical
+     * form, so a caller that needs `schema.project` populated must pass it back in.
+     */
+    readonly project?: string;
+}
+/**
+ * Reconstructs a runnable schema from canonical JSON. Throws with a pointed message on anything
+ * malformed; the caller (deploy, the tenant wake path) treats that as a corrupt deployment.
+ */
+declare function schemaFromCanonical(json: string, options?: FromCanonicalOptions): AnySchema;
+
+/**
+ * Plain (untracked) entity collections and state objects. `track()` wraps these; the codec
+ * reads/writes them. Owners live beside values.
+ */
+
+/** Owner sentinel for "the server". */
+declare const SERVER_OWNER = "";
+/** The implicit id used for singletons in dirty sets and on the wire. */
+declare const SINGLETON_ID = "";
+interface AddOptions {
+    readonly owner?: string;
+}
+interface ReadonlyCollection<T> {
+    get(id: string): T | undefined;
+    has(id: string): boolean;
+    ownerOf(id: string): string | undefined;
+    readonly size: number;
+    ids(): IterableIterator<string>;
+    [Symbol.iterator](): IterableIterator<readonly [string, T]>;
+}
+interface Collection<T, Init = T> extends ReadonlyCollection<T> {
+    /** Adds (or replaces) an instance. Missing `.opt`/`.default()` fields are filled. */
+    add(id: string, values: Init, options?: AddOptions): T;
+    remove(id: string): boolean;
+    setOwner(id: string, owner: string): void;
+    [Symbol.iterator](): IterableIterator<readonly [string, T]>;
+}
+interface Record_<T> {
+    owner: string;
+    value: T;
+}
+/** Plain collection backed by a Map. Values are normalized (defaults filled, f32 frounded) on add. */
+declare class EntityCollection<T extends object = any, Init = T> implements Collection<T, Init> {
+    readonly desc: CollectionDesc;
+    readonly records: Map<string, Record_<T>>;
+    constructor(desc: CollectionDesc);
+    add(id: string, values: Init, options?: AddOptions): T;
+    remove(id: string): boolean;
+    get(id: string): T | undefined;
+    has(id: string): boolean;
+    setOwner(id: string, owner: string): void;
+    ownerOf(id: string): string | undefined;
+    get size(): number;
+    ids(): IterableIterator<string>;
+    [Symbol.iterator](): IterableIterator<readonly [string, T]>;
+}
+/** Builds a full record from init values: every field present, defaults applied, f32 frounded. */
+declare function normalizeRecord(desc: CollectionDesc, values: Record<string, unknown>): Record<string, unknown>;
+/** A record with every field at its default. */
+declare function defaultRecord(desc: CollectionDesc): Record<string, unknown>;
+/** Plain state: `{ [collectionName]: EntityCollection | singletonObject }`. */
+type PlainState = Record<string, EntityCollection | Record<string, unknown>>;
+/**
+ * Creates an empty plain state for a schema: empty collections, singletons at their defaults.
+ * The result is what `track()`, the codec, and tests operate on.
+ */
+declare function createState<S extends AnySchema>(schema: S, init?: Partial<Record<string, Record<string, unknown>>>): PlainState;
+
+/**
+ * Type-level inference over a schema: `State`, `ClientState`, per-role views, `Owned`,
+ * `ServerRpcs` / `ClientRpcs` / `Implementations`, and call-proxy signatures.
+ *
+ * Kept to simple mapped types so a 30-entity schema type-checks fast (see test/large.test-d.ts).
+ */
+
+type DeepReadonly<T> = T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+type DeepWritable<T> = T extends readonly (infer U)[] ? DeepWritable<U>[] : T extends object ? {
+    -readonly [K in keyof T]: DeepWritable<T[K]>;
+} : T;
+/** The writable view of an instance the client owns (the client SDK hands these out). */
+type Owned<T> = DeepWritable<T>;
+type SchemaDefs<S> = S extends Schema<infer D, any, any> ? D : never;
+type SchemaRpc<S> = S extends Schema<any, infer R, any> ? R : never;
+type SchemaRoles<S> = S extends Schema<any, any, infer R> ? R : never;
+type RoleOf<S> = SchemaRoles<S>[number];
+/** Plain instance type of an entity/singleton definition. */
+type InstanceOf<D> = D extends EntityDef<infer F, any> ? InferFields<F> : D extends SingletonDef<infer F, any> ? InferFields<F> : never;
+/** Init type (`add()` values) of an entity definition. */
+type InitOf<D> = D extends EntityDef<infer F, any> ? InitFields<F> : D extends SingletonDef<infer F, any> ? InitFields<F> : never;
+type DefOptions<D> = D extends EntityDef<any, infer O> ? O : D extends SingletonDef<any, infer O> ? O : never;
+type State<S> = {
+    [K in keyof SchemaDefs<S>]: SchemaDefs<S>[K] extends EntityDef<infer F, any> ? Collection<InferFields<F>, InitFields<F>> : SchemaDefs<S>[K] extends SingletonDef<infer F, any> ? InferFields<F> : never;
+};
+type RolesOf<O extends EntityOptions> = O extends {
+    roles: readonly (infer R)[];
+} ? R : never;
+/** Is collection with options `O` visible to `Role`? */
+type VisibleTo<O extends EntityOptions, Role extends string> = O extends {
+    visibility: 'role';
+} ? [Role] extends [RolesOf<O>] ? true : false : true;
+type VisibleKeys<S, Role extends string> = {
+    [K in keyof SchemaDefs<S>]: VisibleTo<DefOptions<SchemaDefs<S>[K]>, Role> extends true ? K : never;
+}[keyof SchemaDefs<S>];
+/**
+ * The client's view of the state for `Role`. `serverOwned` collections and singletons are
+ * `DeepReadonly`; instance-owned collections hand out `DeepReadonly` instances by default
+ * (the client SDK uses `Owned<T>` for instances this client owns).
+ */
+type ClientState<S, Role extends RoleOf<S> & string = RoleOf<S> & string> = Simplify<{
+    [K in VisibleKeys<S, Role>]: SchemaDefs<S>[K] extends EntityDef<infer F, any> ? ReadonlyCollection<DeepReadonly<InferFields<F>>> : SchemaDefs<S>[K] extends SingletonDef<infer F, any> ? DeepReadonly<InferFields<F>> : never;
+}>;
+/** Collections the client can never own (compile-time `serverOwned: true`). */
+type ServerOwnedKeys<S> = {
+    [K in keyof SchemaDefs<S>]: DefOptions<SchemaDefs<S>[K]> extends {
+        serverOwned: true;
+    } ? K : never;
+}[keyof SchemaDefs<S>];
+/** Entity collections whose instances a client may own. */
+type OwnableKeys<S> = {
+    [K in keyof SchemaDefs<S>]: SchemaDefs<S>[K] extends EntityDef<any, infer O> ? O extends {
+        serverOwned: true;
+    } ? never : K : never;
+}[keyof SchemaDefs<S>];
+type RpcParams<D> = D extends RpcDef<any, infer P, any> ? InferFields<P> : never;
+type RpcReturns<D> = D extends RpcDef<any, any, infer R> ? R extends Fields ? InferFields<R> : void : never;
+/** Builder RPCs implemented on the server (client → server). Excludes built-ins. */
+type ServerRpcs<R extends RpcMap> = {
+    [K in keyof R as R[K] extends RpcDef<'server', any, any> ? K : never]: R[K];
+};
+/** Builder RPCs implemented on the client (server → client). */
+type ClientRpcs<R extends RpcMap> = {
+    [K in keyof R as R[K] extends RpcDef<'client', any, any> ? K : never]: R[K];
+};
+/** Exhaustive implementation map: every key required; extra keys rejected (object literals). */
+type Implementations<Rpcs extends Record<string, AnyRpc>, StateT, Ctx> = {
+    [K in keyof Rpcs]: (state: StateT, params: RpcParams<Rpcs[K]>, ctx: Ctx) => RpcReturns<Rpcs[K]>;
+};
+/** Client-side implementations (server → client): params only, may return a Promise. */
+type ClientImplementations<Rpcs extends Record<string, AnyRpc>> = {
+    [K in keyof Rpcs]: (params: RpcParams<Rpcs[K]>) => RpcReturns<Rpcs[K]> | Promise<RpcReturns<Rpcs[K]>>;
+};
+type IsEmptyParams<D> = D extends RpcDef<any, infer P, any> ? keyof P extends never ? true : false : false;
+type CallFn<D> = IsEmptyParams<D> extends true ? (params?: RpcParams<D>) => Promise<RpcReturns<D>> : (params: RpcParams<D>) => Promise<RpcReturns<D>>;
+/** `room.call.<rpc>(params)` on the client: every server RPC. */
+type ClientCallProxy<R extends RpcMap> = {
+    [K in keyof ServerRpcs<R>]: CallFn<R[K]>;
+};
+/** `room.call(clientId).<rpc>(params)` on the server: every client RPC. */
+type ServerCallProxy<R extends RpcMap> = {
+    [K in keyof ClientRpcs<R>]: CallFn<R[K]>;
+};
+type VoidKeys<M extends Record<string, AnyRpc>> = {
+    [K in keyof M]: RpcReturns<M[K]> extends void ? K : never;
+}[keyof M];
+/** `room.broadcast.<rpc>(params)`: void client RPCs only. */
+type BroadcastProxy<R extends RpcMap> = {
+    [K in VoidKeys<ClientRpcs<R>>]: IsEmptyParams<R[K]> extends true ? (params?: RpcParams<R[K]>) => void : (params: RpcParams<R[K]>) => void;
+};
+
+/**
+ * The dirty-set contract shared by `track()` (producer) and the codec (consumer).
+ *
+ * - Field indices are the declaration indices on the collection/struct descriptor.
+ * - A struct field is dirty when its bit is in `fields`. If `nested` has an entry for it, only the
+ *   nested-dirty fields are sent; no nested entry ⇒ the whole struct value is re-sent.
+ * - `owner: true` ⇒ the owner system field changed (entities only).
+ * - `added` records are sent whole (every field + owner); `removed` ids are sent as removes.
+ *   An id is never in more than one of `added` / `removed` / `updated`.
+ * - Singletons use `SINGLETON_ID` (`''`) in `updated` and never add/remove.
+ */
+interface FieldMask {
+    readonly fields: Set<number>;
+    readonly nested: Map<number, FieldMask>;
+}
+interface RecordDirty {
+    readonly mask: FieldMask;
+    owner: boolean;
+}
+interface CollectionDirty {
+    readonly added: Set<string>;
+    readonly removed: Set<string>;
+    readonly updated: Map<string, RecordDirty>;
+}
+/** Keyed by collection name. */
+type DirtySet = Map<string, CollectionDirty>;
+declare function createDirtySet(): DirtySet;
+declare function createFieldMask(): FieldMask;
+declare function collectionDirty(dirty: DirtySet, collection: string): CollectionDirty;
+/**
+ * Marks a field path (declaration indices, outermost first) dirty on a record. The value at the
+ * end of the path is sent whole; intermediate structs become partial unless already whole.
+ */
+declare function markField(dirty: DirtySet, collection: string, id: string, path: readonly number[]): void;
+declare function markPath(mask: FieldMask, path: readonly number[]): void;
+declare function markOwner(dirty: DirtySet, collection: string, id: string): void;
+declare function markAdd(dirty: DirtySet, collection: string, id: string): void;
+declare function markRemove(dirty: DirtySet, collection: string, id: string): void;
+declare function isDirtyEmpty(dirty: DirtySet): boolean;
+/** Is field `idx` of `mask` dirty and to be sent whole (no partial nested mask)? */
+declare function isWhole(mask: FieldMask, idx: number): boolean;
+/** Merges `src` into `dst` (union of dirtiness). */
+declare function mergeDirty(dst: DirtySet, src: DirtySet): void;
+declare function mergeMask(dst: FieldMask, src: FieldMask): void;
+/** A new dirty set containing only the collections `keep` accepts (entries are shared, not copied). */
+declare function filterDirty(dirty: DirtySet, keep: (collection: string) => boolean): DirtySet;
+
+/**
+ * Synchronous SHA-256 (FIPS 180-4), zero dependencies, runs in Node and browsers.
+ *
+ * `schema.hash` must be available synchronously at module-init time (defineSchema is called at
+ * top level of `irtio/schema.ts`, and the client needs the hash for HELLO), which rules out
+ * `crypto.subtle.digest`. Tests verify this implementation against `crypto.subtle`.
+ */
+/** SHA-256 digest of `data` as 32 bytes. */
+declare function sha256(data: Uint8Array): Uint8Array;
+declare function sha256Hex(data: Uint8Array): string;
+declare function toHex(bytes: Uint8Array): string;
+
+/**
+ * Byte-level primitives shared by the schema codec and `@irtio/protocol` framing.
+ * Little-endian numbers; LEB128 unsigned varints for lengths/indices; strings are
+ * varint byte-length + UTF-8.
+ */
+declare class ByteWriter {
+    private buf;
+    private view;
+    private pos;
+    constructor(initialCapacity?: number);
+    get length(): number;
+    private ensure;
+    u8(v: number): void;
+    bool(v: boolean): void;
+    u16(v: number): void;
+    u32(v: number): void;
+    i32(v: number): void;
+    f32(v: number): void;
+    f64(v: number): void;
+    /** LEB128 unsigned varint (0 .. 2^32-1). */
+    varint(v: number): void;
+    /** Raw bytes, no length prefix. */
+    bytes(b: Uint8Array): void;
+    /** varint length + raw bytes. */
+    blob(b: Uint8Array): void;
+    /** varint UTF-8 byte length + bytes. Returns the byte length written. */
+    str(s: string): number;
+    /** Reserves `n` bytes and returns their offset (for masks filled in later). */
+    reserve(n: number): number;
+    setU8(at: number, v: number): void;
+    orU8(at: number, v: number): void;
+    /** A copy of the written bytes. */
+    finish(): Uint8Array;
+}
+declare class ByteReader {
+    readonly buf: Uint8Array;
+    private readonly view;
+    pos: number;
+    constructor(buf: Uint8Array, offset?: number);
+    get remaining(): number;
+    get eof(): boolean;
+    private need;
+    u8(): number;
+    bool(): boolean;
+    u16(): number;
+    u32(): number;
+    i32(): number;
+    f32(): number;
+    f64(): number;
+    varint(): number;
+    /** `n` raw bytes (a view, not a copy). */
+    bytes(n: number): Uint8Array;
+    /** varint length + raw bytes (a view). */
+    blob(): Uint8Array;
+    str(): string;
+    /** The rest of the buffer (a view). */
+    rest(): Uint8Array;
+}
+declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+ * The binary codec: snapshots, deltas, field-level diffing, and exact size estimation.
+ *
+ * Wire format (little-endian numbers, LEB128 varints, `str` = varint UTF-8 length + bytes):
+ *
+ * - value: `.opt` values are prefixed with a presence byte (0 = undefined, 1 = present).
+ *   bool/u8 1 byte, u16 2, u32/i32/f32 4, f64 8, str/ref = str, enum = u8 index,
+ *   list = varint length + items, struct (snapshot form) = every field in declaration order.
+ * - snapshot: `tick` u32, `hash8` 8 bytes, then every collection in `schema.collections` order —
+ *   entity = varint count + (id str, owner str, record) per record; singleton = record.
+ * - delta: `tick` u32, `hash8` 8 bytes, varint dirty-collection count, then per collection
+ *   (ascending index) varint collectionIndex, varint opCount and the ops. Op byte 0 = add
+ *   (id str, owner str, record), 1 = update, 2 = remove (id str). An update is
+ *   id str, a bitmask of `ceil((nFields + 1) / 8)` bytes (bit i = field i dirty,
+ *   bit nFields = owner changed; bit k lives at byte `k >> 3`, bit `k & 7`), the owner str if
+ *   the owner bit is set, then the dirty fields in index order. A dirty struct field is written
+ *   as its presence byte (when `.opt`) followed by a nested mask of `ceil(n / 8)` bytes — all
+ *   bits set when the whole struct is dirty — and its dirty fields under the same rule.
+ *
+ * Encoding validates: oversize strings/lists, out-of-range or non-integer ints, wrong types,
+ * missing required values and unknown enum members all throw with the field path.
+ */
+
+/**
+ * The subset of `ByteWriter` the codec writes through. `ByteWriter` satisfies it; so does the
+ * internal counting sink used by `estimateSize` (which never allocates the payload).
+ */
+interface ValueSink {
+    u8(v: number): void;
+    bool(v: boolean): void;
+    u16(v: number): void;
+    u32(v: number): void;
+    i32(v: number): void;
+    f32(v: number): void;
+    f64(v: number): void;
+    varint(v: number): void;
+    bytes(b: Uint8Array): void;
+    str(s: string): number;
+}
+/** Writes one value in snapshot form (presence byte first when the descriptor is `.opt`). */
+declare function writeValue(w: ValueSink, desc: TypeDesc, v: unknown, path?: string): void;
+/** Reads one value in snapshot form. */
+declare function readValue(r: ByteReader, desc: TypeDesc): unknown;
+/** Snapshot-form record encoding — used for RPC params and returns. */
+declare function encodeFields(fields: readonly FieldDesc[], value: Record<string, unknown>): Uint8Array;
+/** Decodes a snapshot-form record. Accepts raw bytes or a positioned `ByteReader`. */
+declare function decodeFields(fields: readonly FieldDesc[], bytes: Uint8Array | ByteReader): Record<string, unknown>;
+type PlainRecord = Record<string, unknown>;
+interface Header {
+    readonly tick: number;
+}
+/** Snapshot options: `collections` limits which collections carry data (others are encoded empty/default). */
+interface SnapshotOptions {
+    readonly collections?: (c: CollectionDesc) => boolean;
+}
+declare function encodeSnapshot(schema: AnySchema, state: PlainState, header: Header, options?: SnapshotOptions): Uint8Array;
+interface DecodedSnapshot {
+    readonly tick: number;
+    readonly hash8: Uint8Array;
+    readonly state: PlainState;
+}
+declare function decodeSnapshot(schema: AnySchema, bytes: Uint8Array): DecodedSnapshot;
+type DeltaOp = {
+    readonly op: 'add';
+    readonly id: string;
+    readonly owner: string;
+    readonly value: PlainRecord;
+} | {
+    readonly op: 'update';
+    readonly id: string;
+    readonly owner?: string;
+    readonly mask: FieldMask;
+    readonly patch: PlainRecord;
+} | {
+    readonly op: 'remove';
+    readonly id: string;
+};
+interface DeltaCollection {
+    readonly name: string;
+    readonly ops: DeltaOp[];
+}
+interface Delta {
+    readonly tick: number;
+    readonly hash8: Uint8Array;
+    readonly collections: DeltaCollection[];
+}
+declare function encodeDelta(schema: AnySchema, state: PlainState, dirty: DirtySet, header: Header): Uint8Array;
+/** Exact byte length of `encodeDelta` for the same arguments, without building the payload. */
+declare function estimateSize(schema: AnySchema, state: PlainState, dirty: DirtySet): number;
+declare function decodeDelta(schema: AnySchema, bytes: Uint8Array): Delta;
+/**
+ * `decodeDelta` against a caller-owned reader, which is left positioned at the first byte after
+ * the delta body. Trailing bytes are the caller's: the `CORRECT` frame appends `clientTick`
+ * (u32) after the delta body (week 8, D19) — a decoder that does not know about the suffix
+ * ignores it, which is what makes the extension additive.
+ */
+declare function decodeDeltaFrom(schema: AnySchema, r: ByteReader): Delta;
+/**
+ * Applies a decoded delta in place. Only the `Collection` interface and plain property
+ * assignment are used, so this also works against a tracked proxy state.
+ */
+declare function applyDelta(schema: AnySchema, state: PlainState, delta: Delta): void;
+/** Field-level diff between two plain states: what would have to be sent to turn `from` into `to`. */
+declare function computeDirty(schema: AnySchema, from: PlainState, to: PlainState): DirtySet;
+
+/**
+ * `track()` — a proxy tree over a plain state that records every write into a `DirtySet`.
+ *
+ * The proxies are thin: reads of scalars go straight to the plain object, reads of structs/lists
+ * hand back cached child proxies, and writes normalize the value (so what you read back is what a
+ * wire round-trip would give you: f32 quantized, defaults filled) before marking the dirty set.
+ *
+ * Paths are declaration indices, outermost first (`[fieldIndex, nestedIndex, ...]`), exactly the
+ * shape `markField` wants. Lists are whole-replace on the wire, so anything that changes inside a
+ * list marks the list field itself.
+ */
+
+interface Tracked<S> {
+    /** Proxy tree over the plain state that was passed in. */
+    state: State<S>;
+    /** The live dirty set — replaced by `flush()`. */
+    dirty: DirtySet;
+    /** Returns the accumulated dirty set and starts a fresh one. */
+    flush(): DirtySet;
+}
+/**
+ * Wraps a plain state (from `createState` or a decoded snapshot) in tracking proxies.
+ * Every write through `tracked.state` marks `tracked.dirty`; `flush()` hands it over.
+ */
+declare function track<S extends AnySchema>(schema: S, state: PlainState): Tracked<S>;
+/**
+ * A deeply read-only view that *ignores* writes at runtime (rather than throwing), warning once
+ * per field path. The client SDK hands these out for objects this client does not own.
+ */
+declare function frozenProxy<T>(value: T, ownershipHint: string): DeepReadonly<T>;
+
+/**
+ * Schema diff classifier: compares two compiled `Schema`s (from `defineSchema`) and classifies
+ * every difference as `additive` (safe to deploy without breaking connected/reconnecting
+ * clients) or `breaking` (requires a fresh snapshot / client update). Works from the compiled
+ * descriptors (`collections`, `rpcs`, `roles`), never from the raw builder defs.
+ */
+
+interface SchemaChange {
+    readonly kind: 'additive' | 'breaking';
+    /** Stable machine tag, e.g. `field.removed`, `enum.appended`. */
+    readonly code: string;
+    /** Dotted path to the changed thing, e.g. `players.color`, `rpc.dealCards.params.count`. */
+    readonly path: string;
+    /** One-line human message, printed verbatim by the CLI. */
+    readonly message: string;
+}
+/** Compares two compiled schemas and returns every classified change, sorted by path then code. */
+declare function diffSchemas(oldSchema: AnySchema, newSchema: AnySchema): SchemaChange[];
+
+export { type AddOptions, type AnyDef, type AnyRpc, type AnySchema, type AnyType, type 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 FieldDesc, type FieldMask, type Fields, type FromCanonicalOptions, type Header, ID_MAX_BYTES, type Implementations, type Infer, type InferFields, type InitFields, type InitOf, type InstanceOf, type Kind, type OwnableKeys, type Owned, type PlainState, RESERVED_COLLECTION_NAMES, RESERVED_RPC_NAMES, type ReadonlyCollection, type RecordDirty, type RoleOf, type RpcDef, type RpcDesc, type RpcDirection, type RpcMap, type RpcParams, type RpcReturns, type RpcSpec, SERVER_OWNER, SINGLETON_ID, type Schema, type SchemaChange, type SchemaDefs, type SchemaIssue, type SchemaOptions, type SchemaRoles, type SchemaRpc, type ServerCallProxy, type ServerOwnedKeys, type ServerRpcs, type SingletonDef, type SnapshotOptions, type State, type Tracked, type Type, type TypeDesc, type ValueSink, type Visibility, type VisibleKeys, applyDelta, bool, bytesEqual, 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 };