velocious 1.0.601 → 1.0.603

package/README.md

@@ -15,8 +15,8 @@
 * Controllers and views for HTTP endpoints
 * Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses and one-budget WebSocket startup controls (see [docs/frontend-models.md](docs/frontend-models.md) and [docs/websocket-channels.md](docs/websocket-channels.md))
 * Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see the [shared-resource sync developer guide](docs/shared-resource-sync-guide.md) and [offline sync architecture](docs/offline-sync.md))
-* Declarative client sync scopes with per-scope cursors, automatic mutation tracking, opt-in durable base-version conflict replay, realtime delivery whose per-recipient authorization hook receives the complete persisted sync envelope, and `sync`/`pull` progress reporting for "X of Y" import screens (see [docs/sync-client.md](docs/sync-client.md) and [docs/offline-sync.md](docs/offline-sync.md))
-* Reactive `useLiveQuery(Model.where(...))` queries that stay current from committed local model changes across local writes, pulls, and realtime (see [docs/live-queries.md](docs/live-queries.md))
+* Declarative client sync scopes with per-scope cursors, automatic mutation tracking, opt-in durable base-version conflict replay, realtime delivery, and immutable-handle project clients whose queues, scopes, cursors, receipts, conflicts, pulls, and reconnect catch-up stay in one physical tenant database (see [docs/sync-client.md](docs/sync-client.md) and [docs/offline-sync.md](docs/offline-sync.md))
+* Reactive `useLiveQuery(Model.where(...))` queries for default databases plus immutable-handle tenant live-query sources whose committed events and refreshes stay on the captured physical tenant (see [docs/live-queries.md](docs/live-queries.md))
 * Server-side sync envelope replay orchestration for app-owned sync receivers, including allowlisted authoritative values for conflict resolution (see [docs/sync-envelope-replay-service.md](docs/sync-envelope-replay-service.md))
 * 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))
@@ -1921,10 +1921,21 @@ Genuinely unexpected frontend-model command failures reach this bus too. The fro
 
 Unexpected inbound decoded WebSocket dispatch failures emit one `framework-error` and one matching `all-error`. Established expected client-flow errors remain excluded from both events.
 
