@rvoh/dream 2.22.0 → 2.23.0

package/dist/cjs/src/errors/serializers/NoSerializersResolvedForKey.js

@@ -0,0 +1,30 @@
+/**
+ * Raised when resolving a serializer key against a class yields an empty set of serializers.
+ *
+ * This is an internal-invariant failure, not a misconfiguration: an unresolvable serializer key
+ * raises `MissingSerializersDefinitionForKey` (and a class with no `serializers` getter at all
+ * raises `MissingSerializersDefinition`) while it is being resolved, and STI expansion always
+ * yields at least one class, so there is no supported application shape that reaches this. It is
+ * typed rather than a bare `Error` so that it can be asserted on, and so that the two callers that
+ * guard the invariant raise the same thing.
+ */
+export default class NoSerializersResolvedForKey extends Error {
+    classDef;
+    serializerKey;
+    constructor(classDef, serializerKey) {
+        super();
+        this.classDef = classDef;
+        this.serializerKey = serializerKey;
+    }
+    get message() {
+        const className = this.classDef === null || this.classDef === undefined
+            ? String(this.classDef)
+            : (this.classDef.globalName ?? this.classDef.name);
+        return `
+No serializers resolved for \`${className}\` under serializer key \`${this.serializerKey}\`
+
+This should be impossible — a serializer key that cannot be resolved throws while it is being
+resolved, before reaching here — and indicates a bug in Dream rather than a problem with your
+application. Please report it.`;
+    }
+}

package/dist/cjs/src/serializer/helpers/inferSerializerFromDreamOrViewModel.js

@@ -3,6 +3,7 @@ import MissingSerializersDefinition from '../../errors/serializers/MissingSerial
 import MissingSerializersDefinitionForKey from '../../errors/serializers/MissingSerializersDefinitionForKey.js';
 import NoGlobalSerializerForSpecifiedKey from '../../errors/serializers/NoGlobalSerializerForSpecifiedKey.js';
 import NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey from '../../errors/serializers/NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey.js';
+import NoSerializersResolvedForKey from '../../errors/serializers/NoSerializersResolvedForKey.js';
 import compact from '../../helpers/compact.js';
 import expandStiClasses from '../../helpers/sti/expandStiClasses.js';
 import uniq from '../../helpers/uniq.js';
@@ -35,3 +36,24 @@ export function inferSerializersFromDreamClassOrViewModelClass(classDef, seriali
     const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey));
     return uniq(compact(serializers));
 }
+/**
+ * As `inferSerializersFromDreamClassOrViewModelClass`, but guarantees a non-empty result.
+ *
+ * The guard is unreachable today, and deliberately not phrased as "no serializer found for key": a
+ * serializer key that a class does not register throws `MissingSerializersDefinitionForKey` (and a
+ * class with no `serializers` getter at all throws `MissingSerializersDefinition`) from inside the
+ * inference above, and `expandStiClasses` always yields at least one class. It exists only so that
+ * a future change to any of those cannot turn an unresolvable serializer key into a silently empty
+ * serializer set — which, for the callers below, means a silently empty preload set and a
+ * `NonLoadedAssociation` at render rather than an error naming the real problem.
+ *
+ * Used by everything that walks a serializer graph rooted on a class rather than an instance —
+ * preload-path building and serialization display — so that they raise one typed error between
+ * them.
+ */
+export function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef, serializerKey) {
+    const serializers = inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey);
+    if (serializers.length === 0)
+        throw new NoSerializersResolvedForKey(classDef, serializerKey);
+    return serializers;
+}

package/dist/cjs/src/serializer/helpers/serializerForAssociatedClass.js

