@colyseus/schema 5.0.11 → 5.0.13

package/src/encoder/ChangeTree.ts

@@ -8,7 +8,7 @@
  *
  *   - parentChain.ts     addParent / removeParent / find / has / getAll
  *   - liveIteration.ts   forEachLive
- *   - inheritedFlags.ts  filter / unreliable / transient / static inheritance
+ *   - inheritedFlags.ts  filter / unreliable / patchOnly / static inheritance
  *   - treeAttachment.ts  setRoot / setParent / forEachChild(+WithCtx)
  *
  * Public surface on ChangeTree is unchanged — methods are thin pass-throughs
@@ -34,6 +34,7 @@ import type { DecodeOperation } from "../decoder/DecodeOperation.js";
 
 import {
     addParent as _addParent, removeParent as _removeParent,
+    setParentIndex as _setParentIndex,
     findParent as _findParent, hasParent as _hasParent,
     getAllParents as _getAllParents,
 } from "./changeTree/parentChain.js";
@@ -97,18 +98,19 @@ export interface ChangeTreeNode {
     changeTree: ChangeTree;
     next?: ChangeTreeNode;
     prev?: ChangeTreeNode;
-    position: number; // Cached position in the linked list for O(1) lookup
+    position: number; // strictly increasing along the list — O(1) order test
 }
 
 // Linked list for change trees
 export interface ChangeTreeList {
     next?: ChangeTreeNode;
     tail?: ChangeTreeNode;
+    nextPosition: number; // monotonic per drain cycle (resets when list empties)
 }
 
 // Linked list helper functions
 export function createChangeTreeList(): ChangeTreeList {
-    return { next: undefined, tail: undefined };
+    return { next: undefined, tail: undefined, nextPosition: 0 };
 }
 
 export interface ParentChain {
@@ -117,10 +119,10 @@ export interface ParentChain {
     next?: ParentChain;
 }
 
-// Flags bitfield. *_UNRELIABLE / _TRANSIENT / _STATIC mirror the parent
+// Flags bitfield. *_UNRELIABLE / _PATCH_ONLY / _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;
+export const IS_UNRELIABLE = 8, IS_PATCH_ONLY = 16, IS_FULL_STATE_ONLY = 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
@@ -147,7 +149,7 @@ export const NEEDS_RESTAGE = 128;
  * 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 const INHERITABLE_FLAGS = IS_PATCH_ONLY | IS_FULL_STATE_ONLY;
 
 export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     ref: T;
@@ -170,8 +172,8 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     metadata: Metadata;
 
     /**
-     * Per-class cache of encoder fn / filter fn / isSchema / filterBitmask /
-     * metadata, looked up once at construction. The encode loop reads
+     * Per-class cache of encoder fn / filter fn / isSchema / metadata /
+     * per-field arrays, looked up once at construction. The encode loop reads
      * `tree.encDescriptor` and never touches `ref.constructor` again. See
      * EncodeDescriptor.ts.
      */
@@ -257,10 +259,10 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     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 isPatchOnly() { return (this.flags & IS_PATCH_ONLY) !== 0; }
+    set isPatchOnly(v: boolean) { this.flags = v ? (this.flags | IS_PATCH_ONLY) : (this.flags & ~IS_PATCH_ONLY); }
+    get isFullStateOnly() { return (this.flags & IS_FULL_STATE_ONLY) !== 0; }
+    set isFullStateOnly(v: boolean) { this.flags = v ? (this.flags | IS_FULL_STATE_ONLY) : (this.flags & ~IS_FULL_STATE_ONLY); }
     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); }
     get needsRestage() { return (this.flags & NEEDS_RESTAGE) !== 0; }
@@ -270,7 +272,7 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     // @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`.
+    // pattern as `hasAnyFullStateOnly` / `hasAnyUnreliable` / `hasAnyStream`.
     get hasFilteredFields(): boolean {
         return this.isFiltered || this.encDescriptor.hasAnyView;
     }
@@ -296,7 +298,7 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         // 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).
+        // (shift counts wrap at 32, so the bitmask only covers the low 32).
         const desc = this.encDescriptor;
         if (!desc.hasAnyUnreliable) return false;
         if (index < 32) return (desc.unreliableBitmask & (1 << index)) !== 0;
@@ -305,12 +307,12 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
 
     // @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;
