velocious 1.0.509 → 1.0.511

package/README.md

@@ -30,6 +30,7 @@
 * Planned local-first shared-resource sync architecture (see [docs/offline-sync.md](docs/offline-sync.md))
 * Named database connection checkouts, bounded pool waits, and debugging held connections (see [docs/database-connections.md](docs/database-connections.md))
 * Optional built-in debug endpoint for inspecting server and database connection state (see [docs/debug-endpoint.md](docs/debug-endpoint.md))
+* Optional built-in API manifest endpoint describing every registered frontend-model resource as human- and machine-readable JSON (see [docs/api-manifest-endpoint.md](docs/api-manifest-endpoint.md))
 
 # Setup
 

package/build/configuration-types.js

@@ -554,6 +554,12 @@
  * @typedef {function({configuration: import("./configuration.js").default, databaseConfiguration: DatabaseConfigurationType, identifier: string, tenant: ?}) : DatabaseConfigurationType | Partial<DatabaseConfigurationType> | void} TenantDatabaseResolverType
  */
 
+/**
+ * @typedef {object} ApiManifestConfiguration
+ * @property {string} [path] - HTTP path for the built-in API manifest endpoint. Defaults to `/api/manifest`.
+ * @property {string} [token] - Bearer token required in the `Authorization: Bearer <token>` header. When set, requests without a matching token are not routed (404), so the endpoint stays hidden.
+ */
+
 /**
  * @typedef {object} DebugEndpointConfiguration
  * @property {string} [path] - HTTP path for the built-in debug endpoint. Defaults to `/velocious/debug`.
@@ -583,6 +589,7 @@
  * @property {{[key: string]: {[key: string]: DatabaseConfigurationType}}} database - Database configurations keyed by environment and identifier.
  * @property {boolean} [debug] - Enable debug logging.
  * @property {boolean | DebugEndpointConfiguration} [debugEndpoint] - Enable the built-in debug endpoint. Defaults to false.
+ * @property {boolean | ApiManifestConfiguration} [apiManifest] - Enable the built-in API manifest endpoint. Defaults to false.
  * @property {string} [directory] - Base directory for the project.
  * @property {boolean} [enforceTenantDatabaseScopes] - Require tenant-switched model queries to resolve a tenant database identifier. Defaults to true.
  * @property {string} [environment] - Current environment name.

package/build/configuration.js

@@ -20,7 +20,7 @@ import EventEmitter from "./utils/event-emitter.js"
 import VelociousWebsocketChannelSubscribers from "./http-server/websocket-channel-subscribers.js"
 import {CurrentConfigurationNotSetError, currentConfiguration, setCurrentConfiguration} from "./current-configuration.js"
 import {requestDetails} from "./error-reporting/request-details.js"
-import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
+import {frontendModelApiManifest, frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
 import {currentOfflineGrantSigningKey, normalizeOfflineGrantSigningKey} from "./sync/offline-grant.js"
 import PluginRoutes from "./routes/plugin-routes.js"
 import restArgsError from "./utils/rest-args-error.js"
@@ -129,7 +129,7 @@ export default class VelociousConfiguration {
    * Runs constructor.
    * @param {import("./configuration-types.js").ConfigurationArgsType} args - Configuration arguments.
    */
