velocious 1.0.498 → 1.0.500

package/README.md

@@ -403,7 +403,7 @@ npx velocious g:frontend-models
 
 Frontend-model attributes can usually be declared by name. The generator infers JSDoc typedefs and nullability from backend model columns and translated attribute columns. When an attribute entry needs resource-specific options such as `selectedByDefault: false`, keep only that option in the resource config, for example `{name: "archivedAt", selectedByDefault: false}`; the column type and nullability are still inferred. For computed resource attributes, add a typed `${attributeName}Attribute(model)` method with an `@returns` tag in the backend project's `src` tree. Resource attribute return types take precedence over column types because the resource method controls the serialized value. If Velocious cannot infer a read attribute from a column, generated model accessor, resource method JSDoc, or explicit metadata, generation fails with a clear error instead of emitting a broad fallback type.
 
-This creates `src/frontend-models/user.js` (and one file per configured resource). Every generated file — the per-model files, `index.js`, and `setup.js` here, and the base-model files from `g:base-models` — starts with an auto-generated banner stating it must not be edited manually because changes are overwritten on the next regeneration, and naming the command that regenerates it. Apply changes at their source (resource/model definitions or the generator) and regenerate. Generated classes support:
+This creates `src/frontend-models/user.js` (and one file per configured resource). Import each model directly by its file path (e.g. `import User from ".../frontend-models/user.js"`); `src/frontend-models/setup.js` side-effect-imports every model file so they self-register (import it once at app startup). No barrel/`index.js` is generated. Every generated file — the per-model files and `setup.js` here, and the base-model files from `g:base-models` — starts with an auto-generated banner stating it must not be edited manually because changes are overwritten on the next regeneration, and naming the command that regenerates it. Apply changes at their source (resource/model definitions or the generator) and regenerate. Generated classes support:
 
 - `await User.find(5)`
 - `await User.findBy({email: "john@example.com"})`

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

@@ -148,12 +148,89 @@ export default class VelociousDatabaseDriversMssql extends Base{
     return digg(rows, 0, "db_name")
   }
 
+  /**
+   * Disables every foreign key constraint (bulk `NOCHECK`).
+   * @returns {Promise<void>} - Resolves when foreign keys are disabled.
+   */
   async disableForeignKeys() {
-    await this.query("EXEC sp_MSforeachtable \"ALTER TABLE ? NOCHECK CONSTRAINT all\"")
+    await this._execConstraintToggle("EXEC sp_MSforeachtable \"ALTER TABLE ? NOCHECK CONSTRAINT all\"", "disableForeignKeys")
   }
 
