@colyseus/schema 5.0.14 → 5.0.20

package/src/encoder/StateView.ts

@@ -1,5 +1,5 @@
 import { ChangeTree, Ref } from "./ChangeTree.js";
-import { $changes, $fieldIndexesByViewTag, $refId, $viewFieldIndexes } from "../types/symbols.js";
+import { $changes, $childType, $fieldIndexesByViewTag, $refId, $viewFieldIndexes } from "../types/symbols.js";
 import { DEFAULT_VIEW_TAG } from "../annotations.js";
 import { OPERATION } from "../encoding/spec.js";
 import { Metadata } from "../Metadata.js";
@@ -61,6 +61,16 @@ const _disposeRegistry = new FinalizationRegistry<{ root: Root; id: number; slot
  * populated collection inspects into dozens of lines of encoder
  * internals and buries the message that matters.
  */
+/**
+ * Sentinel inner-map key: "snapshot every live element of this ref-typed
+ * ArraySchema". Written by `_add`'s bulk path instead of one entry per
+ * element; `encodeView` expands it structurally at drain time, so the
+ * emitted slots reflect any reindex that happened after `view.add()` —
+ * and a whole-array snapshot costs one Map insert instead of N.
+ * Real slots are never negative, so -1 cannot collide.
+ */
+export const ARRAY_SNAPSHOT = -1;
+
 function describeArg(value: any): string {
     if (value === undefined) { return "undefined"; }
     if (value === null) { return "null"; }
@@ -107,8 +117,16 @@ export class StateView {
      * Inner storage is a Map so the encode loop in `encodeView` can iterate
      * directly with numeric keys — the legacy `{[index]: OPERATION}` shape
      * forced an `Object.keys(...)` allocation + `Number(key)` parse per ref.
+     *
+     * Inner keys are numbers (Schema field indexes, MapSchema journal
+     * indexes, Set/Collection indexes, stream positions — all stable within
+     * a tick), EXCEPT element bindings under a ref-typed ArraySchema parent,
+     * which are keyed by the child's ChangeTree. An array wire slot captured
+     * at `view.add()` time goes stale if the array reindexes (unshift /
+     * reverse / move) later in the same tick — identity keys let
+     * `encodeView` resolve the CURRENT slot at drain time instead.
      */
-    changes = new Map<number, Map<number, OPERATION>>();
+    changes = new Map<number, Map<number | ChangeTree, OPERATION>>();
 
     constructor(public iterable: boolean = false) {
         if (iterable) {
@@ -368,15 +386,18 @@ export class StateView {
         // subclasses yield a real Metadata object.
         const metadata: Metadata = (obj.constructor as typeof Schema)[Symbol.metadata];
 
+        const wasVisible = this.isVisible(changeTree);
+
         // Add to iterable list (only the explicitly added items), deduping
-        // re-adds of an already-visible instance. isVisible must be read
-        // BEFORE markVisible; indexOf runs only on the re-add path.
-        // NOTE: dedup applies to `items` only — a re-add still re-queues the
-        // full snapshot on purpose (shared-view bootstrap re-add: a
-        // late-attached client may not have consumed earlier drains).
-        // Callers wanting cheap idempotence can guard with `view.has(obj)`.
+        // re-adds of an already-visible instance; indexOf runs only on the
+        // re-add path.
+        // NOTE: dedup applies to `items` only — a default-tag re-add still
+        // re-queues the full snapshot on purpose (shared-view bootstrap
+        // re-add: a late-attached client may not have consumed earlier
+        // drains). Callers wanting cheap idempotence can guard with
+        // `view.has(obj)`.
         if (this.iterable && checkIncludeParent
-            && (!this.isVisible(changeTree) || this.items.indexOf(obj) === -1)) {
+            && (!wasVisible || this.items.indexOf(obj) === -1)) {
             this.items.push(obj);
         }
 
@@ -469,32 +490,51 @@ export class StateView {
                     });
                 }
             }
+        }
 
-        } else if (!changeTree.isNew || isChildAdded) {
-            // new structures will be added as part of .encode() call, no need to force it to .encodeView()
-
-            // Full-sync snapshot: walk the live ref structurally instead of
-            // iterating a cumulative recorder bucket. Every populated index
-            // is emitted as ADD (matching the op-coercion previously done
-            // at encode time). Per-field tags come from the descriptor's
-            // precomputed `tags[]` array — direct index vs a metadata[i].tag
-            // object hop.
-            //
-            // Non-matching custom-tagged fields are NEVER included here —
-            // `view.changes` is drained without a per-field tag re-check,
-            // so anything added leaks straight to the wire.
-            const tags = changeTree.encDescriptor.tags;
-            changeTree.forEachLive((index) => {
-                const tagAtIndex = tags[index];
-                if (
-                    tagAtIndex === undefined || // "all change" with no tag
-                    tagAtIndex === DEFAULT_VIEW_TAG || // visible to all clients
-                    (tag !== DEFAULT_VIEW_TAG && (tagAtIndex & tag) !== 0) // tag bits overlap
-                ) {
-                    changes.set(index, OPERATION.ADD);
+        // Full-sync snapshot of a non-new tree (fresh ones ship via .encode()).
+        // Also runs for custom tags when bootstrapping the tree for this view
+        // (!wasVisible) — the per-field filter admits untagged fields, and
+        // collections behind tagged fields have no `byTag`: without the
+        // snapshot their elements are never introduced ("refId" not found).
+        // A tagged add on an already-visible tree stays incremental (byTag
+        // only); default-tag re-adds re-snapshot on purpose (see `items`
+        // dedup note above).
+        if ((tag === DEFAULT_VIEW_TAG || !wasVisible) && (!changeTree.isNew || isChildAdded)) {
+            if (changeTree.isArray && typeof (changeTree.refTarget as any)[$childType] !== "string") {
+                // Ref-typed ArraySchema (the only proxied collection): one
+                // sentinel entry — encodeView snapshots the live elements at
+                // drain time, so the slots survive a same-tick reindex (see
+                // `changes` field docs) and the write stays O(1).
+                if ((changeTree.refTarget as any).items.length > 0) {
+                    changes.set(ARRAY_SNAPSHOT, OPERATION.ADD);
                     isChildAdded = true;
                 }
-            });
+
+            } else {
+                // Full-sync snapshot: walk the live ref structurally instead of
+                // iterating a cumulative recorder bucket. Every populated index
+                // is emitted as ADD (matching the op-coercion previously done
+                // at encode time). Per-field tags come from the descriptor's
+                // precomputed `tags[]` array — direct index vs a metadata[i].tag
+                // object hop.
+                //
+                // Non-matching custom-tagged fields are NEVER included here —
+                // `view.changes` is drained without a per-field tag re-check,
+                // so anything added leaks straight to the wire.
+                const tags = changeTree.encDescriptor.tags;
+                changeTree.forEachLive((index) => {
+                    const tagAtIndex = tags[index];
+                    if (
+                        tagAtIndex === undefined || // "all change" with no tag
+                        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;
+                    }
+                });
+            }
         }
 
         return isChildAdded;
@@ -575,13 +615,21 @@ export class StateView {
         if (changeTree.getChange(parentIndex) !== OPERATION.DELETE) {
             let changes = this.changes.get(changeTree.ref[$refId]);
             if (changes === undefined) {
-                changes = new Map<number, OPERATION>();
+                changes = new Map<number | ChangeTree, OPERATION>();
                 this.changes.set(changeTree.ref[$refId], changes);
             }
 
             this.addTag(changeTree, tag);
 
-            changes.set(parentIndex, OPERATION.ADD);
+            // ArraySchema parents: key by the child's identity, not the wire
+            // slot it holds right now — a same-tick unshift()/reverse()/move()
+            // would shift the slot before encodeView drains this entry. Other
+            // parents keep numeric keys (Schema fields, MapSchema journal
+            // indexes and Set/Collection indexes are stable within a tick).
+            changes.set(
+                changeTree.isArray ? childChangeTree : parentIndex,
+                OPERATION.ADD,
+            );
         }
     }
 
@@ -641,8 +689,8 @@ export class StateView {
         // out of the stream's per-view state. If it never made it to the
         // wire (still in pending), silent drop; if already sent, queue
         // DELETE via `view.changes` for the next encodeView drain.
-        const parentStreamTree = changeTree.parent?.[$changes];
-        if (parentStreamTree?.isStreamCollection) {
+        const parentTree = changeTree.parent?.[$changes];
+        if (parentTree?.isStreamCollection) {
             this.unmarkVisible(changeTree);
             if (this.iterable && !_isClear) {
                 spliceOne(this.items, this.items.indexOf(obj));
@@ -718,59 +766,46 @@ export class StateView {
             // parent is collection (Map/Array)
             const parent = changeTree.parent;
             if (parent && !Metadata.isValidInstance(parent) && changeTree.isFiltered) {
+                // ArraySchema parents use identity keys (see `changes` field
+                // docs); Map parents keep the (stable) journal index.
+                const key = parentTree!.isArray
+                    ? changeTree
+                    : changeTree.parentIndex;
                 const parentRefId = parent[$refId];
                 let changes = this.changes.get(parentRefId);
                 if (changes === undefined) {
-                    changes = new Map<number, OPERATION>();
+                    changes = new Map<number | ChangeTree, OPERATION>();
                     this.changes.set(parentRefId, changes);
 
-                } else if (changes.get(changeTree.parentIndex) === OPERATION.ADD) {
+                } else if (changes.get(key) === OPERATION.ADD) {
                     //
                     // SAME PATCH ADD + REMOVE:
-                    // The 'changes' of deleted structure should be ignored.
+                    // cancel the structure's pending ops and its descendants' —
+                    // their introduction never reaches this client.
                     //
-                    this.changes.delete(refId);
+                    this._dropPendingEntries(changeTree);
                 }
 
                 // DELETE / DELETE BY REF ID
-                changes.set(changeTree.parentIndex, OPERATION.DELETE);
+                changes.set(key, OPERATION.DELETE);
 
                 // Remove child schema from visible set
                 this._recursiveDeleteVisibleChangeTree(changeTree);
 
             } else {
                 // delete all "tagged" properties.
-                const names = changeTree.encDescriptor.names;
-                metadata?.[$viewFieldIndexes]?.forEach((index) => {
-                    changes.set(index, OPERATION.DELETE);
-
-                    // Remove child structures of @view() fields from visible set.
-                    // (They were added during view.add() via forEachChild)
-                    const value = changeTree.ref[names[index] as keyof Ref];
-                    if (value?.[$changes]) {
-                        this.unmarkVisible(value[$changes]);
-                        this._recursiveDeleteVisibleChangeTree(value[$changes]);
-                    }
-                });
+                metadata?.[$viewFieldIndexes]?.forEach((index) =>
+                    this._removeViewField(changeTree, changes, index));
             }
 
         } else {
             // delete only tagged properties. `$fieldIndexesByViewTag` is
             // keyed per-bit, so a combined tag iterates each set bit.
-            const names = changeTree.encDescriptor.names;
             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]);
-                        }
-                    });
+                    byTag[bits & -bits]?.forEach((index) =>
+                        this._removeViewField(changeTree, changes, index));
                 }
             }
         }