+    isFieldFullStateOnly(index: number): boolean {
+        if (this.isFullStateOnly) 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);
+        if (!desc.hasAnyFullStateOnly) return false;
+        if (index < 32) return (desc.fullStateOnlyBitmask & (1 << index)) !== 0;
+        return Metadata.hasFullStateOnlyAtIndex(this.metadata, index);
     }
 
     // `t.stream(...)` collection fields — encoded via per-view priority/budget
@@ -565,7 +567,7 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         this.unreliableRecorder?.reset();
 
         // back to a freshly-constructed tree: IS_NEW, no inherited flags
-        // (FILTERED/TRANSIENT/STATIC/STREAM are re-derived on the next setParent).
+        // (FILTERED/PATCH_ONLY/STATIC/STREAM are re-derived on the next setParent).
         // NEEDS_RESTAGE makes the next Root.add re-stage retained field values.
         this.flags = IS_NEW | NEEDS_RESTAGE;
         this._fullSyncGen = 0;
@@ -602,7 +604,7 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         if (this._isSchema) throw new Error("ChangeTree (Schema): unshift is not supported");
         const src = this.collDirty!;
         const dst = new Map<number, OPERATION>();
-        const track = !this.paused && !this.isStatic;
+        const track = !this.paused && !this.isFullStateOnly;
         if (track) {
             for (let i = 0; i < count; i++) dst.set(i, OPERATION.ADD);
         }
