@colyseus/schema 5.0.14 → 5.0.19

package/src/codegen/resolve.ts

@@ -0,0 +1,322 @@
+import * as ts from "typescript";
+import * as fs from "fs";
+import * as path from "path";
+
+import { PACKAGE_ROOT } from "./types.js";
+
+export interface ResolveOptions {
+    /** Explicit `--tsconfig`. When set, nearest-config discovery is skipped. */
+    tsconfig?: string;
+}
+
+interface ResolvedConfig {
+    configFilePath: string;
+    options: ts.CompilerOptions;
+    cache?: ts.ModuleResolutionCache;
+}
+
+interface MatchedPattern {
+    substitutions: string[];
+    /** What `*` captured, so substitutions can splice it back in. */
+    matchedStar: string;
+}
+
+const CONFIG_NAMES = ["tsconfig.json", "jsconfig.json"];
+
+/** `No inputs were found in config file` — expected, since readDirectory is stubbed. */
+const NO_INPUTS_FOUND = 18003;
+
+let configByDir: Map<string, ResolvedConfig | null>;
+let override: ResolvedConfig | null | undefined;
+let resolveOptions: ResolveOptions;
+let warned: Set<string>;
+
+reset();
+
+function reset() {
+    configByDir = new Map();
+    override = undefined;
+    resolveOptions = {};
+    warned = new Set();
+}
+
+/**
+ * Drop every cached tsconfig lookup. Called once per top-level `parseFiles()`
+ * run so a long-lived process can generate for two different projects.
+ */
+export function resetResolver(options: ResolveOptions = {}) {
+    reset();
+    resolveOptions = options;
+
+    if (options.tsconfig && !fs.existsSync(options.tsconfig)) {
+        throw new Error(`--tsconfig: file not found: ${options.tsconfig}`);
+    }
+}
+
+function warnOnce(key: string, message: string) {
+    if (warned.has(key)) { return; }
+    warned.add(key);
+    console.warn(message);
+}
+
+/**
+ * `readDirectory` is stubbed on purpose: only `compilerOptions` is wanted here,
+ * and letting TypeScript glob the config's `include` set would stat the user's
+ * whole project on every config discovered.
+ */
+const parseConfigHost: ts.ParseConfigHost = {
+    useCaseSensitiveFileNames: ts.sys?.useCaseSensitiveFileNames ?? true,
+    readDirectory: () => [],
+    fileExists: (fileName) => fs.existsSync(fileName),
+    readFile: (fileName) => {
+        try {
+            return fs.readFileSync(fileName, "utf8");
+        } catch (e) {
+            if (!(e as any)?.code) { throw e; }
+            return undefined;
+        }
+    },
+};
+
+function loadConfig(configFilePath: string): ResolvedConfig | null {
+    const { config, error } = ts.readConfigFile(configFilePath, parseConfigHost.readFile);
+    if (error) {
+        warnOnce(configFilePath,
+            `schema-codegen: could not read "${configFilePath}" ` +
+            `(${ts.flattenDiagnosticMessageText(error.messageText, " ")}) — ` +
+            `its import path aliases will be ignored.`);
+        return null;
+    }
+
+    // parseJsonConfigFileContent (not convertCompilerOptionsFromJson) is what
+    // applies `extends` chains, `${configDir}` templates, and `pathsBasePath` —
+    // the directory of the config that DECLARED `paths`, which in a monorepo is
+    // not the directory of the config being loaded.
+    const parsed = ts.parseJsonConfigFileContent(
+        config,
+        parseConfigHost,
+        path.dirname(configFilePath),
+        undefined,
+        configFilePath,
+    );
+
+    const errors = parsed.errors.filter((d) =>
+        d.code !== NO_INPUTS_FOUND && d.category === ts.DiagnosticCategory.Error);
+
+    if (errors.length > 0) {
+        warnOnce(configFilePath,
+            `schema-codegen: "${configFilePath}" has errors — ` +
+            errors.map((d) => ts.flattenDiagnosticMessageText(d.messageText, " ")).join("; "));
+    }
+
+    const options = parsed.options;
+    if (!options.paths && !options.baseUrl) { return null; }
+
+    const getCanonicalFileName = parseConfigHost.useCaseSensitiveFileNames
+        ? (f: string) => f
+        : (f: string) => f.toLowerCase();
+
+    return {
+        configFilePath,
+        options,
+        cache: ts.createModuleResolutionCache(
+            path.dirname(configFilePath), getCanonicalFileName, options),
+    };
+}
+
+function getOverrideConfig(): ResolvedConfig | null {
+    if (override === undefined) {
+        override = loadConfig(path.resolve(resolveOptions.tsconfig));
+        if (override === null) {
+            warnOnce(`no-aliases:${resolveOptions.tsconfig}`,
+                `schema-codegen: "${resolveOptions.tsconfig}" declares no "paths" or ` +
+                `"baseUrl" — there are no import aliases to resolve.`);
+        }
+    }
+    return override;
+}
+
+/**
+ * Nearest `tsconfig.json`/`jsconfig.json` above `containingFile`. Both names are
+ * checked at every level: a distant tsconfig.json must not win over an adjacent
+ * jsconfig.json. Stops at the first config found even when it declares no
+ * aliases — matching `tsc`, a parent project's `paths` do not leak into a child
+ * that does not `extends` it.
+ */
+function getConfigFor(containingFile: string): ResolvedConfig | null {
+    if (resolveOptions.tsconfig) { return getOverrideConfig(); }
+
+    const dir = path.dirname(containingFile);
+    if (configByDir.has(dir)) { return configByDir.get(dir); }
+
+    let config: ResolvedConfig | null = null;
+    const visited: string[] = [];
+
+    for (let current = dir, parent: string; ; current = parent) {
+        visited.push(current);
+
+        const found = CONFIG_NAMES
+            .map((name) => path.join(current, name))
+            .find((candidate) => fs.existsSync(candidate));
+
+        if (found) {
+            config = loadConfig(found);
+            break;
+        }
+
+        parent = path.dirname(current);
+        if (parent === current) { break; }
+    }
+
+    // memoize the whole walk, negatives included
+    visited.forEach((visitedDir) => configByDir.set(visitedDir, config));
+
+    return config;
+}
+
+/** Exact patterns win outright; among wildcards the longest prefix wins. */
+function findBestPathPattern(specifier: string, paths: ts.MapLike<string[]>): MatchedPattern | undefined {
+    let best: MatchedPattern | undefined;
+    let bestPrefixLength = -1;
+
+    for (const pattern in paths) {
+        const star = pattern.indexOf("*");
+
+        if (star === -1) {
+            if (pattern === specifier) {
+                return { substitutions: paths[pattern], matchedStar: "" };
+            }
+            continue;
+        }
+
+        const prefix = pattern.slice(0, star);
+        const suffix = pattern.slice(star + 1);
+
+        if (
+            specifier.length >= prefix.length + suffix.length &&
+            specifier.startsWith(prefix) &&
+            specifier.endsWith(suffix) &&
+            prefix.length > bestPrefixLength
+        ) {
+            bestPrefixLength = prefix.length;
+            best = {
+                substitutions: paths[pattern],
+                matchedStar: specifier.slice(prefix.length, specifier.length - suffix.length),
+            };
+        }
+    }
+
+    return best;
+}
+
+function resolveViaPathsSubstitution(matched: MatchedPattern, options: ts.CompilerOptions): string | undefined {
+    // mirrors ts.getPathsBasePath(): `paths` may be declared without a baseUrl,
+    // in which case it anchors on the config that declared it
+    const base = options.baseUrl ?? (options as any).pathsBasePath ?? process.cwd();
+
+    for (const substitution of matched.substitutions) {
+        const resolved = resolveSourceFile(
+            path.resolve(base, substitution.replace("*", matched.matchedStar)));
+        if (resolved) { return resolved; }
+    }
+
+    return undefined;
+}
+
+const isDeclaration = (fileName: string) => /\.d\.[cm]?ts$/.test(fileName);
+const isInNodeModules = (fileName: string) => fileName.replace(/\\/g, "/").includes("/node_modules/");
+
+/**
+ * Resolve a non-relative import (`@schemas/Player`, `shared/Player`) to a
+ * first-party source file through the tsconfig governing `containingFile`.
+ * Returns undefined for npm packages, declaration files, and specifiers no
+ * alias covers.
+ */
+export function resolveNonRelativeImport(specifier: string, containingFile: string): string | undefined {
+    const config = getConfigFor(containingFile);
+    if (!config) { return undefined; }
+
+    const { options } = config;
+    const matched = options.paths && findBestPathPattern(specifier, options.paths);
+
+    // no alias hit and no baseUrl: TypeScript could only find this under
+    // node_modules, which costs ~130 failed lookups to prove
+    if (!matched && !options.baseUrl) { return undefined; }
+
+    const resolved = ts.resolveModuleName(
+        specifier, containingFile, options, ts.sys, config.cache).resolvedModule;
+
+    if (resolved) {
+        // a deliberate package/typings hit — not ours to parse, and the
+        // substitution fallback must not second-guess it
+        return (
+            resolved.isExternalLibraryImport ||
+            isDeclaration(resolved.resolvedFileName) ||
+            isInNodeModules(resolved.resolvedFileName)
+        ) ? undefined
+          : path.resolve(resolved.resolvedFileName);
+    }
+
+    // `.mjs` targets are unresolvable by ts.resolveModuleName in every
+    // moduleResolution mode, but schema-codegen parses them
+    const viaSubstitution = matched && resolveViaPathsSubstitution(matched, options);
+    if (viaSubstitution) { return viaSubstitution; }
+
+    if (matched) {
+        warnOnce(`unresolved:${specifier}`,
+            `schema-codegen: '${specifier}' matches a "paths" alias in ` +
+            `${config.configFilePath}, but no source file was found for it — ` +
+            `schemas it exports will be missing from the generated output.`);
+    }
+
+    return undefined;
+}
+
+/** The extension alternatives parseFiles() probes, in order. Pure — no fs. */
+export function sourceFileCandidates(fileName: string): string[] {
+    if (
+        !fileName.endsWith(".ts") &&
+        !fileName.endsWith(".js") &&
+        !fileName.endsWith(".mjs")
+    ) {
+        return [`${fileName}.ts`, `${fileName}/index.ts`];
+
+    } else if (fileName.endsWith(".js")) {
+        // ESM imports often spell a .ts source with a .js extension
+        return [fileName, fileName.replace(/\.js$/, ".ts")];
+
+    } else {
+        return [fileName];
+    }
+}
+
+/** Same probing as parseFiles(), answering "which candidate exists?". */
+export function resolveSourceFile(fileName: string): string | undefined {
+    const candidates = sourceFileCandidates(fileName);
+
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = path.resolve(candidates[i]);
+        try {
+            // statSync, not existsSync: a directory must fall through to the
+            // next candidate, the way readFileSync's EISDIR does
+            if (fs.statSync(candidate).isFile()) { return candidate; }
+        } catch (e) {
+            if (!(e as any)?.code) { throw e; }
+        }
+    }
+
+    return undefined;
+}
+
+/**
+ * The serializer's own source declares wire-internal schemas (`Reflection`,
+ * `ReflectionField`, …) that must never reach generated client code.
+ */
+export function isOwnPackageSource(fileName: string): boolean {
+    const relative = path.relative(PACKAGE_ROOT, fileName);
+    return (
+        !relative.startsWith("..") &&
+        !path.isAbsolute(relative) &&
+        (relative.startsWith(`src${path.sep}`) || relative.startsWith(`build${path.sep}`))
+    );
+}

