velocious 1.0.593 → 1.0.594

package/README.md

@@ -20,7 +20,7 @@
 * Self-sustaining sync feeds: upstream imports triggered by the changes pull itself, with framework-owned coalescing and throttling (see [docs/sync-upstream-imports.md](docs/sync-upstream-imports.md))
 * AwesomeTasks-shaped offline sync proof using routed resources, domain commands, signed offline grants, and peer-forwarded mutations (see the [developer guide](docs/shared-resource-sync-guide.md) and [proof](docs/awesome-tasks-offline-sync-proof.md))
 * SQLite web persistence that automatically prefers OPFS, then IndexedDB, and migrates legacy persisted bytes when possible (see [docs/sqlite-web-persistence.md](docs/sqlite-web-persistence.md))
-* Bounded frontend tenant SQLite handles with durable flush/close, backend-complete deletion, clean-only LRU eviction, and scoped pins (see [docs/frontend-tenant-sqlite-lifecycle.md](docs/frontend-tenant-sqlite-lifecycle.md))
+* Bounded frontend tenant SQLite handles with independently deduplicated per-database migrations/model readiness, React lifecycle integration, durable flush/close, backend-complete deletion, clean-only LRU eviction, and scoped pins (see [docs/frontend-tenant-sqlite-lifecycle.md](docs/frontend-tenant-sqlite-lifecycle.md))
 * Expo / Metro compatibility guidance and a real Expo export check (see [docs/expo-metro-compatibility.md](docs/expo-metro-compatibility.md))
 * Gap-less positional lists with automatic reordering via `actsAsList`, including models with numeric, string, or UUID primary keys (see [docs/acts-as-list.md](docs/acts-as-list.md))
 * Rails-style nested-attribute writes on frontend-model `save()` (see [docs/nested-attributes.md](docs/nested-attributes.md))
@@ -955,7 +955,8 @@ Translated models also get a `currentTranslation` `hasOne` relationship scoped t
 Async class APIs initialize record metadata on first use when a model has not
 already been initialized eagerly. See [docs/model-initialization.md](docs/model-initialization.md)
 for the eager and lazy initialization behavior, including atomic shared bootstrap
-and complete recovery after an eager initialization failure.
+and complete recovery after an eager initialization failure or database-connection
+closure without overlapping stale and current bootstrap side effects.
 
 ## Lifecycle callbacks
 

package/build/configuration.js

@@ -302,8 +302,9 @@ export default class VelociousConfiguration {
      */
     this._initializeModelsPromise = undefined
     /**
-     * In-progress `initialize()` promise, memoized so concurrent callers await
-     * the same bootstrap. Reset to undefined if initialization fails.
+     * Current `initialize()` promise, memoized so concurrent callers await the
+     * same bootstrap. Retained across a connection close until stale bootstrap
+     * work settles, then cleared by identity before the new generation retries.
      * @type {Promise<void> | undefined}
      */
     this._initializePromise = undefined
@@ -1102,6 +1103,18 @@ export default class VelociousConfiguration {
     }
   }
 
