@rvoh/dream 2.25.0 → 2.26.0

package/dist/esm/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -1,5 +1,6 @@
 import { sql } from 'kysely';
 import InternalEncrypt from '../../encrypt/InternalEncrypt.js';
+import DropEnumValueRetypeFailed, { quotedRelationName, } from '../../errors/DropEnumValueRetypeFailed.js';
 export default class DreamMigrationHelpers {
     /**
      * Rename a table and its associated primary key index and sequence.
@@ -169,14 +170,29 @@ export default class DreamMigrationHelpers {
      * @param __namedParameters.replacements - Details about which table and column to change and which value to replace the dropped value with (or remove it if the column is an array)
      */
     static async dropEnumValue(db, { enumName, value, replacements }) {
+        // Read the check constraints on every replacement column up front, before anything is
+        // retyped. They are only ever *used* from the catch blocks below, but they cannot be read
+        // from there: dropEnumValue runs inside a migration transaction (runMigration.ts routes any
+        // migration mentioning it through `newTransaction`), and once a statement in a transaction
+        // block errors, Postgres aborts the block and fails every subsequent statement with
+        // `25P02 current transaction is aborted`. A pg_constraint SELECT issued from a catch block
+        // would therefore throw itself and bury the very error we are trying to explain.
+        const checkConstraintsByPosition = await checkConstraintsOnColumns(db, replacements);
         // temporarily set all table columns depending on this enum to an acceptable alternate type
-        for (const tableAndColumnToChange of replacements) {
+        for (const [position, tableAndColumnToChange] of replacements.entries()) {
             const tableAndColumnToChangeAsArray = tableAndColumnToChange;
             const isArray = tableAndColumnToChangeAsArray.array || false;
-            await db.schema
+            await retypeOrExplain(() => db.schema
                 .alterTable(tableAndColumnToChange.table)
                 .alterColumn(tableAndColumnToChange.column, col => col.setDataType(computedTemporaryType(isArray)))
-                .execute();
+                .execute(), {
+                enumName,
+                value,
+                table: tableAndColumnToChange.table,
+                column: tableAndColumnToChange.column,
+                retypeDirection: 'toText',
+                ...constraintContextFor(checkConstraintsByPosition, position),
+            });
         }
         // collect enum values before dropping type
         const allEnumValues = await getEnumValues(db, enumName);
@@ -187,15 +203,23 @@ export default class DreamMigrationHelpers {
             .createType(enumName)
             .asEnum(allEnumValues.filter(val => val !== value))
             .execute();
-        for (const tableAndColumnToChange of replacements) {
+        for (const [position, tableAndColumnToChange] of replacements.entries()) {
             const isArray = tableAndColumnToChange.array || false;
+            const retypeContext = {
+                enumName,
+                value,
+                table: tableAndColumnToChange.table,
+                column: tableAndColumnToChange.column,
+                retypeDirection: 'toEnum',
+                ...constraintContextFor(checkConstraintsByPosition, position),
+            };
             if (isArray) {
                 await replaceArrayValues(db, value, tableAndColumnToChange);
-                await updateTableColumnToNewEnumArrayType(db, enumName, tableAndColumnToChange);
+                await retypeOrExplain(() => updateTableColumnToNewEnumArrayType(db, enumName, tableAndColumnToChange), retypeContext);
             }
             else {
                 await replaceNonArrayValues(db, value, tableAndColumnToChange);
-                await updateTableColumnToNewEnumType(db, enumName, tableAndColumnToChange);
+                await retypeOrExplain(() => updateTableColumnToNewEnumType(db, enumName, tableAndColumnToChange), retypeContext);
             }
         }
     }
@@ -330,6 +354,103 @@ export default class DreamMigrationHelpers {
         }
     }
 }
+/**
+ * Run one of dropEnumValue's internal column retypes, and on failure re-raise it as a
+ * {@link DropEnumValueRetypeFailed} naming the table, the column and the check constraints
+ * that were read before any retype ran. The original error is kept reachable underneath.
+ *
+ * A caught throwable is normalized to an `Error` rather than cast to one: the error's
+ * message getter dereferences `originalError.message`, so a driver (or a mock) that rejects
+ * with a non-Error would otherwise blow up inside the getter and destroy the very
+ * diagnostic this wrapping exists to produce.
+ */
+async function retypeOrExplain(retype, context) {
+    try {
+        await retype();
+    }
+    catch (error) {
+        throw new DropEnumValueRetypeFailed({
+            ...context,
+            originalError: error instanceof Error ? error : new Error(String(error)),
+        });
+    }
+}
+/**
+ * The check constraints defined on each replacement's column, indexed by the replacement's
+ * position in `replacements` (both of dropEnumValue's loops walk the same array in order, so
+ * the position identifies a replacement exactly and no key string has to be kept in sync).
+ *
+ * Position, rather than the replacement object, because the same object may legitimately
+ * appear at two positions — `const r = {...}; replacements: [r, r]` — and a Map keyed on the
+ * object would collapse those two entries onto one, reporting each column's constraints twice
+ * and emitting a duplicated dropConstraint line for every one of them.
+ *
+ * One catalog query covers every replacement: the (relation, column) pairs are passed as two
+ * arrays and unnested `WITH ORDINALITY`, so each row carries the 1-based position of the
+ * replacement it belongs to. Issuing one query per replacement would cost a round trip per
+ * column on every successful `dropEnumValue`, and Kysely serializes them all on the
+ * migration's single connection.
+ *
+ * `relationResolved` is selected separately from the constraints, because "the table has no
+ * check constraints" and "the table name did not resolve" both produce zero constraint rows
+ * and the error message must not confuse the two.
+ *
+ * `to_regclass` rather than a `::regclass` cast so that an unknown table yields no rows
+ * instead of throwing, leaving the retype itself to report a missing table exactly as it
+ * does today. The name handed to it is quoted per segment, because Kysely quotes the
+ * identifiers it emits (`alterTable('MixedCase')` -> `"MixedCase"`) while an unquoted
+ * `to_regclass` argument case-folds and would silently miss every non-lowercase table.
+ *
+ * The selected aliases are deliberately single words: a `CamelCasePlugin` on the connection
+ * rewrites result keys, and `ord`/`resolved`/`name`/`definition` survive that rewrite
+ * unchanged.
+ */
+async function checkConstraintsOnColumns(db, replacements) {
+    const byPosition = replacements.map(() => ({
+        relationResolved: false,
+        checkConstraints: [],
+    }));
+    if (replacements.length === 0)
+        return byPosition;
+    const relationNames = replacements.map(replacement => quotedRelationName(replacement.table));
+    const columnNames = replacements.map(replacement => replacement.column);
+    const response = await sql `
+    SELECT
+      t.ord::int AS ord,
+      (to_regclass(t.relname) IS NOT NULL) AS resolved,
+      con.name AS name,
+      con.definition AS definition
+    FROM unnest(${relationNames}::text[], ${columnNames}::text[])
+      WITH ORDINALITY AS t(relname, colname, ord)
+    LEFT JOIN LATERAL (
+      SELECT c.conname AS name, pg_get_constraintdef(c.oid) AS definition
+      FROM pg_constraint c
+      JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+      WHERE c.contype = 'c'
+        AND c.conrelid = to_regclass(t.relname)
+        AND a.attname = t.colname
+    ) con ON true
+    ORDER BY t.ord, con.name
+  `.execute(db);
+    for (const row of response.rows) {
+        const entry = byPosition[Number(row.ord) - 1];
+        if (entry === undefined)
+            continue;
+        entry.relationResolved = row.resolved;
+        if (row.name !== null && row.definition !== null) {
+            entry.checkConstraints.push({ name: row.name, definition: row.definition });
+        }
+    }
+    return byPosition;
+}
+/**
+ * The constraint metadata for the replacement at `position`. A position with no entry (which
+ * cannot happen today, but would be a silent lie if it did) reads as "not read", never as
+ * "none defined".
+ */
+function constraintContextFor(byPosition, position) {
+    return byPosition[position] ?? { relationResolved: false, checkConstraints: [] };
+}
 async function getEnumValues(db, enumName) {
     const response = await sql `SELECT unnest(enum_range(NULL::${sql.raw(enumName)}))`.execute(db);
     return response.rows.map(row => row.unnest);

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

@@ -1,5 +1,6 @@
 import yoctocolors from 'yoctocolors';
 import { indent } from '../../helpers/indent.js';
+import serializerGlobalName from '../../serializer/helpers/serializerGlobalName.js';
 /**
  * @internal
  *
@@ -30,10 +31,10 @@ export default function printSerializerHierarchyLevel({ targetSerializers, forDi
         // eslint-disable-next-line no-console
         console.log(indentation + `${prefix}${type} ${yoctocolors.cyan(serializerAssociationName)}`);
         serializers.forEach(serializer => {
+            // Interpolated rather than defaulted so the printed line is unchanged for a serializer with no
+            // globalName; naming inline serializers in this tree is its own change.
             // eslint-disable-next-line no-console
-            console.log(yoctocolors.gray(indentation +
-                indent(prefix.length, { tabWidth: 1 }) +
-                serializer.globalName));
+            console.log(yoctocolors.gray(indentation + indent(prefix.length, { tabWidth: 1 }) + `${serializerGlobalName(serializer)}`));
         });
     });
 }

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

@@ -1,5 +1,6 @@
 import compact from '../../helpers/compact.js';
 import { inferSerializersFromDreamClassOrViewModelClass } from '../../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import serializerGlobalName from '../../serializer/helpers/serializerGlobalName.js';
 /**
  * Keyed on the two arguments. Weak on both, so an entry is collectable once either the Dream class
  * or the serializer is. The cached arrays are handed out by reference and must be treated as
@@ -102,7 +103,19 @@ function buildSerializerAssociationEdges(dreamClass, serializer) {
             // nothing wrong with it.
             const serializers = serializerAssociation.options.serializer
                 ? compact([serializerAssociation.options.serializer])
-                : compact(inferSerializersFromDreamClassOrViewModelClass(associatedClass, serializerAssociation.options.serializerKey));
+                : compact(inferSerializersFromDreamClassOrViewModelClass(associatedClass, serializerAssociation.options.serializerKey, 
+                // Error-only, and derived entirely from this function's two arguments, so nothing
+                // route-dependent is introduced: it never enters the memo key in
+                // `resolveSerializerAssociationEdges` and is never stored in the returned edges.
+                {
+                    edge: {
+                        type: serializerAssociation.type,
+                        associationName: serializerAssociationName,
+                        // Undefined for a serializer built inline, which is never stamped with a
+                        // globalName — the message simply drops the declarer.
+                        declaredBy: serializerGlobalName(serializer),
+                    },
+                }));
             return serializers.map(associatedSerializer => ({
                 dreamClass: associatedClass,
                 serializer: associatedSerializer,

package/dist/esm/src/errors/DropEnumValueRetypeFailed.js

@@ -0,0 +1,208 @@
+/**
+ * SQLSTATEs Postgres raises when it cannot re-derive a stored expression against a column's
+ * new type. `42883 undefined_function` covers both `operator does not exist: text <> my_enum`
+ * (the widen) and `function char_length(my_enum) does not exist` (the restore); `42804
+ * datatype_mismatch` covers the argument-type variant and
+ * `default for column "x" cannot be cast automatically to type my_enum`.
+ *
+ * A retype can fail for reasons that have nothing to do with a stored expression — most
+ * obviously `22P02 invalid input value for enum` when a value written by `replacements` is not
+ * a member of the recreated enum. Those codes are deliberately absent, so the constraints found
+ * on the column are reported as context rather than as the diagnosis.
+ *
+ * These codes say *an* expression could not be re-derived. They do not say **which** one, and
+ * the message must not pretend otherwise: a check constraint, a partial index's `WHERE`
+ * predicate, an expression index and an uncastable column `DEFAULT` all raise them, and
+ * `dropEnumValue` reads only the check constraints. Verified against Postgres 18 —
+ * `CREATE INDEX i ON t (id) WHERE val <> 'a'` followed by `ALTER TABLE t ALTER COLUMN val TYPE
+ * text` raises exactly `42883 operator does not exist: text <> my_enum`, the same code and the
+ * same wording a blocking check constraint produces.
+ */
+const EXPRESSION_RETYPE_SQLSTATES = new Set(['42804', '42883']);
+/**
+ * Quote every segment of a possibly schema-qualified table name the way Kysely quotes the
+ * identifiers it emits, so a `to_regclass` argument resolves exactly the relation the retype
+ * targeted. Exported because `DreamMigrationHelpers`' catalog read and the diagnostic query in
+ * this message must name the relation identically; it lives here because that helper already
+ * imports this module, and the reverse import would be a cycle.
+ */
+export function quotedRelationName(table) {
+    return table
+        .split('.')
+        .map(segment => `"${segment.replace(/"/g, '""')}"`)
+        .join('.');
+}
+/**
+ * Raised when one of the two column retypes inside
+ * `DreamMigrationHelpers.dropEnumValue` fails.
+ *
+ * The raw Postgres error for the common cause of this - a check constraint on the
+ * column that references the enum - is `operator does not exist: text <> my_enum`.
+ * It names no table, no column and no constraint, and the `text` in it comes from
+ * `dropEnumValue`'s own internal widen step, so it appears nowhere in the
+ * migration the developer wrote. This error supplies all of that, and keeps the
+ * original error reachable through both `originalError` and `cause`.
+ *
+ * It never claims a check constraint caused a failure it cannot tie to one. The SQLSTATE gate
+ * separates "a stored expression could not be re-derived" from "a bad value" — but it cannot
+ * say *which* expression, because an index predicate raises the identical code, so even on the
+ * gated path the constraints stay context and the message names the other candidates.
+ */
+export default class DropEnumValueRetypeFailed extends Error {
+    enumName;
+    value;
+    table;
+    column;
+    retypeDirection;
+    relationResolved;
+    checkConstraints;
+    originalError;
+    constructor({ enumName, value, table, column, retypeDirection, relationResolved, checkConstraints, originalError, }) {
+        super(undefined, { cause: originalError });
+        this.enumName = enumName;
+        this.value = value;
+        this.table = table;
+        this.column = column;
+        this.retypeDirection = retypeDirection;
+        this.relationResolved = relationResolved;
+        this.checkConstraints = checkConstraints;
+        this.originalError = originalError;
+    }
+    get message() {
+        return `
+DreamMigrationHelpers.dropEnumValue failed while retyping ${this.table}.${this.column}.
+
+  enum:                ${this.enumName}
+  value being dropped: '${this.value}'
+  table:               ${this.table}
+  column:              ${this.column}
+  failing step:        ${this.failingStepDescription}
+
+${this.stepExplanation}
+
+${this.checkConstraintsSection}
+
+${this.guidanceSection}
+
+The original database error was:
+
+  ${this.originalError.message}
+`;
+    }
+    get failingStepDescription() {
+        return this.retypeDirection === 'toText'
+            ? `widening ${this.column} to text`
+            : `restoring ${this.column} to ${this.enumName}`;
+    }
+    get stepExplanation() {
+        if (this.retypeDirection === 'toText') {
+            return `dropEnumValue temporarily retypes every column listed in \`replacements\` to text so that
+the ${this.enumName} type can be dropped and recreated without '${this.value}'. That text type is
+dropEnumValue's own internal step, which is why the database error below can name a
+type your migration never mentioned.`;
+        }
+        return `dropEnumValue recreated ${this.enumName} without '${this.value}' and was retyping every column
+listed in \`replacements\` back to it.`;
+    }
+    /**
+     * True when the original error is one Postgres raises because a stored expression on the
+     * column could not be re-derived against its new type. A blocking check constraint is one
+     * source of that; a partial index predicate, an expression index and an uncastable column
+     * default are others. Anything else (a bad value, a missing relation, a permission error) is
+     * not evidence that any stored expression was involved.
+     */
+    get originalErrorBlockedAnExpression() {
+        const code = this.originalError.code;
+        return typeof code === 'string' && EXPRESSION_RETYPE_SQLSTATES.has(code);
+    }
+    get checkConstraintsSection() {
+        if (!this.relationResolved) {
+            return `The check constraints on ${this.table}.${this.column} could not be read: ${this.table} did not
+resolve to a table when dropEnumValue looked it up, so whether a check constraint blocked
+this retype is unknown. Read the original database error below.`;
+        }
+        if (this.checkConstraints.length === 0) {
+            return `No check constraint is defined on ${this.table}.${this.column}, so a check constraint is not
+what blocked this retype. Read the original database error below.`;
+        }
+        const constraints = this.checkConstraints
+            .map(constraint => `  - ${constraint.name}\n      ${constraint.definition}`)
+            .join('\n');
+        return `Check constraints defined on ${this.table}.${this.column}:
+
+${constraints}`;
+    }
+    get guidanceSection() {
+        if (this.originalErrorBlockedAnExpression) {
+            return [this.expressionBlockerSection, this.constraintRemedySection].filter(Boolean).join('\n\n');
+        }
+        if (!this.relationResolved)
+            return 'No check constraints could be read, so none can be reconciled here.';
+        if (this.checkConstraints.length === 0)
+            return 'No check constraints to reconcile.';
+        return `The database error below is not the "an expression on this column could not be re-derived
+against its new type" failure that a blocking check constraint produces, so the constraints
+above are listed as context rather than as the diagnosis: they may or may not have anything
+to do with this. Read the original database error below first.`;
+    }
+    /**
+     * What the SQLSTATE does and does not establish, and every expression that raises it. The
+     * candidates are listed rather than diagnosed on purpose: `dropEnumValue` reads the column's
+     * check constraints and nothing else, so naming one of them as the cause would be a guess
+     * that sends the caller to drop a constraint that changes nothing.
+     */
+    get expressionBlockerSection() {
+        return `The database error below is the one Postgres raises when an expression stored against
+${this.column} could not be re-derived for the column's new type. The retype re-evaluates every
+such expression at once, and the error names none of them, so it does not say on its own which
+one blocked the retype. It is one of:
+
+  - a check constraint on the column — ${this.checkConstraintCandidateNote}
+  - a partial index whose WHERE predicate references the column (not read)
+  - an expression index over the column (not read)
+  - the column's DEFAULT, when it cannot be cast to the new type (not read, though that variant
+    names the column and the word "default" in the error below)
+
+A view, a rule or a generated column that reads ${this.column} blocks the retype with a different
+error that names itself ("cannot alter type of a column used by ..."), so none of those is what
+happened here.
+
+The indexes are what dropEnumValue cannot see. List them with:
+
+  SELECT indexrelid::regclass AS index, pg_get_indexdef(indexrelid) AS definition
+    FROM pg_index WHERE indrelid = to_regclass('${quotedRelationName(this.table)}');`;
+    }
+    get checkConstraintCandidateNote() {
+        if (!this.relationResolved)
+            return 'dropEnumValue could not read these, as noted above';
+        if (this.checkConstraints.length === 0)
+            return 'there are none on this column, so this one is ruled out';
+        return this.checkConstraints.length === 1 ? 'the one listed above' : 'the ones listed above';
+    }
+    /**
+     * The copy-pasteable remedy, offered only when there is a constraint to drop and phrased as
+     * conditional on that constraint actually being the blocker — which this error cannot know.
+     */
+    get constraintRemedySection() {
+        if (!this.relationResolved || this.checkConstraints.length === 0)
+            return '';
+        const dropCalls = this.checkConstraints
+            .map(constraint => `  await DreamMigrationHelpers.dropConstraint(db, '${constraint.name}', { table: '${this.table}' })`)
+            .join('\n');
+        const them = this.checkConstraints.length === 1 ? 'it' : 'them';
+        return `If one of the check constraints above is the blocker, drop ${them} before calling dropEnumValue,
+then re-add the ones that should survive. dropEnumValue deliberately does not do this for you:
+only your migration knows which of these three outcomes each constraint needs.
+
+  1. a constraint that exists only to forbid '${this.value}' should be dropped and never re-added
+  2. a constraint that never mentions '${this.value}' should be re-added exactly as it was
+  3. a constraint that mentions '${this.value}' alongside other values should be re-added with
+     '${this.value}' struck from it
+
+Drop ${them} with:
+
+${dropCalls}
+
+If dropping ${them} changes nothing, the blocker is one of the other expressions above.`;
+    }
+}

package/dist/esm/src/errors/serializers/MissingSerializersDefinition.js

@@ -1,8 +1,22 @@
+import serializerResolutionContextMessage from './serializerResolutionContextMessage.js';
 export default class MissingSerializersDefinition extends Error {
     viewModel;
-    constructor(viewModel) {
+    /**
+     * ECMAScript-private (`#`) rather than TypeScript-`private`, unlike the four internal siblings of
+     * this error. A TypeScript `private` parameter property is a real, enumerable own property at
+     * runtime, and this is the one serializer-resolution error the package exports
+     * (`src/package-exports/errors.ts`) — so `Object.keys(err)` and `JSON.stringify(err)` on a
+     * consumer's error-logging path would newly report the diagnostic state threaded in here. `#`
+     * fields are invisible to both, so the exported error's observable runtime shape is unchanged.
+     * `viewModel` keeps its existing form: it predates this and narrowing it is not this change.
+     */
+    #serializerKey;
+    #resolutionContext;
+    constructor(viewModel, serializerKey, resolutionContext) {
         super();
         this.viewModel = viewModel;
+        this.#serializerKey = serializerKey;
+        this.#resolutionContext = resolutionContext;
     }
     get message() {
         const className = this.viewModel?.sanitizedConstructorName ?? this.viewModel.constructor.name;
@@ -18,6 +32,6 @@ class ${className} {
     }
   }
   ...
-}`;
+}${serializerResolutionContextMessage(this.#serializerKey, this.#resolutionContext)}`;
     }
 }

package/dist/esm/src/errors/serializers/MissingSerializersDefinitionForKey.js

@@ -1,10 +1,13 @@
+import serializerResolutionContextMessage from './serializerResolutionContextMessage.js';
 export default class MissingSerializersDefinitionForKey extends Error {
     viewModel;
     serializerKey;
-    constructor(viewModel, serializerKey) {
+    resolutionContext;
+    constructor(viewModel, serializerKey, resolutionContext) {
         super();
         this.viewModel = viewModel;
         this.serializerKey = serializerKey;
+        this.resolutionContext = resolutionContext;
     }
     get message() {
         const className = this.viewModel?.sanitizedConstructorName ?? this.viewModel.constructor.name;
@@ -21,6 +24,6 @@ class ${className} {
     }
   }
   ...
-}`;
+}${serializerResolutionContextMessage(this.serializerKey, this.resolutionContext)}`;
     }
 }

package/dist/esm/src/errors/serializers/NoGlobalSerializerForSpecifiedKey.js

@@ -1,18 +1,20 @@
+import serializerResolutionContextMessage from './serializerResolutionContextMessage.js';
 export default class NoGlobalSerializerForSpecifiedKey extends Error {
     viewModel;
     serializerKey;
     globalName;
-    constructor(viewModel, serializerKey, globalName) {
+    resolutionContext;
+    constructor(viewModel, serializerKey, globalName, resolutionContext) {
         super();
         this.viewModel = viewModel;
         this.serializerKey = serializerKey;
         this.globalName = globalName;
+        this.resolutionContext = resolutionContext;
     }
     get message() {
         const className = this.viewModel?.sanitizedConstructorName ?? this.viewModel.constructor.name;
         return `
 ${className} specified a global name of "${this.globalName}" for serializer key "${this.serializerKey}",
-but no serializer corresponds to "${this.globalName}".
-`;
+but no serializer corresponds to "${this.globalName}".${serializerResolutionContextMessage(this.serializerKey, this.resolutionContext)}`;
     }
 }

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

@@ -1,3 +1,4 @@
+import serializerResolutionContextMessage from './serializerResolutionContextMessage.js';
 /**
  * Raised when resolving a serializer key against a class yields an empty set of serializers.
  *
@@ -11,10 +12,12 @@
 export default class NoSerializersResolvedForKey extends Error {
     classDef;
     serializerKey;
-    constructor(classDef, serializerKey) {
+    resolutionContext;
+    constructor(classDef, serializerKey, resolutionContext) {
         super();
         this.classDef = classDef;
         this.serializerKey = serializerKey;
+        this.resolutionContext = resolutionContext;
     }
     get message() {
         const className = this.classDef === null || this.classDef === undefined
@@ -25,6 +28,6 @@ No serializers resolved for \`${className}\` under serializer key \`${this.seria
 
 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.`;
+application. Please report it.${serializerResolutionContextMessage(this.serializerKey, this.resolutionContext)}`;
     }
 }

package/dist/esm/src/errors/serializers/NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey.js

@@ -1,15 +1,18 @@
 import { inspect } from 'node:util';
+import serializerResolutionContextMessage from './serializerResolutionContextMessage.js';
 export default class NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey extends Error {
     viewModel;
     serializerKey;
     globalName;
     serializer;
-    constructor(viewModel, serializerKey, globalName, serializer) {
+    resolutionContext;
+    constructor(viewModel, serializerKey, globalName, serializer, resolutionContext) {
         super();
         this.viewModel = viewModel;
         this.serializerKey = serializerKey;
         this.globalName = globalName;
         this.serializer = serializer;
+        this.resolutionContext = resolutionContext;
     }
     get message() {
         const className = this.viewModel?.sanitizedConstructorName ?? this.viewModel.constructor.name;
@@ -17,7 +20,6 @@ export default class NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKe
 ${className} specified a global name of "${this.globalName}" for serializer key "${this.serializerKey}",
 but the derived serializer is not a Dream serializer:
 
-${inspect(this.serializer)}
-`;
+${inspect(this.serializer)}${serializerResolutionContextMessage(this.serializerKey, this.resolutionContext)}`;
     }
 }

package/dist/esm/src/errors/serializers/serializerResolutionContextMessage.js

@@ -0,0 +1,46 @@
+/**
+ * @internal
+ *
+ * Renders the trailing "how did resolution reach this class" block shared by the five
+ * serializer-resolution errors.
+ *
+ * Every line is independently well-formed and a line is omitted entirely — no placeholder, no empty
+ * slot — when the path that raised the error does not have that fact. The paths differ, and
+ * deliberately so:
+ *
+ * - the serializer key is on every path, since it is an argument of resolution itself;
+ * - the render edge is present only when a `rendersOne`/`rendersMany` led to the failing class. The
+ *   three root entry points (`Dream.serializationMap`, `Dream.displaySerialization` and
+ *   `buildSerializerPreloadPaths`) resolve a class the caller named directly, so nothing led there;
+ * - the declaring serializer is present only while preload paths and serialization maps are built.
+ *   `SerializerRenderer` holds the rendered attribute but not the serializer that declared it;
+ * - the STI base is present only where expanding one produced the class the error names.
+ */
+export default function serializerResolutionContextMessage(serializerKey, context) {
+    const lines = [];
+    if (serializerKey !== undefined)
+        lines.push(['serializer key', serializerKey]);
+    const edge = context?.edge;
+    if (edge)
+        lines.push([
+            'reached through',
+            edge.declaredBy
+                ? `${edge.type} \`${edge.associationName}\`, declared by ${edge.declaredBy}`
+                : `${edge.type} \`${edge.associationName}\``,
+        ]);
+    if (context?.stiBase)
+        lines.push(['expanded from', `the STI base ${context.stiBase}`]);
+    if (lines.length === 0)
+        return '';
+    return `
+
+Serializer resolution context:
+
+${lines.map(([label, value]) => `  ${`${label}:`.padEnd(LABEL_COLUMN_WIDTH)}${value}`).join('\n')}`;
+}
+/**
+ * Fixed rather than computed from the lines actually present, so that the same fact sits in the
+ * same column in every one of these errors — a reader comparing two failures is not also comparing
+ * two layouts.
+ */
+const LABEL_COLUMN_WIDTH = 'reached through: '.length;

package/dist/esm/src/helpers/cli/generateFactoryContent.js

@@ -54,7 +54,13 @@ export default function generateFactoryContent({ fullyQualifiedModelName, column
                 belongsToNames.push(attributeVariable);
                 belongsToTypedNames.push(`${attributeVariable}: ${associationModelName}`);
                 additionalImports.push(associationFactoryImportStatement);
-                associationCreationStatements.push(`${attributeVariable}: attrs.${attributeVariable} ? null : await create${associationModelName}(),`);
+                // The parens around `await` are what Prettier itself emits for an
+                // `await` operand of `??` (it parenthesizes unconditionally), and this
+                // string is written to the consumer's file verbatim — no formatting
+                // pass — so omitting them makes every freshly generated factory fail
+                // `prettier --check` in their project. See the Prettier fixed-point
+                // specs in spec/unit/cli/generateFactoryContent.spec.ts.
+                associationCreationStatements.push(`${attributeVariable}: attrs.${attributeVariable} ?? (await create${associationModelName}()),`);
                 break;
             }
             case 'encrypted':