package/src/codegen/types.ts

@@ -5,7 +5,10 @@ if (typeof(__dirname) === "undefined") {
     global.__dirname = path.dirname(new URL(import.meta.url).pathname);
 }
 
-const VERSION = JSON.parse(fs.readFileSync(__dirname + "/../../package.json").toString()).version;
+/** Root of the @colyseus/schema package — `src/codegen/` in dev, `build/codegen/` once bundled. */
+export const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+
+const VERSION = JSON.parse(fs.readFileSync(path.resolve(PACKAGE_ROOT, "package.json")).toString()).version;
 const COMMENT_HEADER = `
 THIS FILE HAS BEEN GENERATED AUTOMATICALLY
 DO NOT CHANGE IT MANUALLY UNLESS YOU KNOW WHAT YOU'RE DOING

package/src/decoder/DecodeOperation.ts

@@ -240,7 +240,12 @@ export const decodeSchemaOperation: DecodeOperation = function <T extends Schema
         return DEFINITION_MISMATCH;
     }
 
-    const previousValue = ref[$getByIndex](index);
+    // a peer that still carries a @deprecated() field keeps sending it — the
+    // bytes must be consumed or the stream desyncs, but the local accessor
+    // may throw: read nothing, write nothing, report nothing.
+    const isDeprecated = field.deprecated === true;
+
+    const previousValue = isDeprecated ? undefined : ref[$getByIndex](index);
     const value = decodeValue(
         decoder,
         operation,
@@ -253,6 +258,8 @@ export const decodeSchemaOperation: DecodeOperation = function <T extends Schema
         allChanges,
     );
 
+    if (isDeprecated) { return; }
+
     if (value !== null && value !== undefined) {
         // Write via the generated setter. Bypass to `(ref as any)[$values][index]`
         // was attempted but only works for @type-decorated classes (which
@@ -430,7 +437,11 @@ export const decodeArray: DecodeOperation = function (
         return;
 
     } else if (operation === OPERATION.REVERSE) {
-        tgt.reverse();
+        // Positional reverse of the decoder's authoritative storage. Don't
+        // call `tgt.reverse()` — that's the encoder-side method, and its
+        // dirty-tick check would misread the stale recorder a `clone(true)`
+        // instance carries.
+        tgt.items.reverse();
         return;
 
     } else if (operation === OPERATION.DELETE_BY_REFID) {

package/src/encoder/ChangeTree.ts

@@ -17,7 +17,7 @@
  */
 import { OPERATION } from "../encoding/spec.js";
 import { Schema } from "../Schema.js";
-import { $changes, $childType, $decoder, $onEncodeEnd, $encoder, $getByIndex, $proxyTarget, $refId, $refTypeFieldIndexes, $numFields, type $deleteByIndex } from "../types/symbols.js";
+import { $changes, $childType, $decoder, $onEncodeEnd, $encoder, $getByIndex, $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";
@@ -27,7 +27,7 @@ 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 ChangeRecorder, 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";
@@ -37,6 +37,7 @@ import {
     setParentIndex as _setParentIndex,
     findParent as _findParent, hasParent as _hasParent,
     getAllParents as _getAllParents,
+    indexInParent as _indexInParent,
 } from "./changeTree/parentChain.js";
 import { forEachLive as _forEachLive, forEachLiveWithCtx as _forEachLiveWithCtx } from "./changeTree/liveIteration.js";
 import {
@@ -113,12 +114,27 @@ export function createChangeTreeList(): ChangeTreeList {
     return { next: undefined, tail: undefined, nextPosition: 0 };
 }
 
+/**
+ * Live node in a tree's parent chain — mutating one edits the chain. Only
+ * `parentChain.ts` should hold these.
+ */
 export interface ParentChain {
     ref: Ref;
     index: number;
     next?: ParentChain;
 }
 
+/**
+ * Detached copy of one parent link, handed out by the query helpers. Distinct
+ * from `ParentChain` on purpose: it carries no `next`, so it cannot be walked
+ * as if it were the chain, and it is readonly, so it cannot be mistaken for a
+ * way to move a parent's index — `setParentIndex` does that.
+ */
+export interface ParentEntry {
+    readonly ref: Ref;
+    readonly index: number;
+}
+
 // 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;
@@ -135,6 +151,11 @@ export const IS_STREAM_COLLECTION = 64;
 // only fields assigned after `pool.acquire()` would reach the wire — the
 // retained ones (constructor-initialized children) would never be encoded.
 export const NEEDS_RESTAGE = 128;
+// Queued in `Root.pendingFilterRefresh` — the tree's parent-edge set changed
+// (instance sharing gained/lost an edge) and `isFiltered` /
+// `isVisibilitySharedWithParent` must be re-derived from the LIVE edges
+// before the next encode. See inheritedFlags.refreshFilterState.
+export const PENDING_FILTER_REFRESH = 256;
 /**
  * Flags a child inherits from its parent's own transitive state via
  * `checkInheritedFlags`. Read as a bitwise mask so the inheritance step
@@ -169,6 +190,14 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
      */
     refTarget: T;
 
+    /**
+     * True when `ref` is an ArraySchema — the only proxied type, so its
+     * user-facing identity differs from `refTarget`. Canonical predicate for
+     * "is this tree's ref an array" without probing `ref` (which would hit
+     * the Proxy trap) — two monomorphic loads on the tree itself.
+     */
+    get isArray(): boolean { return this.refTarget !== this.ref; }
+
     metadata: Metadata;
 
     /**
@@ -279,8 +308,7 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
 
     ensureUnreliableRecorder(): ChangeRecorder {
         if (this.unreliableRecorder === undefined) {
-            const isSchema = Metadata.isValidInstance(this.ref);
-            this.unreliableRecorder = isSchema
+            this.unreliableRecorder = this._isSchema
                 ? new SchemaChangeRecorder((this.metadata?.[$numFields] ?? 0) as number)
                 : new CollectionChangeRecorder();
         }
@@ -325,12 +353,13 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         return Metadata.hasStreamAtIndex(this.metadata, index);
     }
 
-    constructor(ref: T) {
+    constructor(ref: T, refTarget: T = ref) {
         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;
+        // Raw (non-Proxy) target, passed explicitly by ArraySchema's ctor —
+        // the only proxied type. Defaulting to `ref` for everything else
+        // skips a guaranteed-miss megamorphic `$proxyTarget` probe per
+        // construction. Cached so hot-path reads skip the Proxy `get` trap.
+        this.refTarget = refTarget;
 
         // Single per-class lookup that subsumes Symbol.metadata,
         // isValidInstance, $encoder, $filter, and the filter bitmask.
@@ -592,28 +621,42 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     }
 
     /**
-     * ArraySchema#unshift(): re-key pending ops on both channels by
-     * `+count`, then record ADDs for the new items at indexes 0..count-1.
+     * ArraySchema insert (unshift / splice with more inserts than deletes):
+     * re-key pending ops at or above `at` by `+count`, then record ADDs for
+     * the new items at indexes `at..at+count-1`.
      *
-     * The rebuilt map's insertion order IS the wire order: new ADDs first
-     * (ascending — the decoder splice-inserts each one, which only works
-     * lowest-index-first), then prior ops in their original relative order
-     * at their shifted positions. See ArraySchema#$setAt.
+     * The rebuilt map's insertion order IS the wire order:
+     *   1. ops below `at` — the insert doesn't move them, and an insert of
+     *      their own must still be applied before this one (ascending);
+     *   2. the new ADDs, ascending — the decoder splice-inserts each one,
+     *      which only works lowest-index-first;
+     *   3. the re-keyed ops, in their original relative order — their
+     *      indexes now address the post-insert layout.
+     * See ArraySchema#$setAt.
      */
-    unshift(count: number): void {
-        if (this._isSchema) throw new Error("ChangeTree (Schema): unshift is not supported");
+    insertAt(at: number, count: number): void {
+        if (this._isSchema) throw new Error("ChangeTree (Schema): insertAt is not supported");
         const src = this.collDirty!;
         const dst = new Map<number, OPERATION>();
         const track = !this.paused && !this.isFullStateOnly;
+        if (at > 0) {
+            for (const [idx, val] of src) if (idx < at) dst.set(idx, val);
+        }
         if (track) {
-            for (let i = 0; i < count; i++) dst.set(i, OPERATION.ADD);
+            for (let i = 0; i < count; i++) dst.set(at + i, OPERATION.ADD);
         }
-        for (const [idx, val] of src) dst.set(idx + count, val);
+        for (const [idx, val] of src) if (idx >= at) dst.set(idx + count, val);
         this.collDirty = dst;
-        (this.unreliableRecorder as ICollectionChangeRecorder | undefined)?.shift(count);
+        // no unreliable re-key — collection trees never carry an unreliable
+        // recorder (tree-level @unreliable is disabled, see isFieldUnreliable)
         if (track) this.root?.enqueueChangeTree(this);
     }
 
+    /** ArraySchema#unshift(): insert `count` items at the head. */
+    unshift(count: number): void {
+        this.insertAt(0, count);
+    }
+
     // 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); }
@@ -762,7 +805,12 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     endEncode() {
         this.reset();
         this.changesNode = undefined;
-        (this.ref as any)[$onEncodeEnd]?.();
+        // Every collection class defines [$onEncodeEnd]; Schema never does —
+        // probing it was a guaranteed megamorphic miss per drained tree.
+        // `?.` stays: a FIELDLESS Schema has no metadata, so its tree is
+        // `_isSchema === false` too. refTarget receiver skips ArraySchema's
+        // proxy hops.
+        if (!this._isSchema) (this.refTarget as any)[$onEncodeEnd]?.();
         this.isNew = false;
     }
 
@@ -770,11 +818,11 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     endEncodeUnreliable() {
         this.unreliableRecorder?.reset();
         this.unreliableChangesNode = undefined;
-        (this.ref as any)[$onEncodeEnd]?.();
+        if (!this._isSchema) (this.refTarget as any)[$onEncodeEnd]?.();
     }
 
     discard() {
-        (this.ref as any)[$onEncodeEnd]?.();
+        if (!this._isSchema) (this.refTarget as any)[$onEncodeEnd]?.();
         this.reset();
         this.unreliableRecorder?.reset();
     }
@@ -811,7 +859,7 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     /** @returns true if parent was found and removed */
     removeParent(parent: Ref = this.parent): boolean { return _removeParent(this, parent); }
 
-    findParent(predicate: (parent: Ref, index: number) => boolean): ParentChain | undefined {
+    findParent(predicate: (parent: Ref, index: number) => boolean): ParentEntry | undefined {
         return _findParent(this, predicate);
     }
 
@@ -819,7 +867,10 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         return _hasParent(this, predicate);
     }
 
-    getAllParents(): Array<{ ref: Ref, index: number }> { return _getAllParents(this); }
+    /** Wire index this tree holds inside `parent`, or undefined if not a parent. */
+    indexInParent(parent: Ref): number | undefined { return _indexInParent(this, parent); }
+
+    getAllParents(): ParentEntry[] { return _getAllParents(this); }
 
 }
 

package/src/encoder/EncodeOperation.ts

@@ -242,8 +242,17 @@ export const encodeArray: EncodeOperation = function (
         if (operation === OPERATION.DELETE) {
             operation = OPERATION.DELETE_BY_REFID;
 
-        } else if (operation === OPERATION.ADD) {
+        } else if ((operation & OPERATION.ADD) === OPERATION.ADD) {
+            // ADD, DELETE_AND_ADD, MOVE_AND_ADD. The wire index below is a
+            // refId — positional ops would make the decoder misread it as a
+            // slot, so everything must degrade to a BY_REFID op here.
             operation = OPERATION.ADD_BY_REFID;
+
+        } else if ((operation & OPERATION.MOVE) === OPERATION.MOVE) {
+            // Pure reorder (MOVE / DELETE_AND_MOVE). Filtered clients hold
+            // per-view subsets, so element order is not synchronized for
+            // them (ADD_BY_REFID appends) — there is nothing to emit.
+            return;
         }
 
     } else if (operation === OPERATION.DELETE && isSchemaChild) {