@rvoh/dream 2.25.0 → 2.26.0

package/dist/esm/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/esm/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/esm/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 } };
 }

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

@@ -9,33 +9,51 @@ import expandStiClasses from '../../helpers/sti/expandStiClasses.js';
 import uniq from '../../helpers/uniq.js';
 import isDreamSerializer from './isDreamSerializer.js';
 export const DEFAULT_SERIALIZER_KEY = 'default';
-export default function inferSerializerFromDreamOrViewModel(obj, serializerKey = DEFAULT_SERIALIZER_KEY) {
+/**
+ * `resolutionContext` says how resolution reached `obj` — the `rendersOne`/`rendersMany` edge that
+ * led here, and the STI base it was expanded from. It is threaded down purely so that the errors
+ * below can name the route instead of only the class, and it is optional so that a caller with no
+ * route to describe (and every existing caller outside this repo) is unaffected. See
+ * `SerializerResolutionContext`.
+ */
+export default function inferSerializerFromDreamOrViewModel(obj, serializerKey = DEFAULT_SERIALIZER_KEY, resolutionContext) {
     if (!obj)
         return null;
     const serializers = obj.serializers;
     if (!serializers)
-        throw new MissingSerializersDefinition(obj);
+        throw new MissingSerializersDefinition(obj, serializerKey, resolutionContext);
     const serializerOrGlobalName = serializers[serializerKey];
     if (!serializerOrGlobalName)
-        throw new MissingSerializersDefinitionForKey(obj, serializerKey);
+        throw new MissingSerializersDefinitionForKey(obj, serializerKey, resolutionContext);
     if (isDreamSerializer(serializerOrGlobalName))
         return serializerOrGlobalName;
     const globalName = serializerOrGlobalName;
     const dreamApp = DreamApp.getOrFail();
     const serializer = dreamApp.serializers[globalName];
     if (!serializer)
-        throw new NoGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName);
+        throw new NoGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, resolutionContext);
     if (!isDreamSerializer(serializer))
-        throw new NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, serializer);
+        throw new NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, serializer, resolutionContext);
     return serializer;
 }
-export function inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey = undefined) {
+export function inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey = undefined, resolutionContext) {
     if (!classDef)
         return [];
     const classes = expandStiClasses(classDef);
-    const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey));
+    // This is the one place that knows *whether* the class an error ends up naming came from STI
+    // expansion: below this line the class the caller passed is gone, replaced by one child per
+    // iteration, and every downstream error names a child. Identity rather than `isSTIBase` because
+    // `classDef` may be a ViewModelClass, which `expandStiClasses` hands straight back.
+    const expandedFromStiBase = classes.length !== 1 || classes[0] !== classDef;
+    const childResolutionContext = expandedFromStiBase
+        ? { ...resolutionContext, stiBase: stiBaseName(classDef) }
+        : resolutionContext;
+    const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey, childResolutionContext));
     return uniq(compact(serializers));
 }
+function stiBaseName(classDef) {
+    return classDef.sanitizedName ?? classDef.name;
+}
 /**
  * As `inferSerializersFromDreamClassOrViewModelClass`, but guarantees a non-empty result.
  *
@@ -51,9 +69,9 @@ export function inferSerializersFromDreamClassOrViewModelClass(classDef, seriali
  * 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);
+export function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef, serializerKey, resolutionContext) {
+    const serializers = inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey, resolutionContext);
     if (serializers.length === 0)
-        throw new NoSerializersResolvedForKey(classDef, serializerKey);
+        throw new NoSerializersResolvedForKey(classDef, serializerKey, resolutionContext);
     return serializers;
 }

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

@@ -28,5 +28,10 @@ export function serializerForAssociatedClass(object, associationName, options) {
     // 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;
+    return (inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey, {
+        // Reached only from SerializerRenderer's rendersOne branch, so the edge type is fixed. No
+        // declaring serializer: the renderer holds the rendered attribute, not the serializer that
+        // declared it.
+        edge: { type: 'rendersOne', associationName },
+    })[0] ?? null);
 }

package/dist/esm/src/serializer/helpers/serializerGlobalName.js

@@ -0,0 +1,16 @@
+/**
+ * @internal
+ *
+ * The single reader of a serializer's `globalName`.
+ *
+ * Serializers are plain functions; `globalName` is stamped onto them by `importSerializers` when the
+ * app loads them, so the property is not on any serializer type and every reader would otherwise
+ * have to invent its own cast — three different spellings of it existed before this helper.
+ *
+ * `undefined` is a legitimate answer: a serializer built inline (a spec, or a `{ serializer }`
+ * option) is never stamped. Callers decide what that means for them — the resolution-context message
+ * simply drops the declarer.
+ */
+export default function serializerGlobalName(serializer) {
+    return serializer.globalName;
+}

