velocious 1.0.592 → 1.0.594

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

package/build/database/query/preloader/has-many.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"
 
 /**
@@ -18,19 +18,23 @@ export function hasManyThroughTargetForeignKey(relationship, throughModelClass,
   // (e.g. a default plus an alternate), so picking the first match would otherwise be ambiguous.
   const explicitForeignKey = relationship.getExplicitForeignKey()
 
-  if (explicitForeignKey) return explicitForeignKey
+  if (explicitForeignKey) {
+    return targetModelClass.getAttributeNameToColumnNameMap()[explicitForeignKey] || explicitForeignKey
+  }
 
   for (const targetRelationship of targetModelClass.getRelationships()) {
     if (targetRelationship.getType() != "belongsTo") continue
 
     const relationshipTargetModelClass = targetRelationship.getTargetModelClass()
 
-    if (relationshipTargetModelClass === throughModelClass) {
-      return targetRelationship.getForeignKey()
+    if (!relationshipTargetModelClass) continue
+
+    if (relationshipTargetModelClass.canonicalRecordMetadataModelClass() === throughModelClass.canonicalRecordMetadataModelClass()) {
+      return targetRelationship.getForeignKeyForModelClasses({modelClass: targetModelClass, targetModelClass: throughModelClass})
     }
   }
 
-  return relationship.getForeignKey()
+  return relationship.getForeignKeyForModelClasses({modelClass: throughModelClass, targetModelClass})
 }
 
 export default class VelociousDatabaseQueryPreloaderHasMany {
@@ -107,15 +111,19 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
     }
 
     const throughRelationshipName = /** @type {string} */ (this.relationship.through)
-    const parentModelClass = this.relationship.getModelClass()
+    const parentModelClass = this.models[0].getModelClass()
     const throughRelationship = parentModelClass.getRelationshipByName(throughRelationshipName)
-    const throughModelClass = throughRelationship.getTargetModelClass()
+    const rawThroughModelClass = throughRelationship.getTargetModelClass()
+
+    if (!rawThroughModelClass) throw new Error(`Through relationship ${throughRelationshipName} has no target model class`)
 
-    if (!throughModelClass) throw new Error(`Through relationship ${throughRelationshipName} has no target model class`)
+    const throughModelClass = bindPreloadModelClass(this.models, rawThroughModelClass)
 
-    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)
 
     const targetForeignKey = hasManyThroughTargetForeignKey(this.relationship, throughModelClass, targetModelClass)
     const {modelsToLoad, satisfiedTargets} = this._partition(targetModelClass, [targetForeignKey])
@@ -127,7 +135,7 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
     await ensureModelClassInitialized(throughModelClass, configuration, modelsToLoad[0])
     await ensureModelClassInitialized(targetModelClass, configuration, modelsToLoad[0])
 