@@ -956,14 +991,16 @@ export class StateView {
         } else {
             // Non-streams: queue DELETE for every current child and
             // unmark their visibility so subsequent mutations stop
-            // reaching this view.
+            // reaching this view. ArraySchema children are keyed by identity
+            // (see `changes` field docs); others by their stable index.
+            const isArray = tree.isArray;
             let changes = this.changes.get(collectionRefId);
             tree.forEachChild((childTree, index) => {
                 if (changes === undefined) {
                     changes = new Map();
                     this.changes.set(collectionRefId, changes);
                 }
-                changes.set(index, OPERATION.DELETE);
+                changes.set(isArray ? childTree : index, OPERATION.DELETE);
                 this.unmarkVisible(childTree);
             });
         }
@@ -999,9 +1036,24 @@ export class StateView {
         // `markVisible` memoizes so the branch fires at most once per
         // (tree, view) pair.
         if (!isVisible && changeTree.isVisibilitySharedWithParent){
+            // Primary grant is intentionally unguarded — pre-existing
+            // semantics; the extras walk below is stricter on purpose.
             if (this.isVisible(changeTree.parent[$changes])) {
                 this.markVisible(changeTree);
                 isVisible = true;
+            } else {
+                // Shared instance: the sharing parent may sit anywhere in the
+                // chain — addParent promotes the LAST container to primary.
+                // Only filtered parents can grant (public ones never share
+                // visibility downward).
+                for (let e = changeTree.extraParents; e !== undefined; e = e.next) {
+                    const parentTree = e.ref[$changes];
+                    if (parentTree.isFiltered && this.isVisible(parentTree)) {
+                        this.markVisible(changeTree);
+                        isVisible = true;
+                        break;
+                    }
+                }
             }
         }
 
@@ -1014,4 +1066,36 @@ export class StateView {
             this._recursiveDeleteVisibleChangeTree(childChangeTree);
         });
     }
