@rvoh/dream 2.29.0 → 2.31.0

package/dist/cjs/src/errors/associations/IncompatibleThroughAssociationTarget.js

@@ -0,0 +1,11 @@
+export default class IncompatibleThroughAssociationTarget extends Error {
+    constructor({ outermostAssociation, outermostTargetModelClass, sourceAssociation, }) {
+        super(`Through association \`${outermostAssociation.as}\` targets \`${outermostTargetModelClass.sanitizedName}\`, but source association \`${sourceAssociation.as}\` targets ${targetDescription(sourceAssociation)}. ` +
+            `The through association's target must be the same as or a subclass of a source target.`);
+    }
+}
+function targetDescription(association) {
+    const targetModelClassOrClasses = association.modelCB();
+    const targetNames = (Array.isArray(targetModelClassOrClasses) ? targetModelClassOrClasses : [targetModelClassOrClasses]).map(targetModelClass => `\`${targetModelClass.sanitizedName}\``);
+    return targetNames.join(', ');
+}

package/dist/cjs/src/errors/associations/MissingRequiredBelongsToAssociation.js

@@ -48,10 +48,15 @@ export default class MissingRequiredBelongsToAssociation extends Error {
 Attempting to access required BelongsTo association \`${this.associationName}\` on an instance of \`${this.dreamClass.sanitizedName}\`,
 but the loaded association is null.
 
-${this.foreignKeyMessage}
-
-If the associated record was deleted, check whether the inverse HasOne/HasMany association should specify dependent: 'destroy'.
+${this.foreignKeyMessage}${this.populatedForeignKeyDiagnosticMessage}
 `;
+    }
+    get populatedForeignKeyDiagnosticMessage() {
+        if (this.foreignKeyValue === null || this.foreignKeyValue === undefined)
+            return '';
+        return `
+
+The associated record may have been deleted (including soft-deleted), or it may not match this association’s target—for example, its STI type may differ from the targeted STI child. If the record was deleted unexpectedly, check whether the inverse HasOne/HasMany association should specify \`dependent: 'destroy'\`.`;
     }
     get foreignKeyMessage() {
         if (this.foreignKeyValue === null || this.foreignKeyValue === undefined) {

package/dist/cjs/src/package-exports/errors.js

@@ -1,18 +1,27 @@
 export { pgErrorType } from '../db/errors.js';
 export { default as NonLoadedAssociation } from '../errors/associations/NonLoadedAssociation.js';
+export { default as CannotSaveMissingDream } from '../errors/CannotSaveMissingDream.js';
 export { default as CreateOrFindByFailedToCreateAndFind } from '../errors/CreateOrFindByFailedToCreateAndFind.js';
 export { default as CheckConstraintViolation } from '../errors/db/CheckConstraintViolation.js';
 export { default as ColumnOverflow } from '../errors/db/ColumnOverflow.js';
 export { default as DataIncompatibleWithDatabaseField } from '../errors/db/DataIncompatibleWithDatabaseField.js';
 export { default as DataTypeColumnTypeMismatch } from '../errors/db/DataTypeColumnTypeMismatch.js';
 export { default as NotNullViolation } from '../errors/db/NotNullViolation.js';
+// Raised by the framework packages layered on Dream, not only by Dream: psychic
+// (`src/controller/index.ts`) raises it for a controller's global name, and
+// psychic-workers (`src/background/BaseBackgroundedService.ts`,
+// `src/background/BaseScheduledService.ts`) for service global names. Both reach it
+// through this entry point, so unexporting it breaks the build of every application
+// that installs either package.
 export { default as GlobalNameNotSet } from '../errors/dream-app/GlobalNameNotSet.js';
 export { default as DecryptionError } from '../errors/encrypt/DecryptionError.js';
 export { default as DecryptionParseError } from '../errors/encrypt/DecryptionParseError.js';
 export { default as DecryptionRotationError } from '../errors/encrypt/DecryptionRotationError.js';
 export { default as RecordNotFound } from '../errors/RecordNotFound.js';
+// Caught through this entry point by psychic
+// (`test-app/src/app/controllers/SerializerTestsController.ts`), which distinguishes it
+// to prove a controller can render a missing-serializers failure as a response.
 export { default as MissingSerializersDefinition } from '../errors/serializers/MissingSerializersDefinition.js';
-export { default as SortableBatchRequiresTooManyScopeLocks } from '../errors/SortableBatchRequiresTooManyScopeLocks.js';
 export { default as SortableScopeDidNotStabilize } from '../errors/SortableScopeDidNotStabilize.js';
 export { default as SortableScopeLockWaitTimedOut } from '../errors/SortableScopeLockWaitTimedOut.js';
 export { default as ValidationError } from '../errors/ValidationError.js';

package/dist/esm/src/Dream.js

@@ -16,7 +16,7 @@ import loadedOrLoadAssociation from './dream/internal/associations/loadedOrLoadA
 import undestroyAssociation from './dream/internal/associations/undestroyAssociation.js';
 import associationStringToNameAndAlias from './dream/internal/associationStringToNameAndAlias.js';
 import destroyDream from './dream/internal/destroyDream.js';
-import { destroyOptions, reallyDestroyOptions, undestroyOptions, } from './dream/internal/destroyOptions.js';
+import { destroyOptions, reallyDestroyOptions, undestroyOptions } from './dream/internal/destroyOptions.js';
 import ensureSTITypeFieldIsSet from './dream/internal/ensureSTITypeFieldIsSet.js';
 import findOrCreateBy from './dream/internal/findOrCreateBy.js';
 import mergeSerializerAssociationEdges from './dream/internal/mergeSerializerAssociationEdges.js';

package/dist/esm/src/decorators/Decorators.js

@@ -147,18 +147,93 @@ export default class Decorators {
         return Scope(opts);
     }
     /**
-     * The Sortable decorator automatically adjusts the value of the columns
-     * corresponding to the decorated field.
-     *
-     * NOTE: the Sortable decorator may not be used in STI child models (it may be used in the STI base class)
+     * Marks an integer column as a sortable position: Dream keeps the positions of
+     * every record in a sort scope contiguous, starting at 1, as records are
+     * created, moved, destroyed and undestroyed.
      *
      * ```ts
-     * class Balloon {
+     * class Post extends ApplicationModel {
      *   @deco.Sortable({ scope: 'user' })
-     *   public position: DreamColumn<Balloon, 'position'>
+     *   public position: number
      * }
+     *
+     * await post.update({ position: 2 }) // the records at 2 and above shift up
      * ```
      *
+     * A position past the end of the scope is clamped to the end, and a position
+     * below 1 — or none at all — lands the record at the end.
+     *
+     * **A save that changes the sort scope ignores a position given alongside it.**
+     * The record lands at the end of the scope it moves into, whatever position the
+     * same `update` supplied:
+     *
+     * ```ts
+     * await post.update({ user: otherUser, position: 1 })
+     * // post is now the last record in otherUser's scope, not the first
+     * ```
+     *
+     * Move it in two saves to place it: `await post.update({ user: otherUser })`,
+     * then `await post.update({ position: 1 })`.
+     *
+     * Sortable requires a query driver that supports advisory transaction locks —
+     * the `PostgresQueryDriver` does — since every position write serializes the
+     * writers of its sort scope on one. This concurrency guarantee first shipped
+     * in Dream 2.28.0 and begins only after every writer is running a lock-aware
+     * release. During the first rolling deployment, older processes take no
+     * advisory locks and can still race the upgraded processes.
+     *
+     * All participating Dream writers of one hot scope serialize. Ordinary saves
+     * and destroys with `skipHooks`, direct query writes, raw SQL, and older
+     * pre-lock Dream processes bypass Sortable maintenance and do not participate
+     * in its locking protocol. Undestroy still performs stabilized Sortable
+     * maintenance and acquires scope locks with `skipHooks: true`; locked query
+     * batches likewise acquire their scope locks during preflight, before any
+     * per-record callbacks, even when those callbacks skip hooks. A waiter that
+     * enters the protocol holds a pooled connection until the holder finishes or
+     * `sortableScopeLockTimeout` expires; sustained contention can therefore
+     * produce latency waves, timeouts, and pool starvation. Keep database work
+     * inside the lock window short, and avoid cross-region database latency for
+     * hot scopes.
+     *
+     * `SortableScopeDidNotStabilize` and `SortableScopeLockWaitTimedOut` are the
+     * expected Dream errors an application may choose to retry. Database deadlocks
+     * remain native adapter errors (for example PostgreSQL code `40P01` or MySQL
+     * errno `1213`) so their driver fields and stacks remain intact. A database
+     * deadlock aborts the whole transaction: retry by starting the transaction
+     * again from the beginning, never by continuing it or retrying only the failed
+     * statement. Recurrent deadlocks call for shorter transactions or a consistent
+     * multi-resource acquisition order; they do not by themselves prove Sortable
+     * caused the cycle.
+     *
+     * ```ts
+     * import {
+     *   SortableScopeDidNotStabilize,
+     *   SortableScopeLockWaitTimedOut,
+     * } from '@rvoh/dream/errors'
+     *
+     * const runTransaction = async () =>
+     *   await ApplicationModel.transaction(async txn => {
+     *     // bind every operation in the attempt to txn
+     *   })
+     *
+     * try {
+     *   await runTransaction()
+     * } catch (error) {
+     *   const adapterDeadlock =
+     *     (error as { code?: string }).code === '40P01' ||
+     *     (error as { errno?: number }).errno === 1213
+     *   const retryable =
+     *     error instanceof SortableScopeDidNotStabilize ||
+     *     error instanceof SortableScopeLockWaitTimedOut ||
+     *     adapterDeadlock
+     *   if (!retryable) throw error
+     *
+     *   await runTransaction() // one whole-transaction retry
+     * }
+     * ```
+     *
+     * NOTE: the Sortable decorator may not be used in STI child models (it may be used in the STI base class)
+     *
      * @param opts - Configuration options for the sortable decorator
      * @param opts.scope - The column, association, or combination thereof which you would like to restrict the incrementing logic to. Can be a single column name, a single belongs-to association name, or an array of column/association names
      * @returns A Sortable decorator

package/dist/esm/src/decorators/field/sortable/Sortable.js

@@ -1,36 +1,9 @@
 import scopeArray from './helpers/scopeArray.js';
 /**
- * Marks an integer column as a sortable position: Dream keeps the positions of
- * every record in a sort scope contiguous, starting at 1, as records are
- * created, moved, destroyed and undestroyed.
- *
- * ```ts
- * class Post extends ApplicationModel {
- *   @deco.Sortable({ scope: 'user' })
- *   public position: number
- * }
- *
- * await post.update({ position: 2 }) // the records at 2 and above shift up
- * ```
- *
- * A position past the end of the scope is clamped to the end, and a position
- * below 1 — or none at all — lands the record at the end.
- *
- * **A save that changes the sort scope ignores a position given alongside it.**
- * The record lands at the end of the scope it moves into, whatever position the
- * same `update` supplied:
- *
- * ```ts
- * await post.update({ user: otherUser, position: 1 })
- * // post is now the last record in otherUser's scope, not the first
- * ```
- *
- * Move it in two saves to place it: `await post.update({ user: otherUser })`,
- * then `await post.update({ position: 1 })`.
- *
- * Sortable requires a query driver that supports advisory transaction locks —
- * the `PostgresQueryDriver` does — since every position write serializes the
- * writers of its sort scope on one.
+ * The implementation behind `@deco.Sortable`. The decorator's semantics —
+ * position clamping, what a scope-changing save does with a position given
+ * alongside it, and the advisory-lock concurrency protocol — are documented on
+ * `Decorators#Sortable`, which is where a consumer reads them.
  */
 export default function Sortable(opts = {}) {
     return function (_, context) {

package/dist/esm/src/decorators/field/sortable/helpers/setPosition.js

@@ -1,3 +1,5 @@
+import installPersistedAttribute from '../../../../dream/internal/installPersistedAttribute.js';
+import RecordNotFound from '../../../../errors/RecordNotFound.js';
 import range from '../../../../helpers/range.js';
 import ops from '../../../../ops/index.js';
 import acquireSortableScopeLocks from './acquireSortableScopeLocks.js';
@@ -9,9 +11,16 @@ import { invalidateSortableRowCache } from './sortableRowCache.js';
 import { snapshotScopeValue } from './sortableSnapshot.js';
 import validPosition from './validPosition.js';
 export default async function setPosition(obj) {
-    const { dream, txn } = obj;
     await applyUpdates(obj);
-    await dream.txn(txn).reload();
+    await refreshPosition(obj);
+}
+async function refreshPosition({ dream, positionField, query }) {
+    const positions = await query['removeAllDefaultScopes']()
+        .where({ [dream['_primaryKey']]: dream.primaryKeyValue() })
+        .pluck(positionField);
+    if (!positions.length)
+        throw new RecordNotFound(dream['sanitizedConstructorName']);
+    installPersistedAttribute(dream, positionField, positions[0]);
 }
 async function applyUpdates(obj) {
     const { dream, positionField, scope, txn } = obj;

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

@@ -10,7 +10,7 @@ import destroyAssociation from './internal/associations/destroyAssociation.js';
 import loadedOrLoadAssociation from './internal/associations/loadedOrLoadAssociation.js';
 import undestroyAssociation from './internal/associations/undestroyAssociation.js';
 import destroyDream from './internal/destroyDream.js';
-import { destroyOptions, reallyDestroyOptions, undestroyOptions, } from './internal/destroyOptions.js';
+import { destroyOptions, reallyDestroyOptions, undestroyOptions } from './internal/destroyOptions.js';
 import reload from './internal/reload.js';
 import saveDream from './internal/saveDream.js';
 import { DEFAULT_BYPASS_ALL_DEFAULT_SCOPES, DEFAULT_DEFAULT_SCOPES_TO_BYPASS, DEFAULT_SKIP_HOOKS, } from './internal/scopeHelpers.js';

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

@@ -1914,13 +1914,15 @@ export default class Query {
      *   {@link Query.delete | delete} (a single statement, no hooks or cascade)
      *   are the right tools for bulk removal.
      *
+     * To bypass a default scope, chain `removeDefaultScope` onto the Query
+     * before calling this method; it is Query state, not an option, and it
+     * carries through to the cascade.
+     *
      * @param options - Options for destroying the instance
      * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
      * @param options.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. Defaults to false
      * @param options.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when cascade destroying; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
@@ -2034,11 +2036,12 @@ export default class Query {
      *   transaction ends, so every batch's scope keys are still held when the
      *   next one preflights. That accumulation is bounded — the preflight counts
      *   the keys the transaction already holds along with the ones the batch
-     *   would add, and refuses with `SortableBatchRequiresTooManyScopeLocks`
-     *   rather than letting a long run over a high-cardinality sort scope exhaust
-     *   `max_locks_per_transaction` for the whole cluster — so a run long enough
-     *   raises instead of completing. Letting Dream open a transaction per batch
-     *   releases the keys as it goes and gives each batch the whole budget.
+     *   would add, and raises rather than letting a long run over a
+     *   high-cardinality sort scope exhaust `max_locks_per_transaction` for the
+     *   whole cluster — so a run long enough raises instead of completing. That
+     *   refusal is a sizing failure to fix, not a condition to catch: letting
+     *   Dream open a transaction per batch releases the keys as it goes and gives
+     *   each batch the whole budget, and a smaller `batchSize` takes fewer.
      * - the preflight covers **the claimed rows' own scopes only**. A
      *   `dependent: 'destroy'` cascade under `destroy({ lock: true })` destroys
      *   child records of other tables, and a sortable child takes its own table's
@@ -2116,8 +2119,18 @@ export default class Query {
     }
     /**
      * Destroys all records matching the Query,
-     * ignoring the SoftDelete decorator and
-     * permanently removing records from the database.
+     * permanently removing each matched record from
+     * the database instead of soft deleting it.
+     *
+     * The SoftDelete decorator is bypassed when
+     * deleting each matched record, not when
+     * matching: the Query selects under its default
+     * scopes, `dream:SoftDelete` among them, so on a
+     * SoftDelete model it matches only records that
+     * have not already been soft deleted. Reaching
+     * soft deleted records takes
+     * `removeDefaultScope('dream:SoftDelete')` on
+     * the Query.
      *
      * Calls model hooks and applies cascade destroy
      * to associations with `dependent: 'destroy'`,
@@ -2132,17 +2145,26 @@ export default class Query {
      * // 12
      * ```
      *
+     * ```ts
+     * await User.removeDefaultScope('dream:SoftDelete')
+     *   .where({ email: ops.ilike('%burpcollaborator%') })
+     *   .reallyDestroy()
+     * // 12
+     * ```
+     *
      * A `limit` or `offset` on the Query is incompatible with `reallyDestroy`,
      * exactly as it is with {@link Query.destroy}: a limit- or offset-carrying
      * Query throws at runtime.
      *
+     * To bypass a default scope, chain `removeDefaultScope` onto the Query
+     * before calling this method; it is Query state, not an option, and it
+     * carries through to the cascade.
+     *
      * @param options - Options for destroying the instance
      * @param options.skipHooks - If true, skips applying model hooks during the destroy operation. Defaults to false
      * @param options.cascade - If false, skips destroying associations marked `dependent: 'destroy'`. Defaults to true
      * @param options.lock - If true, each batch is re-selected with an exclusive row lock inside its own transaction before being destroyed, making the destroy a compare-and-set. See {@link Query.destroy} for the full semantics. Defaults to false
      * @param options.batchSize - The number of records to process per batch. Must be a positive integer. Defaults to 10 when `lock` is true, and to 1000 otherwise
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when cascade destroying; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The number of records that were removed
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
@@ -2168,11 +2190,13 @@ export default class Query {
      * re-applied to every window — so a limit- or offset-carrying Query throws
      * at runtime.
      *
+     * To bypass a default scope, chain `removeDefaultScope` onto the Query
+     * before calling this method; it is Query state, not an option, and it
+     * carries through to the cascade. The SoftDelete scope is always bypassed.
+     *
      * @param options - Options for undestroying the instance
      * @param options.skipHooks - If true, skips applying model hooks during the undestroy operation. Defaults to false
      * @param options.cascade - If false, skips undestroying associations marked `dependent: 'destroy'`. Defaults to true
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when cascade undestroying; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade undestroying (soft delete is always bypassed). Defaults to an empty array
      * @returns The number of records that were removed
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
      */

package/dist/esm/src/dream/QueryDriver/Kysely.js

@@ -7,7 +7,7 @@
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore
 import pg from 'pg';
-import { PostgresDialect, sql, } from 'kysely';
+import { NoResultError, PostgresDialect, sql, } from 'kysely';
 import pluralize from 'pluralize-esm';
 import { CliFileWriter } from '../../cli/CliFileWriter.js';
 import DreamCLI from '../../cli/index.js';
@@ -21,6 +21,7 @@ import DreamApp from '../../dream-app/index.js';
 import Dream from '../../Dream.js';
 import ArrayTargetIncompatibleWithThroughAssociation from '../../errors/associations/ArrayTargetIncompatibleWithThroughAssociation.js';
 import CannotJoinPolymorphicBelongsToError from '../../errors/associations/CannotJoinPolymorphicBelongsToError.js';
+import IncompatibleThroughAssociationTarget from '../../errors/associations/IncompatibleThroughAssociationTarget.js';
 import JoinAttemptedOnMissingAssociation from '../../errors/associations/JoinAttemptedOnMissingAssociation.js';
 import MissingRequiredAssociationAndClause from '../../errors/associations/MissingRequiredAssociationAndClause.js';
 import MissingRequiredPassthroughForAssociationAndClause from '../../errors/associations/MissingRequiredPassthroughForAssociationAndClause.js';
@@ -29,6 +30,7 @@ import MissingThroughAssociationSource from '../../errors/associations/MissingTh
 import CannotNegateSimilarityClause from '../../errors/CannotNegateSimilarityClause.js';
 import CannotNamespaceAssociationFilterToAnotherTable from '../../errors/CannotNamespaceAssociationFilterToAnotherTable.js';
 import CannotPassUndefinedAsAValueToAWhereClause from '../../errors/CannotPassUndefinedAsAValueToAWhereClause.js';
+import CannotSaveMissingDream from '../../errors/CannotSaveMissingDream.js';
 import ArrayEqualityRequiresArrayColumn from '../../errors/ops/ArrayEqualityRequiresArrayColumn.js';
 import RowLockIncompatibleWithDistinct from '../../errors/RowLockIncompatibleWithDistinct.js';
 import RowLockIncompatibleWithJoinLoad from '../../errors/RowLockIncompatibleWithJoinLoad.js';
@@ -805,6 +807,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             }
         }
         catch (error) {
+            if (dream.isPersisted && error instanceof NoResultError)
+                throw new CannotSaveMissingDream(dream);
             switch (pgErrorType(error)) {
                 case COLUMN_OVERFLOW:
                     throw new ColumnOverflow(error instanceof Error ? error : new Error('database column overflow'));
@@ -1547,7 +1551,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 joinAndStatement,
                 joinType,
                 previousThroughAssociations: [],
-                dreamClassThroughAssociationWantsToHydrate: undefined,
+                polymorphicSourceTargetModelClass: undefined,
             });
             query = results.query;
             /**
@@ -1976,7 +1980,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 joinAndStatement: {},
                 previousThroughAssociations: [],
                 joinType,
-                dreamClassThroughAssociationWantsToHydrate: undefined,
+                polymorphicSourceTargetModelClass: undefined,
             });
         }
         const associatedDreamClass = associationReferencedByThroughAssociation.modelCB();
@@ -1992,12 +1996,24 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 association: throughAssociation,
                 throughClass: associatedDreamClass,
             });
+        const outermostThroughAssociation = previousThroughAssociations[0]?.association ?? throughAssociation;
+        const outermostTargetModelClass = outermostThroughAssociation.modelCB();
+        const sourceTargetModelClassOrClasses = sourceAssociation.modelCB();
+        const sourceTargetModelClasses = Array.isArray(sourceTargetModelClassOrClasses)
+            ? sourceTargetModelClassOrClasses
+            : [sourceTargetModelClassOrClasses];
+        if (!sourceTargetModelClasses.some(sourceTargetModelClass => outermostTargetModelClass.typeof(sourceTargetModelClass)))
+            throw new IncompatibleThroughAssociationTarget({
+                outermostAssociation: outermostThroughAssociation,
+                outermostTargetModelClass,
+                sourceAssociation,
+            });
         /**
-         * When the source is a polymorphic BelongsTo association, use the target of the through
-         * association to determine which class to target.
+         * A polymorphic source can accept several model classes. The outermost
+         * association target selects the one this through chain is following.
          */
-        const dreamClassThroughAssociationWantsToHydrate = Array.isArray(sourceAssociation.modelCB())
-            ? throughAssociation.modelCB()
+        const polymorphicSourceTargetModelClass = Array.isArray(sourceTargetModelClassOrClasses)
+            ? outermostTargetModelClass
             : undefined;
         /**
          * Add the source that `sourceAssociation` points to. Note that since joinsBridgeThroughAssociations
@@ -2031,7 +2047,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 { association: throughAssociation, selfTableAlias: previousTableAlias },
             ],
             joinType,
-            dreamClassThroughAssociationWantsToHydrate,
+            polymorphicSourceTargetModelClass,
         });
     }
     applyOneJoin({ query, dreamClass, association, 
@@ -2054,7 +2070,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     /**
      * previousTableAlias is always set
      */
-    previousTableAlias, selfTableAlias = previousTableAlias, joinAndStatement = {}, previousThroughAssociations, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
+    previousTableAlias, selfTableAlias = previousTableAlias, joinAndStatement = {}, previousThroughAssociations, joinType, polymorphicSourceTargetModelClass, }) {
         if (association.type !== 'BelongsTo' && association.through) {
             return this.joinsBridgeThroughAssociations({
                 query,
@@ -2077,7 +2093,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             joinAndStatement,
             previousThroughAssociations,
             joinType,
-            dreamClassThroughAssociationWantsToHydrate,
+            polymorphicSourceTargetModelClass,
         });
     }
     addAssociationJoinStatementToQuery({ query, dreamClass, association, 
@@ -2100,12 +2116,38 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     /**
      * previousTableAlias is always set
      */
-    previousTableAlias, selfTableAlias, joinAndStatement, previousThroughAssociations, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
+    previousTableAlias, selfTableAlias, joinAndStatement, previousThroughAssociations, joinType, polymorphicSourceTargetModelClass, }) {
         const currentTableAlias = explicitAlias ?? association.as;
-        const _associatedDreamClass = association.modelCB();
-        const associatedDreamClass = Array.isArray(_associatedDreamClass)
-            ? _associatedDreamClass[0]
-            : _associatedDreamClass;
+        const associationModelClassOrPolymorphicModelClasses = association.modelCB();
+        const modelClassUsedForJoinConditions = Array.isArray(associationModelClassOrPolymorphicModelClasses)
+            ? associationModelClassOrPolymorphicModelClasses[0]
+            : associationModelClassOrPolymorphicModelClasses;
+        /**
+         * The outermost through association defines what callers expect this join to
+         * return, so its target is the single owner of the target table's default
+         * scopes. Inner associations describe how to reach that table; the
+         * compatibility check in `joinsBridgeThroughAssociations` ensures they can
+         * actually return the outer target.
+         *
+         * For example, BearBnB already defines `Host.places` and `Place.rooms`. It
+         * could expose only bedrooms from a host without adding `Place.bedrooms`:
+         *
+         *   // Place.ts
+         *   @deco.HasMany('Room')
+         *   public rooms: Room[]
+         *
+         *   // Host.ts
+         *   @deco.HasMany('Room/Bedroom', { through: 'places', source: 'rooms' })
+         *   public bedrooms: Bedroom[]
+         *
+         * `Host.bedrooms` is the outermost association, so Bedroom's `dream:STI`
+         * scope is applied once to the final rooms join. Bedroom is a subclass of
+         * Room, so `Place.rooms` is a compatible path. Reversing those targets, or
+         * mixing sibling STI children, raises instead of silently changing meaning.
+         */
+        const modelClassWhoseDefaultScopesApplyToJoin = previousThroughAssociations[0]?.association.modelCB() ??
+            polymorphicSourceTargetModelClass ??
+            modelClassUsedForJoinConditions;
         /**
          * Stacked order/distinct clauses are applied in join order: the options of
          * the through association whose bridging joins were added to the query
@@ -2131,22 +2173,22 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             }
         }
         if (association.type === 'BelongsTo') {
-            if (!dreamClassThroughAssociationWantsToHydrate && Array.isArray(association.modelCB()))
+            if (!polymorphicSourceTargetModelClass && Array.isArray(association.modelCB()))
                 throw new CannotJoinPolymorphicBelongsToError({
                     dreamClass,
                     association,
                     innerJoinStatements: this.query['innerJoinStatements'],
                     leftJoinStatements: this.query['leftJoinStatements'],
                 });
-            const to = (dreamClassThroughAssociationWantsToHydrate ?? association.modelCB()).table;
+            const to = (polymorphicSourceTargetModelClass ?? association.modelCB()).table;
             const joinTableExpression = this.aliasedJoinTableExpression(to, currentTableAlias);
             query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
                 join = join.onRef(this.namespaceColumn(association.foreignKey(), previousTableAlias), '=', this.namespaceColumn(association.primaryKey(undefined, {
-                    associatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
+                    associatedClassOverride: polymorphicSourceTargetModelClass,
                 }), currentTableAlias));
-                if (dreamClassThroughAssociationWantsToHydrate) {
+                if (polymorphicSourceTargetModelClass) {
                     join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement({
-                        [association.foreignKeyTypeField()]: dreamClassThroughAssociationWantsToHydrate.sanitizedName,
+                        [association.foreignKeyTypeField()]: polymorphicSourceTargetModelClass.sanitizedName,
                     }, previousTableAlias)));
                 }
                 join = this.applyPreviousThroughAssociationAndStatementsToJoinStatement({
@@ -2156,14 +2198,14 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     currentTableAlias,
                     joinAndStatement,
                 });
-                join = this.conditionallyApplyDefaultScopesDependentOnAssociation({
+                join = this.applyAssociationDefaultScopesToJoin({
                     dreamClass,
                     join,
                     tableNameOrAlias: currentTableAlias,
                     association,
-                    throughAssociatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
+                    modelClassWhoseDefaultScopesApply: modelClassWhoseDefaultScopesApplyToJoin,
                 });
-                join = this.applyJoinAndStatement(associatedDreamClass, join, joinAndStatement, currentTableAlias);
+                join = this.applyJoinAndStatement(modelClassUsedForJoinConditions, join, joinAndStatement, currentTableAlias);
                 return join;
             });
         }
@@ -2174,8 +2216,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 join = join.onRef(this.namespaceColumn(association.primaryKey(), previousTableAlias), '=', this.namespaceColumn(association.foreignKey(), currentTableAlias));
                 if (association.polymorphic) {
                     join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement({
-                        [association.foreignKeyTypeField()]: dreamClassThroughAssociationWantsToHydrate
-                            ? dreamClassThroughAssociationWantsToHydrate.referenceTypeString
+                        [association.foreignKeyTypeField()]: polymorphicSourceTargetModelClass
+                            ? polymorphicSourceTargetModelClass.referenceTypeString
                             : dreamClass.referenceTypeString,
                     }, currentTableAlias)));
                 }
@@ -2194,14 +2236,14 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     selfTableAlias,
                     joinAndStatement,
                 });
-                join = this.conditionallyApplyDefaultScopesDependentOnAssociation({
+                join = this.applyAssociationDefaultScopesToJoin({
                     dreamClass,
                     join,
                     tableNameOrAlias: currentTableAlias,
                     association,
-                    throughAssociatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
+                    modelClassWhoseDefaultScopesApply: modelClassWhoseDefaultScopesApplyToJoin,
                 });
-                join = this.applyJoinAndStatement(associatedDreamClass, join, joinAndStatement, currentTableAlias);
+                join = this.applyJoinAndStatement(modelClassUsedForJoinConditions, join, joinAndStatement, currentTableAlias);
                 return join;
             });
             if (association.type === 'HasMany') {
@@ -2312,11 +2354,9 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         if (missingRequiredWhereStatements.length)
             throw new MissingRequiredAssociationAndClause(association, missingRequiredWhereStatements[0]);
     }
-    conditionallyApplyDefaultScopesDependentOnAssociation({ dreamClass, join, tableNameOrAlias, association, throughAssociatedClassOverride, }) {
+    applyAssociationDefaultScopesToJoin({ dreamClass, join, tableNameOrAlias, association, modelClassWhoseDefaultScopesApply, }) {
         let scopesQuery = new Query(this.dreamInstance);
-        const associationClass = throughAssociatedClassOverride ?? association.modelCB();
-        const associationScopes = associationClass['scopes'].default;
-        for (const scope of associationScopes) {
+        for (const scope of modelClassWhoseDefaultScopesApply['scopes'].default) {
             if (!shouldBypassDefaultScope(scope.method, {
                 bypassAllDefaultScopes: this.query['bypassAllDefaultScopes'],
                 defaultScopesToBypass: [
@@ -2324,7 +2364,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     ...(association.withoutDefaultScopes || []),
                 ],
             })) {
-                const tempQuery = associationClass[scope.method](scopesQuery);
+                const tempQuery = modelClassWhoseDefaultScopesApply[scope.method](scopesQuery);
                 // The scope method on a Dream model should return a clone of the Query it receives
                 // (e.g. by returning `scope.where(...)`), but in case the function doesn't return,
                 // or returns the wrong thing, we check before overriding `scopesQuery` with what the

package/dist/esm/src/dream/internal/associations/loadedOrLoadAssociation.js

@@ -5,6 +5,8 @@ export default async function loadedOrLoadAssociation(dream, dreamOrTransactionB
         let scope = dreamOrTransactionBuilder.associationQuery(associationName, associationQueryOptions);
         if (options?.passthrough)
             scope = scope.passthrough(options.passthrough);
+        if (options?.connection)
+            scope = scope.connection(options.connection);
         if (association?.type === 'HasMany') {
             dream[associationName] = (await scope.all());
         }

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

@@ -0,0 +1,9 @@
+/**
+ * Installs one database-sourced scalar as the persisted value without
+ * replacing the saved-change history established by the current save.
+ */
+export default function installPersistedAttribute(dream, column, val) {
+    dream['currentAttributes'][column] = val;
+    dream['frozenAttributes'][column] = val;
+    dream['originalAttributes'][column] = val;
+}

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

@@ -0,0 +1 @@
+export {};