-    const throughForeignKey = throughRelationship.getForeignKey()
+    const throughForeignKey = throughRelationship.getForeignKeyForModelClasses({modelClass: parentModelClass, targetModelClass: throughModelClass})
 
     /**
      * Models primary key values.
@@ -260,16 +268,19 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
    * @returns {Promise<import("../../record/index.js").default[]>} - Loaded target models.
    */
   async _runDirect() {
-    const foreignKey = this.relationship.getForeignKey()
     const primaryKey = this.relationship.getPrimaryKey()
 
     if (!primaryKey) {
       throw new Error(`${this.relationship.getModelClass().name}#${this.relationship.getRelationshipName()} doesn't have a primary key`)
     }
 
-    const targetModelClass = this.relationship.getTargetModelClass()
+    const rawTargetModelClass = this.relationship.getTargetModelClass()
+
+    if (!rawTargetModelClass) throw new Error("No target model class could be gotten from relationship")
 
-    if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+    const sourceModelClass = this.models[0].getModelClass()
+    const targetModelClass = bindPreloadModelClass(this.models, rawTargetModelClass)
+    const foreignKey = this.relationship.getForeignKeyForModelClasses({modelClass: sourceModelClass, targetModelClass})
 
     const {modelsToLoad, satisfiedTargets} = this._partition(targetModelClass, [foreignKey])
 

package/build/database/query/preloader/has-one.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 VelociousDatabaseQueryPreloaderHasOne {
@@ -32,13 +32,16 @@ export default class VelociousDatabaseQueryPreloaderHasOne {
      * @type {Record<number | string, Array<import("../../record/index.js").default>>} */
     const modelsByPrimaryKeyValue = {}
 
-    const foreignKey = this.relationship.getForeignKey()
     const primaryKey = this.relationship.getPrimaryKey()
     const relationshipName = this.relationship.getRelationshipName()
 
-    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 sourceModelClass = this.models[0].getModelClass()
+    const targetModelClass = bindPreloadModelClass(this.models, rawTargetModelClass)
+    const foreignKey = this.relationship.getForeignKeyForModelClasses({modelClass: sourceModelClass, targetModelClass})
 
     /**
      * Preload collections.

package/build/database/query/preloader/query-for-model.js

@@ -1,5 +1,20 @@
 // @ts-check
 
+/**
+ * Binds a preload target to the source records' physical database generation.
+ * @template {typeof import("../../record/index.js").default} MC
+ * @param {import("../../record/index.js").default[]} models - Source records.
+ * @param {MC} ModelClass - Target model class.
+ * @returns {MC} - Generation-bound target model class.
+ */
+export function bindPreloadModelClass(models, ModelClass) {
+  const sourceModel = models[0]
+
+  if (!sourceModel) throw new Error("Cannot bind a preload model class without source records")
+
+  return /** @type {MC} */ (sourceModel.getModelClass().bindRecordMetadataModelClass(ModelClass))
+}
+
 /**
  * Builds a target query preserving the explicit database operation owned by
  * the source records.
@@ -13,5 +28,5 @@ export default function preloadQueryForModel(models, ModelClass) {
 
   if (!sourceModel) throw new Error("Cannot build a preload query without source records")
 
-  return sourceModel.queryForModel(ModelClass)
+  return sourceModel.queryForModel(bindPreloadModelClass(models, ModelClass))
 }

package/build/database/query/preloader.js

@@ -88,7 +88,7 @@ export default class VelociousDatabaseQueryPreloader {
   static async preload(models, queryOrSpec, {force = false} = {}) {
     if (models.length == 0) return
 
-    const modelClass = /** @type {typeof import("../record/index.js").default} */ (models[0].constructor)
+    const modelClass = models[0].getModelClass()
     const isQuery = Boolean(queryOrSpec) && typeof queryOrSpec == "object" && "_preload" in queryOrSpec
     // Reuse the query builder's preload/select normalization for raw specs
     // instead of duplicating it here.
@@ -176,15 +176,17 @@ export default class VelociousDatabaseQueryPreloader {
 
             if (models.length == 0) continue
 
-            const targetModelClass = configuration.getModelClass(className)
+            const targetModelClass = this.modelClass.bindRecordMetadataModelClass(configuration.getModelClass(className))
             const preloader = new VelociousDatabaseQueryPreloader({modelClass: targetModelClass, models, preload: normalizedPreload, selection: this.selection})
 
             await preloader.run()
           }
         } else {
-          const targetModelClass = relationship.getTargetModelClass()
+          const rawTargetModelClass = 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 = this.modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
 
           const preloader = new VelociousDatabaseQueryPreloader({modelClass: targetModelClass, models: targetModels, preload: normalizedPreload, selection: this.selection})
 

package/build/database/query/query-data.js

@@ -153,13 +153,13 @@ function resolveTargetModelClass(rootModelClass, chain) {
 
   for (const segment of chain) {
     const relationship = modelClass.getRelationshipByName(segment)
-    const target = relationship.getTargetModelClass()
+    const rawTarget = relationship.getTargetModelClass()
 
-    if (!target) {
+    if (!rawTarget) {
       throw new Error(`queryData: could not resolve target model for ${modelClass.name}#${segment}`)
     }
 
-    modelClass = target
+    modelClass = modelClass.bindRecordMetadataModelClass(rawTarget)
   }
 
   return modelClass

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

@@ -403,9 +403,11 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
       if (relationship && tuples) {
         if (index > 0) sql += " AND "
 
-        const targetModelClass = relationship.getTargetModelClass()
+        const rawTargetModelClass = relationship.getTargetModelClass()
 
-        if (!targetModelClass) throw new Error(`Relationship "${whereKey}" for ${modelClass.name} has no target model class`)
+        if (!rawTargetModelClass) throw new Error(`Relationship "${whereKey}" for ${modelClass.name} has no target model class`)
+
+        const targetModelClass = modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
 
         const nestedPath = path.concat([whereKey])
         const nestedTableName = modelQuery.getTableReferenceForJoin(...nestedPath)
@@ -431,9 +433,11 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
           throw new Error(`Unknown relationship "${whereKey}" for ${modelClass.name}`)
         }
 
-        const targetModelClass = relationship.getTargetModelClass()
+        const rawTargetModelClass = relationship.getTargetModelClass()
+
+        if (!rawTargetModelClass) throw new Error(`Relationship "${whereKey}" for ${modelClass.name} has no target model class`)
 
-        if (!targetModelClass) throw new Error(`Relationship "${whereKey}" for ${modelClass.name} has no target model class`)
+        const targetModelClass = modelClass.bindRecordMetadataModelClass(rawTargetModelClass)
 
         const nestedHash = /** @type {WhereHash} */ (whereValue)
         const nestedPath = path.concat([whereKey])