-MySQL/MariaDB transaction deadlock retries emit a structured `database-deadlock-retry` event (also
-mirrored to `all-error`) with retry metadata, a redacted SQL fingerprint when available, and a
-best-effort bounded/redacted InnoDB deadlock excerpt. Diagnostic capture never joins the retry
-control flow. See [deadlock retry diagnostics](docs/logging.md#deadlock-retry-diagnostics).
+MySQL/MariaDB transaction contention that will run another outer attempt emits a structured
+`database-deadlock-retry` event through `configuration.getErrorEvents()` and mirrors it to `all-error` with
+`errorType: "database-deadlock-retry"`. Required context fields are `stage`, `driverType`,
+`contentionKind`, `attempt`, `maxAttempts`, `willRetry` (always `true` for this retry-only event), and
+`transactionAttemptDurationMs`. Exhausted/non-retried contention emits no retry event.
+Pool-owned connections optionally add logical `databaseIdentifier` and opaque
+`databaseIdentifierFingerprint`/`databaseIdentityFingerprint` fields; the logical identifier itself
+is always redacted. Named checkouts always redact `operationName` and add only its bounded opaque
+`operationNameFingerprint` for correlation. Query failures add
+`sqlOperation`/`sqlFingerprint`. True deadlocks may add `statusCapture` and the bounded structural
+`innodbDeadlockSummary`, including explicit bounded MariaDB counterparty conflict edges whose owner
+is intentionally not inferred; lock-wait timeouts report `statusCapture: "not-applicable"` and never attach a
+historical graph. Capture, parsing, and listeners remain detached from rollback and retry control
+flow. See the exact identity, redaction, structural bounds, failure-channel, and optional-field
+contract in [deadlock retry diagnostics](docs/logging.md#deadlock-retry-diagnostics).
 
 ## Use the Websocket client API (HTTP-like)
 
@@ -2687,7 +2698,7 @@ Tenant lifecycle commands print start and final counts, report each completed te
 
 `afterMigrateTenant` hooks run inside the active default and tenant database connection scope for the tenant being migrated.
 
-At runtime, the apartment-style `Tenant` façade (`velocious/build/src/tenants/tenant.js`) is the single entry point: `Tenant.with(tenant, callback)` / `Tenant.current()` to switch into and read a Node async context, `Tenant.handle(tenant)` to deeply capture immutable application and physical database identity for overlapping browser/native work, `Tenant.each({identifier, callback, parallel?, filter?})` to run a callback within every provider-listed tenant, and `Tenant.drop({identifier, tenant})` (plus the `db:tenants:drop` CLI command) to drop a tenant's database through the provider's `dropDatabase` hook. SQLite handles additionally expose framework-owned `open`, `flush`, `close`, `delete`, `inspect`, and `withPin` lifecycle methods; `frontendTenantSqlite.maxOpenHandles` bounds resident identities and clean, idle, unpinned handles are evicted least-recently-used. `Tenant.handle(...).databaseOperation(...)` and `.transaction(...)` use bounded pool-owned checkouts and pin model/query/write/association/preload/audit/attachment/raw work to the captured database even if a later UI project switch changes ambient tenant state. `Model.usingTenant(tenant)` uses the same safe core and adds eager helpers plus general `databaseOperation`/`transaction` model callbacks; eager records preserve legacy ambient Node follow-up semantics, while browser/native follow-up database work belongs inside the callback APIs. Inactive identifiers, mixed physical tenants, unsupported/cyclic descriptors, and expired operations fail closed. `Tenant.with` and `Tenant.each` retain their connection-establishing and model-initializing ambient behavior for Node request/job flows. `Tenant.aggregateAcross({identifier, aggregates, keyColumns, subquery, tenants?, filter?})` runs one aggregate over the same table across many tenant databases and returns the merged result — grouping tenants by server and using a single cross-database `UNION ALL` where the driver supports two-part `` `database`.`table` `` references (MySQL/MariaDB) or one query per tenant otherwise (PostgreSQL/SQLite/MSSQL).
+At runtime, the apartment-style `Tenant` façade (`velocious/build/src/tenants/tenant.js`) is the single entry point: `Tenant.with(tenant, callback)` / `Tenant.current()` to switch into and read a Node async context, `Tenant.handle(tenant)` to deeply capture immutable application and physical database identity for overlapping browser/native work, `Tenant.each({identifier, callback, parallel?, filter?})` to run a callback within every provider-listed tenant, and `Tenant.drop({identifier, tenant})` (plus the `db:tenants:drop` CLI command) to drop a tenant's database through the provider's `dropDatabase` hook. SQLite handles additionally expose framework-owned `open`, `flush`, `close`, `delete`, `inspect`, and `withPin` lifecycle methods; `frontendTenantSqlite.maxOpenHandles` bounds resident identities and clean, idle, unpinned handles are evicted least-recently-used. `Tenant.handle(...).databaseOperation(...)` and `.transaction(...)` use bounded pool-owned checkouts and pin model/query/write/association/preload/audit/attachment/raw work to the captured database even if a later UI project switch changes ambient tenant state. The handle also builds tenant-bound live-query sources, exposes an opaque physical identity for filtered record-change subscriptions, and binds project `SyncClient` instances. `Model.usingTenant(tenant)` uses the same safe core and adds eager helpers plus general `databaseOperation`/`transaction` model callbacks; eager records preserve legacy ambient Node follow-up semantics, while browser/native follow-up database work belongs inside the callback APIs. Inactive identifiers, mixed physical tenants, unsupported/cyclic descriptors, expired operations, unscoped tenant event subscriptions, and stale/cross-tenant sync state fail closed. `Tenant.with` and `Tenant.each` retain their connection-establishing and model-initializing ambient behavior for Node request/job flows. `Tenant.aggregateAcross({identifier, aggregates, keyColumns, subquery, tenants?, filter?})` runs one aggregate over the same table across many tenant databases and returns the merged result — grouping tenants by server and using a single cross-database `UNION ALL` where the driver supports two-part `` `database`.`table` `` references (MySQL/MariaDB) or one query per tenant otherwise (PostgreSQL/SQLite/MSSQL).
 
 `SchemaCloner` adds a missing auto-increment column and its separate source unique index in one schema alteration, including on MySQL/MariaDB where an auto-increment column must be keyed when it is created.
 

package/build/database/drivers/base.js

@@ -54,6 +54,7 @@
  * @property {boolean} retry - Whether the error should be retried.
  * @property {boolean} reconnect - Whether to reconnect before retrying.
  * @property {boolean} [deadlock] - Whether the error is a transaction deadlock/lock-wait-timeout that should retry the whole transaction.
+ * @property {"deadlock" | "lock-wait-timeout"} [contentionKind] - Classified transaction contention kind.
  * @property {number} [maxTries] - Override the max retry attempts.
  * @property {number} [waitMs] - Wait time before retrying in milliseconds.
  */
@@ -71,6 +72,25 @@
  * @property {symbol} [operationOwner] - Opaque owner for an operation-leased connection.
  */
 
+/**
+ * DeadlockRetryDiagnosticSnapshot type.
+ * @typedef {object} DeadlockRetryDiagnosticSnapshot
+ * @property {number} attempt - One-based transaction attempt.
+ * @property {"deadlock" | "lock-wait-timeout"} contentionKind - Classified contention kind.
+ * @property {string} [databaseIdentifier] - Redacted logical database pool identifier marker.
+ * @property {string} [databaseIdentifierFingerprint] - Opaque logical database pool identity.
+ * @property {string} [databaseIdentityFingerprint] - Opaque physical database identity.
+ * @property {string} driverType - Driver type.
+ * @property {number} maxAttempts - Configured transaction attempt budget.
+ * @property {string} [operationName] - Redacted operation-name marker.
+ * @property {string} [operationNameFingerprint] - Opaque operation-name identity.
+ * @property {string} [sqlFingerprint] - Normalized SQL-shape fingerprint.
+ * @property {string} [sqlOperation] - SQL verb.
+ * @property {string} stage - Error-event stage.
+ * @property {number} transactionAttemptDurationMs - Duration of the failed outer attempt.
+ * @property {boolean} willRetry - Whether another outer transaction attempt will run.
+ */
+
 /**
  * ActiveQueryDebugSnapshot type.
  * @typedef {object} ActiveQueryDebugSnapshot
@@ -144,19 +164,23 @@ import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/build/wait.js"
 import { optionalPositiveInteger } from "typanic"
 import { coordinateSharedTransactionConnection } from "../../testing/shared-transaction-connection-coordinator.js"
+import sha256Hex from "../../utils/sha256-hex.js"
 
 /** Maximum characters inspected when building the debug SQL preview. */
 const SQL_PREVIEW_SCAN_LIMIT = 4096
 /** Maximum characters inspected when deciding whether a statement invalidates schema metadata. */
 const SCHEMA_INVALIDATION_SCAN_LIMIT = 8192
+/** Maximum checkout-name characters inspected by retry diagnostics. */
+const OPERATION_NAME_SCAN_LIMIT = 1024
+const REDACTED_DIAGNOSTIC_LABEL = "[REDACTED]"
 
 /**
  * Builds a non-reversible, stable SQL fingerprint without retaining SQL text. Literal spelling is
  * normalized first so the same statement shape produces the same fingerprint across values.
  * @param {string} sql - SQL to fingerprint.
- * @returns {string} - Bounded fingerprint.
+ * @returns {{sqlFingerprint: string, sqlOperation: string}} - Bounded query diagnostic.
  */
-function sqlFingerprint(sql) {
+function sqlDiagnostic(sql) {
   let fingerprintInput = ""
 
   for (let index = 0; index < sql.length;) {
@@ -206,7 +230,12 @@ function sqlFingerprint(sql) {
     hash = BigInt.asUintN(64, hash * 0x100000001b3n)
   }
 
-  return `fnv1a64:${hash.toString(16).padStart(16, "0")}`
+  const operationMatch = /^([a-z]+)/.exec(normalized)
+
+  return {
+    sqlFingerprint: `fnv1a64:${hash.toString(16).padStart(16, "0")}`,
+    sqlOperation: operationMatch ? operationMatch[1].toUpperCase() : "UNKNOWN"
+  }
 }
 
 /**
@@ -270,6 +299,10 @@ export default class VelociousDatabaseDriversBase {
    * Narrows the runtime value to the documented type.
    * @type {string | undefined} */
   _connectionCheckoutName
+  /** @type {string | undefined} */
+  _databaseIdentifier
+  /** @type {string | undefined} */
+  _databaseIdentityFingerprint
   /**
    * Active query.
    * @type {ActiveQueryState | null} */
@@ -465,6 +498,16 @@ export default class VelociousDatabaseDriversBase {
     this._connectionCheckedOutAtUnixMs = undefined
   }
 
+  /**
+   * Sets the pool-owned identity used by safe database diagnostics.
+   * @param {{databaseIdentifier: string, databaseIdentityFingerprint: string}} identity - Pool-stamped identity redacted at diagnostic snapshot time.
+   * @returns {void}
+   */
+  setPoolDiagnosticIdentity({databaseIdentifier, databaseIdentityFingerprint}) {
+    this._databaseIdentifier = databaseIdentifier
+    this._databaseIdentityFingerprint = databaseIdentityFingerprint
+  }
+
   /**
    * Runs reconnect.
    * @returns {Promise<void>} - Resolves when complete.
@@ -1304,6 +1347,7 @@ export default class VelociousDatabaseDriversBase {
 
     while (true) {
       attempt++
+      const attemptStartedAtMs = this._nowMs()
 
       try {
         return await this._runTransactionAttempt(callback, options)
@@ -1312,9 +1356,17 @@ export default class VelociousDatabaseDriversBase {
         if (!(error instanceof Error)) throw error
 
         const retryInfo = this.retryableDatabaseError(error)
-
-        if (retryInfo.deadlock && attempt < maxAttempts && this._transactionsCount == 0) {
-          this._reportDeadlockRetryDiagnostic({attempt, error, maxAttempts})
+        const willRetry = Boolean(retryInfo.deadlock && attempt < maxAttempts && this._transactionsCount == 0)
+
+        if (willRetry) {
+          this._reportDeadlockRetryDiagnostic({
+            attempt,
+            contentionKind: retryInfo.contentionKind || "deadlock",
+            error,
+            maxAttempts,
+            transactionAttemptDurationMs: Math.max(0, this._nowMs() - attemptStartedAtMs),
+            willRetry
+          })
 
           // An explicitly-configured base wins so the tuning knob is effective even on drivers
           // whose classifier supplies its own `waitMs` (MySQL/MariaDB return a fixed 50ms for
@@ -1330,7 +1382,9 @@ export default class VelociousDatabaseDriversBase {
           const ceilingWaitMs = Math.min(baseWaitMs * (2 ** (attempt - 1)), deadlockMaxWaitMs)
           const jitteredWaitMs = Math.floor(Math.random() * (ceilingWaitMs + 1))
 
-          this.logger.warn(`Retrying transaction after deadlock (attempt ${attempt}/${maxAttempts})`)
+          const loggedContentionKind = retryInfo.contentionKind || "transaction contention"
+
+          this.logger.warn(`Retrying transaction after ${loggedContentionKind} (attempt ${attempt}/${maxAttempts})`)
           await this._waitMs(jitteredWaitMs)
           continue
         }
@@ -1350,29 +1404,67 @@ export default class VelociousDatabaseDriversBase {
     await wait(ms)
   }
 
+  /**
+   * Returns the clock used for transaction-attempt diagnostics.
+   * @returns {number} - Monotonic milliseconds where available.
+   */
+  _nowMs() {
+    return nowMs()
+  }
+
   /**
    * Starts best-effort deadlock diagnostics without joining the retry control flow. Subclasses may
    * add bounded driver-specific context; capture and event-listener failures cannot affect retry.
-   * @param {{attempt: number, error: Error, maxAttempts: number}} args - Retry metadata.
+   * @param {{attempt: number, contentionKind: "deadlock" | "lock-wait-timeout", error: Error, maxAttempts: number, transactionAttemptDurationMs: number, willRetry: boolean}} args - Retry metadata.
    * @returns {void}
    */
-  _reportDeadlockRetryDiagnostic({attempt, error, maxAttempts}) {
-    const queryDiagnostic = this._failedQueryDiagnostics.get(error)
+  _reportDeadlockRetryDiagnostic({attempt, contentionKind, error, maxAttempts, transactionAttemptDurationMs, willRetry}) {
+    let snapshot
 
-    void this._deadlockDiagnosticContext()
+    try {
+      const queryDiagnostic = this._failedQueryDiagnostics.get(error)
+
+      snapshot = Object.freeze({
+        attempt,
+        contentionKind,
+        driverType: this.getType(),
+        maxAttempts,
+        stage: "database-deadlock-retry",
+        transactionAttemptDurationMs,
+        willRetry,
+        ...this._poolDiagnosticIdentityContext(),
+        ...this._operationDiagnosticContext(),
+        ...queryDiagnostic
+      })
+    } catch (diagnosticError) {
+      this._reportDeadlockDiagnosticPipelineFailure(diagnosticError)
+      return
+    }
+
+    let driverContextResult
+
+    try {
+      driverContextResult = this._deadlockDiagnosticContext(snapshot)
+    } catch (diagnosticError) {
+      this._reportDeadlockDiagnosticPipelineFailure(diagnosticError)
+      return
+    }
+
+    const hasPromiseContract = driverContextResult instanceof Promise
+
+    void Promise.resolve(driverContextResult)
       .then((driverContext) => {
+        if (!hasPromiseContract) throw new Error("Database deadlock diagnostic context must return a Promise")
+
         const context = {
-          attempt,
-          driverType: this.getType(),
-          maxAttempts,
-          stage: "database-deadlock-retry",
-          willRetry: true,
-          ...queryDiagnostic,
+          ...snapshot,
           ...driverContext
         }
         const payload = {
           context,
-          error: new Error("Database transaction deadlock will be retried")
+          error: new Error(willRetry
+            ? `Database transaction ${contentionKind} will be retried`
+            : `Database transaction ${contentionKind} exhausted its retry budget`)
         }
         const errorEvents = this.configuration.getErrorEvents()
 
@@ -1388,30 +1480,93 @@ export default class VelociousDatabaseDriversBase {
           this.logger.warn("Database deadlock retry all-error listener failed", {error: eventError})
         }
       })
-      .catch((diagnosticError) => {
-        const normalizedError = diagnosticError instanceof Error
-          ? diagnosticError
-          : new Error("Database deadlock retry diagnostic failed", {cause: diagnosticError})
-        const payload = {
-          context: {stage: "database-deadlock-retry-diagnostic"},
-          error: normalizedError
-        }
+      .catch((diagnosticError) => this._reportDeadlockDiagnosticPipelineFailure(diagnosticError))
+  }
 
-        try {
-          const errorEvents = this.configuration.getErrorEvents()
-          errorEvents.emit("framework-error", payload)
-          errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
-        } catch (reportingError) {
-          this.logger.warn("Database deadlock retry diagnostic pipeline failed", {error: normalizedError, reportingError})
-        }
-      })
+  /**
+   * Returns pool identity only when this driver was stamped by a pool.
+   * @returns {{databaseIdentifier?: string, databaseIdentifierFingerprint?: string, databaseIdentityFingerprint?: string}} - Safe pool identity.
+   */
+  _poolDiagnosticIdentityContext() {
+    if (this._databaseIdentifier === undefined || !this._databaseIdentityFingerprint) return {}
+
+    const identifierFingerprintInput = typeof this._databaseIdentifier === "string"
+      ? this._databaseIdentifier
+      : `invalid:${typeof this._databaseIdentifier}`
+    const databaseIdentifierFingerprint = `sha256:${sha256Hex(`database-logical-identifier:v1\0${identifierFingerprintInput}`)}`
+
+    return {
+      databaseIdentifier: REDACTED_DIAGNOSTIC_LABEL,
+      databaseIdentifierFingerprint,
+      databaseIdentityFingerprint: this._databaseIdentityFingerprint
+    }
+  }
+
+  /**
+   * Builds the bounded operation portion of an immutable retry snapshot.
+   * @returns {{operationName?: string, operationNameFingerprint?: string}} - Safe operation fields.
+   */
+  _operationDiagnosticContext() {
+    const rawOperationName = this._connectionCheckoutName
+
+    if (rawOperationName === undefined) return {}
+    if (typeof rawOperationName !== "string") {
+      return {
+        operationName: REDACTED_DIAGNOSTIC_LABEL,
+        operationNameFingerprint: `sha256:${sha256Hex(`database-operation:v1\0invalid:${typeof rawOperationName}`)}`
+      }
+    }
+
+    const scannedOperationName = rawOperationName.slice(0, OPERATION_NAME_SCAN_LIMIT)
+    const operationNameFingerprint = `sha256:${sha256Hex(`database-operation:v1\0${scannedOperationName}\0length:${rawOperationName.length}`)}`
+
+    return {
+      operationName: REDACTED_DIAGNOSTIC_LABEL,
+      operationNameFingerprint
+    }
+  }
+
+  /**
+   * Reports an unexpected detached diagnostics failure without changing transaction control flow.
+   * @param {ReturnType<typeof JSON.parse>} diagnosticError - Diagnostics failure.
+   * @returns {void}
+   */
+  _reportDeadlockDiagnosticPipelineFailure(diagnosticError) {
+    const normalizedError = diagnosticError instanceof Error
+      ? diagnosticError
+      : new Error("Database deadlock retry diagnostic failed", {cause: diagnosticError})
+    const payload = {
+      context: {stage: "database-deadlock-retry-diagnostic"},
+      error: normalizedError
+    }
+    let errorEvents
+
+    try {
+      errorEvents = this.configuration.getErrorEvents()
+    } catch (reportingError) {
+      this.logger.warn("Database deadlock retry diagnostic pipeline reporting failed", {error: normalizedError, reportingError})
+      return
+    }
+
+    try {
+      errorEvents.emit("framework-error", payload)
+    } catch (reportingError) {
+      this.logger.warn("Database deadlock retry framework-error listener failed", {error: normalizedError, reportingError})
+    }
+
+    try {
+      errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+    } catch (reportingError) {
+      this.logger.warn("Database deadlock retry all-error listener failed", {error: normalizedError, reportingError})
+    }
   }
 
   /**
    * Builds driver-specific deadlock context. The base driver has no server diagnostic source.
+   * @param {DeadlockRetryDiagnosticSnapshot} _snapshot - Immutable retry snapshot.
    * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - Safe context fields.
    */
-  async _deadlockDiagnosticContext() {
+  async _deadlockDiagnosticContext(_snapshot) {
     return {}
   }
 
@@ -1716,10 +1871,7 @@ export default class VelociousDatabaseDriversBase {
       } catch (error) {
         if (!(error instanceof Error)) throw error
 
-        this._failedQueryDiagnostics.set(error, {
-          sqlFingerprint: sqlFingerprint(sql),
-          sqlOperation: sql.trim().split(/\s+/, 1)[0]?.toUpperCase() || "UNKNOWN"
-        })
+        this._failedQueryDiagnostics.set(error, sqlDiagnostic(sql))
 
         // A deliberately-aborted query must never be silently re-run — its
         // connection was destroyed on purpose, so treat it as terminal.

package/build/database/drivers/mysql/deadlock-diagnostic-parser.js

@@ -0,0 +1,227 @@
+// @ts-check
+
+/**
+ * InnodbDeadlockLockNode type.
+ * @typedef {object} InnodbDeadlockLockNode
+ * @property {string} indexFingerprint - Opaque index identity.
+ * @property {string} lockMode - Allowlisted lock mode.
+ * @property {"conflicting" | "held" | "waiting"} state - Lock relationship to its transaction.
+ * @property {string} tableFingerprint - Opaque table identity.
+ */
+
+/**
+ * InnodbDeadlockTransactionNode type.
+ * @typedef {object} InnodbDeadlockTransactionNode
+ * @property {InnodbDeadlockLockNode[]} conflictingLocks - Bounded counterparty conflict edges whose owner is unavailable.
+ * @property {InnodbDeadlockLockNode[]} locks - Bounded locks owned or awaited by this transaction.
+ * @property {number} ordinal - Report-local transaction ordinal.
+ */
+
+/**
+ * InnodbDeadlockParserState type.
+ * @typedef {object} InnodbDeadlockParserState
+ * @property {InnodbDeadlockTransactionNode | undefined} currentTransaction - Current bounded transaction node.
+ * @property {"conflicting" | "held" | "waiting" | undefined} currentLockState - Current lock section state.
+ * @property {number} lockRecordCount - Total emitted lock nodes.
+ * @property {boolean} lockRecordsTruncated - Whether a lock-node bound was reached.
+ * @property {InnodbDeadlockTransactionNode[]} transactionNodes - Bounded transaction nodes.
+ * @property {boolean} transactionNodesTruncated - Whether the transaction-node bound was reached.
+ * @property {number} transactions - Transaction headers observed in the bounded section.
+ * @property {number | null} victimTransaction - Victim ordinal.
+ */
+
+import sha256Hex from "../../../utils/sha256-hex.js"
+
+const INNODB_STATUS_SCAN_MAX_CHARS = 65536
+const INNODB_DEADLOCK_SECTION_MAX_CHARS = 16384
+const INNODB_DEADLOCK_TRANSACTION_MAX = 8
+const INNODB_DEADLOCK_LOCKS_PER_TRANSACTION_MAX = 8
+const INNODB_DEADLOCK_LOCK_RECORD_MAX = 32
+const INNODB_DEADLOCK_LINE_MAX_CHARS = 1024
+
+/**
+ * Parses a bounded InnoDB latest-deadlock section into safe structural context.
+ * @param {string} status - SHOW ENGINE INNODB STATUS text.
+ * @returns {{lockRecordsTruncated: boolean, sectionTruncated: boolean, transactionNodes: InnodbDeadlockTransactionNode[], transactionNodesTruncated: boolean, transactions: number, victimTransaction: number | null}} - Structural deadlock summary.
+ */
+export default function parseInnodbDeadlockSummary(status) {
+  const {candidate, sectionTruncated} = boundedDeadlockSection(status)
+  /** @type {InnodbDeadlockParserState} */
+  const state = {
+    currentTransaction: undefined,
+    currentLockState: undefined,
+    lockRecordCount: 0,
+    lockRecordsTruncated: false,
+    transactionNodes: [],
+    transactionNodesTruncated: false,
+    transactions: 0,
+    victimTransaction: null
+  }
+
+  for (const line of candidate.split(/\r?\n/)) {
+    const trimmed = line.slice(0, INNODB_DEADLOCK_LINE_MAX_CHARS).trim()
+    const transactionOrdinal = transactionHeaderOrdinal(trimmed)
+
+    if (transactionOrdinal !== undefined) {
+      startTransactionNode(state, transactionOrdinal)
+      continue
+    }
+
+    const lockStateMarker = transactionLockStateMarker(trimmed, state.currentTransaction)
+
+    if (lockStateMarker.matched) {
+      state.currentLockState = lockStateMarker.state
+      continue
+    }
+
+    const victimOrdinal = victimTransactionOrdinal(trimmed)
+
+    if (victimOrdinal !== undefined) state.victimTransaction = victimOrdinal
+    appendLockNode(state, trimmed)
+  }
+
+  return {
+    lockRecordsTruncated: state.lockRecordsTruncated,
+    sectionTruncated,
+    transactionNodes: state.transactionNodes,
+    transactionNodesTruncated: state.transactionNodesTruncated,
+    transactions: state.transactions,
+    victimTransaction: state.victimTransaction
+  }
+}
+
+/**
+ * Extracts and caps the latest-deadlock section.
+ * @param {string} status - Raw server status.
+ * @returns {{candidate: string, sectionTruncated: boolean}} - Bounded candidate and truncation state.
+ */
+function boundedDeadlockSection(status) {
+  const scannedStatus = status.slice(0, INNODB_STATUS_SCAN_MAX_CHARS)
+  const deadlockStart = scannedStatus.indexOf("LATEST DETECTED DEADLOCK")
+  const availableSection = deadlockStart >= 0 ? scannedStatus.slice(deadlockStart) : ""
+  const boundedSection = availableSection.slice(0, INNODB_DEADLOCK_SECTION_MAX_CHARS)
+  const sectionEndMatch = /\n-{10,}\r?\nTRANSACTIONS\r?\n-{10,}/.exec(boundedSection)
+  const scannedStatusTruncated = status.length > scannedStatus.length
+
+  return {
+    candidate: sectionEndMatch ? boundedSection.slice(0, sectionEndMatch.index) : boundedSection,
+    sectionTruncated: !sectionEndMatch && deadlockStart >= 0 && (
+      availableSection.length > boundedSection.length || scannedStatusTruncated
+    )
+  }
+}
+
+/**
+ * Returns a fixed-format transaction header ordinal.
+ * @param {string} line - Bounded status line.
+ * @returns {number | undefined} - Transaction ordinal.
+ */
+function transactionHeaderOrdinal(line) {
+  const match = /^\*\*\* \((\d{1,6})\) TRANSACTION:$/.exec(line)
+
+  return match ? Number(match[1]) : undefined
+}
+
+/**
+ * Starts a bounded transaction node.
+ * @param {InnodbDeadlockParserState} state - Parser state.
+ * @param {number} ordinal - Transaction ordinal.
+ * @returns {void}
+ */
+function startTransactionNode(state, ordinal) {
+  state.transactions++
+  state.currentLockState = undefined
+
+  if (state.transactionNodes.length >= INNODB_DEADLOCK_TRANSACTION_MAX) {
+    state.currentTransaction = undefined
+    state.transactionNodesTruncated = true
+    return
+  }
+
+  state.currentTransaction = {conflictingLocks: [], locks: [], ordinal}
+  state.transactionNodes.push(state.currentTransaction)
+}
+
+/**
+ * Parses a fixed-format held/waiting marker for the current transaction.
+ * @param {string} line - Bounded status line.
+ * @param {InnodbDeadlockTransactionNode | undefined} currentTransaction - Current transaction.
+ * @returns {{matched: boolean, state: "conflicting" | "held" | "waiting" | undefined}} - Marker result.
+ */
+function transactionLockStateMarker(line, currentTransaction) {
+  const numberedMatch = /^\*\*\* \((\d{1,6})\) (HOLDS THE LOCK\(S\)|WAITING FOR THIS LOCK TO BE GRANTED):$/.exec(line)
+
+  if (numberedMatch) {
+    if (!currentTransaction || currentTransaction.ordinal != Number(numberedMatch[1])) return {matched: true, state: undefined}
+
+    return {matched: true, state: numberedMatch[2] == "HOLDS THE LOCK(S)" ? "held" : "waiting"}
+  }
+
+  const unnumberedMatch = /^\*\*\* (WAITING FOR THIS LOCK TO BE GRANTED|CONFLICTING WITH):$/.exec(line)
+
+  if (!unnumberedMatch) return {matched: false, state: undefined}
+  if (!currentTransaction) return {matched: true, state: undefined}
+
+  return {matched: true, state: unnumberedMatch[1] == "CONFLICTING WITH" ? "conflicting" : "waiting"}
+}
+
+/**
+ * Returns a fixed-format victim ordinal.
+ * @param {string} line - Bounded status line.
+ * @returns {number | undefined} - Victim ordinal.
+ */
+function victimTransactionOrdinal(line) {
+  const match = /^\*\*\* WE ROLL BACK TRANSACTION \((\d{1,6})\)$/.exec(line)
+
+  return match ? Number(match[1]) : undefined
+}
+
+/**
+ * Appends one bounded, fixed-format lock node when the line is eligible.
+ * @param {InnodbDeadlockParserState} state - Parser state.
+ * @param {string} line - Bounded status line.
+ * @returns {void}
+ */
+function appendLockNode(state, line) {
+  if (!state.currentTransaction || !state.currentLockState || !line.startsWith("RECORD LOCKS ")) return
+
+  if (
+    state.lockRecordCount >= INNODB_DEADLOCK_LOCK_RECORD_MAX ||
+    state.currentTransaction.locks.length + state.currentTransaction.conflictingLocks.length >= INNODB_DEADLOCK_LOCKS_PER_TRANSACTION_MAX
+  ) {
+    state.lockRecordsTruncated = true
+    return
+  }
+
+  const lock = deadlockLockNode(line, state.currentLockState)
+
+  if (!lock) return
+
+  if (state.currentLockState == "conflicting") {
+    state.currentTransaction.conflictingLocks.push(lock)
+  } else {
+    state.currentTransaction.locks.push(lock)
+  }
+  state.lockRecordCount++
+}
+
+/**
+ * Parses one fixed-format RECORD LOCKS line into safe structural fields.
+ * @param {string} line - One bounded InnoDB status line.
+ * @param {"conflicting" | "held" | "waiting"} state - Lock relationship to its transaction.
+ * @returns {InnodbDeadlockLockNode | undefined} - Safe lock node.
+ */
+function deadlockLockNode(line, state) {
+  const identifier = "(?:`(?:``|[^`\\r\\n]){1,128}`|[A-Za-z0-9_$-]{1,128})"
+  const tableIdentifier = `(?:${identifier}\\.)?${identifier}`
+  const lockMatch = new RegExp(`^RECORD LOCKS .{1,512}? index (${identifier}) of table (${tableIdentifier}) trx id \\S{1,64}(?: \\S{1,64})? lock_mode (X|S|IX|IS|AUTO_INC)(?:\\s|$)`).exec(line)
+
+  if (!lockMatch) return undefined
+
+  return {
+    indexFingerprint: `sha256:${sha256Hex(`innodb-index:v1\0${lockMatch[1]}`)}`,
+    lockMode: lockMatch[3],
+    state,
+    tableFingerprint: `sha256:${sha256Hex(`innodb-table:v1\0${lockMatch[2]}`)}`
+  }
+}