@@ -15,5 +15,18 @@ export function serializerForAssociatedClass(object, associationName, options) {
     const associatedClass = association.modelCB();
     if (Array.isArray(associatedClass))
         throw new Error('rendersOne flatten is incompatible with a polymorphic belongs-to association');
+    // Taking the first is only a narrowing when `associatedClass` is an STI base, where
+    // inferSerializersFromDreamClassOrViewModelClass returns one serializer per child sorted by
+    // sanitizedName. It is correct here because there is no associated row: this function is reached
+    // only from SerializerRenderer's `flatten: true` branch for a *null* associated object, so no
+    // child of the base is the right one — the row that would have decided is absent. (rendersMany
+    // never reaches here and does not accept `flatten`.)
+    //
+    // It is observable, though, so it is not "nothing happens": the picked serializer is invoked and
+    // its output spread into the parent's payload, so the parent JSON carries the
+    // alphabetically-first child's flattened keys as nulls, and omits keys only a later-sorting child
+    // would flatten. Unioning every child's serializer here — which is what buildSerializerPreloadPaths
+    // does for preload paths — is meaningless: exactly one set of keys can be flattened into the
+    // payload.
     return inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey)[0] ?? null;
 }

package/dist/esm/src/Dream.js

@@ -19,9 +19,9 @@ import destroyDream from './dream/internal/destroyDream.js';
 import { destroyOptions, reallyDestroyOptions, undestroyOptions, } from './dream/internal/destroyOptions.js';
 import ensureSTITypeFieldIsSet from './dream/internal/ensureSTITypeFieldIsSet.js';
 import findOrCreateBy from './dream/internal/findOrCreateBy.js';
+import mergeSerializerAssociationEdges from './dream/internal/mergeSerializerAssociationEdges.js';
 import printSerializerHierarchyLevel from './dream/internal/printSerializerHierarchyLevel.js';
 import reload from './dream/internal/reload.js';
-import resolveSerializerAssociationEdges from './dream/internal/resolveSerializerAssociationEdges.js';
 import runValidations from './dream/internal/runValidations.js';
 import saveDream from './dream/internal/saveDream.js';
 import { DEFAULT_BYPASS_ALL_DEFAULT_SCOPES, DEFAULT_DEFAULT_SCOPES_TO_BYPASS, DEFAULT_SKIP_HOOKS, } from './dream/internal/scopeHelpers.js';
@@ -48,7 +48,7 @@ import areEqual from './helpers/areEqual.js';
 import cloneDeepSafe from './helpers/cloneDeepSafe.js';
 import isJsonColumn from './helpers/db/types/isJsonColumn.js';
 import notEqual from './helpers/notEqual.js';