+
+    /**
+     * Drop the pending `view.changes` entries of `tree` and every descendant.
+     * Called when a same-patch pending ADD is cancelled: the subtree's
+     * introduction never reaches this client, so its entries would emit
+     * refIds the decoder cannot resolve ("refId" not found).
+     */
+    private _dropPendingEntries(tree: ChangeTree): void {
+        this.changes.delete(tree.ref[$refId]);
+        tree.forEachChild((child) => this._dropPendingEntries(child));
+    }
+
+    /**
+     * Queue DELETE for a @view field on `changes` and hide the field
+     * value's subtree from this view. When the field's ADD is still
+     * pending (same-patch add + remove), the value's introduction never
+     * ships — its pending subtree entries are dropped along with it.
+     */
+    private _removeViewField(changeTree: ChangeTree, changes: Map<number | ChangeTree, OPERATION>, index: number): void {
+        const wasPendingAdd = changes.get(index) === OPERATION.ADD;
+        changes.set(index, OPERATION.DELETE);
+
+        const value = changeTree.ref[changeTree.encDescriptor.names[index] as keyof Ref];
+        const valueTree: ChangeTree = value?.[$changes];
+        if (valueTree) {
+            this.unmarkVisible(valueTree);
+            this._recursiveDeleteVisibleChangeTree(valueTree);
+            if (wasPendingAdd) {
+                this._dropPendingEntries(valueTree);
+            }
+        }
+    }
 }