+  /**
+   * Invalidates record metadata owned by one closed/deleted physical tenant
+   * database while preserving every other tenant generation.
+   * @param {string} databaseIdentity - Logical identifier plus pool reuse key.
+   * @returns {void}
+   */
+  clearRecordMetadataForDatabaseIdentity(databaseIdentity) {
+    for (const modelClass of Object.values(this.modelClasses)) {
+      modelClass.clearRecordMetadataValuesForDatabaseIdentity(databaseIdentity)
+    }
+  }
+
   /**
    * Runs get database pool type.
    * @param {string} identifier - Identifier.
@@ -2054,10 +2067,25 @@ export default class VelociousConfiguration {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async initializeModels(args = {type: "server"}) {
+    const modelInitializationGeneration = this._modelInitializationGeneration
+
     if (this._modelsInitialized) return
-    if (this._initializeModelsPromise) return await this._initializeModelsPromise
+    if (this._initializeModelsPromise) {
+      const initializeModelsPromise = this._initializeModelsPromise
+
+      await initializeModelsPromise
+
+      if (this._modelInitializationGeneration === modelInitializationGeneration && !this._modelsInitialized) {
+        if (this._initializeModelsPromise === initializeModelsPromise) {
+          this._initializeModelsPromise = undefined
+        }
+
+        return await this.initializeModels(args)
+      }
+
+      return
+    }
 
-    const modelInitializationGeneration = this._modelInitializationGeneration
     const initializeModelsPromise = (async () => {
       const shouldSkipDummyModelInitialization = process.env.VELOCIOUS_SKIP_DUMMY_MODEL_INITIALIZATION === "1"
         && process.env.VELOCIOUS_BROWSER_TESTS === "true"
@@ -2110,6 +2138,12 @@ export default class VelociousConfiguration {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async initialize({type} = {type: "undefined"}) {
+    if (this._closeDatabaseConnectionsPromise) {
+      await this._closeDatabaseConnectionsPromise
+    }
+
+    const initializationGeneration = this._modelInitializationGeneration
+
     if (this._isInitialized) return
     // Memoize the in-progress initialization so concurrent callers await the same
     // bootstrap instead of racing. `_isInitialized` was previously set to `true`
@@ -2117,15 +2151,29 @@ export default class VelociousConfiguration {
     // `pooledRunnerConcurrency > 1` starting several jobs on a cold child) could
     // skip initialization and load models / perform a job while the first call
     // was still awaiting model discovery and initializers. Mirrors connectBeacon.
-    if (this._initializePromise) return await this._initializePromise
+    if (this._initializePromise) {
+      const initializePromise = this._initializePromise
 
-    this._initializePromise = (async () => {
+      await initializePromise
+
+      if (this._modelInitializationGeneration === initializationGeneration && !this._isInitialized) {
+        if (this._initializePromise === initializePromise) {
+          this._initializePromise = undefined
+        }
+
+        return await this.initialize({type})
+      }
+
+      return
+    }
+
+    const initializePromise = (async () => {
       await this.initializeModels({type})
 
       // Model initialization can be invalidated by a concurrent connection close.
       // If models are not ready, stop without marking the configuration initialized
       // so the next caller retries a full bootstrap.
-      if (!this._modelsInitialized) return
+      if (this._modelInitializationGeneration !== initializationGeneration || !this._modelsInitialized) return
 
       await this.getEnvironmentHandler().autoDiscoverResources(this)
       this._mergeDiscoveredAbilityResources()
@@ -2147,22 +2195,28 @@ export default class VelociousConfiguration {
         }
       }
 
-      this._isInitialized = true
+      if (this._modelInitializationGeneration === initializationGeneration) {
+        this._isInitialized = true
+      }
     })()
 
+    this._initializePromise = initializePromise
+
     try {
-      await this._initializePromise
+      await initializePromise
     } catch (error) {
       // Let a later call retry a failed initialization instead of every future
       // caller awaiting the same cached rejection.
-      this._initializePromise = undefined
+      if (this._initializePromise === initializePromise) {
+        this._initializePromise = undefined
+      }
       throw error
     }
 
     // If the inner IIFE returned without marking the configuration initialized
     // (e.g. because models were invalidated mid-bootstrap), clear the promise so
     // a later call retries a full bootstrap.
-    if (!this._isInitialized) {
+    if (!this._isInitialized && this._initializePromise === initializePromise) {
       this._initializePromise = undefined
     }
   }
@@ -3072,11 +3126,11 @@ export default class VelociousConfiguration {
    * database configuration. No ambient tenant value is read during checkout or
    * execution.
    * @template T
-   * @param {{databaseConfiguration: import("./configuration-types.js").DatabaseConfigurationType, databaseIdentifier: string, name?: string, tenant?: object}} options - Captured operation options.
+   * @param {{databaseConfiguration: import("./configuration-types.js").DatabaseConfigurationType, databaseIdentifier: string, name?: string, schemaGeneration?: string, tenant?: object}} options - Captured operation options.
    * @param {(operation: DatabaseOperation) => Promise<T>} callback - Operation callback.
    * @returns {Promise<T>} - Callback result.
    */
