@colyseus/schema 4.0.20 → 5.0.0

package/src/encoder/ChangeTree.ts

@@ -1,20 +1,56 @@
+/**
+ * ChangeTree — the per-`Ref` mutation tracker attached via `$changes`.
+ *
+ * This file owns: class shape (fields, flags, ctor), inline
+ * ChangeRecorder implementation (record / forEach / …), mutation API
+ * (change / delete / operation / …), and encode lifecycle (endEncode /
+ * discard / …). Helpers split out into ./changeTree/:
+ *
+ *   - parentChain.ts     addParent / removeParent / find / has / getAll
+ *   - liveIteration.ts   forEachLive
+ *   - inheritedFlags.ts  filter / unreliable / transient / static inheritance
+ *   - treeAttachment.ts  setRoot / setParent / forEachChild(+WithCtx)
+ *
+ * Public surface on ChangeTree is unchanged — methods are thin pass-throughs
+ * into the helpers. V8 inlines the pass-throughs; the runtime shape stays
+ * a single class to preserve hidden-class + IC behavior.
+ */
 import { OPERATION } from "../encoding/spec.js";
 import { Schema } from "../Schema.js";
-import { $changes, $childType, $decoder, $onEncodeEnd, $encoder, $getByIndex, $refId, $refTypeFieldIndexes, $viewFieldIndexes, type $deleteByIndex } from "../types/symbols.js";
+import { $changes, $childType, $decoder, $onEncodeEnd, $encoder, $getByIndex, $proxyTarget, $refId, $refTypeFieldIndexes, $numFields, type $deleteByIndex } from "../types/symbols.js";
 
 import type { MapSchema } from "../types/custom/MapSchema.js";
 import type { ArraySchema } from "../types/custom/ArraySchema.js";
 import type { CollectionSchema } from "../types/custom/CollectionSchema.js";
 import type { SetSchema } from "../types/custom/SetSchema.js";
+import type { StreamSchema } from "../types/custom/StreamSchema.js";
 
 import { Root } from "./Root.js";
 import { Metadata } from "../Metadata.js";
+import { type ChangeRecorder, type ICollectionChangeRecorder, SchemaChangeRecorder, CollectionChangeRecorder, popcount32 } from "./ChangeRecorder.js";
 import type { EncodeOperation } from "./EncodeOperation.js";
+import { type EncodeDescriptor, getEncodeDescriptor } from "./EncodeDescriptor.js";
 import type { DecodeOperation } from "../decoder/DecodeOperation.js";
 