package/src/encoder/changeTree/inheritedFlags.ts

@@ -13,16 +13,17 @@ import {
     // (see INHERITABLE_FLAGS comment in ChangeTree.ts). Per-field unreliable
     // routing on primitive fields still uses it via `isFieldUnreliable()`.
 } from "../../types/symbols.js";
-import type { Schema } from "../../Schema.js";
 import {
-    INHERITABLE_FLAGS, IS_FULL_STATE_ONLY, IS_PATCH_ONLY,
+    INHERITABLE_FLAGS, IS_FULL_STATE_ONLY, IS_PATCH_ONLY, PENDING_FILTER_REFRESH,
     // IS_UNRELIABLE — tree-level unreliable currently disabled; see
     // INHERITABLE_FLAGS comment in ChangeTree.ts.
     type ChangeTree, type Ref,
 } from "../ChangeTree.js";
 import type { ICollectionChangeRecorder } from "../ChangeRecorder.js";
-import type { Streamable } from "../Root.js";
+import type { Root, Streamable } from "../Root.js";
 import { ensureStreamState } from "../streaming.js";
+import { restageLiveCb } from "./liveIteration.js";
+import { isEdgeLive } from "./parentChain.js";
 
 /**
  * Reconcile queue membership + inherited flags for a tree that just had
@@ -71,25 +72,13 @@ export function checkIsFiltered(
  * etc.) inherit these from the Schema field that holds them.
  *
  * The common case — fresh tree attached to a parent field that carries
- * none of the inheritable annotations — produces no flag change, no
- * queue update, and no `parentFiltered` hit. Two small structural
- * choices keep that case cheap without any precomputed descriptor
- * bitmask:
- *
- *  1) Flag inheritance is a single bitwise OR onto `tree.flags`. The
- *     three per-annotation reads pack into `fieldBits`, the parent's
- *     inherited bits come from `parentChangeTree.flags` directly; one
- *     read-modify-write replaces three getter/setter cycles, and the
- *     bit diff against `beforeFlags` gives us the "just became static /
- *     unreliable" signal for the side-effect branches.
- *
- *  2) The `parentFiltered` string-key lookup is gated on
- *     `types.hasParentFilteredEntries`, which is only flipped true when
- *     `registerFilteredByParent` actually records an entry — i.e. when
- *     some @view-tagged field reaches this (child, parent, index)
- *     triple through the ancestry walk. Schemas with @view tags only on
- *     sibling fields (not along any attachment chain) skip the string
- *     concat + hash lookup entirely.
+ * none of the inheritable annotations — produces no flag change and no
+ * queue update. Flag inheritance is a single bitwise OR onto
+ * `tree.flags`: the per-annotation reads pack into `fieldBits`, the
+ * parent's inherited bits come from `parentChangeTree.flags` directly,
+ * and one read-modify-write replaces three getter/setter cycles. The bit
+ * diff against `beforeFlags` gives the "just became static / unreliable"
+ * signal for the side-effect branches.
  */
 export function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex: number): void {
     if (!parent) { return; }
@@ -97,15 +86,17 @@ export function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex:
     // Walk up a collection level so `parent` lands on the Schema that
     // owns the field at `parentIndex`. Field annotations live on Schema
     // metadata; collections have none.
-    let parentChangeTree: ChangeTree = parent[$changes];
-    const parentIsCollection = !Metadata.isValidInstance(parent);
+    const parentChangeTree: ChangeTree = parent[$changes];
+    const parentIsCollection = !parentChangeTree._isSchema;
+    let parentMetadata: any;
     if (parentIsCollection) {
         parent = parentChangeTree.parent;
         parentIndex = parentChangeTree.parentIndex;
+        parentMetadata = parent?.[$changes].metadata;
+    } else {
+        parentMetadata = parentChangeTree.metadata;
     }
 
-    const parentMetadata: any = (parent as any)?.constructor?.[Symbol.metadata];
-
     // Flag inheritance — pack the patchOnly/static annotation checks into
     // flag bits alongside the parent's own transitive flags, then OR onto
     // `tree.flags` in one write. The bit diff tells us which flag just
@@ -159,21 +150,12 @@ export function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex:
     // pass is the only way elements become visible to a view.
     const fieldHasStream = parentMetadata?.[$streamFieldIndexes]?.includes(parentIndex) ?? false;
 
-    // Skip the `parentFiltered` string-key lookup when no class has
-    // actually registered filter inheritance via ancestry. The lookup
-    // cannot hit in that state, so the string concat + hash lookup would
-    // be wasted work every attach.
-    let parentFiltered = false;
-    const parentConstructor = (parent as any)?.constructor as typeof Schema | undefined;
-    if (types.hasParentFilteredEntries && parentConstructor !== undefined) {
-        const refType = Metadata.isValidInstance(tree.ref)
-            ? tree.ref.constructor
-            : (tree.ref as any)[$childType];
-        const key = `${types.getTypeId(refType as typeof Schema)}-${types.schemas.get(parentConstructor)}-${parentIndex}`;
-        parentFiltered = types.parentFiltered[key] ?? false;
-    }
-
-    const newFiltered = parentChangeTree.isFiltered || parentFiltered || fieldHasViewTag || fieldHasStream;
+    // Filtering is a property of the *attachment*, never of the child class:
+    // the same Schema class may sit under a @view field here and under a
+    // public field there (#204). `parentChangeTree.isFiltered` carries the
+    // ancestry — `setRoot` derives it parent-first before recursing — so the
+    // field annotation only has to answer for this one edge.
+    const newFiltered = parentChangeTree.isFiltered || fieldHasViewTag || fieldHasStream;
     tree.isFiltered = newFiltered;
 
     // Flag collection trees attached to a `.stream()` field so the encoder
@@ -204,9 +186,7 @@ export function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex:
     }
 
     if (newFiltered) {
-        const refType = Metadata.isValidInstance(tree.ref)
-            ? tree.ref.constructor
-            : (tree.ref as any)[$childType];
+        const sharesEligible = _sharesEligible(tree);
         // #218: nested Schema fields inherit visibility from a @view-gated
         // parent regardless of whether the parent is a collection. The
         // `parentIsCollection` constraint that used to live here blocked
@@ -223,9 +203,148 @@ export function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex:
         // are guaranteed to exist when that flag is set).
         tree.isVisibilitySharedWithParent = (
             parentChangeTree.isFiltered
-            && typeof refType !== "string"
+            && sharesEligible
             && !fieldHasStream
             && (!fieldHasViewTag || (parentIsCollection && parentMetadata[parentIndex].tag !== DEFAULT_VIEW_TAG))
         );
     }
 }