package/dist/types/src/Dream.d.ts

@@ -8,7 +8,7 @@ import LoadBuilder from './dream/LoadBuilder.js';
 import Query from './dream/Query.js';
 import { OnStatementForSpecificColumns, PassthroughOnClause, WhereStatement } from './types/associations/shared.js';
 import { AssociationTableNames, DbConnectionType } from './types/db.js';
-import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAssociationNamesWithPassthroughOnClauses, DreamAssociationNamesWithRequiredOnClauses, DreamAttributes, DreamBelongsToAssociationNames, DreamColumnNames, DreamHasManyAssociationNames, DreamHasOneAssociationNames, DreamModelAssociationNames, DreamParamSafeColumnNames, DreamPrimaryKeyType, DreamSerializerKey, FindablePropertiesForClass, GlobalModelNames, GlobalSerializerName, JoinAndStatements, OrderDir, PassthroughColumnNames, PassthroughOnClauseKeys, PluckEachArgs, PrimaryKeyForFind, RequiredOnClauseKeys, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
+import { AllDefaultScopeNames, AssociationNameToDream, AttributeKeys, CreateOrFindByExtraOpts, DefaultOrNamedScopeName, DreamAssociationNames, DreamAssociationNamesWithoutRequiredOnClauses, DreamAssociationNamesWithPassthroughOnClauses, DreamAssociationNamesWithRequiredOnClauses, DreamAttributes, DreamBelongsToAssociationNames, DreamColumnNames, DreamHasManyAssociationNames, DreamHasOneAssociationNames, DreamModelAssociationNames, DreamPrimaryKeyType, DreamSerializerKey, FindablePropertiesForClass, GlobalModelNames, GlobalSerializerName, JoinAndStatements, OrderDir, PassthroughColumnNames, PassthroughOnClauseKeys, PluckEachArgs, PrimaryKeyForFind, RequiredOnClauseKeys, TableColumnNames, UpdateableAssociationProperties, UpdateableProperties, UpdateablePropertiesForClass, UpdateOrCreateByExtraOpts } from './types/dream.js';
 import { BaseModelColumnTypes, CursorPaginatedDreamQueryOptions, CursorPaginatedDreamQueryResult, DefaultQueryTypeOptions, FindEachOpts, LoadForModifierFn, PaginatedDreamQueryOptions, PaginatedDreamQueryResult, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from './types/query.js';
 import { DreamModelSerializerType, SimpleObjectSerializerType } from './types/serializer.js';
 import { ValidationType } from './types/validation.js';
@@ -458,9 +458,15 @@ export default class Dream {
      *   * foreign key fields for belongs to associations (these should usually be verified before being set)
      *   * type fields corresponding to polymorphic associations
      *
+     * @internal
+     *
+     * Not part of the public API. Psychic reaches it through the bracketed
+     * back-door (`dreamClass['paramSafeColumnsOrFallback']()`), the same escape
+     * hatch used for other Dream internals such as `virtualAttributes`.
+     *
      * @returns A subset of columns for the given dream class
      */
-    static paramSafeColumnsOrFallback<T extends typeof Dream, I extends InstanceType<T>, ParamSafeColumnsOverride extends InstanceType<T>['paramSafeColumns' & keyof InstanceType<T>] extends never ? undefined : InstanceType<T>['paramSafeColumns' & keyof InstanceType<T>] & string[], ReturnVal extends ParamSafeColumnsOverride extends string[] ? Extract<DreamParamSafeColumnNames<I>, ParamSafeColumnsOverride[number] & DreamParamSafeColumnNames<I>>[] : DreamParamSafeColumnNames<I>[]>(this: T): ReturnVal;
+    private static paramSafeColumnsOrFallback;
     private static defaultParamSafeColumns;
     /**
      * @internal

package/dist/types/src/cli/index.d.ts

@@ -23,7 +23,7 @@ export declare const columnsWithTypesDescriptionForStiChild: string;
  * example that drifts from what the generator actually produces then fails the
  * suite instead of shipping.
  */
-export declare const migrationNameArgumentDescription = "Kebab-case name describing the change. A -to-<table_name>\n                  anywhere in the name \u2014 not just at the end \u2014 auto-generates\n                  an add-columns alterTable scaffold for that table;\n                  -from-<table_name> generates a remove-columns scaffold, but\n                  only when the name contains no -to- at all. The text after\n                  the marker's first occurrence is snake-cased and pluralized\n                  into the table name, so add-a-to-b-to-cs targets b_to_cs. A\n                  hand-written migration must avoid both strings anywhere in\n                  its name.\n                  \n                  Examples:\n                    add-phone-to-users phone:encrypted      # scaffolds alterTable('users', ...)\n                    remove-status-from-posts status:string  # scaffolds alterTable('posts', ...)\n                    create-many-to-many-posts-users         # WRONG: selects 'many_posts_users'\n                      # -to- inside \"many-to-many\" matches: with no columns\n                      # this errors; with columns it silently scaffolds it\n                    create-posts-users-join-table           # correct: no marker match\n                      # scaffolds alterTable('<table-name>') to hand-edit";
+export declare const migrationNameArgumentDescription = "Kebab-case name describing the change. A -to-<table_name>\n                  anywhere in the name \u2014 not just at the end \u2014 auto-generates\n                  an add-columns alterTable scaffold for that table;\n                  -from-<table_name> generates a remove-columns scaffold, but\n                  only when the name contains no -to- at all. The text after\n                  the marker's first occurrence is snake-cased and pluralized\n                  into the table name, so add-a-to-b-to-cs targets b_to_cs. A\n                  hand-written migration must avoid both strings anywhere in\n                  its name.\n                  \n                  Examples:\n                    add-phone-to-users phone:encrypted      # scaffolds alterTable('users', ...)\n                    remove-status-from-posts status:string  # scaffolds alterTable('posts', ...)\n                    create-many-to-many-posts-users         # WRONG: selects 'many_posts_users'\n                      # -to- inside \"many-to-many\" matches: with no columns\n                      # this errors; with columns it silently scaffolds it\n                    create-posts-users-join-table           # correct: no marker match\n                      # with no columns, generates empty up/down methods to\n                      # write by hand; with columns, scaffolds\n                      # alterTable('<table-name>') to hand-edit";
 export default class DreamCLI {
     /**
      * Starts the Dream console

package/dist/types/src/errors/DropEnumValueRetypeFailed.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A check constraint discovered on the column `dropEnumValue` was retyping.
+ */
+export interface DropEnumValueCheckConstraint {
+    /** the constraint's name in `pg_constraint`, e.g. `pets_species_check` */
+    name: string;
+    /** the constraint as Postgres renders it, e.g. `CHECK (((species)::text <> 'forg'::text))` */
+    definition: string;
+}
+export interface DropEnumValueRetypeFailedOpts {
+    enumName: string;
+    value: string;
+    table: string;
+    column: string;
+    /**
+     * `toText` for the widen step that runs before the enum type is dropped and
+     * recreated; `toEnum` for the restore step that runs after it.
+     */
+    retypeDirection: 'toText' | 'toEnum';
+    /**
+     * Whether the pre-flight catalog read resolved `table` to a real relation. When it did
+     * not, `checkConstraints` being empty means "not read", not "none defined", and the
+     * message says so instead of asserting a negative it cannot support.
+     */
+    relationResolved: boolean;
+    checkConstraints: DropEnumValueCheckConstraint[];
+    originalError: Error;
+}
+/**
+ * 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 declare function quotedRelationName(table: string): string;
+/**
+ * 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 {
+    readonly enumName: string;
+    readonly value: string;
+    readonly table: string;
+    readonly column: string;
+    readonly retypeDirection: 'toText' | 'toEnum';
+    readonly relationResolved: boolean;
+    readonly checkConstraints: DropEnumValueCheckConstraint[];
+    readonly originalError: Error;
+    constructor({ enumName, value, table, column, retypeDirection, relationResolved, checkConstraints, originalError, }: DropEnumValueRetypeFailedOpts);
+    get message(): string;
+    private get failingStepDescription();
+    private get stepExplanation();
+    /**
+     * 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.
+     */
+    private get originalErrorBlockedAnExpression();
+    private get checkConstraintsSection();
+    private get guidanceSection();
+    /**
+     * 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.
+     */
+    private get expressionBlockerSection();
+    private get checkConstraintCandidateNote();
+    /**
+     * 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.
+     */
+    private get constraintRemedySection();
+}

package/dist/types/src/errors/serializers/MissingSerializersDefinition.d.ts

@@ -1,7 +1,9 @@
 import Dream from '../../Dream.js';
 import { ViewModel } from '../../types/dream.js';
+import { SerializerResolutionContext } from '../../types/serializer.js';
 export default class MissingSerializersDefinition extends Error {
+    #private;
     private viewModel;
-    constructor(viewModel: Dream | ViewModel);
+    constructor(viewModel: Dream | ViewModel, serializerKey?: string, resolutionContext?: SerializerResolutionContext);
     get message(): string;
 }

package/dist/types/src/errors/serializers/MissingSerializersDefinitionForKey.d.ts

@@ -1,8 +1,10 @@
 import Dream from '../../Dream.js';
 import { ViewModel } from '../../types/dream.js';
+import { SerializerResolutionContext } from '../../types/serializer.js';
 export default class MissingSerializersDefinitionForKey extends Error {
     private viewModel;
     private serializerKey;
-    constructor(viewModel: Dream | ViewModel, serializerKey: string);
+    private resolutionContext?;
+    constructor(viewModel: Dream | ViewModel, serializerKey: string, resolutionContext?: SerializerResolutionContext | undefined);
     get message(): string;
 }

package/dist/types/src/errors/serializers/NoGlobalSerializerForSpecifiedKey.d.ts

@@ -1,9 +1,11 @@
 import Dream from '../../Dream.js';
 import { ViewModel } from '../../types/dream.js';
+import { SerializerResolutionContext } from '../../types/serializer.js';
 export default class NoGlobalSerializerForSpecifiedKey extends Error {
     private viewModel;
     private serializerKey;
     private globalName;
-    constructor(viewModel: Dream | ViewModel, serializerKey: string, globalName: string);
+    private resolutionContext?;
+    constructor(viewModel: Dream | ViewModel, serializerKey: string, globalName: string, resolutionContext?: SerializerResolutionContext | undefined);
     get message(): string;
 }

package/dist/types/src/errors/serializers/NoSerializersResolvedForKey.d.ts

@@ -1,5 +1,6 @@
 import Dream from '../../Dream.js';
 import { ViewModelClass } from '../../types/dream.js';
+import { SerializerResolutionContext } from '../../types/serializer.js';
 /**
  * Raised when resolving a serializer key against a class yields an empty set of serializers.
  *
@@ -13,6 +14,7 @@ import { ViewModelClass } from '../../types/dream.js';
 export default class NoSerializersResolvedForKey extends Error {
     private classDef;
     private serializerKey;
-    constructor(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey: string);
+    private resolutionContext?;
+    constructor(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey: string, resolutionContext?: SerializerResolutionContext | undefined);
     get message(): string;
 }

package/dist/types/src/errors/serializers/NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey.d.ts

@@ -1,10 +1,12 @@
 import Dream from '../../Dream.js';
 import { ViewModel } from '../../types/dream.js';
+import { SerializerResolutionContext } from '../../types/serializer.js';
 export default class NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey extends Error {
     private viewModel;
     private serializerKey;
     private globalName;
     private serializer;
-    constructor(viewModel: Dream | ViewModel, serializerKey: string, globalName: string, serializer: any);
+    private resolutionContext?;
+    constructor(viewModel: Dream | ViewModel, serializerKey: string, globalName: string, serializer: any, resolutionContext?: SerializerResolutionContext | undefined);
     get message(): string;
 }

package/dist/types/src/errors/serializers/serializerResolutionContextMessage.d.ts

@@ -0,0 +1,20 @@
+import { SerializerResolutionContext } from '../../types/serializer.js';
+/**
+ * @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: string | undefined, context: SerializerResolutionContext | undefined): string;

package/dist/types/src/helpers/cli/syncWithFailureContext.d.ts

@@ -0,0 +1,58 @@
+export interface SyncFailureContext {
+    /**
+     * The command the sync is running on behalf of, e.g. `db:rollback`.
+     */
+    commandName: string;
+    /**
+     * What the command finished before the sync ran, written as a sentence with
+     * no trailing period, e.g. `The rollback completed successfully`. It must
+     * only claim the steps that genuinely ran to completion — for a command
+     * whose sync sits in the middle of a sequence, name those steps rather than
+     * the command as a whole.
+     */
+    completedWork: string;
+    /**
+     * What the sync failure prevented from running, written as a clause with no
+     * trailing period, e.g. `db:seed did not run`. Omit it when the sync is the
+     * last thing the command does, in which case nothing was skipped.
+     */
+    didNotRun?: string | undefined;
+    /**
+     * What the operator should do once the underlying sync error is fixed,
+     * written as an imperative clause with no trailing period, e.g.
+     * ``run `sync` on its own``. It is rendered as
+     * `Once it is resolved, ${recoveryAdvice}.`
+     *
+     * This is deliberately per-command rather than templated off `commandName`,
+     * because "re-run the command" is only correct for commands that are safe to
+     * repeat. `db:rollback` is the counter-example that motivates the field: its
+     * work is already committed by the time the sync runs, so re-running it rolls
+     * back a *further* migration rather than retrying the step that failed.
+     *
+     * Defaults to ``run `sync` on its own`` — the retry that is safe after any of
+     * these commands, since it repeats only the step that actually failed.
+     */
+    recoveryAdvice?: string | undefined;
+}
+/**
+ * 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 function syncWithFailureContext({ commandName, completedWork, didNotRun, recoveryAdvice }: SyncFailureContext, sync: () => Promise<void>): Promise<void>;
+/**
+ * @internal
+ *
+ * Builds the explanatory message logged when a post-work sync fails.
+ */
+export declare function syncFailureMessage({ commandName, completedWork, didNotRun, recoveryAdvice, }: SyncFailureContext): string;

package/dist/types/src/serializer/helpers/inferSerializerFromDreamOrViewModel.d.ts

@@ -1,9 +1,16 @@
 import Dream from '../../Dream.js';
 import { ViewModel, ViewModelClass } from '../../types/dream.js';
-import { DreamModelSerializerType, SerializerType, SimpleObjectSerializerType } from '../../types/serializer.js';
+import { DreamModelSerializerType, SerializerResolutionContext, SerializerType, SimpleObjectSerializerType } from '../../types/serializer.js';
 export declare const DEFAULT_SERIALIZER_KEY = "default";
-export default function inferSerializerFromDreamOrViewModel<T extends Dream | ViewModel | null | undefined, ReturnType extends T extends null | undefined ? null : T extends Dream | ViewModel ? SerializerType : never>(obj: T, serializerKey?: string | undefined): ReturnType;
-export declare function inferSerializersFromDreamClassOrViewModelClass(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey?: string | undefined): (DreamModelSerializerType | SimpleObjectSerializerType)[];
+/**
+ * `resolutionContext` says how resolution reached `obj` — the `rendersOne`/`rendersMany` edge that
+ * led here, and the STI base it was expanded from. It is threaded down purely so that the errors
+ * below can name the route instead of only the class, and it is optional so that a caller with no
+ * route to describe (and every existing caller outside this repo) is unaffected. See
+ * `SerializerResolutionContext`.
+ */
+export default function inferSerializerFromDreamOrViewModel<T extends Dream | ViewModel | null | undefined, ReturnType extends T extends null | undefined ? null : T extends Dream | ViewModel ? SerializerType : never>(obj: T, serializerKey?: string | undefined, resolutionContext?: SerializerResolutionContext): ReturnType;
+export declare function inferSerializersFromDreamClassOrViewModelClass(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey?: string | undefined, resolutionContext?: SerializerResolutionContext): (DreamModelSerializerType | SimpleObjectSerializerType)[];
 /**
  * As `inferSerializersFromDreamClassOrViewModelClass`, but guarantees a non-empty result.
  *
@@ -19,4 +26,4 @@ export declare function inferSerializersFromDreamClassOrViewModelClass(classDef:
  * preload-path building and serialization display — so that they raise one typed error between
  * them.
  */
-export declare function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey: string): (DreamModelSerializerType | SimpleObjectSerializerType)[];
+export declare function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey: string, resolutionContext?: SerializerResolutionContext): (DreamModelSerializerType | SimpleObjectSerializerType)[];