-  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients = false, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients = false, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
@@ -172,6 +172,7 @@ export default class VelociousConfiguration {
     this.database = database
     this.debug = debug
     this._debugEndpoint = this._normalizeDebugEndpoint(debugEndpoint)
+    this._apiManifest = this._normalizeApiManifest(apiManifest)
     this._environment = environment || process.env.VELOCIOUS_ENV || process.env.NODE_ENV || "development"
     this._environmentHandler = environmentHandler
     this._enforceTenantDatabaseScopes = enforceTenantDatabaseScopes
@@ -273,6 +274,7 @@ export default class VelociousConfiguration {
     this._mailerBackend = mailerBackend
     this._routeResolverHooks = [...(routeResolverHooks || [])]
     this._addDebugEndpointRouteHook()
+    this._addApiManifestRouteHook()
 
     /**
      * Stores the applied route mounts value.
@@ -351,6 +353,59 @@ export default class VelociousConfiguration {
     return {enabled: true, path, token: token === null ? null : token.trim()}
   }
 
+  /**
+   * Runs normalize api manifest.
+   * @param {boolean | {path?: string, token?: string}} value - API manifest configuration.
+   * @returns {{enabled: boolean, path: string, token: string | null}} - Normalized API manifest configuration.
+   */
+  _normalizeApiManifest(value) {
+    if (value === false || value === undefined) return {enabled: false, path: "/api/manifest", token: null}
+    if (value === true) return {enabled: true, path: "/api/manifest", token: null}
+
+    if (typeof value !== "object" || value === null) {
+      throw new Error(`Expected apiManifest to be a boolean or object, got: ${String(value)}`)
+    }
+
+    const path = value.path || "/api/manifest"
+
+    if (typeof path !== "string" || !path.startsWith("/")) {
+      throw new Error(`Expected apiManifest.path to be a string starting with '/', got: ${String(path)}`)
+    }
+
+    const token = value.token === undefined || value.token === null ? null : value.token
+
+    if (token !== null && (typeof token !== "string" || !token.trim())) {
+      throw new Error(`Expected apiManifest.token to be a non-empty string, got: ${String(token)}`)
+    }
+
+    return {enabled: true, path, token: token === null ? null : token.trim()}
+  }
+
+  /**
+   * Runs add api manifest route hook.
+   * @returns {void} - No return value.
+   */
+  _addApiManifestRouteHook() {
+    if (!this._apiManifest.enabled) return
+
+    this.addRouteResolverHook(({currentPath, request}) => {
+      if (request.httpMethod() !== "GET") return null
+      if (currentPath !== this._apiManifest.path) return null
+
+      if (this._apiManifest.token && !this.debugEndpointRequestAuthorized(request, this._apiManifest.token)) return null
+
+      return {
+        action: "show",
+        controller: "velociousApiManifest",
+        controllerPath: "./built-in/api-manifest/controller.js",
+        skipControllerConnections: true,
+        skipAbilityResolution: true,
+        skipTenantResolution: true,
+        viewPath: "./built-in/api-manifest"
+      }
+    })
+  }
+
   /**
    * Runs add debug endpoint route hook.
    * @returns {void} - No return value.
@@ -701,6 +756,7 @@ export default class VelociousConfiguration {
    */
   _debugConfigurationSnapshot() {
     return {
+      apiManifest: this._apiManifestEnabled() ? {enabled: true, path: this._apiManifest.path, tokenConfigured: Boolean(this._apiManifest.token)} : {enabled: false},
       autoload: this.getAutoload(),
       debug: this.debug === true,
       debugEndpoint: this._debugEndpointSnapshot(),
@@ -2875,4 +2931,20 @@ export default class VelociousConfiguration {
 
     return this.getEnvironmentHandler().debugEndpointTokenMatches(match[1], expectedToken)
   }
+
+  /**
+   * Runs get api manifest.
+   * @returns {Promise<Record<string, unknown>>} - API manifest for all registered frontend-model resources.
+   */
+  async getApiManifest() {
+    return frontendModelApiManifest(this._backendProjects)
+  }
+
+  /**
+   * Runs whether API manifest is enabled.
+   * @returns {boolean} - Whether the API manifest endpoint is enabled.
+   */
+  _apiManifestEnabled() {
+    return this._apiManifest.enabled
+  }
 }

package/build/database/advisory-lock-runner.js

@@ -0,0 +1,192 @@
+// @ts-check
+
+import timeout from "awaitery/build/timeout.js"
+
+/**
+ * Thrown when an advisory lock could not be acquired before `timeoutMs` elapsed.
+ */
+class AdvisoryLockTimeoutError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{name: string}} args - The advisory lock name that timed out.
+   */
+  constructor(message, {name}) {
+    super(message)
+    this.name = "AdvisoryLockTimeoutError"
+    this.lockName = name
+  }
+}
+
+/**
+ * Thrown when `withAdvisoryLockOrFail` finds the lock already held.
+ */
+class AdvisoryLockBusyError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{name: string}} args - The advisory lock name that was already held.
+   */
+  constructor(message, {name}) {
+    super(message)
+    this.name = "AdvisoryLockBusyError"
+    this.lockName = name
+  }
+}
+
+/**
+ * Thrown when a callback holds an advisory lock longer than `holdTimeoutMs`.
+ */
+class AdvisoryLockHoldTimeoutError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{name: string}} args - The advisory lock name whose hold timed out.
+   */
+  constructor(message, {name}) {
+    super(message)
+    this.name = "AdvisoryLockHoldTimeoutError"
+    this.lockName = name
+  }
+}
+
+/**
+ * Runs advisory locks on the caller connection by default, using a dedicated
+ * lock connection only when a positive hold timeout needs separate ownership.
+ */
+export default class AdvisoryLockRunner {
+  /**
+   * Creates an advisory-lock runner for one model database identifier.
+   * @param {{configuration: import("../configuration.js").default, connectionProvider: () => import("./drivers/base.js").default, databaseIdentifier: string}} args - Runner dependencies.
+   */
+  constructor({configuration, connectionProvider, databaseIdentifier}) {
+    this.configuration = configuration
+    this.connectionProvider = connectionProvider
+    this.databaseIdentifier = databaseIdentifier
+  }
+
+  /**
+   * Runs a callback after acquiring the advisory lock, waiting up to `timeoutMs`.
+   * @template T
+   * @param {string} name - Lock name.
+   * @param {() => Promise<T>} callback - Callback to invoke while the lock is held.
+   * @param {{timeoutMs?: number | null, holdTimeoutMs?: number | null}} [args] - Lock and hold timeout options.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withAdvisoryLock(name, callback, args = {}) {
+    return await this.withLockConnection(args.holdTimeoutMs, async (connection) => {
+      const acquired = await connection.acquireAdvisoryLock(name, args)
+
+      if (!acquired) {
+        throw new AdvisoryLockTimeoutError(`Timed out waiting for advisory lock ${JSON.stringify(name)}`, {name})
+      }
+
+      return await this.runLockedCallback({callback, connection, holdTimeoutMs: args.holdTimeoutMs, name})
+    })
+  }
+
+  /**
+   * Runs a callback only if the advisory lock can be acquired immediately.
+   * @template T
+   * @param {string} name - Lock name.
+   * @param {() => Promise<T>} callback - Callback to invoke while the lock is held.
+   * @param {{holdTimeoutMs?: number | null}} [args] - Hold timeout options.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withAdvisoryLockOrFail(name, callback, args = {}) {
+    return await this.withLockConnection(args.holdTimeoutMs, async (connection) => {
+      const acquired = await connection.tryAcquireAdvisoryLock(name)
+
+      if (!acquired) {
+        throw new AdvisoryLockBusyError(`Advisory lock ${JSON.stringify(name)} is already held`, {name})
+      }
+
+      return await this.runLockedCallback({callback, connection, holdTimeoutMs: args.holdTimeoutMs, name})
+    })
+  }
+
+  /**
+   * Runs the lock holder callback and releases the lock from its owning connection.
+   * @template T
+   * @param {{callback: () => Promise<T>, connection: import("./drivers/base.js").default, holdTimeoutMs?: number | null, name: string}} args - Locked callback args.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async runLockedCallback({callback, connection, holdTimeoutMs, name}) {
+    try {
+      return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs)
+    } finally {
+      await connection.releaseAdvisoryLock(name)
+    }
+  }
+
+  /**
+   * Runs lock work on the caller connection unless a positive hold timeout needs
+   * its own lock connection.
+   * @template T
+   * @param {number | null | undefined} holdTimeoutMs - Max hold time; positive values use a dedicated lock connection.
+   * @param {(connection: import("./drivers/base.js").default) => Promise<T>} callback - Callback receiving the connection that owns the advisory lock.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withLockConnection(holdTimeoutMs, callback) {
+    if (holdTimeoutMs && holdTimeoutMs > 0) {
+      return await this.withDedicatedConnection(callback)
+    }
+
+    return await callback(this.connectionProvider())
+  }
+
+  /**
+   * Spawns a hold-timeout lock connection and closes it after lock work completes when
+   * the spawned driver owns the underlying physical connection.
+   * @template T
+   * @param {(connection: import("./drivers/base.js").default) => Promise<T>} callback - Callback that receives the dedicated lock connection.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withDedicatedConnection(callback) {
+    const connection = await this.configuration.getDatabasePool(this.databaseIdentifier).spawnConnection()
+
+    try {
+      return await callback(connection)
+    } finally {
+      if (!connection.getArgs().getConnection) {
+        await connection.close()
+      }
+    }
+  }
+
+  /**
+   * Runs `callback`, rejecting with `AdvisoryLockHoldTimeoutError` if it has
+   * not settled within `holdTimeoutMs`. The callback is not cancelled; callers
+   * use a dedicated advisory-lock connection so the lock can still be released.
+   * @template T
+   * @param {string} name - Lock name (for the error message).
+   * @param {() => Promise<T>} callback - Callback holding the lock.
+   * @param {number | null} [holdTimeoutMs] - Max hold time; falsy disables the timeout.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  static async runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs) {
+    if (!holdTimeoutMs || holdTimeoutMs <= 0) {
+      return await callback()
+    }
+
+    let callbackSettled = false
+
+    try {
+      return await timeout({timeout: holdTimeoutMs}, async () => {
+        try {
+          return await callback()
+        } finally {
+          callbackSettled = true
+        }
+      })
+    } catch (error) {
+      if (!callbackSettled) {
+        throw new AdvisoryLockHoldTimeoutError(`Advisory lock ${JSON.stringify(name)} held longer than ${holdTimeoutMs}ms`, {name})
+      }
+
+      throw error
+    }
+  }
+}
+
+export {AdvisoryLockBusyError, AdvisoryLockHoldTimeoutError, AdvisoryLockTimeoutError}

package/build/database/drivers/mysql/index.js

@@ -31,6 +31,9 @@ import Update from "./sql/update.js"
 const MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS = 60 * 60 * 24 * 365
 
 export default class VelociousDatabaseDriversMysql extends Base{
+  /** @type {import("mysql").Pool | undefined} */
+  pool = undefined
+
   /** @type {string | null} */
   _desiredSessionTimeZone = "+00:00"
 

package/build/database/record/index.js

@@ -24,7 +24,7 @@
 
 /** @typedef {import("../../configuration-types.js").TenantDatabaseProviderType} TenantDatabaseProviderType */
 
-import timeout from "awaitery/build/timeout.js"
+import AdvisoryLockRunner, {AdvisoryLockBusyError, AdvisoryLockHoldTimeoutError, AdvisoryLockTimeoutError} from "../advisory-lock-runner.js"
 import BelongsToInstanceRelationship from "./instance-relationships/belongs-to.js"
 import BelongsToRelationship from "./relationships/belongs-to.js"
 import Configuration from "../../configuration.js"
@@ -164,60 +164,6 @@ function buildRelatedRecordWithInverse(parent, relationshipName, attributes, all
   return record
 }
 
-/**
- * Thrown by `Record.withAdvisoryLock` when the caller supplied a
- * `timeoutMs` and the lock was not granted before it elapsed.
- */
-class AdvisoryLockTimeoutError extends Error {
-  /**
-   * Runs constructor.
-   * @param {string} message - Error message.
-   * @param {{name: string}} args - The advisory lock name that timed out.
-   */
-  constructor(message, {name}) {
-    super(message)
-    this.name = "AdvisoryLockTimeoutError"
-    this.lockName = name
-  }
-}
-
-/**
- * Thrown by `Record.withAdvisoryLockOrFail` when the lock is already held
- * by another session at the moment of the call.
- */
-class AdvisoryLockBusyError extends Error {
-  /**
-   * Runs constructor.
-   * @param {string} message - Error message.
-   * @param {{name: string}} args - The advisory lock name that was already held.
-   */
-  constructor(message, {name}) {
-    super(message)
-    this.name = "AdvisoryLockBusyError"
-    this.lockName = name
-  }
-}
-
-/**
- * Thrown by `Record.withAdvisoryLock` / `withAdvisoryLockOrFail` when the
- * caller supplied a `holdTimeoutMs` and the callback ran longer than it. The
- * lock is released before this is thrown, so a hung holder can't block other
- * sessions indefinitely. Note: the callback itself is not cancelled — pass an
- * AbortSignal to the work if it needs to stop.
- */
-class AdvisoryLockHoldTimeoutError extends Error {
-  /**
-   * Runs constructor.
-   * @param {string} message - Error message.
-   * @param {{name: string}} args - The advisory lock name whose hold timed out.
-   */
-  constructor(message, {name}) {
-    super(message)
-    this.name = "AdvisoryLockHoldTimeoutError"
-    this.lockName = name
-  }
-}
-
 class TenantDatabaseScopeError extends Error {
   /**
    * Runs constructor.
@@ -2675,10 +2621,13 @@ class VelociousDatabaseRecord {
   }
 
   /**
-   * Runs the callback while holding a named advisory lock on the current
-   * connection. Advisory locks are cooperative and connection-scoped: they
-   * serialize callers that opt into the same `name`, without touching row
-   * or table locks, so unrelated traffic is free to proceed.
+   * Runs the callback while holding a named advisory lock. Calls without
+   * a positive `holdTimeoutMs` use the caller connection; calls with a positive
+   * `holdTimeoutMs` use a dedicated lock connection so timeout cleanup can
+   * release the lock even when callback database work is stuck. Advisory locks
+   * are cooperative and session-scoped: they serialize callers that opt into
+   * the same `name`, without touching row or table locks, so unrelated traffic
+   * is free to proceed.
    *
    * The lock is acquired before the callback runs and released in a
    * `finally` block afterwards, so the callback's return value is
@@ -2694,18 +2643,13 @@ class VelociousDatabaseRecord {
   static async withAdvisoryLock(name, callback, args = {}) {
     await this.ensureInitialized()
 
-    const connection = this.connection()
-    const acquired = await connection.acquireAdvisoryLock(name, args)
-
-    if (!acquired) {
-      throw new AdvisoryLockTimeoutError(`Timed out waiting for advisory lock ${JSON.stringify(name)}`, {name})
-    }
+    const runner = new AdvisoryLockRunner({
+      configuration: this._getConfiguration(),
+      connectionProvider: () => this.connection(),
+      databaseIdentifier: this.getDatabaseIdentifier()
+    })
 
-    try {
-      return await this.runWithAdvisoryLockHoldTimeout(name, callback, args.holdTimeoutMs)
-    } finally {
-      await connection.releaseAdvisoryLock(name)
-    }
+    return await runner.withAdvisoryLock(name, callback, args)
   }
 
   /**
@@ -2725,31 +2669,19 @@ class VelociousDatabaseRecord {
   static async withAdvisoryLockOrFail(name, callback, args = {}) {
     await this.ensureInitialized()
 
-    const connection = this.connection()
-    const acquired = await connection.tryAcquireAdvisoryLock(name)
-
-    if (!acquired) {
-      throw new AdvisoryLockBusyError(`Advisory lock ${JSON.stringify(name)} is already held`, {name})
-    }
+    const runner = new AdvisoryLockRunner({
+      configuration: this._getConfiguration(),
+      connectionProvider: () => this.connection(),
+      databaseIdentifier: this.getDatabaseIdentifier()
+    })
 
-    try {
-      return await this.runWithAdvisoryLockHoldTimeout(name, callback, args.holdTimeoutMs)
-    } finally {
-      await connection.releaseAdvisoryLock(name)
-    }
+    return await runner.withAdvisoryLockOrFail(name, callback, args)
   }
 
   /**
    * Runs `callback`, rejecting with `AdvisoryLockHoldTimeoutError` if it has
-   * not settled within `holdTimeoutMs`. The caller's `finally` then releases
-   * the lock, so a hung holder can't block other sessions forever. The
-   * callback is not cancelled — this is a safety net, not cancellation.
-   *
-   * Uses `awaitery`'s shared `timeout` helper for the hard timeout, then
-   * translates its timeout into the typed `AdvisoryLockHoldTimeoutError` so
-   * callers can catch it like the other advisory-lock errors. A `callbackSettled`
-   * flag distinguishes the timeout from a rejection thrown by the callback
-   * itself, which is rethrown unchanged.
+   * not settled within `holdTimeoutMs`. The callback is not cancelled — this is
+   * a safety net, not cancellation.
    * @template T
    * @param {string} name - Lock name (for the error message).
    * @param {() => Promise<T>} callback - Callback holding the lock.
@@ -2757,27 +2689,7 @@ class VelociousDatabaseRecord {
    * @returns {Promise<T>}
    */
   static async runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs) {
-    if (!holdTimeoutMs || holdTimeoutMs <= 0) {
-      return await callback()
-    }
-
-    let callbackSettled = false
-
-    try {
-      return await timeout({timeout: holdTimeoutMs}, async () => {
-        try {
-          return await callback()
-        } finally {
-          callbackSettled = true
-        }
-      })
-    } catch (error) {
-      if (!callbackSettled) {
-        throw new AdvisoryLockHoldTimeoutError(`Advisory lock ${JSON.stringify(name)} held longer than ${holdTimeoutMs}ms`, {name})
-      }
-
-      throw error
-    }
+    return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs)
   }
 
   /**

package/build/database/tenants/schema-cloner.js

@@ -152,7 +152,8 @@ export default class SchemaCloner {
 
   /**
    * Creates non-primary-key indexes present on the source but missing from the target,
-   * and throws if an existing target index diverges from the source.
+   * and replaces target indexes whose definition (columns or uniqueness) drifted from
+   * the source.
    * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args
    * @returns {Promise<void>}
    */