+
+// ────────────────────────────────────────────────────────────────────────
+// Per-edge filter refresh — instance sharing across a @view boundary.
+//
+// `checkIsFiltered` classifies a tree from the edge it was FIRST attached
+// through. A shared instance has N parent edges with different visibility,
+// and the wire emits field data per-refId per-channel — so the tree-level
+// invariant is:
+//
+//     isFiltered  ⇔  no fully-public root path reaches this tree
+//
+// Rather than reconciling eagerly at every attach/detach (whose ordering
+// against the container's own storage mutation is fragile), edge events
+// call `Root.enqueueFilterRefresh` and the encoder re-derives the flags at
+// the top of the next encode — after every container mutation of the tick
+// has settled — via `drainFilterRefresh`. `isFiltered` is only CONSUMED at
+// encode time (recording is channel-agnostic), so the deferral is safe for
+// wire routing; only same-tick StateView bootstrap reads see the stale
+// flags, which at worst emits redundant (deduped) entries.
+// ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Drain `root.pendingFilterRefresh`. Called by the encoder before any
+ * emission (per-tick channels and full-sync).
+ */
+export function drainFilterRefresh(root: Root): void {
+    const list = root.pendingFilterRefresh;
+    for (let i = 0; i < list.length; i++) {
+        const tree = list[i];
+        // Already settled as another entry's parent, or detached/recycled
+        // since it was queued.
+        if ((tree.flags & PENDING_FILTER_REFRESH) === 0) continue;
+        refreshFilterState(tree);
+    }
+    list.length = 0;
+}
+
+/**
+ * Primitive-element collections never share visibility downward. One
+ * predicate for both derivations (`checkInheritedFlags` and
+ * `refreshFilterState`) — the InstanceSharing invariant test pins them
+ * together. `_isSchema` short-circuits the `$childType` probe for Schema
+ * trees (whose `$childType` is undefined and would pass anyway).
+ */
+function _sharesEligible(tree: ChangeTree): boolean {
+    return tree._isSchema || typeof (tree.refTarget as any)[$childType] !== "string";
+}
+
+/**
+ * Re-derive `isFiltered` (AND over live edges) and
+ * `isVisibilitySharedWithParent` (OR over live edges) from the parent
+ * chain. On a filtered→public flip, live state is re-staged — it may have
+ * already drained to view channels only, and clients that hold it decode
+ * the duplicate ADDs as no-ops (StateView bootstrap re-adds rely on the
+ * same property). The public→filtered flip needs no re-stage: the public
+ * container's DELETE already ships on the shared channel.
+ *
+ * A flip cascades into children so classifications inherited through this
+ * tree follow it; re-derivation is idempotent and a child that does not
+ * flip does not recurse, so the walk terminates on cyclic instance graphs.
+ */
+function refreshFilterState(tree: ChangeTree): void {
+    tree.flags &= ~PENDING_FILTER_REFRESH;
+    const root = tree.root;
+    if (root === undefined || tree.parentRef === undefined) return;
+
+    const sharesEligible = _sharesEligible(tree);
+
+    let bits = _edgeBits(tree, tree.parentRef, tree._parentIndex, sharesEligible);
+    // Saturated means no further edge can change the outcome.
+    for (let e = tree.extraParents; e !== undefined && bits !== EDGE_SATURATED; e = e.next) {
+        bits |= _edgeBits(tree, e.ref, e.index, sharesEligible);
+    }
+
+    // No live edge resolved (mid-detach churn) — keep the current
+    // classification rather than guess.
+    if (bits === 0) return;
+
+    tree.isVisibilitySharedWithParent = (bits & EDGE_SHARES) !== 0;
+
+    const newFiltered = (bits & EDGE_PUBLIC) === 0;
+    if (newFiltered === tree.isFiltered) return;
+    tree.isFiltered = newFiltered;
+
+    // Became public: clients that only ever had the view channel never saw
+    // this state. Static trees ship via structural walk instead.
+    if (!newFiltered && !tree.isFullStateOnly) {
+        tree.forEachLiveWithCtx(tree, restageLiveCb);
+        if (tree.has()) root.enqueueChangeTree(tree);
+        if (tree.unreliableRecorder?.has()) root.enqueueUnreliable(tree);
+    }
+
+    tree.forEachChildWithCtx(tree, _cascadeRefreshCb);
+}
+
+const EDGE_LIVE = 1, EDGE_PUBLIC = 2, EDGE_SHARES = 4;
+const EDGE_SATURATED = EDGE_LIVE | EDGE_PUBLIC | EDGE_SHARES;
+
+/**
+ * Classify one parent edge: is it live, does it make the tree publicly
+ * reachable, does view visibility flow through it.
+ */
+function _edgeBits(tree: ChangeTree, parentRef: Ref, index: number, sharesEligible: boolean): number {
+    const parentTree: ChangeTree = parentRef[$changes];
+    if (parentTree.root !== tree.root || !isEdgeLive(tree, parentTree, index)) return 0;
+
+    // A queued parent must settle first — this edge reads its `isFiltered`.
+    // The flag-clear on entry terminates cycles, and a cascade re-entering
+    // `tree` is idempotent (same edges, same result — the outer pass then
+    // sees "no change").
+    if (parentTree.flags & PENDING_FILTER_REFRESH) refreshFilterState(parentTree);
+
+    let bits = EDGE_LIVE;
+    if (parentTree._isSchema) {
+        // A @view/stream-marked field stays filtered even under a public
+        // parent, and never shares visibility downward.
+        const marked = parentTree.encDescriptor.tags[index] !== undefined
+            || parentTree.isFieldStream(index);
+        if (!marked) {
+            if (!parentTree.isFiltered) bits |= EDGE_PUBLIC;
+            else if (sharesEligible) bits |= EDGE_SHARES;
+        }
+    } else if (!parentTree.isFiltered) {
+        // Collection edge: the collection's own classification already
+        // folds in the field that holds it.
+        bits |= EDGE_PUBLIC;
+    } else if (sharesEligible && !parentTree.isStreamCollection) {
+        // #226: default-tag @view() collections keep per-item gating;
+        // untagged and non-default-tag @view(N) ones share.
+        const gp = parentTree.parent?.[$changes];
+        const tag = gp?._isSchema ? gp.encDescriptor.tags[parentTree.parentIndex] : undefined;
+        if (tag !== DEFAULT_VIEW_TAG) bits |= EDGE_SHARES;
+    }
+    return bits;
+}
+
+const _cascadeRefreshCb = (_parentTree: ChangeTree, child: ChangeTree, _index: any): void => {
+    refreshFilterState(child);
+};