-import { inferSerializersFromDreamClassOrViewModelClass } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import { inferSerializersFromDreamClassOrViewModelClassOrFail } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
 export default class Dream {
     DB;
     /**
@@ -542,44 +542,89 @@ export default class Dream {
     }
     static serializationMap(serializerKey) {
         const key = serializerKey || 'default';
-        const serializer = inferSerializersFromDreamClassOrViewModelClass(this, key)[0] ?? null;
-        if (!serializer)
-            throw new Error(`unable to find serializer with key: ${key}`);
-        return this.recursiveSerializationMap(serializer);
+        // Deliberately one serializer: this maps a single serializer's view of the class, and taking
+        // the first is only a narrowing when `this` is an STI base (where
+        // inferSerializersFromDreamClassOrViewModelClass returns one serializer per child, sorted by
+        // sanitizedName). That narrowing is deliberate and differs from `buildSerializerPreloadPaths`
+        // and `displaySerialization` below, both of which union every child's serializer because they
+        // answer "what does a query load / display for this class", not "what does one serializer
+        // render". Nothing in src/ calls
+        // this method; it exists as the single-serializer entry point onto recursiveSerializationMap and
+        // is exercised by spec/unit/dream/serializationMap.spec.ts, which pins the narrowing on an STI
+        // base so that the divergence from displaySerialization is executable rather than only
+        // described here. A caller that wants the union for an STI base wants displaySerialization's
+        // shape, not this one.
+        //
+        // Note that the narrowing is to one serializer of *this* class only: every association this
+        // serializer renders is still walked with the full set of serializers its target resolves to,
+        // so an STI base reached as a target below is unioned.
+        const serializer = inferSerializersFromDreamClassOrViewModelClassOrFail(this, key)[0];
+        return this.recursiveSerializationMap([serializer]);
     }
     static displaySerialization(serializerKey) {
         const key = serializerKey || 'default';
-        const serializer = inferSerializersFromDreamClassOrViewModelClass(this, key)[0] ?? null;
-        if (!serializer)
-            throw new Error(`unable to find serializer with key: ${key}`);
+        /**
+         * When `this` is an STI base, this is one serializer per STI child (deduped), since each child
+         * may register a different serializer under `key`. Every one is walked, because this method
+         * backs `psy i:serialization`, whose purpose is verifying what gets preloaded — and
+         * `preloadFor` unions the preload paths of every child's serializer. Walking only one child's
+         * serializer would print a strict subset of what the query actually loads.
+         */
+        // ...OrFail, rather than the plain inference, so that an empty serializer set raises
+        // NoSerializersResolvedForKey instead of silently printing a class name with nothing under it.
+        // That guard is unreachable today and is documented where it lives; it is shared with
+        // buildSerializerPreloadPaths so that the display and the preload walk raise the same thing.
+        const serializers = inferSerializersFromDreamClassOrViewModelClassOrFail(this, key);
         // eslint-disable-next-line no-console
         console.log(yoctocolors.cyan(this.sanitizedName));
-        // eslint-disable-next-line no-console
-        console.log(yoctocolors.gray(serializer.globalName));
-        return this.recursiveSerializationMap(serializer, {
+        // One line per serializer: for an STI base the displayed tree is the union across its children,
+        // so naming a single child's serializer under the base's own name would misattribute the tree.
+        serializers.forEach(serializer => {
+            // eslint-disable-next-line no-console
+            console.log(yoctocolors.gray(serializer.globalName));
+        });
+        return this.recursiveSerializationMap(serializers, {
             forDisplay: true,
         });
     }
-    static recursiveSerializationMap(serializer, { forDisplay = false, forDisplayDepth = 0, repeatedAssociationTracker = {}, } = {}) {
+    /**
+     * @internal
+     *
+     * Maps the association tree reachable from `serializers` — every serializer that can render this
+     * class at this point in the walk, which is more than one when this class is an STI base. The
+     * serializers are merged into one edge set (see mergeSerializerAssociationEdges) rather than
+     * walked one at a time, so an association several of them render is visited once and the nested
+     * trees of a shared target merge instead of clobbering each other.
+     */
+    static recursiveSerializationMap(serializers, { forDisplay = false, forDisplayDepth = 0, repeatedAssociationTracker = {}, } = {}) {
         const depthTrackerId = this.globalName;
         repeatedAssociationTracker[depthTrackerId] ??= 0;
         if (repeatedAssociationTracker[depthTrackerId] + 1 > RECURSIVE_SERIALIZATION_MAX_REPEATS)
             return {};
         repeatedAssociationTracker[depthTrackerId]++;
-        const edges = resolveSerializerAssociationEdges(this, serializer);
+        const edges = mergeSerializerAssociationEdges(this, serializers);
         const mappedAssociations = edges.reduce((accumulator, edge) => {
+            // An edge with no targets terminates: either a delegatedAttribute (never printed, and
+            // carrying `targets: []` by construction) or an association resolving to no serializer. Its
+            // nestedSerializerInfo is `{}` because this reduce never runs.
             const innerAssociationSerializerInfo = edge.targets.reduce((innerAccumulator, target) => {
-                if (forDisplay && edge.type !== 'delegatedAttribute') {
-                    printSerializerHierarchyLevel({
-                        serializerAssociationType: edge.type,
-                        serializerAssociationName: edge.serializerAssociationName,
-                        associationSerializer: target.serializer,
-                        forDisplayDepth,
-                    });
+                if (forDisplay) {
+                    // One heading per (association, target class), naming every serializer that renders that
+                    // target underneath it, and then — below all of them — the union of their association
+                    // trees, which is what `preloadFor` loads through this association.
+                    //
+                    // The recursion below is a single merged walk of every serializer of the target, so
+                    // there is one tree, not one per child. Grouping the serializer names under a single
+                    // heading is what keeps that honest — repeating the heading per serializer would leave
+                    // the merged tree indented directly beneath the last one's name and attribute every
+                    // sibling's associations to it.
+                    printSerializerHierarchyLevel({ targetSerializers: target.serializers, forDisplayDepth });
                 }
                 return {
                     ...innerAccumulator,
-                    ...target.dreamClass['recursiveSerializationMap'](target.serializer, {
+                    // recursed once per target class with *all* of that class's serializers, so their nested
+                    // trees merge rather than the last one winning a shallow spread
+                    ...target.dreamClass['recursiveSerializationMap'](target.serializers.map(({ serializer }) => serializer), {
                         forDisplay,
                         forDisplayDepth: forDisplayDepth + 1,
                         repeatedAssociationTracker,
@@ -588,7 +633,7 @@ export default class Dream {
             }, {});
             accumulator[edge.associationAs] = {
                 parentDreamClass: this,
-                nestedSerializerInfo: edge.type === 'delegatedAttribute' ? {} : innerAssociationSerializerInfo,
+                nestedSerializerInfo: innerAssociationSerializerInfo,
             };
             return accumulator;
         }, {});

package/dist/esm/src/dream/Query.js

@@ -22,8 +22,26 @@ import ops from '../ops/index.js';
 import buildSerializerPreloadPaths from './internal/buildSerializerPreloadPaths.js';
 import computedPaginatePage from './internal/computedPaginatePage.js';
 import convertDreamClassAndAssociationNameTupleArrayToPreloadArgs from './internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js';
-// Cache for serializer preload-path results, keyed by "${globalName}:${serializerKey}"
-const extractedNestedPathsCache = new Map();
+/**
+ * Cache for serializer preload-path results, keyed on the root class itself and then the serializer
+ * key. Keying on the class rather than its global name is what makes the cache self-invalidating:
+ * loading a fresh set of model classes into the process yields new class objects, so entries
+ * resolved against the previous ones become unreachable and collectable rather than being served
+ * under a name that now means something else.
+ */
+let extractedNestedPathsCache = new WeakMap();
+/**
+ * @internal
+ *
+ * Drops every memoized preload path. Only needed when a class object that stays in the process has
+ * its `serializers` getter replaced, which the cache cannot detect — specs that install or remove
+ * one around an example. Replacing the model classes themselves needs no call, since the cache
+ * keys on the class object. See `clearResolvedSerializerAssociationEdgesCache`, which has the same
+ * contract and is cleared alongside it.
+ */
+export function clearSerializerPreloadPathsCache() {
+    extractedNestedPathsCache = new WeakMap();
+}
 export default class Query {
     /**
      * @internal
@@ -560,17 +578,30 @@ export default class Query {
      * @returns A Query with all serialization associations preloaded
      */
     preloadFor(serializerKey, modifierFn) {
-        const cacheKey = `${this.dreamClass.globalName}:${serializerKey ?? 'default'}`;
-        let preloadArgs = extractedNestedPathsCache.get(cacheKey);
+        const cacheKey = serializerKey ?? 'default';
+        let pathsBySerializerKey = extractedNestedPathsCache.get(this.dreamClass);
+        if (!pathsBySerializerKey) {
+            pathsBySerializerKey = new Map();
+            extractedNestedPathsCache.set(this.dreamClass, pathsBySerializerKey);
+        }
+        let preloadArgs = pathsBySerializerKey.get(cacheKey);
         if (!preloadArgs) {
             preloadArgs = buildSerializerPreloadPaths(this.dreamClass, serializerKey);
-            extractedNestedPathsCache.set(cacheKey, preloadArgs);
+            pathsBySerializerKey.set(cacheKey, preloadArgs);
         }
-        let query = this;
+        // Rather than calling `preload` once per path (which deep clones the accumulating preload tree
+        // on every call, making this quadratic in the number of paths), clone once, flesh out every
+        // path against the same accumulators, and clone the Query once at the end. Iteration order is
+        // preserved, so a later path's `and` still wins over an earlier path's for a shared prefix.
+        const preloadStatements = cloneDeepSafe(this.preloadStatements);
+        const preloadOnStatements = cloneDeepSafe(this.preloadOnStatements);
         preloadArgs.forEach(dreamClassAndAssociationNameTupleArray => {
-            query = query.preload(...convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn));
+            const args = convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn);
+            // `modifierFn` returning 'omit' prunes the path from the omitted association down, which can
+            // leave nothing to preload; `fleshOutJoinStatements` treats an empty arg list as a no-op.
+            this.fleshOutJoinStatements([], preloadStatements, preloadOnStatements, null, args);
         });
-        return query;
+        return this.clone({ preloadStatements, preloadOnStatements });
     }
     /**
      * Returns a new Query instance, with the provided

package/dist/esm/src/dream/internal/buildSerializerPreloadPaths.js

@@ -1,18 +1,39 @@
-import { inferSerializersFromDreamClassOrViewModelClass } from '../../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import { inferSerializersFromDreamClassOrViewModelClassOrFail } from '../../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
 import { RECURSIVE_SERIALIZATION_MAX_REPEATS } from '../constants.js';
 import buildAssociationPaths from './buildAssociationPaths.js';
-import resolveSerializerAssociationEdges from './resolveSerializerAssociationEdges.js';
+import mergeSerializerAssociationEdges from './mergeSerializerAssociationEdges.js';
 export default function buildSerializerPreloadPaths(dreamClass, serializerKey) {
     const key = serializerKey || 'default';
-    const serializer = inferSerializersFromDreamClassOrViewModelClass(dreamClass, key)[0] ?? null;
-    if (!serializer)
-        throw new Error(`unable to find serializer with key: ${key}`);
-    const paths = buildAssociationPaths({
-        dreamClass,
-        serializer,
-    }, {
+    /**
+     * When `dreamClass` is an STI base, this returns one serializer per STI child (deduped), since
+     * each child may register a different serializer under `key`. Every child's serializer has to be
+     * walked: an association rendered only by, say, the alphabetically-last child would otherwise be
+     * missing from the preload set and throw NonLoadedAssociation at render time.
+     */
+    const serializers = inferSerializersFromDreamClassOrViewModelClassOrFail(dreamClass, key);
+    /**
+     * All of the serializers are walked in a *single* traversal, as one node per Dream class carrying
+     * the set of serializers that reach it, rather than one traversal per serializer. A path is a
+     * sequence of [DreamClass, associationName] tuples — it records no serializer — so walking each
+     * serializer separately recomputes the same paths once per route through the graph, which is
+     * exponential in the number of sibling serializers when a serializer cycles back to the STI base.
+     * Merging is exactly equivalent: an edge is emitted from the merged node when *some* serializer in
+     * the set declares it, and every serializer in the set is reachable by a real route with this
+     * path's prefix, so the merged walk emits precisely the paths the per-serializer walks emit after
+     * deduping — with one exception: where one serializer of a class renders no associations and
+     * another renders some, the per-serializer walk also emitted the bare prefix path reached by the
+     * first, which is a strict prefix of a path the second contributes and so preloads nothing extra.
+     * The recursion budget is keyed on the Dream class and counted along the current path, so it is
+     * unaffected by the merge.
+     *
+     * Every tuple emitted at the root of the traversal carries `dreamClass` (the STI base) rather than
+     * the contributing child, both so that identical paths dedupe below and so that a caller's
+     * `modifierFn` keeps receiving the class it was queried on. Tuples emitted deeper in a path carry
+     * the association's target class, which is what `modifierFn` receives for a nested association.
+     */
+    const paths = buildAssociationPaths({ dreamClass, serializers }, {
         getKey: node => node.dreamClass.globalName,
-        getEdges: serializerNodeToEdges,
+        getEdges: memoizedSerializerNodeToEdges(),
         maxRepeats: RECURSIVE_SERIALIZATION_MAX_REPEATS,
     });
     const dedupedPaths = new Map();
@@ -23,16 +44,68 @@ export default function buildSerializerPreloadPaths(dreamClass, serializerKey) {
     }
     return [...dedupedPaths.values()];
 }
-function serializerNodeToEdges({ dreamClass, serializer, }) {
-    const edges = resolveSerializerAssociationEdges(dreamClass, serializer);
-    return edges.flatMap(edge => {
-        const tuple = [dreamClass, edge.associationAs];
-        if (edge.type === 'delegatedAttribute' || edge.targets.length === 0) {
-            return [{ nextNode: null, tuple }];
+/**
+ * `serializerNodeToEdges` is a pure function of the node's (Dream class, ordered serializer set), so
+ * two nodes carrying the same pair have the same edges no matter which route reached them. The
+ * traversal hands `getEdges` a *fresh* node object per edge it descends — the `nextNode`s built
+ * below are new objects every time — so memoizing on the object itself would never hit; the key has
+ * to be the node's contents. Without this the whole merge (resolve every serializer's edges, then
+ * one Map per association and one node object per target class) is rebuilt at every visit, and the
+ * visit count is the number of *routes* through the serializer graph rather than the number of
+ * distinct nodes in it: an STI base whose children render `n` differently-named self-referential
+ * associations visits 1 + n + n² + n³ nodes to reach n⁴ paths, all of them the same one node.
+ *
+ * The serializer identifiers are assigned per call rather than globally so that the key stays short
+ * and so that nothing here holds a serializer alive; identity is all that matters, since the key is
+ * only ever compared against others built in the same call. Order-sensitive on purpose: the merge
+ * is insertion-ordered, so two nodes carrying the same serializers in a different order do not have
+ * the same edges.
+ *
+ * Scoped to a single `buildSerializerPreloadPaths` call for the same reason: it cannot then serve
+ * edges resolved against a stale serializer registry or a not-yet-complete set of STI children.
+ */
+function memoizedSerializerNodeToEdges() {
+    const cache = new Map();
+    const serializerIds = new Map();
+    const serializerId = (serializer) => {
+        let id = serializerIds.get(serializer);
+        if (id === undefined) {
+            id = serializerIds.size;
+            serializerIds.set(serializer, id);
         }
-        return edge.targets.map(target => ({
-            nextNode: target,
-            tuple,
-        }));
+        return id;
+    };
+    return node => {
+        const cacheKey = `${node.dreamClass.globalName}|${node.serializers.map(serializerId).join(',')}`;
+        const cached = cache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const edges = serializerNodeToEdges(node);
+        cache.set(cacheKey, edges);
+        return edges;
+    };
+}
+/**
+ * `mergeSerializerAssociationEdges` — the single union both serializer walks run on, the other being
+ * `Dream.recursiveSerializationMap`'s display walk — has already resolved every serializer in the
+ * node's set and merged them into one insertion-ordered edge set keyed on (association, target
+ * class). All that is left here is to shed what only the display walk needs (the per-serializer edge
+ * type and serializer-side association name) and turn each merged edge into path edges: a leaf where
+ * some serializer terminates the association, plus one traversal node per target class carrying that
+ * class's serializers.
+ */
+function serializerNodeToEdges({ dreamClass, serializers, }) {
+    return mergeSerializerAssociationEdges(dreamClass, serializers).flatMap(edge => {
+        const tuple = [dreamClass, edge.associationAs];
+        return [
+            ...(edge.terminates ? [{ nextNode: null, tuple }] : []),
+            ...edge.targets.map(target => ({
+                nextNode: {
+                    dreamClass: target.dreamClass,
+                    serializers: target.serializers.map(({ serializer }) => serializer),
+                },
+                tuple,
+            })),
+        ];
     });
 }

package/dist/esm/src/dream/internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js

@@ -1,15 +1,23 @@
-import compact from '../../helpers/compact.js';
 export default function convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn, counter) {
-    return compact(dreamClassAndAssociationNameTupleArray.flatMap(dreamClassAndAssociationNameTuple => {
+    const preloadArgs = [];
+    for (const dreamClassAndAssociationNameTuple of dreamClassAndAssociationNameTupleArray) {
         const associationName = dreamClassAndAssociationNameTuple[1];
-        const aliasedAssociationName = counter
-            ? `${dreamClassAndAssociationNameTuple[1]} as drsz${counter.count++}`
-            : dreamClassAndAssociationNameTuple[1];
-        if (!modifierFn)
-            return aliasedAssociationName;
+        const aliasedAssociationName = counter ? `${associationName} as drsz${counter.count++}` : associationName;
+        if (!modifierFn) {
+            preloadArgs.push(aliasedAssociationName);
+            continue;
+        }
         const modifier = modifierFn(associationName, dreamClassAndAssociationNameTuple[0]);
+        // omitting an association prunes the entire subtree beneath it: the path is truncated at the
+        // omitted association, keeping the ancestors already accumulated (so the omitted association's
+        // parent is still preloaded) and discarding the remainder, since the surviving tail would be
+        // re-rooted on the class the query was rooted on and preload a different association than the
+        // caller asked for. When the omitted association is the first tuple, this yields an empty list.
         if (modifier === 'omit')
-            return undefined;
-        return [aliasedAssociationName, modifier];
-    }));
+            return preloadArgs;
+        preloadArgs.push(aliasedAssociationName);
+        if (modifier !== undefined && modifier !== null)
+            preloadArgs.push(modifier);
+    }
+    return preloadArgs;
 }

package/dist/esm/src/dream/internal/mergeSerializerAssociationEdges.js

@@ -0,0 +1,75 @@
+import resolveSerializerAssociationEdges from './resolveSerializerAssociationEdges.js';
+/**
+ * @internal
+ *
+ * Resolves the association edges of *every* serializer that can render `dreamClass` at this point
+ * in a serialization walk and merges them into one set, so that a walk rooted at an STI base sees
+ * the union across its children's serializers rather than one child's view of the class.
+ *
+ * The merge is keyed on (association, target class), so:
+ *
+ * - an association several children render identically (all three `stiUnion` serializers render
+ *   `sandbags`) collapses to a single edge with a single target, rather than repeating per child;
+ * - a polymorphic association keeps one target per target class
+ *   (`Polymorphic/Task#taskable` → `Chore` and `Workout`), which is a real distinction, not a
+ *   duplicate;
+ * - an association only some children render (`heartRatings`, rendered only by Latex's `stiUnion`
+ *   serializer) is present exactly once.
+ *
+ * Grouping the serializers *under* the target rather than emitting one target per serializer is
+ * what lets a caller recurse once per target class with the full set, so nested trees from
+ * different children of the same target merge instead of clobbering one another.
+ *
+ * Insertion-ordered throughout, so edges come back in the order the serializers declare them.
+ *
+ * This is the single union both serializer walks run on: `buildSerializerPreloadPaths` turns these
+ * edges into preload paths (taking `terminates` and the target classes, ignoring the per-serializer
+ * edge type and serializer-side name), and `Dream.recursiveSerializationMap` prints them (taking the
+ * per-serializer edge type and name, ignoring `terminates`). Keeping the two walks on one merge is the point: the bug
+ * this exists to prevent is `psy i:serialization` and `preloadFor` disagreeing about which
+ * associations a serializer key reaches, which a second hand-maintained merge invites back.
+ */
+export default function mergeSerializerAssociationEdges(dreamClass, serializers) {
+    /**
+     * Each target carries a Set mirroring its `serializers`, so the identity dedupe below is a lookup
+     * rather than a scan of the array. Dropped when the merged edges are built at the end.
+     */
+    const mergedEdges = new Map();
+    for (const serializer of serializers) {
+        for (const edge of resolveSerializerAssociationEdges(dreamClass, serializer)) {
+            let mergedEdge = mergedEdges.get(edge.associationAs);
+            if (mergedEdge === undefined) {
+                mergedEdge = { terminates: false, targets: new Map() };
+                mergedEdges.set(edge.associationAs, mergedEdge);
+            }
+            if (edge.targets.length === 0) {
+                mergedEdge.terminates = true;
+                continue;
+            }
+            for (const target of edge.targets) {
+                const targetKey = target.dreamClass.globalName;
+                const mergedTarget = mergedEdge.targets.get(targetKey);
+                const targetSerializer = {
+                    serializer: target.serializer,
+                    type: edge.type,
+                    serializerAssociationName: edge.serializerAssociationName,
+                };
+                if (mergedTarget === undefined) {
+                    mergedEdge.targets.set(targetKey, {
+                        target: { dreamClass: target.dreamClass, serializers: [targetSerializer] },
+                        serializerSet: new Set([target.serializer]),
+                    });
+                }
+                else if (!mergedTarget.serializerSet.has(target.serializer)) {
+                    mergedTarget.serializerSet.add(target.serializer);
+                    mergedTarget.target.serializers.push(targetSerializer);
+                }
+            }
+        }
+    }
+    return [...mergedEdges.entries()].map(([associationAs, { terminates, targets }]) => ({
+        associationAs,
+        terminates,
+        targets: [...targets.values()].map(({ target }) => target),
+    }));
+}

package/dist/esm/src/dream/internal/printSerializerHierarchyLevel.js

@@ -1,16 +1,58 @@
 import yoctocolors from 'yoctocolors';
 import { indent } from '../../helpers/indent.js';
-export default function printSerializerHierarchyLevel({ serializerAssociationType, serializerAssociationName, associationSerializer, forDisplayDepth, }) {
+/**
+ * @internal
+ *
+ * Prints one level of `psy i:serialization`'s tree: the heading for an association, then the name
+ * of every serializer that renders the target of that association at this point in the walk. That
+ * is more than one serializer when the target is an STI base, since each child may register a
+ * different serializer under the same key.
+ *
+ * Those serializers are printed under a *single* heading rather than one heading each, because the
+ * caller prints the union of their association trees below, indented one level in from the
+ * heading. Repeating the heading per serializer would leave that union sitting directly beneath
+ * whichever child's serializer happened to print last, reading as though every sibling's
+ * associations belonged to that one child. Grouped, the shape matches what `displaySerialization`
+ * prints at the root of the tree — one name, then every serializer that can render it, then one
+ * merged tree.
+ *
+ * A target reached under more than one edge type or serializer-side name (two children of an STI
+ * base rendering the same class through `rendersOne` and `rendersMany`, say) gets one heading per
+ * distinct (type, name), since those are genuinely different lines rather than repetitions of one.
+ */
+export default function printSerializerHierarchyLevel({ targetSerializers, forDisplayDepth, }) {
     const hierarchyLine = '└───';
     const indentation = indent((hierarchyLine.length + 1) * forDisplayDepth, {
         tabWidth: 1,
     });
     const prefix = `${hierarchyLine} `;
-    const nestedAssociationDisplay = indentation + `${prefix}${serializerAssociationType} ${yoctocolors.cyan(serializerAssociationName)}`;
-    // eslint-disable-next-line no-console
-    console.log(nestedAssociationDisplay);
-    // eslint-disable-next-line no-console
-    console.log(yoctocolors.gray(indentation +
-        indent(prefix.length, { tabWidth: 1 }) +
-        associationSerializer.globalName));
+    groupByHeading(targetSerializers).forEach(({ type, serializerAssociationName, serializers }) => {
+        // eslint-disable-next-line no-console
+        console.log(indentation + `${prefix}${type} ${yoctocolors.cyan(serializerAssociationName)}`);
+        serializers.forEach(serializer => {
+            // eslint-disable-next-line no-console
+            console.log(yoctocolors.gray(indentation +
+                indent(prefix.length, { tabWidth: 1 }) +
+                serializer.globalName));
+        });
+    });
+}
+/**
+ * Collects the serializers rendering a single merged target into one entry per heading they print
+ * under — (edge type, serializer-side association name) — preserving the order the serializers
+ * were merged in.
+ */
+function groupByHeading(targetSerializers) {
+    const headings = new Map();
+    for (const { serializer, type, serializerAssociationName } of targetSerializers) {
+        const headingKey = `${type}:${serializerAssociationName}`;
+        const heading = headings.get(headingKey);
+        if (heading === undefined) {
+            headings.set(headingKey, { type, serializerAssociationName, serializers: [serializer] });
+        }
+        else {
+            heading.serializers.push(serializer);
+        }
+    }
+    return [...headings.values()];
 }