-  async withDatabaseOperation({databaseConfiguration, databaseIdentifier, name = "Configuration.withDatabaseOperation", tenant, ...restArgs}, callback) {
+  async withDatabaseOperation({databaseConfiguration, databaseIdentifier, name = "Configuration.withDatabaseOperation", schemaGeneration, tenant, ...restArgs}, callback) {
     restArgsError(restArgs)
 
     if (!databaseIdentifier) throw new Error("Configuration.withDatabaseOperation requires a databaseIdentifier")
@@ -3095,6 +3149,7 @@ export default class VelociousConfiguration {
         databaseIdentifier,
         enforceCurrentTenantReuseKey: false,
         owner,
+        schemaGeneration,
         tenant
       })
 

package/build/database/drivers/base.js

@@ -195,6 +195,10 @@ export default class VelociousDatabaseDriversBase {
    * Narrows the runtime value to the documented type.
    * @type {TransactionCallbackFrame[]} */
   _transactionCallbackFrames
+  /** @type {Promise<void>} */
+  _transactionCompletionPromise
+  /** @type {(() => void) | undefined} */
+  _resolveTransactionCompletion
   /**
    * Narrows the runtime value to the documented type.
    * @type {Map<string, Promise<ReturnType<typeof JSON.parse>>>} */
@@ -231,6 +235,8 @@ export default class VelociousDatabaseDriversBase {
     this.logger = new Logger(this)
     this._transactionCallbackFrames = []
     this._transactionsCount = 0
+    this._transactionCompletionPromise = Promise.resolve()
+    this._resolveTransactionCompletion = undefined
     this._transactionsActionsMutex = new Mutex()
     this._schemaCache = new Map()
   }
@@ -1426,6 +1432,12 @@ export default class VelociousDatabaseDriversBase {
    */
   insideTransaction() { return this._transactionsCount > 0 }
 
+  /**
+   * Returns the completion promise identifying the current outer transaction.
+   * @returns {Promise<void>} Resolves after that transaction commits or rolls back.
+   */
+  transactionCompletion() { return this._transactionCompletionPromise }
+
   /**
    * Runs start transaction.
    * @param {Pick<QueryOptions, "operationOwner">} [options] - Transaction ownership.
@@ -1446,6 +1458,12 @@ export default class VelociousDatabaseDriversBase {
 
         await this._startTransactionAction(options)
         this._transactionsCount++
+
+        if (this._transactionsCount === 1) {
+          this._transactionCompletionPromise = new Promise((resolve) => {
+            this._resolveTransactionCompletion = resolve
+          })
+        }
       })
 
       if (!blockingOperationLease) return
@@ -1472,9 +1490,20 @@ export default class VelociousDatabaseDriversBase {
     await this._transactionsActionsMutex.sync(async () => {
       await this._commitTransactionAction(options)
       this._transactionsCount--
+      this._resolveCompletedTransaction()
     })
   }
 
+  /** Resolves the current outer transaction completion when it has finished. */
+  _resolveCompletedTransaction() {
+    if (this._transactionsCount !== 0) return
+
+    const resolve = this._resolveTransactionCompletion
+
+    this._resolveTransactionCompletion = undefined
+    if (resolve) resolve()
+  }
+
   /**
    * Runs commit transaction action.
    * @param {Pick<QueryOptions, "operationOwner">} [options] - Transaction ownership.
@@ -2091,6 +2120,7 @@ export default class VelociousDatabaseDriversBase {
         await this._rollbackTransactionAction(options)
       } finally {
         this._transactionsCount--
+        this._resolveCompletedTransaction()
 
         // A rolled-back transaction may have reverted DDL (e.g. a CREATE TABLE
         // run lazily inside the transaction), so any cached schema metadata is

package/build/database/migrator.js

@@ -145,18 +145,75 @@ export default class VelociousDatabaseMigrator {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async migrateFilesFromRequireContext(requireContext) {
-    /**
-     * Files.
-     * @type {import("./migrator/types.js").MigrationObjectType[]} */
-    let files = []
+    const files = this.migrationsFromRequireContext(requireContext)
+
+    await this.configuration.ensureConnections({databaseIdentifiers: this.databaseIdentifiers, name: "Database migrator: migrate require-context files"}, async () => {
+      for (const migration of files) {
+        await this.runMigrationFile({
+          migration,
+          requireMigration: async () => requireContext(migration.file).default
+        })
+      }
+
+      await this._afterMigrations()
+    })
+  }
+
+  /**
+   * Migrates exactly one already-captured physical database. This is the
+   * frontend/tenant counterpart to the ambient multi-database entrypoints:
+   * callers own the captured connection and no configuration fallback is read.
+   * @param {object} args - Captured migration arguments.
+   * @param {import("../configuration-types.js").DatabaseConfigurationType} args.databaseConfiguration - Captured physical database configuration.
+   * @param {string} args.databaseIdentifier - Logical database identifier.
+   * @param {import("./drivers/base.js").default} args.db - Captured physical connection.
+   * @param {import("./migrator/types.js").RequireMigrationContextType} args.requireContext - Frontend migration require context.
+   * @returns {Promise<number>} - Number of newly applied migrations.
+   */
+  async migrateRequireContextForDatabase({databaseConfiguration, databaseIdentifier, db, requireContext}) {
+    if (!databaseConfiguration.migrations) return 0
+
+    await MigrationsLedger.ensureTable(db)
+    const appliedVersions = new Set(await MigrationsLedger.appliedVersions(db))
+    const migrations = this.migrationsFromRequireContext(requireContext)
+    let appliedCount = 0
+
+    for (const migration of migrations) {
+      const version = `${migration.date}`
+
+      if (appliedVersions.has(version)) continue
+
+      const MigrationClass = requireContext(migration.file).default
+
+      if (!MigrationClass || typeof MigrationClass !== "function") {
+        throw new Error(`Migration ${migration.file} must export a default migration class. Type: ${typeof MigrationClass}`)
+      }
+      if (!(MigrationClass.getDatabaseIdentifiers() || ["default"]).includes(databaseIdentifier)) continue
+
+      const migrationInstance = new MigrationClass({configuration: this.configuration, databaseIdentifier, db})
+
+      await this.runMigrationUp({migration, migrationInstance})
+      await MigrationsLedger.recordVersion(db, version)
+      appliedVersions.add(version)
+      appliedCount++
+    }
+
+    return appliedCount
+  }
+
+  /**
+   * Parses and orders migrations from a browser/native require context.
+   * @param {import("./migrator/types.js").RequireMigrationContextType} requireContext - Migration require context.
+   * @returns {import("./migrator/types.js").MigrationObjectType[]} - Ordered migrations.
+   */
+  migrationsFromRequireContext(requireContext) {
+    const migrations = []
 
     for (const file of requireContext.keys()) {
-      // "13,14" because somes "require-context"-npm-module deletes first character!?
       const match = file.match(/(\d{13,14})-(.+)\.js$/)
 
       if (!match) continue
 
-      // Fix require-context-npm-module deletes first character
       let fileName = file
       let dateNumber = match[1]
 
@@ -165,30 +222,39 @@ export default class VelociousDatabaseMigrator {
         fileName = `2${fileName}`
       }
 
-      // Parse regex
-      const date = parseInt(dateNumber)
-      const migrationName = match[2]
-      const migrationClassName = inflection.camelize(migrationName.replaceAll("-", "_"))
-
-      files.push({
+      migrations.push({
+        date: parseInt(dateNumber),
         file: fileName,
-        date,
-        migrationClassName
+        migrationClassName: inflection.camelize(match[2].replaceAll("-", "_"))
       })
     }
 
-    files = files.sort((migration1, migration2) => migration1.date - migration2.date)
+    return migrations.sort((migration1, migration2) => migration1.date - migration2.date)
+  }
 
-    await this.configuration.ensureConnections({databaseIdentifiers: this.databaseIdentifiers, name: "Database migrator: migrate require-context files"}, async () => {
-      for (const migration of files) {
-        await this.runMigrationFile({
-          migration,
-          requireMigration: async () => requireContext(migration.file).default
-        })
-      }
+  /**
+   * Runs one migration's upward implementation.
+   * @param {object} args - Migration arguments.
+   * @param {import("./migrator/types.js").MigrationObjectType} args.migration - Migration descriptor.
+   * @param {import("./migration/index.js").default} args.migrationInstance - Migration instance.
+   * @returns {Promise<void>} - Resolves after the migration succeeds.
+   */
+  async runMigrationUp({migration, migrationInstance}) {
+    try {
+      await migrationInstance.change()
+    } catch (changeError) {
+      if (!(changeError instanceof NotImplementedError)) throw changeError
+
+      try {
+        await migrationInstance.up()
+      } catch (upError) {
+        if (upError instanceof NotImplementedError) {
+          throw new Error(`'change' or 'up' didn't exist on migration: ${migration.file}`, {cause: upError})
+        }
 
-      await this._afterMigrations()
-    })
+        throw upError
+      }
+    }
   }
 
   /**

package/build/database/operation.js

@@ -17,9 +17,10 @@ export default class VelociousDatabaseOperation {
    * @param {import("./drivers/base.js").default} args.connection - Pinned physical connection.
    * @param {string} args.databaseIdentifier - Singular database identifier.
    * @param {symbol} args.owner - Opaque pool lease owner.
+   * @param {string} [args.schemaGeneration] - Tenant schema generation owning record metadata.
    * @param {object | undefined} args.tenant - Tenant descriptor captured by the owning handle.
    */
-  constructor({configuration, databaseConfiguration, configurationReuseKey, connection, databaseIdentifier, enforceCurrentTenantReuseKey = true, owner, tenant}) {
+  constructor({configuration, databaseConfiguration, configurationReuseKey, connection, databaseIdentifier, enforceCurrentTenantReuseKey = true, owner, schemaGeneration, tenant}) {
     this._active = true
     this._configuration = configuration
     this._databaseConfiguration = databaseConfiguration || configuration.resolveDatabaseConfiguration(databaseIdentifier, tenant)
@@ -27,7 +28,10 @@ export default class VelociousDatabaseOperation {
     this._databaseIdentifier = databaseIdentifier
     this._enforceCurrentTenantReuseKey = enforceCurrentTenantReuseKey
     this._physicalConnection = connection
+    this._schemaGeneration = schemaGeneration
     this._tenant = tenant
+    /** @type {WeakMap<typeof import("./record/index.js").default, typeof import("./record/index.js").default>} */
+    this._boundModelClasses = new WeakMap()
     this._connection = new OperationConnection({
       connection,
       operation: this,
@@ -45,12 +49,57 @@ export default class VelociousDatabaseOperation {
     this.assertActive()
     this.assertModel(ModelClass)
 
-    return ModelClass._newQuery({
+    return this.modelClass(ModelClass)._newQuery({
       driver: this.connection(),
       operation: this
     })
   }
 
+  /**
+   * Returns a model-class view whose schema metadata is bound to this physical
+   * database generation. Construction still produces the application's original
+   * model class, so lifecycle callbacks and model registries retain class identity.
+   * @template {typeof import("./record/index.js").default} MC
+   * @param {MC} ModelClass - Canonical model class.
+   * @returns {MC} - Operation-bound model class.
+   */
+  modelClass(ModelClass) {
+    if (!this._schemaGeneration) return ModelClass
+
+    const canonicalModelClass = /** @type {MC} */ (ModelClass._recordMetadataModelClass || ModelClass)
+
+    const existing = this._boundModelClasses.get(canonicalModelClass)
+
+    if (existing) return /** @type {MC} */ (existing)
+
+    const databaseIdentity = this.databaseIdentity()
+    const metadataKey = `${databaseIdentity.length}:${databaseIdentity}:${this._schemaGeneration}`
+    const metadataProperties = canonicalModelClass.recordMetadataPropertyNames()
+    const boundModelClass = new Proxy(canonicalModelClass, {
+      construct: (target, args, newTarget) => Reflect.construct(target, args, newTarget),
+      get: (target, property, receiver) => {
+        if (property === "_recordMetadataModelClass") return target
+        if (property === "_recordMetadataBinder") return (/** @type {typeof import("./record/index.js").default} */ targetModelClass) => this.modelClass(targetModelClass)
+        if (property === "_recordMetadataOperation") return this
+        if (typeof property === "string" && metadataProperties.has(property)) return target.recordMetadataValue(metadataKey, property)
+
+        return Reflect.get(target, property, receiver)
+      },
+      set: (target, property, value, receiver) => {
+        if (typeof property === "string" && metadataProperties.has(property)) {
+          target.setRecordMetadataValue(metadataKey, property, value)
+          return true
+        }
+
+        return Reflect.set(target, property, value, receiver)
+      }
+    })
+
+    this._boundModelClasses.set(canonicalModelClass, boundModelClass)
+
+    return /** @type {MC} */ (boundModelClass)
+  }
+
   /**
    * Verifies that a model belongs to this operation's configuration and database.
    * @param {typeof import("./record/index.js").default} ModelClass - Model class to verify.
@@ -162,9 +211,11 @@ export default class VelociousDatabaseOperation {
   async ensureModelInitialized(ModelClass) {
     this.assertActive()
 
-    if (ModelClass.isInitialized()) this.assertModel(ModelClass)
+    const boundModelClass = this.modelClass(ModelClass)
+
+    if (boundModelClass.isInitialized()) this.assertModel(ModelClass)
 
-    await ModelClass.ensureInitialized({
+    await boundModelClass.ensureInitialized({
       configuration: this._configuration,
       connection: this.connection()
     })

package/build/database/query/join-object.js

@@ -54,12 +54,15 @@ export default class VelociousDatabaseQueryJoinObject extends JoinBase {
     for (const joinKey in join) {
       const joinValue = join[joinKey]
       const relationship = modelClass.getRelationshipByName(joinKey)
-      const targetModelClass = relationship.getTargetModelClass()
+      const rawTargetModelClass = relationship.getTargetModelClass()
 
-      if (!targetModelClass) {
+      if (!rawTargetModelClass) {
         throw new Error(`Relationship ${modelClass.name}#${joinKey} has no target model class`)
       }
 
+      const targetModelClass = query.bindModelClass(rawTargetModelClass)
+      const foreignKey = relationship.getForeignKeyForModelClasses({modelClass, targetModelClass})
+
       const joinPath = path.concat([joinKey])
       const parentTableRef = query.getJoinTableReference(path)
       const targetEntry = query._registerJoinPath(joinPath)
@@ -80,9 +83,9 @@ export default class VelociousDatabaseQueryJoinObject extends JoinBase {
 
       if (relationship.getType() == "belongsTo") {
         sql += `${conn.quoteTable(targetTableRef)}.${conn.quoteColumn(relationship.getPrimaryKey())} = `
-        sql += `${conn.quoteTable(parentTableRef)}.${conn.quoteColumn(relationship.getForeignKey())}`
+        sql += `${conn.quoteTable(parentTableRef)}.${conn.quoteColumn(foreignKey)}`
       } else if (relationship.getType() == "hasMany" || relationship.getType() == "hasOne") {
-        sql += `${conn.quoteTable(targetTableRef)}.${conn.quoteColumn(relationship.getForeignKey())} = `
+        sql += `${conn.quoteTable(targetTableRef)}.${conn.quoteColumn(foreignKey)} = `
         sql += `${conn.quoteTable(parentTableRef)}.${conn.quoteColumn(relationship.getPrimaryKey())}`
       } else {
         throw new Error(`Unknown relationship type: ${relationship.getType()}`)

package/build/database/query/model-class-query.js

@@ -87,6 +87,22 @@ function normalizeScopePath(path) {
   return [...path]
 }
 
+/**
+ * Narrows a shared model-scope descriptor to the backend model class required by ModelClassQuery.
+ * @param {import("../../utils/model-scope.js").ModelScopeDescriptor} scopeDescriptor - Shared scope descriptor.
+ * @returns {typeof import("../record/index.js").default} - Backend scope owner.
+ */
+function backendScopeModelClass(scopeDescriptor) {
+  const modelClass = scopeDescriptor.modelClass
+
+  if (!("canonicalRecordMetadataModelClass" in modelClass)) {
+    throw new Error("A frontend-model scope cannot be applied to a database record query")
+  }
+
+  // The runtime member check above narrows the shared frontend/backend descriptor boundary.
+  return /** @type {typeof import("../record/index.js").default} */ (modelClass)
+}
+
 /**
  * Deep-copies a preload select map (keyed by model name with attribute arrays)
  * so a cloned query's selections can be mutated without affecting the original.
@@ -490,6 +506,15 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     return this.modelClass
   }
 
+  /**
+   * Binds a relationship target to this query's physical database generation.
+   * @param {typeof import("../record/index.js").default} modelClass - Canonical relationship target.
+   * @returns {typeof import("../record/index.js").default} - Query-bound relationship target.
+   */
+  bindModelClass(modelClass) {
+    return this.getModelClass().bindRecordMetadataModelClass(modelClass)
+  }
+
   /**
    * Runs get join base path.
    * @returns {string[]} - The join base path.
@@ -563,7 +588,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
         throw new Error(`No target model class for ${modelClass.name}#${relationshipName}`)
       }
 
-      modelClass = targetModelClass
+      modelClass = this.bindModelClass(targetModelClass)
     }
 
     return modelClass
@@ -642,7 +667,9 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
       throw new Error("scope() expects a descriptor returned by defineScope(...).scope(...)")
     }
 
-    if (scopeDescriptor.modelClass !== this.getModelClass()) {
+    const scopeModelClass = backendScopeModelClass(scopeDescriptor)
+
+    if (scopeModelClass.canonicalRecordMetadataModelClass() !== this.getModelClass().canonicalRecordMetadataModelClass()) {
       throw new Error(`Cannot apply ${scopeDescriptor.modelClass.name} scope to ${this.getModelClass().name} query`)
     }
 
@@ -671,7 +698,9 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     const fullJoinPath = this.getJoinBasePath().concat(joinPath)
     const targetModelClass = this._resolveModelClassForJoinPath(fullJoinPath)
 
-    if (scopeDescriptor.modelClass !== targetModelClass) {
+    const scopeModelClass = backendScopeModelClass(scopeDescriptor)
+
+    if (scopeModelClass.canonicalRecordMetadataModelClass() !== targetModelClass.canonicalRecordMetadataModelClass()) {
       throw new Error(`Cannot apply ${scopeDescriptor.modelClass.name} scope to join path ${fullJoinPath.join(".")} (${targetModelClass.name})`)
     }
 
@@ -1418,11 +1447,12 @@ function splitWhereHash({hash, modelClass}) {
 
     if (isNested) {
       if (relationship) {
-        const targetModelClass = relationship.getTargetModelClass()
-        if (!targetModelClass) {
+        const rawTargetModelClass = relationship.getTargetModelClass()
+        if (!rawTargetModelClass) {
           fallbackHash[key] = value
           continue
         }
+        const targetModelClass = modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
         const nestedResult = splitWhereHash({hash: value, modelClass: targetModelClass})
         const nestedResolvedKeys = Object.keys(nestedResult.resolvedHash)
         const nestedFallbackKeys = Object.keys(nestedResult.fallbackHash)
@@ -1476,8 +1506,9 @@ function buildJoinObjectFromWhereHash({hash, modelClass}) {
     if (!relationship) continue
 
     if (isPlainObject(value)) {
-      const targetModelClass = relationship.getTargetModelClass()
-      if (!targetModelClass) continue
+      const rawTargetModelClass = relationship.getTargetModelClass()
+      if (!rawTargetModelClass) continue
+      const targetModelClass = modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
       const nestedJoinObject = buildJoinObjectFromWhereHash({hash: value, modelClass: targetModelClass})
 
       joinObject[key] = Object.keys(nestedJoinObject).length > 0 ? nestedJoinObject : true

package/build/database/query/preloader/belongs-to.js

@@ -2,7 +2,7 @@
 
 import ensureModelClassInitialized from "./ensure-model-class-initialized.js"
 import PreloaderSelection from "./selection.js"
-import preloadQueryForModel from "./query-for-model.js"
+import preloadQueryForModel, { bindPreloadModelClass } from "./query-for-model.js"
 import restArgsError from "../../../utils/rest-args-error.js"
 
 export default class VelociousDatabaseQueryPreloaderBelongsTo {
@@ -22,7 +22,8 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
   }
 
   async run() {
-    const foreignKey = this.relationship.getForeignKey()
+    const sourceModelClass = this.models[0].getModelClass()
+    const foreignKey = this.relationship.getForeignKeyForModelClasses({modelClass: sourceModelClass, targetModelClass: sourceModelClass})
     const primaryKey = this.relationship.getPrimaryKey()
     const relationshipName = this.relationship.getRelationshipName()
 
@@ -30,9 +31,11 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
       return await this._runPolymorphic({foreignKey, primaryKey, relationshipName})
     }
 
-    const targetModelClass = this.relationship.getTargetModelClass()
+    const rawTargetModelClass = this.relationship.getTargetModelClass()
 
-    if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+    if (!rawTargetModelClass) throw new Error("No target model class could be gotten from relationship")
+
+    const targetModelClass = bindPreloadModelClass(this.models, rawTargetModelClass)
 
     /**
      * Satisfied targets.
@@ -155,7 +158,7 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
     for (const model of this.models) {
       const targetType = /** @type {string | undefined} */ (model.readColumn(typeColumn))
       const instanceRelationship = model.getRelationshipByName(relationshipName)
-      const targetModelClass = targetType ? configuration.getModelClass(targetType) : undefined
+      const targetModelClass = targetType ? bindPreloadModelClass(this.models, configuration.getModelClass(targetType)) : undefined
 
       if (targetModelClass && this.selection.isSatisfied({instanceRelationship, targetModelClass, mappingColumns: [primaryKey]})) {
         const loaded = /** @type {import("../../record/index.js").default | undefined} */ (instanceRelationship.getLoadedOrUndefined())
@@ -203,7 +206,7 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
     const targetModels = []
 
     for (const targetType in foreignKeyValuesByType) {
-      const targetModelClass = configuration.getModelClass(targetType)
+      const targetModelClass = bindPreloadModelClass(this.models, configuration.getModelClass(targetType))
 
       await ensureModelClassInitialized(targetModelClass, configuration, this.models[0])