package/src/encoder/changeTree/liveIteration.ts

@@ -6,10 +6,31 @@
  * Patch-only fields (`@patchOnly`) are skipped — they're delivered only on
  * tick patches and not persisted to snapshots. Collections whose parent
  * field is @patchOnly inherit the skip (`tree.isPatchOnly`).
+ *
+ * `@deprecated()` fields are skipped too: the decorator swaps the field's
+ * prototype accessor for a throwing getter, so `ref[name]` below would blow
+ * up full sync for the whole state. Both skips ride one decoration-time
+ * list (`$fullSyncSkipIndexes`) so the walk pays a single metadata lookup.
  */
-import { $childType, $numFields, $patchOnlyFieldIndexes } from "../../types/symbols.js";
+import { OPERATION } from "../../encoding/spec.js";
+import { $childType, $numFields, $fullSyncSkipIndexes } from "../../types/symbols.js";
 import type { ChangeTree } from "../ChangeTree.js";
 
+/**
+ * Re-stage one live index as a fresh ADD on its channel. Shared by
+ * `Root.add` (refCount-0 / NEEDS_RESTAGE re-adds) and
+ * `inheritedFlags.refreshFilterState` (filtered→public flip) via
+ * `forEachLiveWithCtx(tree, restageLiveCb)` — one home for the
+ * unreliable-routing rule.
+ */
+export const restageLiveCb = (tree: ChangeTree, fieldIndex: number): void => {
+    if (tree.isFieldUnreliable(fieldIndex)) {
+        tree.ensureUnreliableRecorder().record(fieldIndex, OPERATION.ADD);
+    } else {
+        tree.record(fieldIndex, OPERATION.ADD);
+    }
+};
+
 // Adapter that lets `forEachLive(cb)` delegate to `forEachLiveWithCtx(cb, _invokeNoCtx)` —
 // keeps the no-ctx path closure-free and shares one walker implementation.
 const _invokeNoCtx = (cb: (index: number) => void, index: number) => cb(index);
@@ -65,12 +86,12 @@ export function forEachLiveWithCtx<C>(
         const metadata = tree.metadata;
         if (!metadata) return;
         const numFields = (metadata[$numFields] ?? -1) as number;
-        const patchOnlyIndexes = metadata[$patchOnlyFieldIndexes];
+        const skipIndexes = metadata[$fullSyncSkipIndexes] as number[] | undefined;
         const names = tree.encDescriptor.names;
         for (let i = 0; i <= numFields; i++) {
             const name = names[i];
             if (name === undefined) continue;
-            if (patchOnlyIndexes && patchOnlyIndexes.includes(i)) continue;
+            if (skipIndexes && skipIndexes.includes(i)) continue;
             const value = ref[name];
             if (value !== undefined && value !== null) cb(ctx, i);
         }