+import {
+    addParent as _addParent, removeParent as _removeParent,
+    findParent as _findParent, hasParent as _hasParent,
+    getAllParents as _getAllParents,
+} from "./changeTree/parentChain.js";
+import { forEachLive as _forEachLive, forEachLiveWithCtx as _forEachLiveWithCtx } from "./changeTree/liveIteration.js";
+import {
+    setRoot as _setRoot, setParent as _setParent,
+    forEachChild as _forEachChild, forEachChildWithCtx as _forEachChildWithCtx,
+} from "./changeTree/treeAttachment.js";
+
+// Augmenting the global `Object` interface is a deliberate trade-off:
+// any Schema / collection instance — regardless of which bundled
+// `@colyseus/schema` version created it — can be duck-typed against
+// these Symbol-keyed slots. Narrower shapes (e.g. on `IRef`) would break
+// cross-version interop where server-bundled types coexist with client-
+// bundled ones in the same process.
 declare global {
     interface Object {
-        // FIXME: not a good practice to extend globals here
         [$changes]?: ChangeTree;
         // [$refId]?: number;
         [$encoder]?: EncodeOperation,
@@ -22,25 +58,40 @@ declare global {
     }
 }
 
-export interface IRef {
-    // FIXME: we only commented this out to allow mixing @colyseus/schema bundled types with server types in Cocos Creator
-    // [$changes]?: ChangeTree;
-    [$refId]?: number;
-    [$getByIndex]?: (index: number, isEncodeAll?: boolean) => any;
-    [$deleteByIndex]?: (index: number) => void;
+// Pure arithmetic, no `this` — V8 inlines into encode-loop forEach.
+// Mirror of `ChangeTree._opAt` for the inline-ops-only branch.
+function readInlineOpByte(low: number, high: number, index: number): number {
+    const shift = (index & 3) << 3;
+    return (index < 4)
+        ? (low >>> shift) & 0xFF
+        : (high >>> shift) & 0xFF;
 }
 
-export type Ref = Schema | ArraySchema | MapSchema | CollectionSchema | SetSchema;
+// Adapter that lets `forEach(cb)` delegate to `forEachWithCtx(cb, _invokeNoCtx)` —
+// no per-call closure allocation. See ChangeRecorder.ts for the same pattern.
+const _invokeNoCtx = (
+    cb: (index: number, op: OPERATION) => void,
+    index: number,
+    op: OPERATION,
+) => cb(index, op);
 
-export type ChangeSetName = "changes"
-    | "allChanges"
-    | "filteredChanges"
-    | "allFilteredChanges";
-
-export interface IndexedOperations {
-    [index: number]: OPERATION;
+export interface IRef {
+    // `[$changes]?: ChangeTree;` is intentionally omitted here — see the
+    // `declare global` augmentation above. Narrowing to IRef would break
+    // cross-version interop (Cocos Creator bundles server- and client-
+    // side schema types together; a strict declaration here would reject
+    // one side's instances at compile time).
+    [$refId]?: number;
+    // `$getByIndex` / `$deleteByIndex` are required on every actual ref
+    // the decoder / encoder ever touches (Schema + every collection
+    // implements both). Keeping them non-optional lets hot-path call
+    // sites skip the `(ref as any)` cast.
+    [$getByIndex](index: number, isEncodeAll?: boolean): any;
+    [$deleteByIndex](index: number): void;
 }
 
+export type Ref = Schema | ArraySchema | MapSchema | CollectionSchema | SetSchema | StreamSchema;
+
 // Linked list node for change trees
 export interface ChangeTreeNode {
     changeTree: ChangeTree;
@@ -55,345 +106,548 @@ export interface ChangeTreeList {
     tail?: ChangeTreeNode;
 }
 
-export interface ChangeSet {
-    // field index -> operation index
-    indexes: { [index: number]: number };
-    operations: number[];
-    queueRootNode?: ChangeTreeNode; // direct reference to ChangeTreeNode in the linked list
-}
-
-function createChangeSet(queueRootNode?: ChangeTreeNode): ChangeSet {
-    return { indexes: {}, operations: [], queueRootNode };
-}
-
 // Linked list helper functions
 export function createChangeTreeList(): ChangeTreeList {
     return { next: undefined, tail: undefined };
 }
 
-export function setOperationAtIndex(changeSet: ChangeSet, index: number) {
-    const operationsIndex = changeSet.indexes[index];
-    if (operationsIndex === undefined) {
-        changeSet.indexes[index] = changeSet.operations.push(index) - 1;
-    } else {
-        changeSet.operations[operationsIndex] = index;
-    }
-}
-
-export function deleteOperationAtIndex(changeSet: ChangeSet, index: number | string) {
-    let operationsIndex = changeSet.indexes[index as any as number];
-    if (operationsIndex === undefined) {
-        //
-        // if index is not found, we need to find the last operation
-        // FIXME: this is not very efficient
-        //
-        // > See "should allow consecutive splices (same place)" tests
-        //
-        operationsIndex = Object.values(changeSet.indexes).at(-1);
-        index = Object.entries(changeSet.indexes).find(([_, value]) => value === operationsIndex)?.[0];
-    }
-    changeSet.operations[operationsIndex] = undefined;
-    delete changeSet.indexes[index as any as number];
-}
-
-export function debugChangeSet(label: string, changeSet: ChangeSet) {
-    let indexes: string[] = [];
-    let operations: string[] = [];
-
-    for (const index in changeSet.indexes) {
-        indexes.push(`\t${index} => [${changeSet.indexes[index]}]`);
-    }
-
-    for (let i = 0; i < changeSet.operations.length; i++) {
-        const index = changeSet.operations[i];
-        if (index !== undefined) {
-            operations.push(`\t[${i}] => ${index}`);
-        }
-    }
-
-    console.log(`${label} =>\nindexes (${Object.keys(changeSet.indexes).length}) {`);
-    console.log(indexes.join("\n"), "\n}");
-    console.log(`operations (${changeSet.operations.filter(op => op !== undefined).length}) {`);
-    console.log(operations.join("\n"), "\n}");
-}
-
 export interface ParentChain {
     ref: Ref;
     index: number;
     next?: ParentChain;
 }
 
-export class ChangeTree<T extends Ref = any> {
+// Flags bitfield. *_UNRELIABLE / _TRANSIENT / _STATIC mirror the parent
+// field's annotation — inherited at setParent/setRoot time.
+export const IS_FILTERED = 1, IS_VISIBILITY_SHARED = 2, IS_NEW = 4;
+export const IS_UNRELIABLE = 8, IS_TRANSIENT = 16, IS_STATIC = 32;
+// Collection tree attached to a parent field annotated `.stream()` —
+// drives the encoder's priority/broadcast pass. Set in inheritedFlags
+// so both `t.stream(X)` (via StreamSchema's `$isStream` brand) and
+// `t.map(X).stream()` / `t.set(X).stream()` route through the same
+// emission machinery.
+export const IS_STREAM_COLLECTION = 64;
+/**
+ * Flags a child inherits from its parent's own transitive state via
+ * `checkInheritedFlags`. Read as a bitwise mask so the inheritance step
+ * is a single OR instead of three getter/setter pairs.
+ *
+ * `IS_UNRELIABLE` is intentionally excluded: `@unreliable` is rejected
+ * at decoration time for ref-type fields (see `Metadata.setUnreliable`)
+ * because an unreliable ADD/DELETE could leave the decoder unable to
+ * interpret later packets referencing an orphan refId. Tree-level
+ * unreliable is therefore dead on every Schema/Collection tree today;
+ * the bit and its machinery are kept in place so this can be
+ * reconsidered if a safe semantics (e.g. reliable ADD + unreliable
+ * field mutations only) is designed later.
+ */
+export const INHERITABLE_FLAGS = IS_TRANSIENT | IS_STATIC;
+
+export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     ref: T;
-    metadata: Metadata;
 
-    root?: Root;
-    parentChain?: ParentChain; // Linked list for tracking parents
+    /**
+     * Non-Proxy target of `ref` for encoder hot-path reads. For
+     * `ArraySchema`, `ref` is the Proxy users interact with; every property
+     * access on it runs through the `get` trap (even for symbol keys, which
+     * fall through to `Reflect.get` — one extra hop per lookup). The encoder
+     * loop reads `[$getByIndex]`, `[$childType]`, `.items`, `.tmpItems` at
+     * high frequency during `encode()` / `encodeAll()`; going through
+     * `refTarget` skips all of those traps.
+     *
+     * For non-proxied types (Schema, MapSchema, SetSchema, CollectionSchema,
+     * StreamSchema), `refTarget === ref`. Consumers that need the user-
+     * facing identity (debug output, callback parents) keep using `ref`.
+     */
+    refTarget: T;
+
+    metadata: Metadata;
 
     /**
-     * Whether this structure is parent of a filtered structure.
+     * Per-class cache of encoder fn / filter fn / isSchema / filterBitmask /
+     * metadata, looked up once at construction. The encode loop reads
+     * `tree.encDescriptor` and never touches `ref.constructor` again. See
+     * EncodeDescriptor.ts.
      */
-    isFiltered: boolean = false;
-    isVisibilitySharedWithParent?: boolean; // See test case: 'should not be required to manually call view.add() items to child arrays without @view() tag'
+    encDescriptor: EncodeDescriptor;
 
-    indexedOperations: IndexedOperations = {};
+    root?: Root;
 
-    //
-    // TODO:
-    //   try storing the index + operation per item.
-    //   example: 1024 & 1025 => ADD, 1026 => DELETE
-    //
-    // => https://chatgpt.com/share/67107d0c-bc20-8004-8583-83b17dd7c196
-    //
-    changes: ChangeSet = { indexes: {}, operations: [] };
-    allChanges: ChangeSet = { indexes: {}, operations: [] };
-    filteredChanges: ChangeSet;
-    allFilteredChanges: ChangeSet;
+    // Inline single parent (the common case)
+    parentRef?: Ref;
+    _parentIndex?: number;
+    extraParents?: ParentChain; // linked list for 2nd+ parents (rare: instance sharing)
 
-    indexes: { [index: string]: any }; // TODO: remove this, only used by MapSchema/SetSchema/CollectionSchema (`encodeKeyValueOperation`)
+    // Packed boolean flags. See IS_* constants above for bit layout.
+    flags: number = IS_NEW;
 
     /**
-     * Is this a new instance? Used on ArraySchema to determine OPERATION.MOVE_AND_ADD operation.
+     * Per-walk visit stamp written by `Encoder.encodeFullSync`'s DFS. A
+     * tree is considered "already visited by the current walk" iff
+     * `tree._fullSyncGen === ctx.gen` — the encoder bumps its generation
+     * counter once per walk, then stamps each tree with that value on
+     * first visit; any later encounter of the same tree (shared refs
+     * reachable through multiple parents) short-circuits on the equality
+     * check instead of recursing again.
      */
-    isNew = true;
+    _fullSyncGen: number = 0;
 
-    constructor(ref: T) {
-        this.ref = ref;
-        this.metadata = (ref.constructor as typeof Schema)[Symbol.metadata];
+    // Schema vs Collection discriminator. Set once in ctor, never changes —
+    // per-tree-stable branch for inline ChangeRecorder dispatch.
+    _isSchema: boolean = false;
 
-        //
-        // Does this structure have "filters" declared?
-        //
-        if (this.metadata?.[$viewFieldIndexes]) {
-            this.allFilteredChanges = { indexes: {}, operations: [] };
-            this.filteredChanges = { indexes: {}, operations: [] };
-        }
-    }
+    // Inline reliable SchemaChangeRecorder state (valid only if _isSchema).
+    dirtyLow: number = 0;
+    dirtyHigh: number = 0;
 
-    setRoot(root: Root) {
-        this.root = root;
+    // Inline ops for Schemas with ≤8 fields (4 op-bytes per number).
+    // When `ops` is set (>8 fields), reads/writes go through the Uint8Array.
+    opsLow: number = 0;
+    opsHigh: number = 0;
+    ops?: Uint8Array;
 
-        const isNewChangeTree = this.root.add(this);
+    // Inline reliable CollectionChangeRecorder state (valid only if !_isSchema).
+    // `collDirty` is allocated in the ctor. `collPureOps` stays undefined
+    // until the first CLEAR/REVERSE (most workloads never hit this).
+    collDirty?: Map<number, OPERATION>;
+    collPureOps?: Array<[number, OPERATION]>;
 
-        this.checkIsFiltered(this.parent, this.parentIndex, isNewChangeTree);
+    // Lazy-allocated unreliable-channel recorder (rare — opt-in via @unreliable).
+    unreliableRecorder?: ChangeRecorder;
 
-        // Recursively set root on child structures
-        if (isNewChangeTree) {
-            this.forEachChild((child, _) => {
-                if (child.root !== root) {
-                    child.setRoot(root);
-                } else {
-                    root.add(child); // increment refCount
-                }
-            });
-        }
-    }
+    // When true, mutations on the ref are NOT tracked. See pause/resume/untracked.
+    paused: boolean = false;
 
-    setParent(
-        parent: Ref,
-        root?: Root,
-        parentIndex?: number,
-    ) {
-        this.addParent(parent, parentIndex);
+    changesNode?: ChangeTreeNode;            // Root.changes linked-list node
+    unreliableChangesNode?: ChangeTreeNode;  // Root.unreliableChanges linked-list node
 
-        // avoid setting parents with empty `root`
-        if (!root) { return; }
+    // Per-StateView visibility bitmaps. Bit `(viewId & 31)` in slot
+    // `(viewId >> 5)` is set iff the view can see this tree. Replaces
+    // per-view WeakSet lookups with direct bitwise ops.
+    // Lazy: undefined until the tree participates in any view.
+    visibleViews?: number[];
+    invisibleViews?: number[];
 
-        const isNewChangeTree = root.add(this);
+    // Per-(view, tag) bitmap, indexed by tag. Custom tags only —
+    // DEFAULT_VIEW_TAG visibility lives in `visibleViews`.
+    tagViews?: Map<number, number[]>;
 
-        // skip if parent is already set
-        if (root !== this.root) {
-            this.root = root;
-            this.checkIsFiltered(parent, parentIndex, isNewChangeTree);
+    /**
+     * Per-view subscription bitmap — same layout as `visibleViews`. Set by
+     * `StateView.subscribe(collection)` to mark the view as persistently
+     * interested in this collection's contents. When a new child is
+     * attached to a subscribed collection (setParent hook), it's
+     * auto-propagated to every subscribed view (force-shipped for
+     * Array/Map/Set/Collection; enqueued into per-view pending for
+     * streams). Undefined until the first subscribe.
+     */
+    subscribedViews?: number[];
+
+    // Accessor properties for flags
+    get isFiltered() { return (this.flags & IS_FILTERED) !== 0; }
+    set isFiltered(v: boolean) { this.flags = v ? (this.flags | IS_FILTERED) : (this.flags & ~IS_FILTERED); }
+    get isVisibilitySharedWithParent() { return (this.flags & IS_VISIBILITY_SHARED) !== 0; }
+    set isVisibilitySharedWithParent(v: boolean) { this.flags = v ? (this.flags | IS_VISIBILITY_SHARED) : (this.flags & ~IS_VISIBILITY_SHARED); }
+    get isNew() { return (this.flags & IS_NEW) !== 0; }
+    set isNew(v: boolean) { this.flags = v ? (this.flags | IS_NEW) : (this.flags & ~IS_NEW); }
+    get isUnreliable() { return (this.flags & IS_UNRELIABLE) !== 0; }
+    set isUnreliable(v: boolean) { this.flags = v ? (this.flags | IS_UNRELIABLE) : (this.flags & ~IS_UNRELIABLE); }
+    get isTransient() { return (this.flags & IS_TRANSIENT) !== 0; }
+    set isTransient(v: boolean) { this.flags = v ? (this.flags | IS_TRANSIENT) : (this.flags & ~IS_TRANSIENT); }
+    get isStatic() { return (this.flags & IS_STATIC) !== 0; }
+    set isStatic(v: boolean) { this.flags = v ? (this.flags | IS_STATIC) : (this.flags & ~IS_STATIC); }
+    get isStreamCollection() { return (this.flags & IS_STREAM_COLLECTION) !== 0; }
+    set isStreamCollection(v: boolean) { this.flags = v ? (this.flags | IS_STREAM_COLLECTION) : (this.flags & ~IS_STREAM_COLLECTION); }
+
+    // True iff tree inherits `isFiltered` OR its Schema class declares any
+    // @view-tagged fields. StateView.addParentOf uses this to decide whether
+    // a parent must be included in a view's bootstrap. Reads the class-level
+    // "any viewed field" flag that `EncodeDescriptor` precomputes — same
+    // pattern as `hasAnyStatic` / `hasAnyUnreliable` / `hasAnyStream`.
+    get hasFilteredFields(): boolean {
+        return this.isFiltered || this.encDescriptor.hasAnyView;
+    }
+
+    ensureUnreliableRecorder(): ChangeRecorder {
+        if (this.unreliableRecorder === undefined) {
+            const isSchema = Metadata.isValidInstance(this.ref);
+            this.unreliableRecorder = isSchema
+                ? new SchemaChangeRecorder((this.metadata?.[$numFields] ?? 0) as number)
+                : new CollectionChangeRecorder();
         }
+        return this.unreliableRecorder;
+    }
+
+    isFieldUnreliable(index: number): boolean {
+        // Tree-level `isUnreliable` is disabled — @unreliable is rejected
+        // on ref-type fields at decoration time, so no tree ever carries
+        // the flag. Kept as a comment in case a safe semantics is added
+        // later (see INHERITABLE_FLAGS rationale).
+        // if (this.isUnreliable) return true;
+        // Class-level fast path: most schemas have zero unreliable fields,
+        // so the per-mutation check resolves without the symbol-keyed
+        // metadata lookup. For schemas that DO have unreliable fields, the
+        // bitmask answers fields 0-31 in one bitwise op (no Array.includes
+        // linear scan). Fields ≥32 always fall back to the metadata lookup
+        // (same limitation as filterBitmask — bitmask only covers low 32).
+        const desc = this.encDescriptor;
+        if (!desc.hasAnyUnreliable) return false;
+        if (index < 32) return (desc.unreliableBitmask & (1 << index)) !== 0;
+        return Metadata.hasUnreliableAtIndex(this.metadata, index);
+    }
+
+    // @static fields sync once via full-sync; post-init mutations are ignored
+    // by the tracker (the value still lives on the instance).
+    isFieldStatic(index: number): boolean {
+        if (this.isStatic) return true;
+        const desc = this.encDescriptor;
+        if (!desc.hasAnyStatic) return false;
+        if (index < 32) return (desc.staticBitmask & (1 << index)) !== 0;
+        return Metadata.hasStaticAtIndex(this.metadata, index);
+    }
+
+    // `t.stream(...)` collection fields — encoded via per-view priority/budget
+    // gate instead of emitting all dirty ADDs in one tick. Class-level short
+    // circuit avoids the metadata chase on schemas that carry no stream fields.
+    isFieldStream(index: number): boolean {
+        const desc = this.encDescriptor;
+        if (!desc.hasAnyStream) return false;
+        if (index < 32) return (desc.streamBitmask & (1 << index)) !== 0;
+        return Metadata.hasStreamAtIndex(this.metadata, index);
+    }
 
-        // assign same parent on child structures
-        if (isNewChangeTree) {
-            //
-            // assign same parent on child structures
-            //
-            this.forEachChild((child, index) => {
-                if (child.root === root) {
-                    //
-                    // re-assigning a child of the same root, move it next to parent
-                    // so encoding order is preserved
-                    //
-                    root.add(child);
-                    root.moveNextToParent(child);
-                    return;
-                }
-                child.setParent(this.ref, root, index);
-            });
+    constructor(ref: T) {
+        this.ref = ref;
+        // `$proxyTarget` is a self-reference set by ArraySchema on the raw
+        // target; for non-proxied refs it's undefined and we fall back to
+        // `ref`. Cached here so hot-path reads skip the Proxy `get` trap.
+        this.refTarget = ((ref as any)[$proxyTarget] ?? ref) as T;
+
+        // Single per-class lookup that subsumes Symbol.metadata,
+        // isValidInstance, $encoder, $filter, and the filter bitmask.
+        // After this, the encode loop never touches `ref.constructor`.
+        const desc = getEncodeDescriptor(ref);
+        this.encDescriptor = desc;
+        this.metadata = desc.metadata;
+
+        const isSchema = desc.isSchema;
+        this._isSchema = isSchema;
+
+        // Assign every optional slot so Schema and Collection trees share
+        // one hidden-class transition path (tsconfig useDefineForClassFields=false
+        // otherwise leaves uninitialized class fields absent from the shape).
+        this.ops = undefined;
+        this.collDirty = undefined;
+        this.collPureOps = undefined;
+
+        if (isSchema) {
+            const numFields = (this.metadata?.[$numFields] ?? 0) as number;
+            if (numFields > 7) this.ops = new Uint8Array(numFields + 1);
+        } else {
+            this.collDirty = new Map();
         }
     }
 
-    forEachChild(callback: (change: ChangeTree, at: any) => void) {
-        //
-        // assign same parent on child structures
-        //
-        if ((this.ref as any)[$childType]) {
-            if (typeof ((this.ref as any)[$childType]) !== "string") {
-                // MapSchema / ArraySchema, etc.
-                for (const [key, value] of (this.ref as MapSchema).entries()) {
-                    if (!value) { continue; } // sparse arrays can have undefined values
-                    callback(value[$changes], this.indexes?.[key] ?? key);
-                };
-            }
+    // ────────────────────────────────────────────────────────────────────
+    // Inline ChangeRecorder implementation. Each method branches once on
+    // `_isSchema` (per-tree-stable → predictable branch). Kills one
+    // CollectionChangeRecorder+Map allocation per Collection tree.
+    // ────────────────────────────────────────────────────────────────────
 
-        } else {
-            for (const index of this.metadata?.[$refTypeFieldIndexes] ?? []) {
-                const field = this.metadata[index as any as number];
-                const value = this.ref[field.name as keyof Ref];
-                if (!value) { continue; }
-                callback(value[$changes], index);
+    // Schema-only helpers that own all inline-vs-array dispatch.
+    private _opAt(index: number): number {
+        const ops = this.ops;
+        if (ops !== undefined) return ops[index];
+        const shift = (index & 3) << 3;
+        return (index < 4)
+            ? (this.opsLow >>> shift) & 0xFF
+            : (this.opsHigh >>> shift) & 0xFF;
+    }
+
+    private _opPut(index: number, op: OPERATION): void {
+        const ops = this.ops;
+        if (ops !== undefined) {
+            ops[index] = op;
+            return;
+        }
+        const shift = (index & 3) << 3;
+        const mask = ~(0xFF << shift);
+        if (index < 4) this.opsLow = (this.opsLow & mask) | (op << shift);
+        else this.opsHigh = (this.opsHigh & mask) | (op << shift);
+    }
+
+    private _markDirty(index: number): void {
+        if (index < 32) this.dirtyLow |= (1 << index);
+        else this.dirtyHigh |= (1 << (index - 32));
+    }
+
+    record(index: number, op: OPERATION): void {
+        if (this._isSchema) {
+            const prev = this._opAt(index);
+            if (prev === 0) this._opPut(index, op);
+            else if (prev === OPERATION.DELETE) this._opPut(index, OPERATION.DELETE_AND_ADD);
+            // Promote ADD → DELETE_AND_ADD when a ref is replaced in the
+            // same tick. Otherwise the on-wire op collapses to plain ADD
+            // and the decoder's `refs` map leaks the displaced refId —
+            // harmless on its own, but refId pooling turns that leak into
+            // a catastrophic rebinding when the refId is later reused.
+            else if (prev === OPERATION.ADD && op === OPERATION.DELETE_AND_ADD) {
+                this._opPut(index, OPERATION.DELETE_AND_ADD);
             }
+            // else: existing ADD / DELETE_AND_ADD — preserve op-byte.
+            this._markDirty(index);
+        } else {
+            const dirty = this.collDirty!;
+            const prev = dirty.get(index);
+            let finalOp: OPERATION;
+            if (prev === undefined) finalOp = op;
+            else if (prev === OPERATION.DELETE) finalOp = OPERATION.DELETE_AND_ADD;
+            else if (prev === OPERATION.ADD && op === OPERATION.DELETE_AND_ADD) finalOp = OPERATION.DELETE_AND_ADD;
+            else finalOp = prev;
+            dirty.set(index, finalOp);
         }
     }
 
-    operation(op: OPERATION) {
-        // operations without index use negative values to represent them
-        // this is checked during .encode() time.
-        if (this.filteredChanges !== undefined) {
-            this.filteredChanges.operations.push(-op);
-            this.root?.enqueueChangeTree(this, 'filteredChanges');
+    recordDelete(index: number, op: OPERATION): void {
+        if (this._isSchema) {
+            this._opPut(index, op);
+            this._markDirty(index);
+        } else {
+            this.collDirty!.set(index, op);
+        }
+    }
 
+    recordRaw(index: number, op: OPERATION): void {
+        if (this._isSchema) {
+            this._opPut(index, op);
+            this._markDirty(index);
         } else {
-            this.changes.operations.push(-op);
-            this.root?.enqueueChangeTree(this, 'changes');
+            this.collDirty!.set(index, op);
         }
     }
 
-    change(index: number, operation: OPERATION = OPERATION.ADD) {
-        const isFiltered = this.isFiltered || (this.metadata?.[index]?.tag !== undefined);
-        const changeSet = (isFiltered)
-            ? this.filteredChanges
-            : this.changes;
-
-        const previousOperation = this.indexedOperations[index];
-        if (!previousOperation || previousOperation === OPERATION.DELETE) {
-            const op = (!previousOperation)
-                ? operation
-                : (previousOperation === OPERATION.DELETE)
-                    ? OPERATION.DELETE_AND_ADD
-                    : operation
-            //
-            // TODO: are DELETE operations being encoded as ADD here ??
-            //
-            this.indexedOperations[index] = op;
+    recordPure(op: OPERATION): void {
+        if (this._isSchema) {
+            throw new Error("ChangeTree (Schema): pure operations are not supported");
         }
+        (this.collPureOps ??= []).push([this.collDirty!.size, op]);
+    }
 
-        setOperationAtIndex(changeSet, index);
+    operationAt(index: number): OPERATION | undefined {
+        if (this._isSchema) {
+            const op = this._opAt(index);
+            return op === 0 ? undefined : op;
+        }
+        return this.collDirty!.get(index);
+    }
 
-        if (isFiltered) {
-            setOperationAtIndex(this.allFilteredChanges, index);
+    setOperationAt(index: number, op: OPERATION): void {
+        // Schema: overwrite only (no dirty-mark). Collection: overwrite iff key exists (legacy).
+        if (this._isSchema) {
+            this._opPut(index, op);
+        } else {
+            const dirty = this.collDirty!;
+            if (dirty.has(index)) dirty.set(index, op);
+        }
+    }
 
-            if (this.root) {
-                this.root.enqueueChangeTree(this, 'filteredChanges');
-                this.root.enqueueChangeTree(this, 'allFilteredChanges');
+    // Cold-path delegate: all `forEach` callers are debug/dump utilities
+    // (Schema.ts debug output, utils.ts change dump, discardAll in tests).
+    // The hot encode loop uses `forEachWithCtx` directly. See ChangeRecorder.ts
+    // for the same adapter pattern.
+    forEach(cb: (index: number, op: OPERATION) => void): void {
+        this.forEachWithCtx(cb, _invokeNoCtx);
+    }
+
+    forEachWithCtx<C>(ctx: C, cb: (ctx: C, index: number, op: OPERATION) => void): void {
+        if (this._isSchema) {
+            let low = this.dirtyLow;
+            let high = this.dirtyHigh;
+            const ops = this.ops;
+            if (ops !== undefined) {
+                while (low !== 0) {
+                    const bit = low & -low;
+                    const fieldIndex = 31 - Math.clz32(bit);
+                    low ^= bit;
+                    cb(ctx, fieldIndex, ops[fieldIndex]);
+                }
+                while (high !== 0) {
+                    const bit = high & -high;
+                    const fieldIndex = 31 - Math.clz32(bit) + 32;
+                    high ^= bit;
+                    cb(ctx, fieldIndex, ops[fieldIndex]);
+                }
+            } else {
+                const ol = this.opsLow;
+                const oh = this.opsHigh;
+                while (low !== 0) {
+                    const bit = low & -low;
+                    const fieldIndex = 31 - Math.clz32(bit);
+                    low ^= bit;
+                    cb(ctx, fieldIndex, readInlineOpByte(ol, oh, fieldIndex));
+                }
+            }
+            return;
+        }
+        const dirty = this.collDirty!;
+        const pure = this.collPureOps;
+        if (pure !== undefined && pure.length > 0) {
+            let pureIdx = 0, i = 0;
+            for (const [index, op] of dirty) {
+                while (pureIdx < pure.length && pure[pureIdx][0] <= i) {
+                    const pureOp = pure[pureIdx++][1];
+                    cb(ctx, -pureOp, pureOp);
+                }
+                cb(ctx, index, op);
+                i++;
+            }
+            while (pureIdx < pure.length) {
+                const pureOp = pure[pureIdx++][1];
+                cb(ctx, -pureOp, pureOp);
             }
-
         } else {
-            setOperationAtIndex(this.allChanges, index);
-            this.root?.enqueueChangeTree(this, 'changes');
+            for (const [index, op] of dirty) cb(ctx, index, op);
         }
     }
 
-    shiftChangeIndexes(shiftIndex: number) {
-        //
-        // Used only during:
-        //
-        // - ArraySchema#unshift()
-        //
-        const changeSet = (this.isFiltered)
-            ? this.filteredChanges
-            : this.changes;
-
-        const newIndexedOperations: any = {};
-        const newIndexes: { [index: number]: number } = {};
-        for (const index in this.indexedOperations) {
-            newIndexedOperations[Number(index) + shiftIndex] = this.indexedOperations[index];
-            newIndexes[Number(index) + shiftIndex] = changeSet.indexes[index];
+    size(): number {
+        if (this._isSchema) return popcount32(this.dirtyLow) + popcount32(this.dirtyHigh);
+        return this.collDirty!.size + (this.collPureOps?.length ?? 0);
+    }
+
+    has(): boolean {
+        if (this._isSchema) return (this.dirtyLow | this.dirtyHigh) !== 0;
+        return this.collDirty!.size > 0 || (this.collPureOps !== undefined && this.collPureOps.length > 0);
+    }
+
+    reset(): void {
+        if (this._isSchema) {
+            this.dirtyLow = 0;
+            this.dirtyHigh = 0;
+            if (this.ops !== undefined) this.ops.fill(0);
+            else { this.opsLow = 0; this.opsHigh = 0; }
+            return;
         }
-        this.indexedOperations = newIndexedOperations;
-        changeSet.indexes = newIndexes;
+        this.collDirty!.clear();
+        if (this.collPureOps !== undefined) this.collPureOps.length = 0;
+    }
 
-        changeSet.operations = changeSet.operations.map((index) => index + shiftIndex);
+    shift(shiftIndex: number): void {
+        if (this._isSchema) throw new Error("ChangeTree (Schema): shift is not supported");
+        const src = this.collDirty!;
+        const dst = new Map<number, OPERATION>();
+        for (const [idx, val] of src) dst.set(idx + shiftIndex, val);
+        this.collDirty = dst;
     }
 
-    shiftAllChangeIndexes(shiftIndex: number, startIndex: number = 0) {
-        //
-        // Used only during:
-        //
-        // - ArraySchema#splice()
-        //
-        if (this.filteredChanges !== undefined) {
-            this._shiftAllChangeIndexes(shiftIndex, startIndex, this.allFilteredChanges);
-            this._shiftAllChangeIndexes(shiftIndex, startIndex, this.allChanges);
+    // Tree attachment + child iteration — see ./changeTree/treeAttachment.ts.
+    setRoot(root: Root): void { _setRoot(this, root); }
+    setParent(parent: Ref, root?: Root, parentIndex?: number): void { _setParent(this, parent, root, parentIndex); }
+    forEachChild(cb: (change: ChangeTree, at: any) => void): void { _forEachChild(this, cb); }
+    forEachChildWithCtx<C>(ctx: C, cb: (ctx: C, change: ChangeTree, at: any) => void): void {
+        _forEachChildWithCtx(this, ctx, cb);
+    }
+    forEachLive(cb: (index: number) => void): void { _forEachLive(this, cb); }
+    forEachLiveWithCtx<C>(ctx: C, cb: (ctx: C, index: number) => void): void {
+        _forEachLiveWithCtx(this, ctx, cb);
+    }
 
-        } else {
-            this._shiftAllChangeIndexes(shiftIndex, startIndex, this.allChanges);
-        }
+    operation(op: OPERATION) {
+        if (this.paused || this.isStatic) return;
+        // Pure ops (CLEAR/REVERSE) only emit from collection trees — the
+        // recorder here is always a CollectionChangeRecorder by construction.
+        //
+        // Tree-level `isUnreliable` is disabled (see INHERITABLE_FLAGS):
+        // no collection tree can be marked unreliable as a whole under the
+        // ref-field rejection rule in `Metadata.setUnreliable`. The branch
+        // is kept as a comment for re-enablement.
+        // if (this.isUnreliable) {
+        //     (this.ensureUnreliableRecorder() as ICollectionChangeRecorder).recordPure(op);
+        //     this.root?.enqueueUnreliable(this);
+        // } else {
+            this.recordPure(op);
+            this.root?.enqueueChangeTree(this);
+        // }
     }
 
-    private _shiftAllChangeIndexes(shiftIndex: number, startIndex: number = 0, changeSet: ChangeSet) {
-        const newIndexes: { [index: number]: number } = {};
-        let newKey = 0;
-        for (const key in changeSet.indexes) {
-            newIndexes[newKey++] = changeSet.indexes[key];
+    /**
+     * Route a field-level mutation to the reliable or unreliable channel
+     * and enqueue into the matching queue. Shared by `change` and
+     * `indexedOperation`; `raw=true` bypasses DELETE→ADD merge
+     * (ArraySchema positional writes), `raw=false` merges inside `record`.
+     *
+     * Note: record() on both channels handles DELETE→ADD merge internally,
+     * so callers do not need to pre-compute the merged op.
+     *
+     * `@unreliable` is decoration-time-validated to apply only to primitive
+     * fields (see annotations.ts), so the per-field unreliable flag here
+     * always means "primitive value updates" — the structural-ADD-routes-
+     * reliable footgun for ref-type fields can't reach this code path.
+     */
+    private _routeAndRecord(index: number, op: OPERATION, raw: boolean): void {
+        if (this.paused || this.isFieldStatic(index)) return;
+        if (this.isFieldUnreliable(index)) {
+            const r = this.ensureUnreliableRecorder();
+            if (raw) r.recordRaw(index, op);
+            else r.record(index, op);
+            this.root?.enqueueUnreliable(this);
+            return;
         }
-        changeSet.indexes = newIndexes;
+        if (raw) this.recordRaw(index, op);
+        else this.record(index, op);
+        this.root?.enqueueChangeTree(this);
+    }
 
-        for (let i = 0; i < changeSet.operations.length; i++) {
-            const index = changeSet.operations[i];
-            if (index > startIndex) {
-                changeSet.operations[i] = index + shiftIndex;
-            }
-        }
+    change(index: number, operation: OPERATION = OPERATION.ADD) {
+        this._routeAndRecord(index, operation, false);
     }
 
-    indexedOperation(index: number, operation: OPERATION, allChangesIndex: number = index) {
-        this.indexedOperations[index] = operation;
+    indexedOperation(index: number, operation: OPERATION) {
+        this._routeAndRecord(index, operation, true);
+    }
 
-        if (this.filteredChanges !== undefined) {
-            setOperationAtIndex(this.allFilteredChanges, allChangesIndex);
-            setOperationAtIndex(this.filteredChanges, index);
-            this.root?.enqueueChangeTree(this, 'filteredChanges');
+    // ArraySchema#unshift(): apply shift to both channels.
+    // Unreliable recorder on an array is always a CollectionChangeRecorder.
+    shiftChangeIndexes(shiftIndex: number) {
+        this.shift(shiftIndex);
+        (this.unreliableRecorder as ICollectionChangeRecorder | undefined)?.shift(shiftIndex);
+    }
 
-        } else {
-            setOperationAtIndex(this.allChanges, allChangesIndex);
-            setOperationAtIndex(this.changes, index);
-            this.root?.enqueueChangeTree(this, 'changes');
-        }
+    getChange(index: number) {
+        return this.operationAt(index);
     }
 
-    getType(index?: number) {
-        return (
-            //
-            // Get the child type from parent structure.
-            // - ["string"] => "string"
-            // - { map: "string" } => "string"
-            // - { set: "string" } => "string"
-            //
-            (this.ref as any)[$childType] || // ArraySchema | MapSchema | SetSchema | CollectionSchema
-            this.metadata[index].type // Schema
-        );
+    // ────────────────────────────────────────────────────────────────────
+    // Change-tracking control API
+    // ────────────────────────────────────────────────────────────────────
+
+    pause(): void { this.paused = true; }
+    resume(): void { this.paused = false; }
+
+    untracked<T>(fn: () => T): T {
+        const wasPaused = this.paused;
+        this.paused = true;
+        try { return fn(); }
+        finally { this.paused = wasPaused; }
     }
 
-    getChange(index: number) {
-        return this.indexedOperations[index];
+    // Manually mark a field dirty for the next encode(). Useful after a
+    // paused mutation or a nested mutation that bypassed the setter.
+    markDirty(index: number, operation: OPERATION = OPERATION.ADD): void {
+        const wasPaused = this.paused;
+        this.paused = false;
+        try { this.change(index, operation); }
+        finally { this.paused = wasPaused; }
     }
 
-    //
-    // used during `.encode()`
-    //
+    // used during `.encode()` — `isEncodeAll` is only consumed by ArraySchema.
+    // Reads via `refTarget` so ArraySchema's Proxy trap is bypassed on the
+    // hot per-field encode path.
     getValue(index: number, isEncodeAll: boolean = false) {
-        //
-        // `isEncodeAll` param is only used by ArraySchema
-        //
-        return (this.ref as any)[$getByIndex](index, isEncodeAll);
+        return this.refTarget[$getByIndex](index, isEncodeAll);
     }
 
-    delete(index: number, operation?: OPERATION, allChangesIndex = index) {
+    delete(index: number, operation?: OPERATION) {
         if (index === undefined) {
             try {
                 throw new Error(`@colyseus/schema ${this.ref.constructor.name}: trying to delete non-existing index '${index}'`);
@@ -403,292 +657,193 @@ export class ChangeTree<T extends Ref = any> {
             return;
         }
 
-        const changeSet = (this.filteredChanges !== undefined)
-            ? this.filteredChanges
-            : this.changes;
+        if (this.paused || this.isFieldStatic(index)) return this.getValue(index);
 
-        this.indexedOperations[index] = operation ?? OPERATION.DELETE;
-        setOperationAtIndex(changeSet, index);
-        deleteOperationAtIndex(this.allChanges, allChangesIndex);
+        const unreliable = this.isFieldUnreliable(index);
+        if (unreliable) this.ensureUnreliableRecorder().recordDelete(index, operation ?? OPERATION.DELETE);
+        else this.recordDelete(index, operation ?? OPERATION.DELETE);
 
         const previousValue = this.getValue(index);
 
-        // remove `root` reference
-        if (previousValue && previousValue[$changes]) {
-            //
-            // FIXME: this.root is "undefined"
-            //
-            // This method is being called at decoding time when a DELETE operation is found.
-            //
-            // - This is due to using the concrete Schema class at decoding time.
-            // - "Reflected" structures do not have this problem.
-            //
-            // (The property descriptors should NOT be used at decoding time. only at encoding time.)
-            //
-            this.root?.remove(previousValue[$changes]);
-        }
+        // `this.root` is always undefined on decoder-side instances
+        // (they're built via `initializeForDecoder`, which skips Root
+        // attachment). The optional chain handles both sides; this is
+        // an intentional invariant, not a bug.
+        if (previousValue && previousValue[$changes]) this.root?.remove(previousValue[$changes]);
 
-        //
-        // FIXME: this is looking a ugly and repeated
-        //
-        if (this.filteredChanges !== undefined) {
-            deleteOperationAtIndex(this.allFilteredChanges, allChangesIndex);
-            this.root?.enqueueChangeTree(this, 'filteredChanges');
-
-        } else {
-            this.root?.enqueueChangeTree(this, 'changes');
-        }
+        if (unreliable) this.root?.enqueueUnreliable(this);
+        else this.root?.enqueueChangeTree(this);
 
         return previousValue;
     }
 
-    endEncode(changeSetName: ChangeSetName) {
-        this.indexedOperations = {};
-
-        // clear changeset
-        this[changeSetName] = createChangeSet();
-
-        // ArraySchema and MapSchema have a custom "encode end" method
+    // Clear the reliable dirty bucket after a reliable encode pass.
+    endEncode() {
+        this.reset();
+        this.changesNode = undefined;
         (this.ref as any)[$onEncodeEnd]?.();
-
-        // Not a new instance anymore
         this.isNew = false;
     }
 
-    discard(discardAll: boolean = false) {
-        //
-        // > MapSchema:
-        //      Remove cached key to ensure ADD operations is unsed instead of
-        //      REPLACE in case same key is used on next patches.
-        //
+    // Clear the unreliable dirty bucket after an unreliable encode pass.
+    endEncodeUnreliable() {
+        this.unreliableRecorder?.reset();
+        this.unreliableChangesNode = undefined;
         (this.ref as any)[$onEncodeEnd]?.();
+    }
 
-        this.indexedOperations = {};
-        this.changes = createChangeSet(this.changes.queueRootNode);
-
-        if (this.filteredChanges !== undefined) {
-            this.filteredChanges = createChangeSet(this.filteredChanges.queueRootNode);
-        }
-
-        if (discardAll) {
-            // preserve queueRootNode references
-            this.allChanges = createChangeSet(this.allChanges.queueRootNode);
-
-            if (this.allFilteredChanges !== undefined) {
-                this.allFilteredChanges = createChangeSet(this.allFilteredChanges.queueRootNode);
-            }
-        }
+    discard() {
+        (this.ref as any)[$onEncodeEnd]?.();
+        this.reset();
+        this.unreliableRecorder?.reset();
     }
 
-    /**
-     * Recursively discard all changes from this, and child structures.
-     * (Used in tests only)
-     */
+    // Recursively discard all changes on this + child structures. Tests only.
     discardAll() {
-        const keys = Object.keys(this.indexedOperations);
-        for (let i = 0, len = keys.length; i < len; i++) {
-            const value = this.getValue(Number(keys[i]));
-
-            if (value && value[$changes]) {
-                value[$changes].discardAll();
-            }
-        }
-
+        const discardChild = (index: number) => {
+            if (index < 0) return;
+            const value = this.getValue(index);
+            if (value && value[$changes]) value[$changes].discardAll();
+        };
+        this.forEach(discardChild);
+        this.unreliableRecorder?.forEach(discardChild);
         this.discard();
     }
 
     get changed() {
-        return (Object.entries(this.indexedOperations).length > 0);
+        return this.has() || (this.unreliableRecorder?.has() ?? false);
     }
 
-    protected checkIsFiltered(parent: Ref, parentIndex: number, isNewChangeTree: boolean) {
-        if (this.root.types.hasFilters) {
-            //
-            // At Schema initialization, the "root" structure might not be available
-            // yet, as it only does once the "Encoder" has been set up.
-            //
-            // So the "parent" may be already set without a "root".
-            //
-            this._checkFilteredByParent(parent, parentIndex);
+    // ────────────────────────────────────────────────────────────────────
+    // Parent chain — implementations in ./changeTree/parentChain.ts.
+    // ────────────────────────────────────────────────────────────────────
 
-            if (this.filteredChanges !== undefined) {
-                this.root?.enqueueChangeTree(this, 'filteredChanges');
+    /** Immediate parent (primary). See `extraParents` for the 2nd+ chain. */
+    get parent(): Ref | undefined { return this.parentRef; }
+    get parentIndex(): number | undefined { return this._parentIndex; }
 
-                if (isNewChangeTree) {
-                    this.root?.enqueueChangeTree(this, 'allFilteredChanges');
-                }
-            }
-        }
+    addParent(parent: Ref, index: number): void { _addParent(this, parent, index); }
 
-        if (!this.isFiltered) {
-            this.root?.enqueueChangeTree(this, 'changes');
+    /** @returns true if parent was found and removed */
+    removeParent(parent: Ref = this.parent): boolean { return _removeParent(this, parent); }
 
-            if (isNewChangeTree) {
-                this.root?.enqueueChangeTree(this, 'allChanges');
-            }
-        }
+    findParent(predicate: (parent: Ref, index: number) => boolean): ParentChain | undefined {
+        return _findParent(this, predicate);
     }
 
-    protected _checkFilteredByParent(parent: Ref, parentIndex: number) {
-        // skip if parent is not set
-        if (!parent) { return; }
-
-        //
-        // ArraySchema | MapSchema - get the child type
-        // (if refType is typeof string, the parentFiltered[key] below will always be invalid)
-        //
-        const refType = Metadata.isValidInstance(this.ref)
-            ? this.ref.constructor
-            : (this.ref as any)[$childType];
-
-        let parentChangeTree: ChangeTree;
-
-        let parentIsCollection = !Metadata.isValidInstance(parent);
-        if (parentIsCollection) {
-            parentChangeTree = parent[$changes];
-            parent = parentChangeTree.parent;
-            parentIndex = parentChangeTree.parentIndex;
-
-        } else {
-            parentChangeTree = parent[$changes]
-        }
-
-        const parentConstructor = parent.constructor as typeof Schema;
-
-        let key = `${this.root.types.getTypeId(refType as typeof Schema)}`;
-        if (parentConstructor) {
-            key += `-${this.root.types.schemas.get(parentConstructor)}`;
-        }
-        key += `-${parentIndex}`;
-
-        const fieldHasViewTag = Metadata.hasViewTagAtIndex(parentConstructor?.[Symbol.metadata], parentIndex);
-
-        this.isFiltered = parent[$changes].isFiltered // in case parent is already filtered
-            || this.root.types.parentFiltered[key]
-            || fieldHasViewTag;
-
-        //
-        // "isFiltered" may not be imedialely available during `change()` due to the instance not being attached to the root yet.
-        // when it's available, we need to enqueue the "changes" changeset into the "filteredChanges" changeset.
-        //
-        if (this.isFiltered) {
-
-            this.isVisibilitySharedWithParent = (
-                parentChangeTree.isFiltered &&
-                typeof (refType) !== "string" &&
-                !fieldHasViewTag &&
-                parentIsCollection
-            );
-
-            if (!this.filteredChanges) {
-                this.filteredChanges = createChangeSet();
-                this.allFilteredChanges = createChangeSet();
-            }
-
-            if (this.changes.operations.length > 0) {
-                this.changes.operations.forEach((index) =>
-                    setOperationAtIndex(this.filteredChanges, index));
-
-                this.allChanges.operations.forEach((index) =>
-                    setOperationAtIndex(this.allFilteredChanges, index));
-
-                this.changes = createChangeSet();
-                this.allChanges = createChangeSet();
-            }
-        }
+    hasParent(predicate: (parent: Ref, index: number) => boolean): boolean {
+        return _hasParent(this, predicate);
     }
 
-    /**
-     * Get the immediate parent
-     */
-    get parent(): Ref | undefined {
-        return this.parentChain?.ref;
-    }
+    getAllParents(): Array<{ ref: Ref, index: number }> { return _getAllParents(this); }
 
-    /**
-     * Get the immediate parent index
-     */
-    get parentIndex(): number | undefined {
-        return this.parentChain?.index;
-    }
+}
 
-    /**
-     * Add a parent to the chain
-     */
-    addParent(parent: Ref, index: number) {
-        // Check if this parent already exists in the chain
-        if (this.hasParent((p, _) => p[$changes] === parent[$changes])) {
-        // if (this.hasParent((p, i) => p[$changes] === parent[$changes] && i === index)) {
-            this.parentChain.index = index;
-            return;
-        }
+/**
+ * Lightweight per-instance no-op ChangeTree used for instances the decoder
+ * builds. Those instances never feed back into an Encoder, so the full
+ * `ChangeTree` machinery (EncodeDescriptor lookup, recorder state, Maps /
+ * Uint8Arrays for change slots) is pure overhead — this stub carries only a
+ * `ref` back-pointer and no-op methods, so tree walkers and debug tooling
+ * continue to work.
+ *
+ * Plug-in contract: each collection class and the `Decoder` pick between
+ * `new ChangeTree(ref)` and `createUntrackedChangeTree(ref)` explicitly via
+ * dedicated factories (`initializeForDecoder` on collections,
+ * `createInstanceOfType` on the `Decoder`). There is no global state — every
+ * decision is local to the call site.
+ */
+export class UntrackedChangeTree {
+    ref: Ref;
 
-        this.parentChain = {
-            ref: parent,
-            index,
-            next: this.parentChain
-        };
+    // Mirror the subset of ChangeTree state that decoder-path readers touch.
+    // Everything else is deliberately undefined (matches the shape of a
+    // freshly-constructed tree that never participated in a Root).
+    root: undefined = undefined;
+    parentRef: undefined = undefined;
+    paused: boolean = false;
+    isNew: boolean = false;
+    flags: number = 0;
+
+    constructor(ref: Ref) {
+        this.ref = ref;
     }
 
-    /**
-     * Remove a parent from the chain
-     * @param parent - The parent to remove
-     * @returns true if parent was removed
-     */
-    removeParent(parent: Ref = this.parent): boolean {
-        let current = this.parentChain;
-        let previous = null;
-        while (current) {
-            //
-            // FIXME: it is required to check against `$changes` here because
-            // ArraySchema is instance of Proxy
-            //
-            if (current.ref[$changes] === parent[$changes]) {
-                if (previous) {
-                    previous.next = current.next;
-                } else {
-                    this.parentChain = current.next;
+    // Mutation surface — all no-ops.
+    change(): void {}
+    delete(): void {}
+    indexedOperation(): void {}
+    operation(): void {}
+    setParent(): void {}
+    addParent(): void {}
+    removeParent(): boolean { return false; }
+    getChange(): number { return 0; }
+    discard(): void {}
+    discardAll(): void {}
+    pause(): void {}
+    resume(): void {}
+    untracked<T>(fn: () => T): T { return fn(); }
+    markDirty(): void {}
+
+    // Tree-walk surface. Mirrors `treeAttachment.forEachChild` so debug tools
+    // and `ArraySchema.clear()` can still descend from a tracked root into
+    // decoder-built subtrees and read each child's `$changes` (which is
+    // itself an UntrackedChangeTree carrying the right `ref`).
+    forEachChild(callback: (change: any, at: any) => void): void {
+        const ref = this.ref as any;
+        if (ref[$childType]) {
+            if (typeof ref[$childType] !== "string") {
+                for (const [key, value] of ref.entries()) {
+                    if (!value) continue;
+                    callback(value[$changes], ref._collectionIndexes?.[key] ?? key);
                 }
-                return true;
             }
-            previous = current;
-            current = current.next;
+            return;
         }
-        return this.parentChain === undefined;
-    }
-
-    /**
-     * Find a specific parent in the chain
-     */
-    findParent(predicate: (parent: Ref, index: number) => boolean): ParentChain | undefined {
-        let current = this.parentChain;
-        while (current) {
-            if (predicate(current.ref, current.index)) {
-                return current;
-            }
-            current = current.next;
+        const ctor = ref.constructor as any;
+        const metadata = ctor?.[Symbol.metadata];
+        if (!metadata) return;
+        const refFieldIndexes: number[] = metadata[$refTypeFieldIndexes] ?? [];
+        for (let i = 0; i < refFieldIndexes.length; i++) {
+            const index = refFieldIndexes[i];
+            const value = ref[metadata[index].name];
+            if (!value) continue;
+            callback(value[$changes], index);
         }
-        return undefined;
     }
 
-    /**
-     * Check if this ChangeTree has a specific parent
-     */
-    hasParent(predicate: (parent: Ref, index: number) => boolean): boolean {
-        return this.findParent(predicate) !== undefined;
+    forEachChildWithCtx<C>(ctx: C, callback: (ctx: C, change: any, at: any) => void): void {
+        this.forEachChild((change, at) => callback(ctx, change, at));
     }
 
-    /**
-     * Get all parents as an array (for debugging/testing)
-     */
-    getAllParents(): Array<{ ref: Ref, index: number }> {
-        const parents: Array<{ ref: Ref, index: number }> = [];
-        let current = this.parentChain;
-        while (current) {
-            parents.push({ ref: current.ref, index: current.index });
-            current = current.next;
-        }
-        return parents;
-    }
+    forEachLive(): void {}
+    forEachLiveWithCtx(): void {}
+    forEach(): void {}
+}
+
+// Factory, cast to ChangeTree so call sites that type `$changes` as
+// `ChangeTree` accept it. The surface overlap above covers every read/write
+// the decoder path reaches.
+export function createUntrackedChangeTree(ref: Ref): ChangeTree {
+    return new UntrackedChangeTree(ref) as unknown as ChangeTree;
+}
 
+/**
+ * Install a non-enumerable `$changes: UntrackedChangeTree` on `target`.
+ * Shared by `Schema.initializeForDecoder` and every collection's
+ * `initializeForDecoder`. `publicRef` defaults to `target` — pass a Proxy
+ * instead (ArraySchema) so children attached to this tree see the Proxy
+ * as their parent, not the raw target.
+ *
+ * `enumerable: false` is load-bearing — tests use `deepStrictEqual` on
+ * decoded instances and walking into `$changes` would recurse through
+ * circular refs. Same descriptor shape as the tracked `Schema.initialize`
+ * + collection ctors.
+ */
+export function installUntrackedChangeTree(target: object, publicRef: object = target): void {
+    Object.defineProperty(target, $changes, {
+        value: createUntrackedChangeTree(publicRef as Ref),
+        enumerable: false,
+        writable: true,
+    });
 }