@@ -161,7 +162,7 @@ export default class SchemaCloner {
     /** @type {Map<string, import("../drivers/base-columns-index.js").default>} */
     const targetIndexesByName = new Map()
     const targetIndexSignatures = new Set()
-    let createdIndex = false
+    let dirty = false
 
     for (const targetIndex of await targetTable.getIndexes()) {
       targetIndexesByName.set(targetIndex.getName(), targetIndex)
@@ -183,28 +184,63 @@ export default class SchemaCloner {
 
       const targetIndex = this.targetDb.getType() === "sqlite" ? undefined : targetIndexesByName.get(sourceIndex.getName())
 
-      if (!targetIndex) {
-        const createIndexSqls = await this.targetDb.createIndexSQLs(this.createIndexArgsFromSourceIndex({sourceIndex, tableName}))
-
-        for (const createIndexSql of createIndexSqls) {
-          await this.targetDb.query(createIndexSql)
+      if (targetIndex) {
+        if (!this.indexesMatch(sourceIndex, targetIndex)) {
+          // Replacing a non-unique index with a unique one is unsafe because
+          // the target may have duplicate values that will reject the new
+          // unique constraint, and the old index was already dropped by this
+          // point. The opposite direction (unique → non-unique) is always
+          // safe — non-unique indexes never fail on duplicate values.
+          if (sourceIndex.isUnique() && !targetIndex.isUnique()) {
+            throw new Error(`Schema clone index drift for ${tableName}.${sourceIndex.getName()}: cannot safely replace a non-unique index with a unique one.`)
+          }
+
+          await this.dropTargetIndex({tableName, targetIndex})
+          targetIndexesByName.delete(targetIndex.getName())
+          targetIndexSignatures.delete(this.indexSignature(targetIndex))
+        } else {
+          continue
         }
+      }
 
-        createdIndex = true
-        targetIndexSignatures.add(sourceIndexSignature)
-        continue
+      // Drop any target index that shares the source name but survived the
+      // drift check above because the driver was skipped (SQLite).
+      const sameNameTargetIndex = targetIndexesByName.get(sourceIndex.getName())
+
+      if (sameNameTargetIndex) {
+        await this.dropTargetIndex({tableName, targetIndex: sameNameTargetIndex})
+        targetIndexesByName.delete(sameNameTargetIndex.getName())
+        targetIndexSignatures.delete(this.indexSignature(sameNameTargetIndex))
       }
 
-      if (!this.indexesMatch(sourceIndex, targetIndex)) {
-        throw new Error(`Schema clone index drift for ${tableName}.${sourceIndex.getName()}`)
+      const createIndexSqls = await this.targetDb.createIndexSQLs(this.createIndexArgsFromSourceIndex({sourceIndex, tableName}))
+
+      for (const createIndexSql of createIndexSqls) {
+        await this.targetDb.query(createIndexSql)
       }
+
+      dirty = true
+      targetIndexSignatures.add(sourceIndexSignature)
     }
 
-    if (createdIndex) {
+    if (dirty) {
       this.targetDb.clearSchemaCache()
     }
   }
 
+  /**
+   * Drops an index on the target database.
+   * @param {{tableName: string, targetIndex: import("../drivers/base-columns-index.js").default}} args
+   * @returns {Promise<void>}
+   */
+  async dropTargetIndex({tableName, targetIndex}) {
+    const dropSqls = await this.targetDb.removeIndexSQLs({name: targetIndex.getName(), tableName})
+
+    for (const sql of dropSqls) {
+      await this.targetDb.query(sql)
+    }
+  }
+
   /**
    * Baselines the target ledger so the cloned schema is recorded as already-applied.
    * @returns {Promise<string[]>} The versions newly recorded on the target.