@rvoh/dream 2.25.0 → 2.27.0

package/dist/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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':

package/dist/cjs/src/helpers/cli/generateMigrationContent.js

@@ -175,19 +175,8 @@ export default function generateMigrationContent({ connectionName = 'default', t
         }
         return acc;
     }, { columnDefs: [], columnDrops: [], indexDefs: [] });
-    if (!table) {
-        return `\
-import { Kysely, sql } from 'kysely'
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export async function up(db: Kysely<any>): Promise<void> {
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export async function down(db: Kysely<any>): Promise<void> {
-}\
-`;
-    }
+    if (!table)
+        return emptyMigrationContent();
     // An alter migration (either `-to-`/add or `-from-`/remove) with no valid
     // columns to add/drop would otherwise emit a bare `.alterTable(...).execute()`
     // with no column operation at all, which Postgres rejects at migration-run
@@ -207,6 +196,22 @@ export async function down(db: Kysely<any>): Promise<void> {
         !stiChildClassName) {
         throw new NoColumnsToAlterMigration(table, alterDirection, migrationName, alterMarker);
     }
+    // The placeholder table is the standalone `g:migration` markerless path (see
+    // MIGRATION_TABLE_NAME_PLACEHOLDER above): the migration name resolved no
+    // table, so there is nothing to alter. With no columns declared either, there
+    // is no column operation to scaffold, so emit genuinely empty `up`/`down`
+    // bodies for the developer to fill in rather than an
+    // `alterTable('<table-name>')` statement that cannot run as generated.
+    //
+    // The test is `columnsWithTypes`, deliberately, and not `columnDefs`: the two
+    // diverge. A declaration the reduce above filters out entirely (e.g.
+    // `comments:has_many`) leaves `columnDefs` empty while the user did type a
+    // column, and emptying the bodies there would silently discard it. Markerless
+    // *with* columns therefore keeps the placeholder scaffold — the table name is
+    // the only part the generator cannot work out, and `g:migration`'s help
+    // already documents that case as a stub to hand-edit.
+    if (altering && table === MIGRATION_TABLE_NAME_PLACEHOLDER && columnsWithTypes.length === 0)
+        return emptyMigrationContent();
     const citextExtension = requireCitextExtension
         ? `  await DreamMigrationHelpers.createExtension(db, 'citext')\n\n`
         : '';
