@colyseus/schema 5.0.6 → 5.0.9

package/src/encoder/Encoder.ts

@@ -89,6 +89,12 @@ function ensureStructSwitch(ctx: EncodeCtx): void {
  * Module-level adapter for `forEachLiveWithCtx`. Full-sync emits every live
  * field as ADD, so we re-enter `encodeChangeCb` with that fixed op — keeps
  * the callback closure-free across the entire DFS walk.
+ *
+ * The resync sweep (decoder/Resync.ts) depends on this shape: full-sync
+ * output is dense plain ADDs — no DELETEs, no gap-writes (so decoding it
+ * never compacts arrays mid-walk), and replaced occupants arrive as plain
+ * ADD (the sweep's touch hook releases them). Changing full-sync emission
+ * means revisiting the sweep.
  */
 function encodeFullSyncCb(ctx: EncodeCtx, fieldIndex: number): void {
     encodeChangeCb(ctx, fieldIndex, OPERATION.ADD);
@@ -200,7 +206,18 @@ function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
 }
 
 export class Encoder<T extends Schema = any> {
-    static BUFFER_SIZE = 8 * 1024; // 8KB
+    /**
+     * Per-encoder shared output buffer size. The encoder auto-grows on
+     * overflow and logs a one-time warning suggesting a higher value, so
+     * the default just needs to comfortably cover typical room state.
+     *
+     * Sized to fit ~100 items in a `MapSchema<{x,y,z}>` keyed by
+     * `nanoid(9)` (~4.5 KB worst-case full encode, float64-heavy) with
+     * ~3-4× headroom for surrounding state (player list, world refs,
+     * etc.). Raise per app via `Encoder.BUFFER_SIZE = N * 1024` before
+     * constructing any Encoder.
+     */
+    static BUFFER_SIZE = 16 * 1024;
     sharedBuffer: Uint8Array = new Uint8Array(Encoder.BUFFER_SIZE);
 
     context: TypeContext;
@@ -337,7 +354,12 @@ export class Encoder<T extends Schema = any> {
 
         if (it.offset > buffer.byteLength) {
             buffer = this._resizeBuffer(buffer, it.offset);
-            return this._encodeChannel({ offset: initialOffset }, view, buffer, initialOffset, unreliable);
+            // Reuse `it` (reset its offset) instead of a fresh iterator so the
+            // caller's `it.offset` ends at the true final offset. A fresh one
+            // strands `it.offset` at the overflow value and corrupts the next
+            // view's region in a multi-view encode.
+            it.offset = initialOffset;
+            return this._encodeChannel(it, view, buffer, initialOffset, unreliable);
         }
 
         return buffer.subarray(0, it.offset);
@@ -380,7 +402,8 @@ export class Encoder<T extends Schema = any> {
 
         if (it.offset > buffer.byteLength) {
             buffer = this._resizeBuffer(buffer, it.offset);
-            return this.encodeFullSync({ offset: initialOffset }, buffer, emitFiltered, view);
+            it.offset = initialOffset; // reuse `it` so the caller's offset stays accurate
+            return this.encodeFullSync(it, buffer, emitFiltered, view, initialOffset);
         }
 
         return buffer.subarray(0, it.offset);
@@ -420,7 +443,9 @@ export class Encoder<T extends Schema = any> {
     ) {
         const viewOffset = it.offset;
 
-        this.encodeFullSync(it, bytes, /* emitFiltered */ true, view, viewOffset);
+        // encodeFullSync() may reallocate the buffer on overflow — keep its
+        // return, not the stale `bytes`, or the concat below reads a dead buffer.
+        bytes = this.encodeFullSync(it, bytes, /* emitFiltered */ true, view, viewOffset);
 
         return concatBytes(
             bytes.subarray(0, sharedOffset),
@@ -428,6 +453,16 @@ export class Encoder<T extends Schema = any> {
         );
     }
 
+    /** Grow `buffer` to keep BUFFER_SIZE free bytes past `offset`, preserving `[0, offset)`. */
+    protected ensureCapacity(buffer: Uint8Array, offset: number): Uint8Array {
+        if (offset + Encoder.BUFFER_SIZE <= buffer.byteLength) { return buffer; }
+        const size = Math.ceil((offset + Encoder.BUFFER_SIZE) / Encoder.BUFFER_SIZE) * Encoder.BUFFER_SIZE;
+        const grown = new Uint8Array(size);
+        grown.set(buffer.subarray(0, offset));
+        if (buffer === this.sharedBuffer) { this.sharedBuffer = grown; }
+        return grown;
+    }
+
     encodeView(
         view: StateView,
         sharedOffset: number,
@@ -476,6 +511,10 @@ export class Encoder<T extends Schema = any> {
             const ref = changeTree.ref;
             const refTarget = changeTree.refTarget;
 
+            // These writes are unguarded and unrecoverable (view.changes is cleared
+            // below), so unlike encode() they can't re-encode on overflow — grow ahead.
+            bytes = this.ensureCapacity(bytes, it.offset);
+
             bytes[it.offset++] = SWITCH_TO_STRUCTURE & 255;
             encode.number(bytes, ref[$refId], it);
 
@@ -498,9 +537,14 @@ export class Encoder<T extends Schema = any> {
         //
         view.changes.clear();
 
-        // per-tick view-scoped pass: walks the same `changes` queue as the
+        // Per-tick view-scoped pass: walks the same `changes` queue as the
         // shared pass, but `encodeChangeCb` emits only filtered fields.
-        this.encode(it, view, bytes, viewOffset);
+        // encode() may reallocate the buffer on overflow — keep its return,
+        // not the stale `bytes`. Anchor the re-encode at the current offset
+        // (the default `initialOffset = it.offset`), NOT `viewOffset`: a
+        // resize must not clobber the view.changes already written at
+        // [viewOffset, it.offset).
+        bytes = this.encode(it, view, bytes);
 
         return concatBytes(
             bytes.subarray(0, sharedOffset),
@@ -523,7 +567,9 @@ export class Encoder<T extends Schema = any> {
     ) {
         const viewOffset = it.offset;
 
-        this.encodeUnreliable(it, view, bytes, viewOffset);
+        // Capture the return: a resize on overflow reallocates the buffer, and
+        // the concat below must read from the live one, not the stale `bytes`.
+        bytes = this.encodeUnreliable(it, view, bytes, viewOffset);
 
         return concatBytes(
             bytes.subarray(0, sharedOffset),
@@ -763,11 +809,6 @@ export class Encoder<T extends Schema = any> {
         }
         list.next = undefined;
         list.tail = undefined;
-
-        // End-of-tick: refIds released during this tick have now had their
-        // DELETEs emitted through `encode()` / `encodeView()`, so they are
-        // safe to recycle on the next tick.
-        root.refIds.flushReleases();
     }
 
     discardUnreliableChanges() {

package/src/encoder/Pool.ts

@@ -0,0 +1,90 @@
+import { Schema } from "../Schema.js";
+
+/**
+ * Server-side object pool for Schema instances.
+ *
+ * Constructing a Schema is comparatively expensive (per-instance ChangeTree +
+ * `Object.defineProperty($changes)` + values array, multiplied by the number
+ * of instances in the entity tree). For workloads that spawn/despawn entities
+ * (ECS, matchmaking bots, projectiles), reusing instances avoids that cost.
+ *
+ * The pool relies on {@link Schema.reset} to return a detached instance to a
+ * pristine, construction-default state — including dropping its `$refId` so a
+ * re-add re-acquires a fresh id (making reuse wire-format-identical to `new`).
+ *
+ * Lifecycle:
+ * ```ts
+ * const pool = createPool(Entity, { preallocate: 1000 });
+ *
+ * // spawn
+ * const e = pool.acquire();
+ * e.x = 10; e.y = 20;            // re-assign fields (pool does NOT reset primitives)
+ * state.entities.set(id, e);
+ *
+ * // despawn — remove from the state tree FIRST, then release
+ * state.entities.delete(id);
+ * pool.release(e);
+ * ```
+ *
+ * Not supported (throws on release): instances shared across multiple parents,
+ * `@stream` collections, and decoder-side (mirror) instances.
+ */
+export interface PoolOptions {
+    /** Construct this many instances up front, so the first spawns reuse rather than allocate. */
+    preallocate?: number;
+    /**
+     * Cap on retained free instances. Releases beyond the cap are dropped (and
+     * garbage-collected), keeping a long-running pool bounded. Default: no cap.
+     */
+    maxSize?: number;
+}
+
+/**
+ * Object pool for Schema instances. Exported as a **type only** — construct one
+ * via {@link createPool}, which is the public entry point. The class is public
+ * for typing (`SchemaPool<Entity>` annotations) and `instanceof` checks.
+ */
+export class SchemaPool<T extends Schema> {
+    private readonly _free: T[] = [];
+    private readonly _factory: () => T;
+    private readonly _maxSize: number;
+
+    constructor(factory: () => T, opts: PoolOptions = {}) {
+        this._factory = factory;
+        this._maxSize = opts.maxSize ?? Infinity;
+        const preallocate = opts.preallocate ?? 0;
+        for (let i = 0; i < preallocate; i++) {
+            this._free.push(factory());
+        }
+    }
+
+    /** Pop a pre-reset free instance, or construct a fresh one. */
+    acquire(): T {
+        return this._free.length > 0 ? this._free.pop()! : this._factory();
+    }
+
+    /**
+     * Reset `instance` to construction defaults and return it to the pool.
+     * PRECONDITION: the instance must already be detached from the state tree
+     * (removed from its parent collection/field, so the encoder released it).
+     */
+    release(instance: T): void {
+        Schema.reset(instance);
+        if (this._free.length < this._maxSize) {
+            this._free.push(instance);
+        }
+    }
+
+    /** Number of instances currently available for reuse. */
+    get size(): number {
+        return this._free.length;
+    }
+}
+
+/** Convenience factory: `createPool(Entity, { preallocate: 64 })`. */
+export function createPool<T extends Schema>(
+    ctor: new () => T,
+    opts: PoolOptions = {},
+): SchemaPool<T> {
+    return new SchemaPool<T>(() => new ctor(), opts);
+}

package/src/encoder/Root.ts

@@ -2,7 +2,6 @@ import { OPERATION } from "../encoding/spec.js";
 import { TypeContext } from "../types/TypeContext.js";
 import { ChangeTree, ChangeTreeList, createChangeTreeList, type ChangeTreeNode } from "./ChangeTree.js";
 import { $changes, $refId } from "../types/symbols.js";
-import { RefIdAllocator } from "./RefIdAllocator.js";
 import type { StateView } from "./StateView.js";
 import type { StreamSchema } from "../types/custom/StreamSchema.js";
 import type { StreamableState } from "./streaming.js";
@@ -23,12 +22,18 @@ export interface Streamable {
     _unregister(): void;
 }
 
+// Reused across Root.add calls — defineProperty is unavoidable ($refId must
+// stay non-enumerable for deepStrictEqual) but the descriptor literal isn't.
+const $refIdDescriptor = { value: 0, enumerable: false, writable: true };
+
 export class Root {
     /**
-     * Allocates and recycles refIds. See `RefIdAllocator` for the reuse
-     * pool semantics (one-tick defer + resurrection).
+     * Monotonic refId counter. RefIds are never recycled — a refId is a
+     * stable identity for the lifetime of the room, so a client that
+     * missed DELETEs (reconnect) can never see an old id rebound to a
+     * different instance. DevMode reads/writes this across HMR cycles.
      */
-    public readonly refIds: RefIdAllocator;
+    protected nextUniqueId: number = 0;
 
     refCount: {[id: number]: number} = {};
     changeTrees: {[refId: number]: ChangeTree} = {};
@@ -134,7 +139,7 @@ export class Root {
     }
 
     constructor(public types: TypeContext, startRefId: number = 0) {
-        this.refIds = new RefIdAllocator(startRefId);
+        this.nextUniqueId = startRefId;
     }
 
     add(changeTree: ChangeTree) {
@@ -145,11 +150,8 @@ export class Root {
         // *enumerable* own Symbols, so we keep defineProperty(enumerable:false)
         // to keep $refId hidden from deep-equal comparisons in tests.
         if (ref[$refId] === undefined) {
-            Object.defineProperty(ref, $refId, {
-                value: this.refIds.acquire(),
-                enumerable: false,
-                writable: true
-            });
+            $refIdDescriptor.value = this.nextUniqueId++;
+            Object.defineProperty(ref, $refId, $refIdDescriptor);
         }
 
         const refId = ref[$refId];
@@ -157,21 +159,19 @@ export class Root {
         const isNewChangeTree = (this.changeTrees[refId] === undefined);
         if (isNewChangeTree) { this.changeTrees[refId] = changeTree; }
 
-        // Resurrection path: a ref whose refId is still queued for reuse
-        // is being re-added. Pull the refId out of the pool before it gets
-        // handed out to someone else.
-        if (this.refIds.isPooled(refId)) {
-            this.refIds.reclaim(refId);
-        }
-
         const previousRefCount = this.refCount[refId];
-        if (previousRefCount === 0) {
+        if (previousRefCount === 0 || changeTree.needsRestage) {
             //
-            // When a ChangeTree is re-added, it means that it was previously
-            // removed. Re-stage every currently-populated non-transient index
-            // as a fresh ADD in the matching dirty bucket so the next encode
-            // re-emits it on the correct channel.
+            // Re-stage every currently-populated non-transient index as a
+            // fresh ADD in the matching dirty bucket so the next encode
+            // re-emits it on the correct channel. Two triggers:
+            // - refCount 0: a previously-removed tree re-added under the
+            //   same refId (its ops were consumed by an earlier encode).
+            // - NEEDS_RESTAGE: a `Schema.reset` instance re-entering under
+            //   a fresh refId (reset cleared the buckets; its retained
+            //   values would otherwise never be encoded).
             //
+            changeTree.needsRestage = false;
             changeTree.forEachLive((fieldIndex) => {
                 if (changeTree.isFieldUnreliable(fieldIndex)) {
                     changeTree.ensureUnreliableRecorder().record(fieldIndex, OPERATION.ADD);
@@ -211,16 +211,6 @@ export class Root {
 
             this.refCount[refId] = 0;
 
-            // Return refId to the reuse pool (deferred to end-of-tick via
-            // the allocator's pending set). Stream collections are excluded
-            // because their per-view delivery bookkeeping is harder to
-            // audit for reuse safety and the savings there are negligible.
-            // If the ref is later resurrected, `add()` evicts the refId
-            // from the pool before it's handed to another instance.
-            if (!changeTree.isStreamCollection) {
-                this.refIds.release(refId);
-            }
-
             changeTree.forEachChild((child, _) => {
                 if (child.removeParent(changeTree.ref)) {
                     if ((

package/src/encoder/StateView.ts

@@ -224,39 +224,61 @@ export class StateView {
     // `Schema.ts` filter check — `hasTagOnTree` is O(1) bitwise.
     // ──────────────────────────────────────────────────────────────────
 
-    /** True iff this view has `tag` associated with `tree`. */
+    /**
+     * True iff this view shares at least one tag bit with `tree`.
+     *
+     * `tagViews` is keyed by individual power-of-two bits (custom tags must
+     * be powers of two; `@view(A|B)` field masks are decomposed on store).
+     * A field whose mask is `tag` is visible if the view was `add()`ed with
+     * any overlapping bit — so we walk `tag`'s set bits and return on the
+     * first match. Passing DEFAULT_VIEW_TAG (-1, all bits) answers "does
+     * this view hold ANY custom tag on the tree".
+     */
     public hasTagOnTree(tree: ChangeTree, tag: number): boolean {
         const map = tree.tagViews;
         if (map === undefined) return false;
-        const arr = map.get(tag);
         const slot = this._slot;
-        return arr !== undefined && slot < arr.length && (arr[slot] & this._bit) !== 0;
+        const bit = this._bit;
+        for (let bits = tag; bits !== 0; bits &= bits - 1) {
+            const arr = map.get(bits & -bits); // isolate lowest set bit
+            if (arr !== undefined && slot < arr.length && (arr[slot] & bit) !== 0) return true;
+        }
+        return false;
     }
 
-    /** Mark `tree` as carrying `tag` for this view. */
+    /** Mark `tree` as carrying `tag` (each of its bits) for this view. */
     public addTag(tree: ChangeTree, tag: number): void {
+        // DEFAULT_VIEW_TAG visibility lives in `visibleViews`, not here.
+        if (tag === DEFAULT_VIEW_TAG) return;
         let map = tree.tagViews;
         if (map === undefined) {
             map = tree.tagViews = new Map();
         }
-        let arr = map.get(tag);
-        if (arr === undefined) {
-            arr = [];
-            map.set(tag, arr);
-        }
         const slot = this._slot;
-        while (arr.length <= slot) arr.push(0);
-        arr[slot] |= this._bit;
+        const bit = this._bit;
+        for (let bits = tag; bits > 0; bits &= bits - 1) {
+            const b = bits & -bits; // isolate lowest set bit
+            let arr = map.get(b);
+            if (arr === undefined) {
+                arr = [];
+                map.set(b, arr);
+            }
+            while (arr.length <= slot) arr.push(0);
+            arr[slot] |= bit;
+        }
     }
 
-    /** Clear this view's `tag` bit on `tree`. */
+    /** Clear each of `tag`'s bits for this view on `tree`. */
     public removeTag(tree: ChangeTree, tag: number): void {
+        if (tag === DEFAULT_VIEW_TAG) return;
         const map = tree.tagViews;
         if (map === undefined) return;
-        const arr = map.get(tag);
-        if (arr === undefined) return;
         const slot = this._slot;
-        if (slot < arr.length) arr[slot] &= ~this._bit;
+        const clearMask = ~this._bit;
+        for (let bits = tag; bits > 0; bits &= bits - 1) {
+            const arr = map.get(bits & -bits);
+            if (arr !== undefined && slot < arr.length) arr[slot] &= clearMask;
+        }
     }
 
     /** Clear ALL tag bits this view holds on `tree` (used when the per-tag isn't known). */
@@ -409,10 +431,16 @@ export class StateView {
         // direct array index instead of a per-field-object hop.
         const tags = changeTree.encDescriptor.tags;
         changeTree.forEachChild((change, index) => {
-            // Do not ADD children that don't have the same tag
+            // Do not ADD children whose field tag shares no bit with `tag`.
+            // DEFAULT_VIEW_TAG fields are visible to all clients; custom-tag
+            // fields only when bits overlap, and never to default-tag clients.
             const fieldTag = tags[index];
-            if (fieldTag !== undefined && fieldTag !== tag) {
-                return;
+            if (fieldTag !== undefined) {
+                const tagMatch = fieldTag === DEFAULT_VIEW_TAG ||
+                    (tag !== DEFAULT_VIEW_TAG && (fieldTag & tag) !== 0);
+                if (!tagMatch) {
+                    return;
+                }
             }
 
             if (this.add(change.ref, tag, false)) {
@@ -424,12 +452,19 @@ export class StateView {
         if (tag !== DEFAULT_VIEW_TAG) {
             this.addTag(changeTree, tag);
 
-            // Ref: add tagged properties
-            metadata?.[$fieldIndexesByViewTag]?.[tag]?.forEach((index) => {
-                if (changeTree.getChange(index) !== OPERATION.DELETE) {
-                    changes.set(index, OPERATION.ADD);
+            // Ref: add tagged properties. `$fieldIndexesByViewTag` is keyed
+            // per-bit, so a combined add-tag (`view.add(obj, A|B)`) must look
+            // up each set bit to force-ADD every field that shares a bit.
+            const byTag = metadata?.[$fieldIndexesByViewTag];
+            if (byTag !== undefined) {
+                for (let bits = tag; bits > 0; bits &= bits - 1) {
+                    byTag[bits & -bits]?.forEach((index) => {
+                        if (changeTree.getChange(index) !== OPERATION.DELETE) {
+                            changes.set(index, OPERATION.ADD);
+                        }
+                    });
                 }
-            });
+            }
 
         } else if (!changeTree.isNew || isChildAdded) {
             // new structures will be added as part of .encode() call, no need to force it to .encodeView()
@@ -447,7 +482,8 @@ export class StateView {
                 if (
                     isInvisible || // if "invisible", include all
                     tagAtIndex === undefined || // "all change" with no tag
-                    tagAtIndex === tag // tagged property
+                    tagAtIndex === DEFAULT_VIEW_TAG || // visible to all clients
+                    (tag !== DEFAULT_VIEW_TAG && (tagAtIndex & tag) !== 0) // tag bits overlap
                 ) {
                     changes.set(index, OPERATION.ADD);
                     isChildAdded = true;
@@ -479,7 +515,11 @@ export class StateView {
         const tags = tree.encDescriptor.tags;
         tree.forEachChild((child, index) => {
             const fieldTag = tags[index];
-            if (fieldTag !== undefined && fieldTag !== tag) return;
+            if (fieldTag !== undefined) {
+                const tagMatch = fieldTag === DEFAULT_VIEW_TAG ||
+                    (tag !== DEFAULT_VIEW_TAG && (fieldTag & tag) !== 0);
+                if (!tagMatch) return;
+            }
 
             if (child.isNew) {
                 this.markVisible(child);
@@ -497,21 +537,26 @@ export class StateView {
         if (!this.isVisible(changeTree)) {
             // view must have all "changeTree" parent tree
             this.markVisible(changeTree);
+        }
 
-            // Recurse all the way to the root regardless of whether the
-            // parent is filtered. Walking the full chain is what makes
-            // `view.changes` topologically ordered by construction — any
-            // filtered ancestor up the chain is touched here, before the
-            // descendant's entry. The actual entry-write below is gated
-            // on `hasFilteredFields` so non-filtered ancestors don't
-            // emit redundant wire bytes (the decoder already knows them
-            // via the shared encode pass). Marking them visible is
-            // still useful: it makes this short-circuit fire on the next
-            // `view.add` instead of re-walking the chain.
-            const parentChangeTree: ChangeTree = changeTree.parent?.[$changes];
-            if (parentChangeTree) {
-                this.addParentOf(changeTree, tag);
-            }
+        // Recurse all the way to the root REGARDLESS of whether this parent
+        // is already visible. Walking the full chain keeps `view.changes`
+        // topologically ordered by construction (ancestors touched before
+        // the descendant's entry), and — crucially — re-queues the ancestor
+        // binding ops every time: visibility bits are per-VIEW, but the ADD
+        // ops they once queued are consumed per-ENCODE. With a shared view,
+        // an earlier encode (for other clients) or a dropped backlog leaves
+        // an already-visible ancestor whose binding a late-attached client
+        // never received — its filtered-container refId would then arrive
+        // unbound ("refId not found"). Re-writing the entry ops is cheap
+        // (Map.set dedupes within a patch) and decodes as a no-op for
+        // clients that already hold the refs. The entry-write below is
+        // still gated on `hasFilteredFields` so non-filtered ancestors
+        // don't emit redundant wire bytes (the decoder already knows them
+        // via the shared encode pass).
+        const parentChangeTree: ChangeTree = changeTree.parent?.[$changes];
+        if (parentChangeTree) {
+            this.addParentOf(changeTree, tag);
         }
 
         // Skip the entry-write for non-filtered ancestors: their refIds
@@ -702,21 +747,27 @@ export class StateView {
             }
 
         } else {
-            // delete only tagged properties
+            // delete only tagged properties. `$fieldIndexesByViewTag` is
+            // keyed per-bit, so a combined tag iterates each set bit.
             const names = changeTree.encDescriptor.names;
-            metadata?.[$fieldIndexesByViewTag][tag].forEach((index) => {
-                changes.set(index, OPERATION.DELETE);
-
-                // Remove child structures from visible set
-                const value = changeTree.ref[names[index] as keyof Ref];
-                if (value?.[$changes]) {
-                    this.unmarkVisible(value[$changes]);
-                    this._recursiveDeleteVisibleChangeTree(value[$changes]);
+            const byTag = metadata?.[$fieldIndexesByViewTag];
+            if (byTag !== undefined) {
+                for (let bits = tag; bits > 0; bits &= bits - 1) {
+                    byTag[bits & -bits]?.forEach((index) => {
+                        changes.set(index, OPERATION.DELETE);
+
+                        // Remove child structures from visible set
+                        const value = changeTree.ref[names[index] as keyof Ref];
+                        if (value?.[$changes]) {
+                            this.unmarkVisible(value[$changes]);
+                            this._recursiveDeleteVisibleChangeTree(value[$changes]);
+                        }
+                    });
                 }
-            });
+            }
         }
 
-        // remove tag bit for this view
+        // remove tag bits for this view
         if (tag === undefined) {
             this.removeAllTagsOnTree(changeTree);
         } else {

package/src/encoder/changeTree/liveIteration.ts

@@ -30,6 +30,8 @@ export function forEachLiveWithCtx<C>(
 
     if (ref[$childType] !== undefined) {
         // Collection inheriting @transient from parent field: skip entirely.
+        // The resync sweep (decoder/Resync.ts) relies on this: a collection
+        // absent from full-sync output is never pruned client-side.
         if (tree.isTransient) return;
 
         // Collection types: dispatch by shape.
@@ -54,6 +56,8 @@ export function forEachLiveWithCtx<C>(
         // Schema: walk declared fields. `null` is treated as absent —
         // the setter records a DELETE when a field is set to null or
         // undefined, so it should not appear in full-sync output.
+        // (@transient skips below matter to the resync sweep — see
+        // decoder/Resync.ts: absent-from-payload means never pruned.)
         //
         // Read names from the per-class descriptor's parallel array —
         // saves the `metadata[i]` (per-field obj) + `.name` chain on

package/src/encoder/changeTree/treeAttachment.ts

@@ -4,7 +4,6 @@
  * goes through here, which is why the recursive walk uses a hoisted
  * callback + ctx-pool instead of per-call closures.
  */
-import type { MapSchema } from "../../types/custom/MapSchema.js";
 import { $changes, $childType, $refTypeFieldIndexes } from "../../types/symbols.js";
 import { Root } from "../Root.js";
 import type { ChangeTree, Ref } from "../ChangeTree.js";
@@ -81,26 +80,11 @@ export function forEachChild(
     tree: ChangeTree,
     callback: (change: ChangeTree, at: any) => void,
 ): void {
-    //
-    // assign same parent on child structures
-    //
-    if ((tree.ref as any)[$childType]) {
-        if (typeof ((tree.ref as any)[$childType]) !== "string") {
-            // MapSchema / ArraySchema, etc.
-            for (const [key, value] of (tree.ref as MapSchema).entries()) {
-                if (!value) { continue; } // sparse arrays can have undefined values
-                callback(value[$changes], (tree.ref as any)._collectionIndexes?.[key] ?? key);
-            };
-        }
+    forEachChildWithCtx(tree, callback, _forEachChildTrampoline);
+}
 
-    } else {
-        const names = tree.encDescriptor.names;
-        for (const index of tree.metadata?.[$refTypeFieldIndexes] ?? []) {
-            const value = tree.ref[names[index] as keyof Ref];
-            if (!value) { continue; }
-            callback(value[$changes], index);
-        }
-    }
+function _forEachChildTrampoline(cb: (change: ChangeTree, at: any) => void, change: ChangeTree, at: any): void {
+    cb(change, at);
 }
 
 /**
@@ -124,10 +108,30 @@ export function forEachChildWithCtx<C>(
     const ref = tree.refTarget as any;
     if (ref[$childType]) {
         if (typeof ref[$childType] !== "string") {
-            const collectionIndexes = ref._collectionIndexes;
-            for (const [key, value] of (ref as MapSchema).entries()) {
-                if (!value) { continue; }
-                callback(ctx, value[$changes], collectionIndexes?.[key] ?? key);
+            const items = ref.items;
+            if (items !== undefined) {
+                // ArraySchema (raw target): dense index loop — the previous
+                // `for..of entries()` allocated an iterator + a [key, value]
+                // pair array per child (top-10 allocation site in the
+                // stateview and deep-nested heap profiles).
+                for (let i = 0, len = items.length; i < len; i++) {
+                    const value = items[i];
+                    if (!value) { continue; } // sparse arrays can have undefined values
+                    callback(ctx, value[$changes], i);
+                }
+            } else {
+                // Map-backed collections (MapSchema/SetSchema/CollectionSchema/
+                // StreamSchema all store `$items: Map`): keys() loop skips the
+                // per-child [key, value] pair arrays of entries(), with no
+                // closure either (a forEach closure showed up as a GC
+                // regression on the construct bench).
+                const $items = ref.$items as Map<any, any>;
+                const collectionIndexes = ref._collectionIndexes;
+                for (const key of $items.keys()) {
+                    const value = $items.get(key);
+                    if (!value) { continue; }
+                    callback(ctx, value[$changes], collectionIndexes?.[key] ?? key);
+                }
             }
         }
     } else {