@colyseus/schema 5.0.14 → 5.0.19

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);
         }

package/src/encoder/changeTree/parentChain.ts

@@ -5,7 +5,7 @@
  * additional parents live in the `extraParents` linked list.
  */
 import { $changes } from "../../types/symbols.js";
-import type { ChangeTree, ParentChain, Ref } from "../ChangeTree.js";
+import type { ChangeTree, ParentEntry, Ref } from "../ChangeTree.js";
 
 /**
  * Add a parent to the chain. If `parent` already exists anywhere in the
@@ -115,39 +115,69 @@ export function removeParent(tree: ChangeTree, parent: Ref): boolean {
 }
 
 /**
- * Find the first parent in the chain matching `predicate`.
+ * First parent matching `predicate`, as a detached `ParentEntry`. Never returns
+ * a live `ParentChain` node — the inline parent has no node to return in the
+ * first place, so handing out the real node for the `extraParents` case only
+ * would make writes land or vanish depending on which parent matched. Use
+ * `setParentIndex` to move an index and `indexInParent` to read one.
  */
 export function findParent(
     tree: ChangeTree,
     predicate: (parent: Ref, index: number) => boolean,
-): ParentChain | undefined {
-    // Check inline parent first
-    if (tree.parentRef && predicate(tree.parentRef, tree._parentIndex)) {
+): ParentEntry | undefined {
+    if (tree.parentRef !== undefined && predicate(tree.parentRef, tree._parentIndex)) {
         return { ref: tree.parentRef, index: tree._parentIndex };
     }
-
-    let current = tree.extraParents;
-    while (current) {
-        if (predicate(current.ref, current.index)) {
-            return current;
+    for (let entry = tree.extraParents; entry !== undefined; entry = entry.next) {
+        if (predicate(entry.ref, entry.index)) {
+            return { ref: entry.ref, index: entry.index };
         }
-        current = current.next;
     }
     return undefined;
 }
 
+/** Walks in place — `addParent` calls this per shared-instance attach. */
 export function hasParent(
     tree: ChangeTree,
     predicate: (parent: Ref, index: number) => boolean,
 ): boolean {
-    return findParent(tree, predicate) !== undefined;
+    if (tree.parentRef !== undefined && predicate(tree.parentRef, tree._parentIndex)) {
+        return true;
+    }
+    for (let entry = tree.extraParents; entry !== undefined; entry = entry.next) {
+        if (predicate(entry.ref, entry.index)) { return true; }
+    }
+    return false;
 }
 
 /**
- * Return all parents as an array (debug/test helper).
+ * Wire index `tree` holds inside `parent`, or undefined when `parent` is
+ * nowhere in the chain. Allocation-free variant of `findParent` for the
+ * encodeView drain, which resolves identity-keyed view entries per emission.
+ *
+ * A child detached from `parent` this tick usually still resolves: Root.remove
+ * leaves the child's own parent link dangling, and the staged snapshot keeps
+ * the child in `tmpItems` (so reindexes keep the index current) until
+ * `$onEncodeEnd` — which runs after the drain.
  */
-export function getAllParents(tree: ChangeTree): Array<{ ref: Ref, index: number }> {
-    const parents: Array<{ ref: Ref, index: number }> = [];
+export function indexInParent(tree: ChangeTree, parent: Ref): number | undefined {
+    // `$changes` comparison — ArraySchema parents arrive proxied.
+    if (tree.parentRef && tree.parentRef[$changes] === parent[$changes]) {
+        return tree._parentIndex;
+    }
+    for (let entry = tree.extraParents; entry !== undefined; entry = entry.next) {
+        if (entry.ref[$changes] === parent[$changes]) {
+            return entry.index;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Return all parents as detached entries (debug/test helper).
+ */
+export function getAllParents(tree: ChangeTree): ParentEntry[] {
+    const parents: ParentEntry[] = [];
     if (tree.parentRef) {
         parents.push({ ref: tree.parentRef, index: tree._parentIndex });
     }
@@ -158,3 +188,30 @@ export function getAllParents(tree: ChangeTree): Array<{ ref: Ref, index: number
     }
     return parents;
 }
+
+/**
+ * True iff `parent` currently holds `tree`. Detached edges linger in the
+ * parent chain (load-bearing for same-tick view drains — see
+ * `indexInParent` above), so the chain alone cannot answer which edges
+ * are live. ArraySchema is probed by scanning `items`: the recorded slot
+ * can go stale after reorders, and `items` — unlike `$getByIndex`'s staged
+ * view — reflects the tick's completed mutations.
+ */
+export function isEdgeLive(tree: ChangeTree, parentTree: ChangeTree, index: number): boolean {
+    const target = parentTree.refTarget as any;
+    if (parentTree.isArray) {
+        // Read `items` directly, not `$getByIndex` — the latter serves the
+        // staged (tmpItems) view, which can still hold a same-tick removal.
+        const items = target.items;
+        const at = items[index];
+        if (at !== undefined && at[$changes] === tree) return true;
+        // Recorded slot goes stale after reorders — scan before declaring dead.
+        for (let i = 0, len = items.length; i < len; i++) {
+            const v = items[i];
+            if (v !== undefined && v[$changes] === tree) return true;
+        }
+        return false;
+    }
+    const at = parentTree.getValue(index);
+    return at !== undefined && at[$changes] === tree;
+}

package/src/encoder/streaming.ts

@@ -204,7 +204,8 @@ export function streamDequeueForView(
     viewId: number,
     refId: number,
     index: number,
-    viewChanges: Map<number, Map<number, number>>,
+    // widened key: StateView.changes carries identity-keyed array entries too
+    viewChanges: Map<number, Map<number | object, number>>,
 ): boolean {
     const st = s._stream;
     if (st === undefined) return false;

package/src/types/TypeContext.ts

@@ -8,16 +8,6 @@ export class TypeContext {
     schemas = new Map<typeof Schema, number>();
 
     hasFilters: boolean = false;
-    parentFiltered: {[typeIdAndParentIndex: string]: boolean} = {};
-    /**
-     * True iff `parentFiltered` has at least one entry. Flipped on by
-     * `registerFilteredByParent` and read in `checkInheritedFlags` as a
-     * cheap gate to skip the string-keyed `parentFiltered[key]` lookup
-     * when no class has registered filter inheritance via ancestry — the
-     * common case when @view tags exist only on sibling fields, not
-     * along any attachment chain.
-     */
-    hasParentFilteredEntries: boolean = false;
 
     /**
      * For inheritance support
@@ -84,17 +74,13 @@ export class TypeContext {
         return this.schemas.get(klass);
     }
 
-    private discoverTypes(klass: typeof Schema, parentType?: typeof Schema, parentIndex?: number, parentHasViewTag?: boolean) {
-        if (parentHasViewTag) {
-            this.registerFilteredByParent(klass, parentType, parentIndex);
-        }
-
+    private discoverTypes(klass: typeof Schema) {
         // skip if already registered
         if (!this.add(klass)) { return; }
 
         // add classes inherited from this base class
         TypeContext.inheritedTypes.get(klass)?.forEach((child) => {
-            this.discoverTypes(child, parentType, parentIndex, parentHasViewTag);
+            this.discoverTypes(child);
         });
 
         // add parent classes
@@ -120,7 +106,6 @@ export class TypeContext {
             const index = fieldIndex as any as number;
 
             const fieldType = metadata[index].type;
-            const fieldHasViewTag = (metadata[index].tag !== undefined);
 
             if (typeof (fieldType) === "string") {
                 continue;
@@ -133,7 +118,7 @@ export class TypeContext {
             }
 
             if (typeof (fieldType) === "function") {
-                this.discoverTypes(fieldType as typeof Schema, klass, index, parentHasViewTag || fieldHasViewTag);
+                this.discoverTypes(fieldType as typeof Schema);
 
             } else {
                 const type = Object.values(fieldType)[0];
@@ -143,47 +128,15 @@ export class TypeContext {
                     continue;
                 }
 
-                this.discoverTypes(type as typeof Schema, klass, index, parentHasViewTag || fieldHasViewTag);
+                this.discoverTypes(type as typeof Schema);
             }
         }
     }
 
-    /**
-     * Keep track of which classes have filters applied.
-     * Format: `${typeid}-${parentTypeid}-${parentIndex}`
-     */
-    private registerFilteredByParent(schema: typeof Schema, parentType?: typeof Schema, parentIndex?: number) {
-        const typeid = this.schemas.get(schema) ?? this.schemas.size;
-
-        let key = `${typeid}`;
-        if (parentType) { key += `-${this.schemas.get(parentType)}`; }
-
-        key += `-${parentIndex}`;
-        this.parentFiltered[key] = true;
-        this.hasParentFilteredEntries = true;
-    }
-
     debug() {
-        let parentFiltered = "";
-
-        for (const key in this.parentFiltered) {
-            const keys: number[] = key.split("-").map(Number);
-            const fieldIndex = keys.pop();
-
-            parentFiltered += `\n\t\t`;
-            parentFiltered += `${key}: ${keys.reverse().map((id, i) => {
-                const klass = this.types[id];
-                const metadata: Metadata = klass[Symbol.metadata];
-                let txt = klass.name;
-                if (i === 0) { txt += `[${metadata[fieldIndex].name}]`; }
-                return `${txt}`;
-            }).join(" -> ")}`;
-        }
-
         return `TypeContext ->\n` +
             `\tSchema types: ${this.schemas.size}\n` +
-            `\thasFilters: ${this.hasFilters}\n` +
-            `\tparentFiltered:${parentFiltered}`;
+            `\thasFilters: ${this.hasFilters}`;
     }
 
 }

package/src/types/builder.ts

@@ -307,16 +307,24 @@ function primitive<TBase>(name: RawPrimitiveType): PrimitiveFactory<TBase> {
     return (() => new FieldBuilder<TBase>(name)) as PrimitiveFactory<TBase>;
 }
 
-// Accepts a Schema class, a primitive string, or another FieldBuilder as a child type.
+// Collection element: a Schema class or a primitive type NAME (`"string"`).
 export type ChildType =
     | RawPrimitiveType
-    | Constructor<Schema>
-    | FieldBuilder<any>;
+    | Constructor<Schema>;
 
+/**
+ * Guard against `t.array(t.string())`. A builder child looks like it should
+ * work — and its bare `_type` would — but every modifier on it (`.view()`,
+ * `.default()`, quantize options) would be silently dropped, since modifiers
+ * describe the FIELD, not the elements. Fail loudly instead.
+ */
 function resolveChild(child: ChildType): DefinitionType {
     if (isBuilder(child)) {
-        // `_type` is private; element access bypasses the visibility check.
-        return child['_type'];
+        const inner = child['_type']; // private; element access bypasses the check
+        const hint = (typeof inner === "string")
+            ? `use the type name instead: t.array("${inner}")`
+            : `collections accept a Schema class or a primitive type name ("string", "number", …)`;
+        throw new Error(`t.array/map/set/collection(): a t.* builder is not a valid element type — ${hint}.`);
     }
     return child as DefinitionType;
 }
@@ -326,28 +334,24 @@ function resolveChild(child: ChildType): DefinitionType {
 // ---------------------------------------------------------------------------
 
 // Overloaded factories for collections. Implementation lives in a single function;
-// overloads narrow the return type for Schema/primitive/builder children.
+// overloads narrow the return type for Schema/primitive children.
 // All collection factories tag `HasDefault = true` because schema() auto-
 // instantiates an empty collection when no explicit default is given.
 interface ArrayFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>, true, false>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<ArraySchema<V>, true, false>;
 }
 interface MapFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>, true, false>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<MapSchema<V>, true, false>;
 }
 interface SetFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>, true, false>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<SetSchema<V>, true, false>;
 }
 interface CollectionFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>, true, false>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<CollectionSchema<V>, true, false>;
 }
 // t.stream(Entity) — priority-batched collection of Schema instances.
 // Element type is restricted to Schema subclasses (no primitives) because