+  /**
+   * Re-enables and re-validates every foreign key constraint (`WITH CHECK`).
+   * @returns {Promise<void>} - Resolves when foreign keys are enabled.
+   */
   async enableForeignKeys() {
-    await this.query("EXEC sp_MSforeachtable @command1=\"print '?'\", @command2=\"ALTER TABLE ? WITH CHECK CHECK CONSTRAINT all\"")
+    await this._execConstraintToggle("EXEC sp_MSforeachtable @command1=\"print '?'\", @command2=\"ALTER TABLE ? WITH CHECK CHECK CONSTRAINT all\"", "enableForeignKeys")
+  }
+
+  /**
+   * Runs a bulk constraint-toggle statement. `ALTER TABLE ... NOCHECK/CHECK
+   * CONSTRAINT` needs a schema-modification lock on every table, so if the
+   * request times out it is almost always blocked by another session that is
+   * still holding a lock (a leaked/uncommitted connection). On a timeout,
+   * capture which sessions were blocking so the real culprit is named instead
+   * of leaving a bare "Request failed to complete in 15000ms".
+   * @param {string} sql - Constraint-toggle SQL.
+   * @param {string} label - Operation label for the error.
+   * @returns {Promise<void>} - Resolves when the toggle completes.
+   */
+  async _execConstraintToggle(sql, label) {
+    try {
+      await this.query(sql)
+    } catch (error) {
+      if (error instanceof Error && /Timeout: Request failed to complete/i.test(error.message)) {
+        const snapshot = await this._captureBlockingSessionsForDebug().catch(
+          (diagError) => `(blocking diagnostics query failed: ${diagError instanceof Error ? diagError.message : diagError})`
+        )
+
+        throw new Error(`${error.message}\n\n[${label} blocked] other user sessions with open transactions or active requests:\n${snapshot}`, {cause: error})
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * Snapshots the sessions that could be blocking a constraint toggle in THIS
+   * database — every session other than this one that holds a lock in `DB_ID()`
+   * or is running a request against it — with its last statement, wait state,
+   * and blocking session, enough to identify a connection that leaked a lock.
+   * Scoped to the current database so a multi-database server does not leak
+   * unrelated sessions' SQL into the error and bury the real blocker.
+   * @returns {Promise<string>} - JSON snapshot, or a "(none)" marker.
+   */
+  async _captureBlockingSessionsForDebug() {
+    const rows = await this.query(`
+      WITH lock_sessions AS (
+        SELECT DISTINCT request_session_id AS session_id
+        FROM sys.dm_tran_locks
+        WHERE resource_database_id = DB_ID()
+      )
+      SELECT
+        s.session_id AS sessionId,
+        s.status AS sessionStatus,
+        s.login_time AS loginTime,
+        s.last_request_start_time AS lastRequestStart,
+        s.last_request_end_time AS lastRequestEnd,
+        s.open_transaction_count AS openTransactionCount,
+        r.status AS requestStatus,
+        r.command AS command,
+        r.wait_type AS waitType,
+        r.wait_time AS waitTimeMs,
+        r.blocking_session_id AS blockingSessionId,
+        CAST(ib.event_info AS NVARCHAR(MAX)) AS lastSql
+      FROM sys.dm_exec_sessions s
+      LEFT JOIN sys.dm_exec_requests r ON r.session_id = s.session_id
+      OUTER APPLY sys.dm_exec_input_buffer(s.session_id, NULL) ib
+      WHERE s.is_user_process = 1
+        AND s.session_id <> @@SPID
+        AND (s.session_id IN (SELECT session_id FROM lock_sessions) OR r.database_id = DB_ID())
+    `)
+
+    if (rows.length === 0) return "(none — no other session held a lock or ran a request in this database when queried)"
+
+    return JSON.stringify(rows, null, 2)
   }
 
   /**

package/build/database/record/counter-cache-magnitude.js

@@ -0,0 +1,240 @@
+// @ts-check
+
+/**
+ * Reactive counter-cache driven by a per-record magnitude.
+ *
+ * Maintains a counter column on a `belongsTo` parent as the running sum of each
+ * child's magnitude — a small number derived from one source attribute (e.g.
+ * `1` while a build's `status` is `running`, else `0`). On every create, update
+ * and destroy the change in magnitude is applied to the parent as a single
+ * atomic increment (`SET col = col + delta`), and when the foreign key changes
+ * the magnitude is moved from the old parent to the new one.
+ *
+ * Because the counter is derived from the source attribute and diffed on every
+ * write, it follows that attribute automatically no matter which code path wrote
+ * it — there is no per-transition increment/decrement to forget. The old value is
+ * captured in `beforeSave` (Velocious clears `changes()` during the post-update
+ * reload) and consumed in `afterSave`, so the increment commits atomically with
+ * the row it reflects.
+ * @typedef {{
+ *   belongsTo: string,
+ *   counterColumn: string,
+ *   sourceAttribute: string,
+ *   magnitude: (sourceValue: ?) => number
+ * }} MagnitudeCounterCacheDefinition
+ */
+
+/**
+ * Captured pending magnitude change stashed on a record between beforeSave and afterSave.
+ * @typedef {{newMagnitude: number, oldMagnitude: number, newParentId: ?, oldParentId: ?}} PendingMagnitudeDelta
+ */
+
+/**
+ * Registers a reactive magnitude counter-cache on a model class.
+ * @param {typeof import("./index.js").default} modelClass - Model class to add the counter cache to.
+ * @param {MagnitudeCounterCacheDefinition} definition - Counter cache definition.
+ * @returns {void}
+ */
+export function registerMagnitudeCounterCache(modelClass, definition) {
+  /**
+   * Dynamic class.
+   * @type {?} */
+  const dynamicClass = modelClass
+  const registeredFlag = `_magnitudeCounterCacheRegistered_${definition.counterColumn}`
+
+  // Idempotent per counter column: re-declaring (or subclassing) must not double-register.
+  if (Object.prototype.hasOwnProperty.call(dynamicClass, registeredFlag) && dynamicClass[registeredFlag]) {
+    return
+  }
+
+  dynamicClass[registeredFlag] = true
+
+  const pendingKey = `_magnitudeCounterCachePending_${definition.counterColumn}`
+
+  modelClass.beforeSave(async function (record) {
+    /**
+     * Dynamic record.
+     * @type {?} */
+    const dynamicRecord = record
+
+    dynamicRecord[pendingKey] = computePendingMagnitudeDelta(record, definition)
+  })
+
+  modelClass.afterSave(async function (record) {
+    /**
+     * Dynamic record.
+     * @type {?} */
+    const dynamicRecord = record
+    const pending = /** @type {PendingMagnitudeDelta | null} */ (dynamicRecord[pendingKey])
+
+    dynamicRecord[pendingKey] = null
+
+    if (pending) {
+      await applyPendingMagnitudeDelta(record, definition, pending)
+    }
+  })
+
+  modelClass.afterDestroy(async function (record) {
+    const magnitude = definition.magnitude(record.readAttribute(definition.sourceAttribute))
+    const parentId = currentParentId(record, definition)
+
+    if (parentId && magnitude !== 0) {
+      await incrementParentCounter(record, definition, parentId, -magnitude)
+    }
+  })
+}
+
+/**
+ * Diffs the source attribute (and foreign key) across the pending save to capture
+ * how the parent counter should move. Runs in beforeSave, where `changes()` still
+ * holds the pre-save values.
+ * @param {import("./index.js").default} record - Record being saved.
+ * @param {MagnitudeCounterCacheDefinition} definition - Counter cache definition.
+ * @returns {PendingMagnitudeDelta} The captured magnitude change.
+ */
+function computePendingMagnitudeDelta(record, definition) {
+  const changes = record.changes()
+  const sourceColumn = columnNameForAttribute(record, definition.sourceAttribute)
+  const foreignKeyColumn = record.getModelClass().getRelationshipByName(definition.belongsTo).getForeignKey()
+
+  const newSource = record.readAttribute(definition.sourceAttribute)
+  const oldSource = oldSourceValueThroughReadCast(record, definition.sourceAttribute, sourceColumn, changes, newSource)
+
+  const newParentId = currentParentId(record, definition)
+  const oldParentId = foreignKeyColumn in changes ? changes[foreignKeyColumn][0] : newParentId
+
+  return {
+    newMagnitude: definition.magnitude(newSource),
+    oldMagnitude: definition.magnitude(oldSource),
+    newParentId,
+    oldParentId
+  }
+}
+
+/**
+ * Applies a captured magnitude change to the parent counter(s) as atomic increments.
+ * @param {import("./index.js").default} record - Record that was saved.
+ * @param {MagnitudeCounterCacheDefinition} definition - Counter cache definition.
+ * @param {PendingMagnitudeDelta} pending - The captured magnitude change.
+ * @returns {Promise<void>}
+ */
+async function applyPendingMagnitudeDelta(record, definition, pending) {
+  const {newMagnitude, oldMagnitude, newParentId, oldParentId} = pending
+
+  if (oldParentId === newParentId) {
+    const delta = newMagnitude - oldMagnitude
+
+    if (newParentId && delta !== 0) {
+      await incrementParentCounter(record, definition, newParentId, delta)
+    }
+
+    return
+  }
+
+  // The foreign key moved: take the old magnitude off the old parent and put the
+  // new magnitude on the new parent.
+  if (oldParentId && oldMagnitude !== 0) {
+    await incrementParentCounter(record, definition, oldParentId, -oldMagnitude)
+  }
+
+  if (newParentId && newMagnitude !== 0) {
+    await incrementParentCounter(record, definition, newParentId, newMagnitude)
+  }
+}
+
+/**
+ * Reads the pre-save value of the source attribute through the normal read/cast
+ * path, so `magnitude` receives the old value in the same shape as the new one
+ * (e.g. a declared boolean as `true`/`false`, not the raw stored `1`/`0`). Drops
+ * the pending change so `readAttribute` falls back to the committed value and
+ * applies the same cast a fresh read would, then restores the pending change.
+ * @param {import("./index.js").default} record - Record being saved.
+ * @param {string} sourceAttribute - Source attribute name.
+ * @param {string} sourceColumn - Source column name.
+ * @param {Record<string, ?>} changes - The record's pre-save changes (column-keyed).
+ * @param {?} currentValue - The current (new) read value, returned when the source did not change.
+ * @returns {?} The read-cast pre-save value.
+ */
+function oldSourceValueThroughReadCast(record, sourceAttribute, sourceColumn, changes, currentValue) {
+  if (!(sourceColumn in changes)) {
+    return currentValue
+  }
+
+  /**
+   * Dynamic record.
+   * @type {?} */
+  const dynamicRecord = record
+  const pendingChange = dynamicRecord._changes[sourceColumn]
+
+  delete dynamicRecord._changes[sourceColumn]
+
+  try {
+    return record.readAttribute(sourceAttribute)
+  } finally {
+    dynamicRecord._changes[sourceColumn] = pendingChange
+  }
+}
+
+/**
+ * Reads the record's current foreign-key value for the counter-cache parent.
+ * @param {import("./index.js").default} record - Record whose parent is targeted.
+ * @param {MagnitudeCounterCacheDefinition} definition - Counter cache definition.
+ * @returns {?} The current foreign-key value.
+ */
+function currentParentId(record, definition) {
+  const foreignKeyColumn = record.getModelClass().getRelationshipByName(definition.belongsTo).getForeignKey()
+
+  return record.readAttribute(attributeNameForColumn(record, foreignKeyColumn))
+}
+
+/**
+ * Atomically adds `amount` to the parent's counter column for one parent row.
+ * @param {import("./index.js").default} record - Child record (for connection + relationship metadata).
+ * @param {MagnitudeCounterCacheDefinition} definition - Counter cache definition.
+ * @param {?} parentId - Parent primary-key value.
+ * @param {number} amount - Signed integer to add.
+ * @returns {Promise<void>}
+ */
+async function incrementParentCounter(record, definition, parentId, amount) {
+  const modelClass = record.getModelClass()
+  const relationship = modelClass.getRelationshipByName(definition.belongsTo)
+  const parentModelClass = relationship.getTargetModelClass()
+
+  if (!parentModelClass) {
+    throw new Error(`magnitudeCounterCache on ${modelClass.getModelName()} could not resolve the "${definition.belongsTo}" parent model class`)
+  }
+
+  // Update through the PARENT model's connection: the row being modified belongs
+  // to the parent, which may live on a different database/tenant than the child.
+  const db = parentModelClass.connection()
+  const counterColumnSql = db.quoteColumn(definition.counterColumn)
+  const truncatedAmount = Math.trunc(amount)
+
+  await db.query(
+    `UPDATE ${db.quoteTable(parentModelClass.tableName())} ` +
+    `SET ${counterColumnSql} = COALESCE(${counterColumnSql}, 0) + ${truncatedAmount} ` +
+    `WHERE ${db.quoteColumn(relationship.getPrimaryKey())} = ${db.quote(parentId)}`
+  )
+}
+
+/**
+ * Resolves the column name backing an attribute name.
+ * @param {import("./index.js").default} record - Record.
+ * @param {string} attributeName - Attribute name.
+ * @returns {string} The column name for the attribute (falls back to the attribute name).
+ */
+function columnNameForAttribute(record, attributeName) {
+  return record.getModelClass().getAttributeNameToColumnNameMap()[attributeName] || attributeName
+}
+
+/**
+ * Resolves the attribute name backing a column name.
+ * @param {import("./index.js").default} record - Record.
+ * @param {string} columnName - Column name.
+ * @returns {string} The attribute name for the column (falls back to the column name).
+ */
+function attributeNameForColumn(record, columnName) {
+  const map = record.getModelClass().getAttributeNameToColumnNameMap()
+
+  return Object.keys(map).find((attributeName) => map[attributeName] === columnName) || columnName
+}

package/build/database/record/index.js

@@ -47,6 +47,8 @@ import {defineModelScope} from "../../utils/model-scope.js"
 import { normalizeDateStringForWrite, normalizeDateValueForRead, normalizeDateValueForWrite } from "../datetime-storage.js"
 import {formatValue} from "../../utils/format-value.js"
 import {captureCreateAuditChanges, captureUpdateAuditChanges, createAudit, createCreateAudit, createDestroyAudit, createUpdateAudit, registerAuditCallback, registerAuditing, withoutAudit} from "./auditing.js"
+import {registerMagnitudeCounterCache} from "./counter-cache-magnitude.js"
+import {stateMachine} from "./state-machine.js"
 import ValidatorsFormat from "./validators/format.js"
 import ValidatorsLength from "./validators/length.js"
 import ValidatorsPresence from "./validators/presence.js"
@@ -668,6 +670,30 @@ class VelociousDatabaseRecord {
     registerAuditing(this)
   }
 
+  /**
+   * Declares an aasm-style state machine on this model: named states, events
+   * (guarded transitions), and enter/exit + before/after transition hooks. See
+   * `state-machine.js`. Generates `event()` / `eventAndSave()` / `canEvent()`
+   * transition methods per declared event.
+   * @param {import("./state-machine.js").StateMachineDefinition} definition - State machine definition.
+   * @returns {void}
+   */
+  static stateMachine(definition) {
+    stateMachine(this, definition)
+  }
+
+  /**
+   * Maintains a counter column on a `belongsTo` parent as the sum of a per-record
+   * magnitude, kept current by atomic increments diffed on every create/update/
+   * destroy (and moved between parents when the foreign key changes). See
+   * `counter-cache-magnitude.js`.
+   * @param {import("./counter-cache-magnitude.js").MagnitudeCounterCacheDefinition} definition - Counter cache definition.
+   * @returns {void}
+   */
+  static magnitudeCounterCache(definition) {
+    registerMagnitudeCounterCache(this, definition)
+  }
+
   /**
    * Registers a callback invoked after this model writes an audit row for the action.
    * @template {typeof VelociousDatabaseRecord} MC

package/build/database/record/state-machine.js

@@ -10,7 +10,9 @@
  * }} StateMachineDefinition
  * @typedef {{
  *   beforeEnter?: (model: import("./index.js").default) => void | Promise<void>,
- *   afterEnter?: (model: import("./index.js").default) => void | Promise<void>
+ *   afterEnter?: (model: import("./index.js").default) => void | Promise<void>,
+ *   beforeExit?: (model: import("./index.js").default) => void | Promise<void>,
+ *   afterExit?: (model: import("./index.js").default) => void | Promise<void>
  * }} StateDefinition
  * @typedef {{
  *   from: string | string[],
@@ -68,6 +70,14 @@ export function stateMachine(ModelClass, definition) {
    * @type {?} */
   const dynamicClass = ModelClass
 
+  // Idempotent: re-declaring on the same class (or a re-evaluated module) must not
+  // register the before/after-save transition hooks twice. Guard on an own property
+  // so a subclass declaring its own machine is unaffected by the parent's flag.
+  if (Object.prototype.hasOwnProperty.call(dynamicClass, "_stateMachineRegistered") && dynamicClass._stateMachineRegistered) {
+    return
+  }
+
+  dynamicClass._stateMachineRegistered = true
   dynamicClass._stateMachineDefinition = definition
   dynamicClass._stateMachineColumn = column
 
@@ -229,7 +239,13 @@ export function stateMachine(ModelClass, definition) {
       await eventDef.before(model)
     }
 
-    // Run state-level beforeEnter callback
+    // Run the exited state's beforeExit, then the entered state's beforeEnter
+    const fromStateDefinition = definition.states[pending.from]
+
+    if (fromStateDefinition?.beforeExit) {
+      await fromStateDefinition.beforeExit(model)
+    }
+
     const stateDefinition = definition.states[pending.to]
 
     if (stateDefinition?.beforeEnter) {
@@ -252,13 +268,19 @@ export function stateMachine(ModelClass, definition) {
     // Clear the pending transition now that save is complete
     dynamicModel[PENDING_TRANSITION_KEY] = null
 
-    // Run state-level afterEnter callback
+    // Run the entered state's afterEnter, then the exited state's afterExit
     const stateDefinition = definition.states[pending.to]
 
     if (stateDefinition?.afterEnter) {
       await stateDefinition.afterEnter(model)
     }
 
+    const fromStateDefinition = definition.states[pending.from]
+
+    if (fromStateDefinition?.afterExit) {
+      await fromStateDefinition.afterExit(model)
+    }
+
     // Run event-level after callback
     const eventDef = definition.events[pending.eventName]
 

package/build/database/tenants/data-copier.js

@@ -94,6 +94,33 @@ export default class DataCopier {
     return sourceRowsByTableName
   }
 
+  /**
+   * Deletes one tenant's rows from the target database, children before parents, with
+   * foreign keys disabled inside a single transaction. This is `copy` without the reinsert:
+   * the same plan traversal selects the tenant's current target rows and `deleteTargetRows`
+   * removes them children-first so the ordering never trips a foreign key. Multi-tenant apps
+   * use it to purge a tenant — for example clearing the tenant's master copy in the
+   * global/default database on teardown, so foreign keys stop referencing the tenant's
+   * about-to-be-removed root row.
+   *
+   * Returns the deleted rows keyed by table name so the caller can perform any app-specific
+   * post-delete work (record-location cleanup, auditing) without that policy leaking into the
+   * framework.
+   * @param {string} keyValue - Tenant key whose rows should be removed from the target.
+   * @returns {Promise<Map<string, Record<string, unknown>[]>>} - The deleted rows by table name.
+   */
+  async deleteTenantRows(keyValue) {
+    const rowsByTableName = await this.loadRows(this.targetDb, keyValue)
+
+    await this.targetDb.withDisabledForeignKeys(async () => {
+      await this.targetDb.transaction(async () => {
+        await this.deleteTargetRows(rowsByTableName)
+      })
+    })
+
+    return rowsByTableName
+  }
+
   /**
    * Loads the rows for `keyValue` for every table in the plan from `db`, resolving
    * parent-scoped tables from the ids already selected for their parent table. Used for

package/build/environment-handlers/node/cli/commands/generate/frontend-models.js

@@ -167,11 +167,10 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     }
 
     for (const [frontendModelsDir, generatedFiles] of generatedFilesByDirectory) {
-      const indexContent = this.buildIndexFileContent(generatedFiles)
-
-      await fs.writeFile(`${frontendModelsDir}/index.js`, indexContent)
-
-      console.log("create src/frontend-models/index.js")
+      // The index.js barrel is no longer generated — nothing imports it (models are
+      // imported by file path, and setup.js performs the registration side-effects).
+      // Remove any stale one left from an older generator.
+      await fs.rm(`${frontendModelsDir}/index.js`, {force: true})
 
       const setupContent = this.buildSetupFileContent(generatedFiles)
 
@@ -632,21 +631,6 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     return fileContent
   }
 
-  /**
-   * Runs build index file content.
-   * @param {Array<{className: string, fileName: string}>} generatedFiles - Generated model files.
-   * @returns {string} - Index file content that imports and re-exports all models.
-   */
-  buildIndexFileContent(generatedFiles) {
-    let content = generatedFileBanner(FRONTEND_MODELS_REGENERATE_COMMAND)
-
-    for (const {className, fileName} of generatedFiles) {
-      content += `export {default as ${className}} from "./${fileName}"\n`
-    }
-
-    return content
-  }
-
   /**
    * Runs build setup file content.
    * @param {Array<{className: string, fileName: string}>} generatedFiles - Generated model files.

package/build/src/database/drivers/mssql/index.d.ts

@@ -16,6 +16,28 @@ export default class VelociousDatabaseDriversMssql extends Base {
      * @returns {Promise<string>} - Resolves with the current database.
      */
     currentDatabase(): Promise<string>;
+    /**
+     * Runs a bulk constraint-toggle statement. `ALTER TABLE ... NOCHECK/CHECK
+     * CONSTRAINT` needs a schema-modification lock on every table, so if the
+     * request times out it is almost always blocked by another session that is
+     * still holding a lock (a leaked/uncommitted connection). On a timeout,
+     * capture which sessions were blocking so the real culprit is named instead
+     * of leaving a bare "Request failed to complete in 15000ms".
+     * @param {string} sql - Constraint-toggle SQL.
+     * @param {string} label - Operation label for the error.
+     * @returns {Promise<void>} - Resolves when the toggle completes.
+     */
+    _execConstraintToggle(sql: string, label: string): Promise<void>;
+    /**
+     * Snapshots the sessions that could be blocking a constraint toggle in THIS
+     * database — every session other than this one that holds a lock in `DB_ID()`
+     * or is running a request against it — with its last statement, wait state,
+     * and blocking session, enough to identify a connection that leaked a lock.
+     * Scoped to the current database so a multi-database server does not leak
+     * unrelated sessions' SQL into the error and bury the real blocker.
+     * @returns {Promise<string>} - JSON snapshot, or a "(none)" marker.
+     */
+    _captureBlockingSessionsForDebug(): Promise<string>;
     /**
      * Drops the foreign key constraints that reference the given table. MSSQL
      * refuses to drop a table that is still referenced by a FOREIGN KEY

package/build/src/database/drivers/mssql/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/database/drivers/mssql/index.js"],"names":[],"mappings":"AAyBA;IAgBM,6CAAqD;IAavD,0DAA+B;IAsBjC;;;;;;OAMG;IACH,gCALW,MAAM,SAEd;QAAuB,WAAW;KAClC,GAAU,MAAM,EAAE,CAOpB;IAoDD;;;OAGG;IACH,mBAFa,OAAO,CAAC,MAAM,CAAC,CAM3B;IAuBD;;;;;;;;;OASG;IACH,uCAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAczB;IAsED;;;;OAIG;IACH,cAHW,OAAC,GACC,MAAM,CAUlB;IAwFD,6BAOC;IAOqB,8BAA2C;CA4NlE;iBAnlBgB,YAAY;kBAWX,OAAO;oBADL,cAAc"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/database/drivers/mssql/index.js"],"names":[],"mappings":"AAyBA;IAgBM,6CAAqD;IAavD,0DAA+B;IAsBjC;;;;;;OAMG;IACH,gCALW,MAAM,SAEd;QAAuB,WAAW;KAClC,GAAU,MAAM,EAAE,CAOpB;IAoDD;;;OAGG;IACH,mBAFa,OAAO,CAAC,MAAM,CAAC,CAM3B;IAkBD;;;;;;;;;;OAUG;IACH,2BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAgBzB;IAED;;;;;;;;OAQG;IACH,oCAFa,OAAO,CAAC,MAAM,CAAC,CAiC3B;IAeD;;;;;;;;;OASG;IACH,uCAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAczB;IAsED;;;;OAIG;IACH,cAHW,OAAC,GACC,MAAM,CAUlB;IAwFD,6BAOC;IAOqB,8BAA2C;CA4NlE;iBAhqBgB,YAAY;kBAWX,OAAO;oBADL,cAAc"}