@@ -273,6 +278,68 @@ ${downBody}
 }\
 `;
 }
+/**
+ * A migration file with nothing in it: correct imports, the standard `up`/`down`
+ * signatures, and empty bodies.
+ *
+ * Three deliberate departures from the scaffolded migrations above. All three
+ * exist so that the file this generator writes is clean the instant it lands in
+ * a consumer's project — under their formatter as well as their linter. See
+ * `spec/unit/cli/generateMigrationContent.spec.ts`
+ * ("the generated empty migration is clean under a consumer's tooling"), which
+ * runs this exact output through Prettier and through ESLint's
+ * `recommended` + `typescript-eslint recommended` and pins zero of both.
+ *
+ * - The bodies are `{}`, closed on the signature's own line, not `{\n}`, and
+ *   the file ends in a newline. Prettier collapses an empty block onto one line
+ *   and requires a final newline, so either spelling is a formatting violation
+ *   the moment it is written and fails `prettier --check` in the consumer's CI
+ *   (and this repo's own `pnpm lint`, which ends in `pnpm prettier . --check`);
+ *   `writeGeneratedFile` writes this string byte-for-byte with no formatting
+ *   pass. The final newline is why this template does not end with the
+ *   backslash line-continuation the scaffolded return above uses. (Those
+ *   scaffolds are missing their own final newline, which is pre-existing and
+ *   pinned by ~90 `toEqual` expectations across three spec files; it is not
+ *   this template's to fix. `generateFactoryContent` and
+ *   `generateUnitSpecContent` already terminate their output the way this one
+ *   now does.)
+ * - `sql` is left out of the import list. Every other generated migration
+ *   imports it unconditionally because most bodies need it, but an empty body
+ *   never does, and an unused import is an error under
+ *   `@typescript-eslint/no-unused-vars` in a file that would otherwise have
+ *   nothing to report.
+ * - `db` keeps its name — the developer's first keystroke in the body is going
+ *   to be `db.`, and dropping the parameter (with the `Kysely` import that only
+ *   it uses) would make them type both back — and the existing
+ *   `no-explicit-any` directive is widened to disable `no-unused-vars` too.
+ *   `db` is unused until the body is written, and `no-unused-vars` is
+ *   *error*-level under `typescript-eslint`'s `recommended` with
+ *   `args: 'after-used'`, so without the directive `psy g:migration <name> &&
+ *   pnpm lint` fails on a brand-new, untouched file. (The `await`-less `async`
+ *   needs nothing: `require-await` deliberately ignores empty function bodies.)
+ *   An `_db` rename is not a substitute: `no-unused-vars` sets no
+ *   `argsIgnorePattern` by default, so `_db` reports too, and the developer
+ *   then has to rename it back.
+ *
+ *   The cost of the widened directive is that the `no-unused-vars` half goes
+ *   stale once the body uses `db`, which ESLint 9 reports via its default
+ *   `reportUnusedDisableDirectives`. That is a *warning* rather than the two
+ *   *errors* it replaces, it lands in the file the developer is already
+ *   editing, and `eslint --fix` removes just that rule name from the directive
+ *   and leaves `no-explicit-any` in place — so it is strictly the cheaper of
+ *   the two, in severity and in effort.
+ */
+function emptyMigrationContent() {
+    return `\
+import { Kysely } from 'kysely'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+export async function up(db: Kysely<any>): Promise<void> {}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+export async function down(db: Kysely<any>): Promise<void> {}
+`;
+}
 function getAttributeType(attributeType, descriptors) {
     switch (attributeType) {
         case 'string':

package/dist/cjs/src/helpers/cli/syncWithFailureContext.js

@@ -0,0 +1,41 @@
+import DreamCLI from '../../cli/index.js';
+/**
+ * Runs the type/schema sync a command performs after its own work has already
+ * succeeded, and — when that sync fails — logs a message naming what completed
+ * and naming the sync as the step that failed, before re-raising the original
+ * error untouched.
+ *
+ * Without this, a failing sync surfaces a bare sync error immediately after
+ * e.g. `db:rollback`, which reads as a failed rollback even though the
+ * rollback itself is already committed.
+ *
+ * The original error is re-thrown rather than wrapped, so the error a caller
+ * sees, and the command's non-zero exit status, are exactly what they were
+ * before. Callers keep their own `EnvInternal.isTest` / `--skip-sync` guards:
+ * this wrapper takes the sync call, not the decision to make it.
+ */
+export default async function syncWithFailureContext({ commandName, completedWork, didNotRun, recoveryAdvice }, sync) {
+    try {
+        await sync();
+    }
+    catch (error) {
+        DreamCLI.logger.log(syncFailureMessage({ commandName, completedWork, didNotRun, recoveryAdvice }));
+        throw error;
+    }
+}
+/**
+ * @internal
+ *
+ * Builds the explanatory message logged when a post-work sync fails.
+ */
+export function syncFailureMessage({ commandName, completedWork, didNotRun, recoveryAdvice, }) {
+    const skipped = didNotRun ? `; ${didNotRun}` : '';
+    const recovery = recoveryAdvice ?? 'run `sync` on its own';
+    return `
+${commandName}: the sync step failed — not ${commandName}'s own work.
+
+${completedWork}. What failed afterward is the sync that ${commandName} runs to regenerate the auto-generated type and schema files${skipped}.
+
+The sync error itself is printed alongside this message. Once it is resolved, ${recovery}.
+`;
+}

package/dist/cjs/src/serializer/SerializerRenderer.js

@@ -97,7 +97,7 @@ export default class SerializerRenderer {
                     const associatedObject = data[attribute.name];
                     let serializer = null;
                     if (associatedObject) {
-                        serializer = serializerForAssociatedObject(associatedObject, attribute.options);
+                        serializer = serializerForAssociatedObject(associatedObject, attribute.options, renderTimeResolutionContext(attribute.options, 'rendersOne', attribute.name));
                     }
                     else if (attribute.options.flatten) {
                         /**
@@ -146,8 +146,12 @@ export default class SerializerRenderer {
                     const associatedObjects = data[attribute.name];
                     if (!associatedObjects)
                         throw new RendersManyMustReceiveArray(attribute, associatedObjects);
+                    // Hoisted out of the map: the context is identical for every element, is immutable, and is
+                    // read only while an error message is being built, so one object serves the whole
+                    // collection rather than one per element.
+                    const resolutionContext = renderTimeResolutionContext(attribute.options, 'rendersMany', attribute.name);
                     accumulator[outputAttributeName] = compact(associatedObjects).map(associatedObject => {
-                        const serializer = serializerForAssociatedObject(associatedObject, attribute.options);
+                        const serializer = serializerForAssociatedObject(associatedObject, attribute.options, resolutionContext);
                         return (
                         // passthrough data going into the serializer is the argument that gets
                         // used in the custom attribute callback function
@@ -206,8 +210,32 @@ function _applyRenderingOptionsToAttribute(data, value, attributeName, options,
         return round(value, precision);
     return value ?? null;
 }
-function serializerForAssociatedObject(associatedObject, options) {
+/**
+ * `resolutionContext` is error-only: it names the rendersOne/rendersMany this object is being
+ * rendered through, so that a serializer that cannot be resolved for it says which association led
+ * here rather than only which class failed. It is `undefined` whenever no resolution will happen —
+ * see `renderTimeResolutionContext`.
+ */
+function serializerForAssociatedObject(associatedObject, options, resolutionContext) {
     if (options.serializer)
         return options.serializer;
-    return inferSerializerFromDreamOrViewModel(associatedObject, options.serializerKey);
+    return inferSerializerFromDreamOrViewModel(associatedObject, options.serializerKey, resolutionContext);
+}
+/**
+ * Builds the error-only resolution context for one rendered association, or `undefined` when the
+ * render will not resolve a serializer at all.
+ *
+ * Rendering is a hot path — once per rendered association per request, and `rendersMany` renders one
+ * element at a time from a collection — so this deliberately allocates nothing it cannot use:
+ * `serializerForAssociatedObject` returns `options.serializer` before resolving anything when the
+ * association declares its own serializer, and in that case there is no resolution to describe.
+ * Callers build this once per rendered association and share it across every element.
+ *
+ * The renderer holds no serializer object, so the edge carries no `declaredBy` — see
+ * `SerializerResolutionContext`.
+ */
+function renderTimeResolutionContext(options, type, associationName) {
+    if (options.serializer)
+        return undefined;
+    return { edge: { type, associationName } };
 }