@@ -625,7 +627,7 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     }
 
     operation(op: OPERATION) {
-        if (this.paused || this.isStatic) return;
+        if (this.paused || this.isFullStateOnly) return;
         // Pure ops (CLEAR/REVERSE) only emit from collection trees — the
         // recorder here is always a CollectionChangeRecorder by construction.
         //
@@ -655,10 +657,22 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
      * 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.
+     *
+     * `!isNew` holds an `@unreliable` field on the RELIABLE channel until this
+     * tree's own ADD has shipped there. A decoder can only apply a field write
+     * to a ref it already knows, so a value emitted before the ADD is dropped —
+     * permanently, if the field is never written again. `isNew` clears in
+     * `endEncode()`, i.e. after a reliable pass, and recording reliably is
+     * itself what enqueues the tree for that pass; the state is self-clearing
+     * and no tree can be stranded on the wrong channel. Mirrors `encodeAll`,
+     * which has always seeded these fields for late joiners.
+     *
+     * Ordering matters: `isFieldUnreliable` short-circuits on the class-level
+     * `hasAnyUnreliable`, so schemas without the modifier never read `flags`.
      */
     private _routeAndRecord(index: number, op: OPERATION, raw: boolean): void {
-        if (this.paused || this.isFieldStatic(index)) return;
-        if (this.isFieldUnreliable(index)) {
+        if (this.paused || this.isFieldFullStateOnly(index)) return;
+        if (this.isFieldUnreliable(index) && !this.isNew) {
             const r = this.ensureUnreliableRecorder();
             if (raw) r.recordRaw(index, op);
             else r.record(index, op);
@@ -722,9 +736,11 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
             return;
         }
 
-        if (this.paused || this.isFieldStatic(index)) return this.getValue(index);
+        if (this.paused || this.isFieldFullStateOnly(index)) return this.getValue(index);
 
-        const unreliable = this.isFieldUnreliable(index);
+        // Same pre-ADD hold as `_routeAndRecord` — a DELETE naming a ref the
+        // decoder hasn't seen is dropped just like a field write.
+        const unreliable = this.isFieldUnreliable(index) && !this.isNew;
         if (unreliable) this.ensureUnreliableRecorder().recordDelete(index, operation ?? OPERATION.DELETE);
         else this.recordDelete(index, operation ?? OPERATION.DELETE);
 
@@ -789,6 +805,9 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
 
     addParent(parent: Ref, index: number): void { _addParent(this, parent, index); }
 
+    /** Re-point an existing parent's cached index after the parent reindexed. */
+    setParentIndex(parent: Ref, index: number): void { _setParentIndex(this, parent, index); }
+
     /** @returns true if parent was found and removed */
     removeParent(parent: Ref = this.parent): boolean { return _removeParent(this, parent); }
 
@@ -841,6 +860,7 @@ export class UntrackedChangeTree {
     operation(): void {}
     setParent(): void {}
     addParent(): void {}
+    setParentIndex(): void {}
     removeParent(): boolean { return false; }
     getChange(): number { return 0; }
     discard(): void {}

package/src/encoder/EncodeDescriptor.ts

@@ -10,14 +10,13 @@
  *   ctor[$filter]
  *   ctor[Symbol.metadata]
  *   Metadata.isValidInstance(ref)
- *   getFilterBitmask(metadata)
  *
  * Lives in its own file to break the Encoder.ts ↔ ChangeTree.ts import
  * cycle (ChangeTree caches descriptors at construction; Encoder reads them
  * during encode).
  */
 import { Metadata } from "../Metadata.js";
-import { $encodeDescriptor, $encoder, $encoders, $filter, $filterBitmask, $numFields, $staticFieldIndexes, $streamFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "../types/symbols.js";
+import { $encodeDescriptor, $encoder, $encoders, $filter, $numFields, $fullStateOnlyFieldIndexes, $streamFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "../types/symbols.js";
 import type { StateView } from "./StateView.js";
 import type { EncodeOperation } from "./EncodeOperation.js";
 
@@ -28,35 +27,34 @@ export interface EncodeDescriptor {
     isSchema: boolean;
     /**
      * Bit i set iff field i has a @view tag. 0 for collection trees.
-     * Lets `encodeChangeCb` do a single bitwise op instead of a
-     * per-field metadata[i]?.tag chase.
+     * Lets `encodeChangeCb` do a single bitwise op instead of a per-field
+     * metadata[i]?.tag chase. Fields 0–31 only, like the bitmasks below —
+     * `encodeChangeCb` reads `tags` past that.
      */
     filterBitmask: number;
 
     /**
      * Class-level "any field has the flag" booleans + per-field bitmasks.
-     * Hot path: per-mutation `_routeAndRecord` calls `isFieldStatic` and
+     * Hot path: per-mutation `_routeAndRecord` calls `isFieldFullStateOnly` and
      * `isFieldUnreliable`. The common case is "no static/unreliable fields
      * anywhere on this class" (booleans short-circuit before the symbol-keyed
      * metadata lookup); the secondary common case is "this class has some
      * such fields and we need to know if THIS field is one" — the bitmask
      * answers in one bitwise op instead of an `Array.includes` linear scan.
      *
-     * Bitmasks cover fields 0–31 only (matches the `filterBitmask` limitation).
-     * Fields ≥32 fall back to `Metadata.hasXAtIndex` — same handling as the
-     * filter-bitmask path.
+     * Bitmasks cover fields 0–31 only — shift counts wrap at 32. Fields ≥32
+     * fall back to `Metadata.hasXAtIndex`.
      */
-    hasAnyStatic: boolean;
+    hasAnyFullStateOnly: boolean;
     hasAnyUnreliable: boolean;
     hasAnyStream: boolean;
     /**
-     * Class-level "any field carries a `@view` tag" — covers fields both
-     * within and beyond index 31 (unlike `filterBitmask`, which only
-     * captures the low 32). Read by `ChangeTree.hasFilteredFields` to
-     * decide whether a parent tree must be included in a view's bootstrap.
+     * Class-level "any field carries a `@view` tag". Read by
+     * `ChangeTree.hasFilteredFields` to decide whether a parent tree must
+     * be included in a view's bootstrap.
      */
     hasAnyView: boolean;
-    staticBitmask: number;
+    fullStateOnlyBitmask: number;
     unreliableBitmask: number;
     /**
      * Bit i set iff field i holds a `t.stream(...)` collection. Hot encode
@@ -84,29 +82,10 @@ export interface EncodeDescriptor {
     encoders: (((bytes: Uint8Array, value: any, it: any) => void) | undefined)[];
 }
 
-function computeFilterBitmask(metadata: any): number {
-    if (metadata === undefined) return 0;
-    let bm: number | undefined = metadata[$filterBitmask];
-    if (bm !== undefined) return bm;
-    bm = 0;
-    const tagged = metadata[$viewFieldIndexes];
-    if (tagged !== undefined) {
-        for (let i = 0, len = tagged.length; i < len; i++) bm |= (1 << tagged[i]);
-    }
-    // Non-enumerable so `for (const k in metadata)` iteration in TypeContext
-    // and elsewhere doesn't mistake this cache for a real field index.
-    Object.defineProperty(metadata, $filterBitmask, {
-        value: bm,
-        enumerable: false,
-        writable: true,
-        configurable: true,
-    });
-    return bm;
-}
-
 /**
  * Bitmask of field indexes 0–31 in `indexes`. For fields ≥32 callers must
- * fall back to the array lookup (same as `filterBitmask`).
+ * fall back to the array lookup — shift counts wrap at 32, so an unguarded
+ * `1 << 40` would set bit 8 and misclassify field 8.
  */
 function indexesToBitmask(indexes: number[] | undefined): number {
     if (indexes === undefined) return 0;
@@ -190,12 +169,12 @@ export function getEncodeDescriptor(ref: any): EncodeDescriptor {
         filter,
         metadata,
         isSchema,
-        filterBitmask: isSchema ? computeFilterBitmask(metadata) : 0,
-        hasAnyStatic: (metadata?.[$staticFieldIndexes]?.length ?? 0) > 0,
+        filterBitmask: isSchema ? indexesToBitmask(metadata?.[$viewFieldIndexes]) : 0,
+        hasAnyFullStateOnly: (metadata?.[$fullStateOnlyFieldIndexes]?.length ?? 0) > 0,
         hasAnyUnreliable: (metadata?.[$unreliableFieldIndexes]?.length ?? 0) > 0,
         hasAnyStream: (metadata?.[$streamFieldIndexes]?.length ?? 0) > 0,
         hasAnyView,
-        staticBitmask: indexesToBitmask(metadata?.[$staticFieldIndexes]),
+        fullStateOnlyBitmask: indexesToBitmask(metadata?.[$fullStateOnlyFieldIndexes]),
         unreliableBitmask: indexesToBitmask(metadata?.[$unreliableFieldIndexes]),
         streamBitmask: indexesToBitmask(metadata?.[$streamFieldIndexes]),
         names: arrays.names,

package/src/encoder/EncodeOperation.ts

@@ -75,7 +75,9 @@ export const encodeSchemaOperation: EncodeOperation = function <T extends Schema
     _: any,
     __: any,
 ) {
-    // "compress" field index + operation
+    // "compress" field index + operation. Can't collide with
+    // SWITCH_TO_STRUCTURE (255): that needs `DELETE_AND_ADD | 63`, and
+    // `Metadata.MAX_FIELDS` keeps index 63 unassignable.
     bytes[it.offset++] = (index | operation) & 255;
 
     // Do not encode value for DELETE operations

package/src/encoder/Encoder.ts

@@ -43,12 +43,21 @@ interface EncodeCtx {
     emitFiltered: boolean;
 
     /**
-     * Bitmask: bit i set iff field i has a @view tag. Lets the per-field
-     * filter check be a single bitwise op instead of a metadata[i]?.tag chase.
-     * Always 0 for collection trees.
+     * Bitmask: bit i set iff field i has a @view tag, for i < 32. Lets the
+     * per-field filter check be a single bitwise op instead of a
+     * metadata[i]?.tag chase. Always 0 for collection trees.
      */
     filterBitmask: number;
 
+    /**
+     * Per-field @view tags of the current tree (`undefined` where untagged),
+     * covering the fields the bitmask can't reach. Empty for collections.
+     * Read through the ctx rather than `changeTree.encDescriptor`: a
+     * multi-hop chain here costs ~2% on full-sync even though only Schemas
+     * with 32+ fields ever evaluate it.
+     */
+    tags: (number | undefined)[];
+
     /**
      * Current walk's visit stamp. `_fullSyncWalk` compares it against each
      * tree's `_fullSyncGen` on entry: match means "already visited by
@@ -131,6 +140,7 @@ function _fullSyncWalk(ctx: EncodeCtx, changeTree: ChangeTree): void {
         ctx.treeIsFiltered = changeTree.isFiltered;
         ctx.isSchema = desc.isSchema;
         ctx.filterBitmask = desc.filterBitmask;
+        ctx.tags = desc.tags;
         ctx.structSwitchEmitted = false;
         ctx.shouldEmitSwitch = (ctx.hasView || ctx.it.offset > ctx.initialOffset || changeTree !== ctx.rootChangeTree);
 
@@ -174,10 +184,13 @@ function encodeChangeCb(ctx: EncodeCtx, fieldIndex: number, op: OPERATION): void
 
     // Per-field filter decision (same rule as ChangeTree.change()):
     // a field is filtered iff the tree inherits isFiltered OR the field
-    // itself carries a @view tag. Schema trees check via the precomputed
-    // bitmask; collection trees inherit tree-level (bitmask is 0).
+    // itself carries a @view tag. The bitmask only spans 0–31 — `1 << 40`
+    // wraps onto bit 8 — so fields past it read their tag directly. Reaching
+    // that arm needs a Schema with more than 32 fields.
     const fieldFiltered = ctx.isSchema
-        ? (ctx.treeIsFiltered || (ctx.filterBitmask & (1 << fieldIndex)) !== 0)
+        ? (ctx.treeIsFiltered || (fieldIndex < 32
+            ? (ctx.filterBitmask & (1 << fieldIndex)) !== 0
+            : ctx.tags[fieldIndex] !== undefined))
         : ctx.treeIsFiltered;
     if (fieldFiltered !== ctx.emitFiltered) return;
 
@@ -239,7 +252,7 @@ export class Encoder<T extends Schema = any> {
         ref: undefined, encoder: undefined!, filter: undefined, metadata: undefined,
         view: undefined, isEncodeAll: false, hasView: false,
         treeIsFiltered: false, isSchema: false, emitFiltered: false,
-        filterBitmask: 0,
+        filterBitmask: 0, tags: undefined!,
         structSwitchEmitted: false, isRootTree: false, shouldEmitSwitch: false,
         gen: 0, initialOffset: 0, rootChangeTree: undefined!,
     };
@@ -320,6 +333,7 @@ export class Encoder<T extends Schema = any> {
             ctx.treeIsFiltered = changeTree.isFiltered;
             ctx.isSchema = desc.isSchema;
             ctx.filterBitmask = desc.filterBitmask;
+            ctx.tags = desc.tags;
             ctx.structSwitchEmitted = false;
             ctx.isRootTree = (changeTree === rootChangeTree);
             // Root's struct switch is skipped at the very start of the shared
@@ -639,7 +653,7 @@ export class Encoder<T extends Schema = any> {
                 // Emit each element's full state — forEachLive walks populated
                 // fields structurally, mirroring encodeAllView's bootstrap.
                 // Covers both static elements (dirty state was reset by
-                // inheritedFlags' becameStatic branch) and non-static (still
+                // inheritedFlags' becameFullStateOnly branch) and non-static (still
                 // has dirty state but the main loop skipped them because
                 // they're filtered).
                 for (const element of emittedElements) {
@@ -718,24 +732,86 @@ export class Encoder<T extends Schema = any> {
             // `t.stream(X).priority(fn)` or the decorator form) and seeded
             // into `_stream.priority` when the stream was attached. Users
             // can also override per-instance by assigning to the setter.
+            // A per-view callback (registered by `subscribe(coll, fn)`)
+            // wins over the declaration-scope one: it closes over the
+            // client's own entity, so it needs no view-carried anchor.
+            const perView = st.priorityByView?.get(viewId);
+            const usePerView = perView !== undefined;
             const priority = st.priority;
+            const max = st.maxPerTick;
 
-            // Materialize pending into an array so we can sort + slice.
-            // Small sets (typical: tens to low hundreds) — allocation is
-            // negligible compared to the priority sort and element walk.
+            // Select the `max` highest-priority candidates.
+            //
+            // A comparator-based sort invokes the callback twice per
+            // comparison, each with its own `$getByIndex` lookup — ~2·n·log n
+            // of each to pick `max` entries (38k calls to select 8 out of a
+            // 2000-entry backlog). Scoring every candidate once and keeping a
+            // bounded top-`max` window costs n invocations instead, and sizes
+            // the scratch by `max` rather than by the backlog.
+            //
+            // Ties keep the earlier position (both comparisons below are
+            // strict), so equal-priority entries still drain in insertion
+            // order.
             const positions: number[] = [];
-            for (const p of pending) positions.push(p);
-
-            if (priority !== undefined) {
-                // Use the symbol-keyed accessor so Map/Set/Stream all route
-                // through the same lookup regardless of $items layout.
-                positions.sort(
-                    (a: number, b: number) => priority(view, s[$getByIndex](b)) - priority(view, s[$getByIndex](a)),
-                );
+            const stale: number[] = [];
+
+            if (usePerView || priority !== undefined) {
+                const bestPos: number[] = [];
+                const bestScore: number[] = [];
+                let filled = 0;
+
+                for (const pos of pending) {
+                    // Symbol-keyed accessor so Map/Set/Stream all route
+                    // through the same lookup regardless of $items layout.
+                    const element = s[$getByIndex](pos);
+                    if (element === undefined) {
+                        // Removed after being queued — drop it below without
+                        // spending budget on it.
+                        stale.push(pos);
+                        continue;
+                    }
+
+                    const score = usePerView
+                        ? perView!(element)
+                        : priority!(view, element);
+
+                    // Window not yet full: always insert.
+                    if (filled < max) {
+                        let j = filled++;
+                        while (j > 0 && bestScore[j - 1] < score) {
+                            bestScore[j] = bestScore[j - 1];
+                            bestPos[j] = bestPos[j - 1];
+                            j--;
+                        }
+                        bestScore[j] = score;
+                        bestPos[j] = pos;
+
+                    // Otherwise only a strictly better score displaces the tail.
+                    } else if (score > bestScore[max - 1]) {
+                        let j = max - 1;
+                        while (j > 0 && bestScore[j - 1] < score) {
+                            bestScore[j] = bestScore[j - 1];
+                            bestPos[j] = bestPos[j - 1];
+                            j--;
+                        }
+                        bestScore[j] = score;
+                        bestPos[j] = pos;
+                    }
+                }
+
+                for (let i = 0; i < filled; i++) positions.push(bestPos[i]);
+
+            } else {
+                // FIFO — take the head of the backlog, no scoring needed.
+                for (const pos of pending) {
+                    if (positions.length >= max) break;
+                    positions.push(pos);
+                }
             }
 
-            const max = st.maxPerTick;
-            const count = Math.min(positions.length, max);
+            for (const pos of stale) pending.delete(pos);
+
+            const count = positions.length;
 
             let sent: Set<number> | undefined = st.sentByView.get(viewId);
             if (sent === undefined) {

package/src/encoder/Root.ts

@@ -162,7 +162,7 @@ export class Root {
         const previousRefCount = this.refCount[refId];
         if (previousRefCount === 0 || changeTree.needsRestage) {
             //
-            // Re-stage every currently-populated non-transient index as a
+            // Re-stage every currently-populated non-patchOnly 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
@@ -270,13 +270,9 @@ export class Root {
         const parentNode = parent[$changes][nodeField];
         if (!parentNode || parentNode === node) return;
 
-        // Check if child is already after parent by walking from parent
-        let cursor = parentNode.next;
-        while (cursor) {
-            if (cursor === node) return; // already after parent
-            cursor = cursor.next;
-        }
-        // If we reach here, node is before parent — need to move
+        // Positions are strictly increasing along the list, so this is an
+        // exact O(1) "is child already after parent" test — no queue scan.
+        if (node.position > parentNode.position) return;
 
         // Remove node from current position
         if (node.prev) {
@@ -291,17 +287,18 @@ export class Root {
             changeSet.tail = node.prev;
         }
 
-        // Insert node right after parent
-        node.prev = parentNode;
-        node.next = parentNode.next;
-
-        if (parentNode.next) {
-            parentNode.next.prev = node;
-        } else {
-            changeSet.tail = node;
-        }
-
-        parentNode.next = node;
+        // Re-append at the tail: after `parentNode` AND after every other
+        // queued parent of a multi-referenced instance — relinking next to
+        // the *primary* parent could jump the child ahead of a 2nd/3rd
+        // parent whose ADD the decoder must see first. Tail placement gets
+        // a fresh max position, keeping the invariant append-only.
+        // (`recursivelyMoveNextToParent` visits pre-order, so a moved
+        // subtree re-serializes parent-first behind it.)
+        node.prev = changeSet.tail;
+        node.next = undefined;
+        changeSet.tail!.next = node; // parentNode remains in the list — never empty here
+        changeSet.tail = node;
+        node.position = changeSet.nextPosition++;
     }
 
     public enqueueChangeTree(
@@ -328,11 +325,11 @@ export class Root {
             node.changeTree = changeTree;
             node.next = undefined;
             node.prev = undefined;
-            node.position = 0;
         } else {
             node = { changeTree, next: undefined, prev: undefined, position: 0 };
         }
         if (!list.next) {
+            list.nextPosition = 0; // list drained — restart sequence (stays SMI)
             list.next = node;
             list.tail = node;
         } else {
@@ -340,6 +337,7 @@ export class Root {
             list.tail!.next = node;
             list.tail = node;
         }
+        node.position = list.nextPosition++;
         return node;
     }