@rvoh/dream 2.25.0 → 2.27.0

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, ValidatedPluckEachColumnNames } 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
@@ -1439,7 +1445,8 @@ export default class Dream {
      * @param args - a list of fields to pluck, followed by a callback function to call for each set of found fields
      * @returns void
      */
-    static pluckEach<T extends typeof Dream, I extends InstanceType<T>, ColumnNames extends TableColumnNames<I['DB'], I['table']>[], CbArgTypes extends BaseModelColumnTypes<ColumnNames, I>>(this: T, ...args: PluckEachArgs<ColumnNames, CbArgTypes>): Promise<void>;
+    static pluckEach<T extends typeof Dream, I extends InstanceType<T>, const ColumnNames extends unknown[]>(this: T, ...args: PluckEachArgs<ValidatedPluckEachColumnNames<ColumnNames, TableColumnNames<I['DB'], I['table']>>, BaseModelColumnTypes<ValidatedPluckEachColumnNames<ColumnNames, TableColumnNames<I['DB'], I['table']>>, I>>): Promise<void>;
+    static pluckEach<T extends typeof Dream, I extends InstanceType<T>, const ColumnNames extends TableColumnNames<I['DB'], I['table']>[]>(this: T, ...args: PluckEachArgs<ColumnNames, BaseModelColumnTypes<ColumnNames, I>>): Promise<void>;
     /**
      * Used in conjunction with the Sortable decorator, `resort`
      * takes a list of sortable fields, and for each one, finds and

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/dream/DreamClassTransactionBuilder.d.ts

@@ -1,7 +1,7 @@
 import { SelectArg, SelectExpression } from 'kysely';
 import Dream from '../Dream.js';
 import { PassthroughOnClause, WhereStatement } from '../types/associations/shared.js';
-import { CreateOrFindByExtraOpts, DefaultScopeName, DreamColumnNames, DreamSerializerKey, FindablePropertiesForClass, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableProperties, UpdateOrCreateByExtraOpts } from '../types/dream.js';
+import { CreateOrFindByExtraOpts, DefaultScopeName, DreamColumnNames, DreamSerializerKey, FindablePropertiesForClass, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableProperties, UpdateOrCreateByExtraOpts, ValidatedPluckEachColumnNames } from '../types/dream.js';
 import { BaseModelColumnTypes, FindEachOpts, LoadForModifierFn, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from '../types/query.js';
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
@@ -730,7 +730,8 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * @param fields - A list of fields to pluck, followed by a callback function to call for each set of found fields
      * @returns void
      */
-    pluckEach<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, ColumnName extends keyof UpdateableProperties<DreamInstance>, ColumnNames extends ColumnName[], CbArgTypes extends BaseModelColumnTypes<ColumnNames, DreamInstance>>(this: I, ...args: PluckEachArgs<ColumnNames, CbArgTypes>): Promise<void>;
+    pluckEach<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, const ColumnNames extends unknown[]>(this: I, ...args: PluckEachArgs<ValidatedPluckEachColumnNames<ColumnNames, keyof UpdateableProperties<DreamInstance>>, BaseModelColumnTypes<ValidatedPluckEachColumnNames<ColumnNames, keyof UpdateableProperties<DreamInstance>>, DreamInstance>>): Promise<void>;
+    pluckEach<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, const ColumnNames extends (keyof UpdateableProperties<DreamInstance>)[]>(this: I, ...args: PluckEachArgs<ColumnNames, BaseModelColumnTypes<ColumnNames, DreamInstance>>): Promise<void>;
     /**
      * Sends data through for use as passthrough data
      * for the associations that require it.

package/dist/types/src/dream/Query.d.ts

@@ -2,7 +2,7 @@ import { DeleteQueryBuilder, SelectQueryBuilder, UpdateQueryBuilder } from 'kyse
 import Dream from '../Dream.js';
 import { ColumnNamesAccountingForJoinedAssociations, InternalWhereStatement, LimitStatement, OffsetStatement, OrderQueryStatement, PassthroughOnClause, WhereStatement, WhereStatementForJoinedAssociation } from '../types/associations/shared.js';
 import { DbConnectionType } from '../types/db.js';
-import { AllDefaultScopeNames, DefaultScopeName, DreamColumnNames, DreamConstructorType, DreamSerializerKey, DreamTableSchema, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, RelaxedJoinAndStatement, RelaxedJoinStatement, RelaxedPreloadOnStatement, RelaxedPreloadStatement, TableColumnNames, TableOrAssociationName, UpdateableProperties } from '../types/dream.js';
+import { AllDefaultScopeNames, DefaultScopeName, DreamColumnNames, DreamConstructorType, DreamSerializerKey, DreamTableSchema, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, RelaxedJoinAndStatement, RelaxedJoinStatement, RelaxedPreloadOnStatement, RelaxedPreloadStatement, TableColumnNames, TableOrAssociationName, UpdateableProperties, ValidatedPluckEachColumnNames } from '../types/dream.js';
 import { CursorPaginatedDreamQueryOptions, CursorPaginatedDreamQueryResult, DefaultQueryTypeOptions, ExtendQueryType, LoadForModifierFn, NamespacedOrBaseModelColumnTypes, PaginatedDreamQueryOptions, PaginatedDreamQueryResult, QueryToKyselyDBType, QueryToKyselyTableNamesType } from '../types/query.js';
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, QueryTypeOptions, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
@@ -1006,7 +1006,8 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @returns void
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */
-    pluckEach<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], const ColumnNames extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>[], CbArgTypes extends NamespacedOrBaseModelColumnTypes<ColumnNames, Q, DreamInstance>>(this: Q, ...args: PluckEachArgs<ColumnNames, CbArgTypes>): Promise<void>;
+    pluckEach<Q extends Query<DreamInstance, QueryTypeOpts>, const ColumnNames extends unknown[]>(this: Q, ...args: PluckEachArgs<ValidatedPluckEachColumnNames<ColumnNames, ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DreamInstance['DB'], QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>>, NamespacedOrBaseModelColumnTypes<ValidatedPluckEachColumnNames<ColumnNames, ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DreamInstance['DB'], QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>>, Q, DreamInstance>>): Promise<void>;
+    pluckEach<Q extends Query<DreamInstance, QueryTypeOpts>, const ColumnNames extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DreamInstance['DB'], QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>[]>(this: Q, ...args: PluckEachArgs<ColumnNames, NamespacedOrBaseModelColumnTypes<ColumnNames, Q, DreamInstance>>): Promise<void>;
     /**
      * Retrieves an array containing all records matching the Query.
      * Be careful using this, since it will attempt to pull every

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)[];

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

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

package/dist/types/src/types/associations/shared.d.ts

@@ -29,7 +29,7 @@ type NonKyselySupportedSupplementalWhereClauseValues<DB, Schema, TableName, Colu
 export type WhereStatementForDreamClass<DreamClass extends typeof Dream> = WhereStatement<InstanceType<DreamClass>>;
 export type WhereStatementForDream<DreamInstance extends Dream> = WhereStatement<DreamInstance>;
 type AssociationNameToDotReferencedColumns<DB, TableName extends keyof DB, AssociationName> = `${AssociationName & string}.${TableColumnNames<DB, TableName>}`;
-export type ColumnNamesAccountingForJoinedAssociations<JoinedAssociations extends Readonly<JoinedAssociation[]>, DB, RootTableName extends keyof DB, RootTableAlias extends string> = JoinedAssociations['length'] extends 0 ? TableColumnNames<DB, RootTableName> : JoinedAssociationColumnNames<JoinedAssociations, DB, AssociationNameToDotReferencedColumns<DB, RootTableName & keyof DB, RootTableAlias>>;
+export type ColumnNamesAccountingForJoinedAssociations<JoinedAssociations extends Readonly<JoinedAssociation[]>, DB, RootTableName extends keyof DB, RootTableAlias extends string> = JoinedAssociations['length'] extends 0 ? TableColumnNames<DB, RootTableName> : TableColumnNames<DB, RootTableName> | JoinedAssociationColumnNames<JoinedAssociations, DB, AssociationNameToDotReferencedColumns<DB, RootTableName & keyof DB, RootTableAlias>>;
 type JoinedAssociationColumnNames<JoinedAssociations extends Readonly<JoinedAssociation[]>, DB, AllColumnNames, Depth extends number = 0, CurrentJoinedAssociation = Readonly<JoinedAssociations[0]>, NextTableName = CurrentJoinedAssociation extends Readonly<JoinedAssociation> ? CurrentJoinedAssociation['table'] : never, NextAssociationName = CurrentJoinedAssociation extends Readonly<JoinedAssociation> ? CurrentJoinedAssociation['alias'] : never> = JoinedAssociations['length'] extends 0 ? AllColumnNames : Depth extends MAX_JOINED_TABLES_DEPTH ? AllColumnNames : JoinedAssociationColumnNames<ReadonlyTail<JoinedAssociations>, DB, AllColumnNames | AssociationNameToDotReferencedColumns<DB, NextTableName & keyof DB, NextAssociationName>, Inc<Depth>>;
 type Whereable<R> = {
     [K in keyof Selectable<R>]?: Selectable<R>[K] | Selectable<R>[K][];

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

@@ -265,4 +265,7 @@ export type AllDefaultScopeNames<DreamConf, ConnectionTypeConfig = DreamConf['co
 export type NamedScopeName<DreamInstance extends Dream, Schema = DreamInstance['schema'], SchemaTable = Schema[DreamInstance['table'] & keyof Schema], SchemaNamedScopes extends string[] = SchemaTable['scopes' & keyof SchemaTable]['named' & keyof SchemaTable['scopes' & keyof SchemaTable]] & string[]> = SchemaNamedScopes[number];
 export type DefaultOrNamedScopeName<DreamInstance extends Dream> = DefaultScopeName<DreamInstance> | NamedScopeName<DreamInstance>;
 export type PluckEachArgs<ColumnNames extends unknown[], CbArgTypes extends unknown[]> = [...fields: ColumnNames] | [...fields: ColumnNames, callback: (...values: CbArgTypes) => void | Promise<void>] | [...fields: ColumnNames, callback: (...values: CbArgTypes) => void | Promise<void>, opts: FindEachOpts];
+export type ValidatedPluckEachColumnNames<ColumnNames extends unknown[], AllowedColumnName> = {
+    [Index in keyof ColumnNames]: ColumnNames[Index] extends AllowedColumnName ? ColumnNames[Index] : AllowedColumnName;
+};
 export {};

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

@@ -46,7 +46,7 @@ export type ExtendQueryType<OriginalOpts extends Readonly<QueryTypeOptions>, Opt
     allowOffset: Opts['allowOffset'] extends false ? false : OriginalOpts['allowOffset'];
     allowPaginate: Opts['allowPaginate'] extends false ? false : OriginalOpts['allowPaginate'];
 }>;
-export type NamespacedColumnType<ColumnName, Q extends Query<any, any>, DreamInstance extends Dream, JoinedAssociationsArr = Q['queryTypeOpts']['joinedAssociations'], AssociationName = ColumnName extends `${infer Name extends string}.${string}` ? Name : never, RealColumnName = ColumnName extends `${string}.${infer Col extends string}` ? Col : never, JoinedAssociation extends FindInterfaceWithValue<JoinedAssociationsArr, 'alias', AssociationName> = FindInterfaceWithValue<JoinedAssociationsArr, 'alias', AssociationName>, JoinedTable = JoinedAssociation['table'] extends never ? DreamInstance['table'] : JoinedAssociation['table'], ReturnType = ModelColumnType<DreamInstance['schema'], JoinedTable, RealColumnName>> = ReturnType;
+export type NamespacedColumnType<ColumnName, Q extends Query<any, any>, DreamInstance extends Dream, JoinedAssociationsArr = Q['queryTypeOpts']['joinedAssociations'], AssociationName = ColumnName extends `${infer Name extends string}.${string}` ? Name : never, RealColumnName = ColumnName extends `${string}.${infer Col extends string}` ? Col : ColumnName, JoinedAssociation extends FindInterfaceWithValue<JoinedAssociationsArr, 'alias', AssociationName> = FindInterfaceWithValue<JoinedAssociationsArr, 'alias', AssociationName>, JoinedTable = JoinedAssociation['table'] extends never ? DreamInstance['table'] : JoinedAssociation['table'], ReturnType = ModelColumnType<DreamInstance['schema'], JoinedTable, RealColumnName>> = ReturnType;
 type NamespacedColumnTypes<ColumnNames, Q extends Query<any, any>, DreamInstance extends Dream> = ColumnNames extends Readonly<[infer First, ...infer Rest]> ? [
     NamespacedColumnType<First, Q, DreamInstance>,
     ...NamespacedColumnTypes<Readonly<Rest>, Q, DreamInstance>

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

@@ -39,6 +39,44 @@ export interface InternalAnyRendersOneOrManyOpts {
     serializer?: DreamModelSerializerType | SimpleObjectSerializerType;
     serializerKey?: string;
 }
+/**
+ * @internal
+ *
+ * How serializer resolution arrived at the class it is resolving against, threaded down to the
+ * errors raised when that resolution fails so the message can say *how* it got there rather than
+ * only which class it landed on.
+ *
+ * Every field is optional because the paths that resolve serializers do not all know the same
+ * things, and a message prints only what its own path has: the three root entry points
+ * (`Dream.serializationMap`, `Dream.displaySerialization`, `buildSerializerPreloadPaths`) resolve
+ * with no edge at all, `SerializerRenderer` has no serializer object in scope to name as the
+ * declarer, and an STI base is only recorded where expanding one produced the class the error
+ * names. The serializer key is not here because it is already an argument of resolution, so every
+ * error that renders this context has it in hand.
+ */
+export interface SerializerResolutionContext {
+    edge?: SerializerResolutionEdge;
+    /**
+     * The STI base whose expansion produced the class the error names. Absent when the class was
+     * resolved directly rather than reached through `expandStiClasses`.
+     */
+    stiBase?: string;
+}
+/**
+ * @internal
+ *
+ * The `rendersOne`/`rendersMany` that led resolution to the failing class.
+ */
+export interface SerializerResolutionEdge {
+    type: 'rendersOne' | 'rendersMany';
+    associationName: string;
+    /**
+     * The global name of the serializer that declares the edge. In scope while preload paths and
+     * serialization maps are built, and absent at render time, where the renderer holds the rendered
+     * attribute but not the serializer that declared it.
+     */
+    declaredBy?: string | undefined;
+}
 export interface InternalAnyTypedSerializerRendersOne<DataType, AttributeName extends keyof DataType & string = keyof DataType & string> {
     type: 'rendersOne';
     name: AttributeName;

package/dist/types/src/types/types/associations/shared.ts

@@ -216,12 +216,14 @@ export type ColumnNamesAccountingForJoinedAssociations<
   RootTableAlias extends string,
 > = JoinedAssociations['length'] extends 0
   ? TableColumnNames<DB, RootTableName> // no associations; simply return the un-namespaced columns for the root table
-  : JoinedAssociationColumnNames<
-      JoinedAssociations,
-      DB,
-      // namespace columns for the root table
-      AssociationNameToDotReferencedColumns<DB, RootTableName & keyof DB, RootTableAlias>
-    >
+  :
+      | TableColumnNames<DB, RootTableName>
+      | JoinedAssociationColumnNames<
+          JoinedAssociations,
+          DB,
+          // namespace columns for the root table
+          AssociationNameToDotReferencedColumns<DB, RootTableName & keyof DB, RootTableAlias>
+        >
 type JoinedAssociationColumnNames<
   JoinedAssociations extends Readonly<JoinedAssociation[]>,
   DB,

package/dist/types/src/types/types/dream.ts

@@ -925,3 +925,9 @@ export type PluckEachArgs<ColumnNames extends unknown[], CbArgTypes extends unkn
   | [...fields: ColumnNames]
   | [...fields: ColumnNames, callback: (...values: CbArgTypes) => void | Promise<void>]
   | [...fields: ColumnNames, callback: (...values: CbArgTypes) => void | Promise<void>, opts: FindEachOpts]
+
+export type ValidatedPluckEachColumnNames<ColumnNames extends unknown[], AllowedColumnName> = {
+  [Index in keyof ColumnNames]: ColumnNames[Index] extends AllowedColumnName
+    ? ColumnNames[Index]
+    : AllowedColumnName
+}

package/dist/types/src/types/types/query.ts

@@ -101,7 +101,7 @@ export type NamespacedColumnType<
   // begin: inferred types
   JoinedAssociationsArr = Q['queryTypeOpts']['joinedAssociations'],
   AssociationName = ColumnName extends `${infer Name extends string}.${string}` ? Name : never,
-  RealColumnName = ColumnName extends `${string}.${infer Col extends string}` ? Col : never,
+  RealColumnName = ColumnName extends `${string}.${infer Col extends string}` ? Col : ColumnName,
   JoinedAssociation extends FindInterfaceWithValue<
     JoinedAssociationsArr,
     'alias',