@quereus/quereus 3.3.0 → 4.1.0

package/dist/src/core/database-events.d.ts

@@ -59,8 +59,68 @@ export interface DatabaseSchemaChangeEvent {
     /** True if event originated from sync/remote source, false for local changes */
     remote: boolean;
 }
+/**
+ * Materialized-view key-coarsening **collision** event emitted at the database
+ * level — the operational complement to the create-time key-coarsening warning
+ * (`docs/materialized-views.md` § Coarsened backing keys). Fired from row-time
+ * maintenance whenever an upsert under the coarsened backing key K′ replaces a
+ * backing row whose **source identity differs** from the incoming row's — i.e.
+ * two distinct source-key tuples (`'Bob'` / `'bob'`) merged into one derived row
+ * under K′'s coarsened (output) collation, last-writer-win (`docs/migration.md`
+ * § Convergence hazards). One event per realized colliding merge, delivered on
+ * the commit that realized it (it rides the same transaction batching the
+ * data/schema channels use, so a collision inside a rolled-back transaction
+ * reports nothing).
+ */
+export interface MaintenanceCollisionEvent {
+    /** Schema name of the maintained (backing) table. */
+    schemaName: string;
+    /** Maintained (backing) table name. */
+    tableName: string;
+    /** The coarsened backing key K′ values (from the incoming/new row), in key order. */
+    key: SqlValue[];
+    /** Names of the weakened K′ column(s) whose values diverged under the source
+     *  (pre-coarsening, stricter) collation — the columns whose coarsening realized
+     *  the merge. */
+    weakenedColumns: string[];
+    /** The replaced backing row (the losing source identity's prior image). */
+    oldRow: Row;
+    /** The incoming backing row that won the merge (the new image). */
+    newRow: Row;
+    /** Reserved: true when the colliding write arrived via the external-change
+     *  ingest seam (peer) rather than local DML. Not threaded through maintenance
+     *  in v1 (see the ticket's Out of scope) — left unset. */
+    remote?: boolean;
+}
+/**
+ * The complete, ordered fact set of one committed logical transaction, delivered
+ * as a single group on the {@link DatabaseEventEmitter.onTransactionCommit}
+ * channel. This is the authoritative "one transaction = one group" boundary the
+ * sync layer anchors an HLC to: it spans **all** tables touched by the
+ * transaction (every module's emitter feeds the same engine-level batch), so a
+ * cross-table commit is never split — unlike a per-table store coordinator, which
+ * commits each table separately. See `docs/sync.md` § Transaction-Based Change
+ * Grouping.
+ *
+ * Delivered once from `flushBatch()` (i.e. after a successful commit), never on
+ * rollback. The `dataEvents`/`schemaEvents` carry the same
+ * {@link DatabaseDataChangeEvent}/{@link DatabaseSchemaChangeEvent} shapes the
+ * per-event `onDataChange`/`onSchemaChange` channels deliver — `onTransactionCommit`
+ * is purely additive and does not replace them.
+ */
+export interface TransactionCommitBatch {
+    /** All data events of the committed transaction, in flush order (base batch
+     *  then each savepoint layer, in push order — the same order `flushBatch`
+     *  emits per-event). Per-module/per-table arrival order at commit, not global
+     *  DML-interleave order; deterministic and replayable. */
+    readonly dataEvents: ReadonlyArray<DatabaseDataChangeEvent>;
+    /** All schema events of the committed transaction, in flush order. */
+    readonly schemaEvents: ReadonlyArray<DatabaseSchemaChangeEvent>;
+}
 export type DatabaseDataChangeListener = (event: DatabaseDataChangeEvent) => void;
 export type DatabaseSchemaChangeListener = (event: DatabaseSchemaChangeEvent) => void;
+export type MaintenanceCollisionListener = (event: MaintenanceCollisionEvent) => void;
+export type TransactionCommitListener = (batch: TransactionCommitBatch) => void;
 /**
  * Options for subscribing to data change events.
  * Reserved fields for future filtering capabilities, plus pass-through for module-specific options.
@@ -89,13 +149,26 @@ export interface SchemaChangeSubscriptionOptions {
 export declare class DatabaseEventEmitter {
     private dataListeners;
     private schemaListeners;
+    private collisionListeners;
+    private transactionCommitListeners;
     private maxListeners;
     /** Batched events waiting for commit (base transaction level) */
     private batchedDataEvents;
     private batchedSchemaEvents;
+    private batchedCollisionEvents;
     /** Savepoint layers for event batching - each layer captures events since that savepoint */
     private dataEventLayers;
     private schemaEventLayers;
+    private collisionEventLayers;
+    /**
+     * Cumulative count of COMMITTED key-coarsening collisions, keyed by lowercased
+     * qualified `schema.table` of the maintained table. Incremented in
+     * {@link flushBatch} as each batched collision is emitted (or immediately on the
+     * non-batching path) — so the count reflects only collisions that actually
+     * committed, consistent with event delivery, and survives a host that never
+     * subscribed an `onMaintenanceCollision` listener.
+     */
+    private collisionCounts;
     /** Whether we're currently in a transaction (batching mode) */
     private isBatching;
     /** Map of module emitters we've subscribed to, for cleanup */
@@ -132,6 +205,58 @@ export declare class DatabaseEventEmitter {
      * Check if there are any schema change listeners registered.
      */
     hasSchemaListeners(): boolean;
+    /**
+     * Subscribe to materialized-view key-coarsening collision events
+     * ({@link MaintenanceCollisionEvent}). Events share the data/schema channels'
+     * transaction-batching discipline — delivered after the commit that realized
+     * the merge, dropped on rollback.
+     * @param listener Callback invoked for each committed collision
+     * @returns Unsubscribe function
+     */
+    onMaintenanceCollision(listener: MaintenanceCollisionListener): () => void;
+    /**
+     * Check if there are any maintenance-collision listeners registered.
+     */
+    hasCollisionListeners(): boolean;
+    /**
+     * Subscribe to grouped per-transaction commit batches
+     * ({@link TransactionCommitBatch}). Fired **once** per committed logical
+     * transaction, after the per-event {@link onDataChange}/{@link onSchemaChange}
+     * delivery, carrying every data and schema event of that transaction (across
+     * all tables) in flush order — the authoritative grouping boundary for
+     * "one transaction = one group". Never fires on rollback, and never fires for a
+     * transaction that produced no data or schema events (an empty/idle commit).
+     * This is additive: the per-event channels are untouched.
+     * @param listener Callback invoked once per committed transaction
+     * @returns Unsubscribe function
+     */
+    onTransactionCommit(listener: TransactionCommitListener): () => void;
+    /**
+     * Check if there are any transaction-commit listeners registered.
+     */
+    hasTransactionCommitListeners(): boolean;
+    /**
+     * Whether the engine must collect data-change events for delivery — true when
+     * any per-event {@link onDataChange} listener OR any {@link onTransactionCommit}
+     * listener is registered. A transaction-commit listener needs the grouped data
+     * events, so the auto-event generation gate must open for it too even when no
+     * per-event data listener is subscribed. Consulted by the DML executor's
+     * auto-event gate (see `dml-executor.ts`).
+     */
+    needsDataEvents(): boolean;
+    /**
+     * Whether the engine must collect schema-change events for delivery — true when
+     * any per-event {@link onSchemaChange} listener OR any {@link onTransactionCommit}
+     * listener is registered. Companion to {@link needsDataEvents}; consulted by the
+     * schema manager's auto-event gate (see `schema/manager.ts`).
+     */
+    needsSchemaEvents(): boolean;
+    /**
+     * Read-only snapshot of the cumulative committed-collision counter, keyed by
+     * lowercased qualified `schema.table`. A fresh copy each call, so the caller
+     * cannot mutate the live counter.
+     */
+    getMaterializedViewCollisionStats(): ReadonlyMap<string, number>;
     /**
      * Hook a module's event emitter to forward events to the database level.
      * Called when a module with native event support is detected.
@@ -159,6 +284,10 @@ export declare class DatabaseEventEmitter {
      * Get the active schema event store (top layer or base).
      */
     private getActiveSchemaStore;
+    /**
+     * Get the active collision event store (top savepoint layer or base).
+     */
+    private getActiveCollisionStore;
     /**
      * Handle a data change event from a module.
      * If batching, queue the event; otherwise emit immediately.
@@ -186,6 +315,34 @@ export declare class DatabaseEventEmitter {
      * @param event The event to emit
      */
     emitAutoSchemaEvent(moduleName: string, event: VTableSchemaChangeEvent): void;
+    /**
+     * Queue a materialized-view key-coarsening collision for delivery. If batching
+     * (inside a transaction/savepoint), the event is captured in the active store
+     * and emitted only on commit (dropped on rollback); otherwise it is emitted —
+     * and counted — immediately. Mirrors {@link emitAutoDataEvent}.
+     */
+    queueCollision(event: MaintenanceCollisionEvent): void;
+    /**
+     * Count and emit one collision event. The cumulative committed-collision
+     * counter is incremented FIRST (always — even with no listeners, so the count
+     * survives a host that never subscribed), then the event is delivered to each
+     * listener. A throwing listener is isolated so it cannot break emission to the
+     * others or the commit (mirrors {@link emitDataEvent}).
+     */
+    private emitCollisionEvent;
+    /**
+     * Project a pending data event into the database-level {@link DatabaseDataChangeEvent}
+     * shape delivered to listeners. The single source of truth for the projection,
+     * reused by both the per-event {@link emitDataEvent} path and the grouped
+     * {@link flushBatch} transaction-commit batch so listeners on either channel see
+     * identical shapes.
+     */
+    private toDataChangeEvent;
+    /**
+     * Project a pending schema event into the database-level {@link DatabaseSchemaChangeEvent}
+     * shape. Companion to {@link toDataChangeEvent}; same dual-use rationale.
+     */
+    private toSchemaChangeEvent;
     /**
      * Emit a data event to all listeners.
      */
@@ -203,6 +360,12 @@ export declare class DatabaseEventEmitter {
      * Collects events from all layers (base + savepoint layers) and emits them.
      */
     flushBatch(): void;
+    /**
+     * Deliver one grouped {@link TransactionCommitBatch} to each transaction-commit
+     * listener. A throwing listener is isolated so it cannot break delivery to the
+     * others or the commit (mirrors {@link emitDataEvent}).
+     */
+    private emitTransactionCommit;
     /**
      * Discard all batched events (called on rollback).
      */

package/dist/src/core/database-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database-events.d.ts","sourceRoot":"","sources":["../../../src/core/database-events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"database-events.d.ts","sourceRoot":"","sources":["../../../src/core/database-events.ts"],"names":[],"mappings":"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"}

package/dist/src/core/database-events.js

@@ -28,13 +28,26 @@ const DEFAULT_MAX_LISTENERS = 100;
 export class DatabaseEventEmitter {
     dataListeners = new Set();
     schemaListeners = new Set();
+    collisionListeners = new Set();
+    transactionCommitListeners = new Set();
     maxListeners = DEFAULT_MAX_LISTENERS;
     /** Batched events waiting for commit (base transaction level) */
     batchedDataEvents = [];
     batchedSchemaEvents = [];
+    batchedCollisionEvents = [];
     /** Savepoint layers for event batching - each layer captures events since that savepoint */
     dataEventLayers = [];
     schemaEventLayers = [];
+    collisionEventLayers = [];
+    /**
+     * Cumulative count of COMMITTED key-coarsening collisions, keyed by lowercased
+     * qualified `schema.table` of the maintained table. Incremented in
+     * {@link flushBatch} as each batched collision is emitted (or immediately on the
+     * non-batching path) — so the count reflects only collisions that actually
+     * committed, consistent with event delivery, and survives a host that never
+     * subscribed an `onMaintenanceCollision` listener.
+     */
+    collisionCounts = new Map();
     /** Whether we're currently in a transaction (batching mode) */
     isBatching = false;
     /** Map of module emitters we've subscribed to, for cleanup */
@@ -95,6 +108,84 @@ export class DatabaseEventEmitter {
     hasSchemaListeners() {
         return this.schemaListeners.size > 0;
     }
+    /**
+     * Subscribe to materialized-view key-coarsening collision events
+     * ({@link MaintenanceCollisionEvent}). Events share the data/schema channels'
+     * transaction-batching discipline — delivered after the commit that realized
+     * the merge, dropped on rollback.
+     * @param listener Callback invoked for each committed collision
+     * @returns Unsubscribe function
+     */
+    onMaintenanceCollision(listener) {
+        this.collisionListeners.add(listener);
+        this.checkListenerCount('collision', this.collisionListeners.size);
+        log('Added maintenance-collision listener, total: %d', this.collisionListeners.size);
+        return () => {
+            this.collisionListeners.delete(listener);
+            log('Removed maintenance-collision listener, total: %d', this.collisionListeners.size);
+        };
+    }
+    /**
+     * Check if there are any maintenance-collision listeners registered.
+     */
+    hasCollisionListeners() {
+        return this.collisionListeners.size > 0;
+    }
+    /**
+     * Subscribe to grouped per-transaction commit batches
+     * ({@link TransactionCommitBatch}). Fired **once** per committed logical
+     * transaction, after the per-event {@link onDataChange}/{@link onSchemaChange}
+     * delivery, carrying every data and schema event of that transaction (across
+     * all tables) in flush order — the authoritative grouping boundary for
+     * "one transaction = one group". Never fires on rollback, and never fires for a
+     * transaction that produced no data or schema events (an empty/idle commit).
+     * This is additive: the per-event channels are untouched.
+     * @param listener Callback invoked once per committed transaction
+     * @returns Unsubscribe function
+     */
+    onTransactionCommit(listener) {
+        this.transactionCommitListeners.add(listener);
+        this.checkListenerCount('transaction-commit', this.transactionCommitListeners.size);
+        log('Added transaction-commit listener, total: %d', this.transactionCommitListeners.size);
+        return () => {
+            this.transactionCommitListeners.delete(listener);
+            log('Removed transaction-commit listener, total: %d', this.transactionCommitListeners.size);
+        };
+    }
+    /**
+     * Check if there are any transaction-commit listeners registered.
+     */
+    hasTransactionCommitListeners() {
+        return this.transactionCommitListeners.size > 0;
+    }
+    /**
+     * Whether the engine must collect data-change events for delivery — true when
+     * any per-event {@link onDataChange} listener OR any {@link onTransactionCommit}
+     * listener is registered. A transaction-commit listener needs the grouped data
+     * events, so the auto-event generation gate must open for it too even when no
+     * per-event data listener is subscribed. Consulted by the DML executor's
+     * auto-event gate (see `dml-executor.ts`).
+     */
+    needsDataEvents() {
+        return this.dataListeners.size > 0 || this.transactionCommitListeners.size > 0;
+    }
+    /**
+     * Whether the engine must collect schema-change events for delivery — true when
+     * any per-event {@link onSchemaChange} listener OR any {@link onTransactionCommit}
+     * listener is registered. Companion to {@link needsDataEvents}; consulted by the
+     * schema manager's auto-event gate (see `schema/manager.ts`).
+     */
+    needsSchemaEvents() {
+        return this.schemaListeners.size > 0 || this.transactionCommitListeners.size > 0;
+    }
+    /**
+     * Read-only snapshot of the cumulative committed-collision counter, keyed by
+     * lowercased qualified `schema.table`. A fresh copy each call, so the caller
+     * cannot mutate the live counter.
+     */
+    getMaterializedViewCollisionStats() {
+        return new Map(this.collisionCounts);
+    }
     /**
      * Hook a module's event emitter to forward events to the database level.
      * Called when a module with native event support is detected.
@@ -163,6 +254,14 @@ export class DatabaseEventEmitter {
             ? this.schemaEventLayers[this.schemaEventLayers.length - 1]
             : this.batchedSchemaEvents;
     }
+    /**
+     * Get the active collision event store (top savepoint layer or base).
+     */
+    getActiveCollisionStore() {
+        return this.collisionEventLayers.length > 0
+            ? this.collisionEventLayers[this.collisionEventLayers.length - 1]
+            : this.batchedCollisionEvents;
+    }
     /**
      * Handle a data change event from a module.
      * If batching, queue the event; otherwise emit immediately.
@@ -222,12 +321,51 @@ export class DatabaseEventEmitter {
         }
     }
     /**
-     * Emit a data event to all listeners.
+     * Queue a materialized-view key-coarsening collision for delivery. If batching
+     * (inside a transaction/savepoint), the event is captured in the active store
+     * and emitted only on commit (dropped on rollback); otherwise it is emitted —
+     * and counted — immediately. Mirrors {@link emitAutoDataEvent}.
      */
-    emitDataEvent(moduleName, event) {
-        if (this.dataListeners.size === 0)
+    queueCollision(event) {
+        if (this.isBatching) {
+            this.getActiveCollisionStore().push(event);
+            log('Batched maintenance-collision event on %s.%s', event.schemaName, event.tableName);
+        }
+        else {
+            this.emitCollisionEvent(event);
+        }
+    }
+    /**
+     * Count and emit one collision event. The cumulative committed-collision
+     * counter is incremented FIRST (always — even with no listeners, so the count
+     * survives a host that never subscribed), then the event is delivered to each
+     * listener. A throwing listener is isolated so it cannot break emission to the
+     * others or the commit (mirrors {@link emitDataEvent}).
+     */
+    emitCollisionEvent(event) {
+        const counterKey = `${event.schemaName}.${event.tableName}`.toLowerCase();
+        this.collisionCounts.set(counterKey, (this.collisionCounts.get(counterKey) ?? 0) + 1);
+        if (this.collisionListeners.size === 0)
             return;
-        const dbEvent = {
+        log('Emitting maintenance-collision event on %s.%s (weakened: %s)', event.schemaName, event.tableName, event.weakenedColumns.join(', '));
+        for (const listener of this.collisionListeners) {
+            try {
+                listener(event);
+            }
+            catch (e) {
+                errorLog('Maintenance-collision listener error on %s.%s: %O', event.schemaName, event.tableName, e);
+            }
+        }
+    }
+    /**
+     * Project a pending data event into the database-level {@link DatabaseDataChangeEvent}
+     * shape delivered to listeners. The single source of truth for the projection,
+     * reused by both the per-event {@link emitDataEvent} path and the grouped
+     * {@link flushBatch} transaction-commit batch so listeners on either channel see
+     * identical shapes.
+     */
+    toDataChangeEvent(moduleName, event) {
+        return {
             type: event.type,
             moduleName,
             schemaName: event.schemaName,
@@ -238,6 +376,31 @@ export class DatabaseEventEmitter {
             changedColumns: event.changedColumns,
             remote: event.remote ?? false,
         };
+    }
+    /**
+     * Project a pending schema event into the database-level {@link DatabaseSchemaChangeEvent}
+     * shape. Companion to {@link toDataChangeEvent}; same dual-use rationale.
+     */
+    toSchemaChangeEvent(moduleName, event) {
+        return {
+            type: event.type,
+            objectType: event.objectType,
+            moduleName,
+            schemaName: event.schemaName,
+            objectName: event.objectName,
+            columnName: event.columnName,
+            oldColumnName: event.oldColumnName,
+            ddl: event.ddl,
+            remote: event.remote ?? false,
+        };
+    }
+    /**
+     * Emit a data event to all listeners.
+     */
+    emitDataEvent(moduleName, event) {
+        if (this.dataListeners.size === 0)
+            return;
+        const dbEvent = this.toDataChangeEvent(moduleName, event);
         log('Emitting data event: %s on %s.%s (module: %s, remote: %s)', dbEvent.type, dbEvent.schemaName, dbEvent.tableName, moduleName, dbEvent.remote);
         for (const listener of this.dataListeners) {
             try {
@@ -254,17 +417,7 @@ export class DatabaseEventEmitter {
     emitSchemaEvent(moduleName, event) {
         if (this.schemaListeners.size === 0)
             return;
-        const dbEvent = {
-            type: event.type,
-            objectType: event.objectType,
-            moduleName,
-            schemaName: event.schemaName,
-            objectName: event.objectName,
-            columnName: event.columnName,
-            oldColumnName: event.oldColumnName,
-            ddl: event.ddl,
-            remote: event.remote ?? false,
-        };
+        const dbEvent = this.toSchemaChangeEvent(moduleName, event);
         log('Emitting schema event: %s %s %s (module: %s, remote: %s)', dbEvent.type, dbEvent.objectType, dbEvent.objectName, moduleName, dbEvent.remote);
         for (const listener of this.schemaListeners) {
             try {
@@ -282,8 +435,10 @@ export class DatabaseEventEmitter {
         this.isBatching = true;
         this.batchedDataEvents = [];
         this.batchedSchemaEvents = [];
+        this.batchedCollisionEvents = [];
         this.dataEventLayers = [];
         this.schemaEventLayers = [];
+        this.collisionEventLayers = [];
         log('Started event batching');
     }
     /**
@@ -301,12 +456,18 @@ export class DatabaseEventEmitter {
         for (const layer of this.schemaEventLayers) {
             allSchemaEvents.push(...layer);
         }
+        const allCollisionEvents = [...this.batchedCollisionEvents];
+        for (const layer of this.collisionEventLayers) {
+            allCollisionEvents.push(...layer);
+        }
         // Clear all
         this.batchedDataEvents = [];
         this.batchedSchemaEvents = [];
+        this.batchedCollisionEvents = [];
         this.dataEventLayers = [];
         this.schemaEventLayers = [];
-        log('Flushing %d data events and %d schema events', allDataEvents.length, allSchemaEvents.length);
+        this.collisionEventLayers = [];
+        log('Flushing %d data events, %d schema events, and %d collision events', allDataEvents.length, allSchemaEvents.length, allCollisionEvents.length);
         // Emit schema events first (table creation before data insertion makes logical sense)
         for (const { moduleName, event } of allSchemaEvents) {
             this.emitSchemaEvent(moduleName, event);
@@ -315,6 +476,40 @@ export class DatabaseEventEmitter {
         for (const { moduleName, event } of allDataEvents) {
             this.emitDataEvent(moduleName, event);
         }
+        // Then count + emit collision events (each increments the cumulative counter,
+        // so the count reflects only committed collisions).
+        for (const event of allCollisionEvents) {
+            this.emitCollisionEvent(event);
+        }
+        // Finally, deliver the whole committed transaction as a single grouped
+        // batch on the additive onTransactionCommit channel. Built from the same
+        // allDataEvents/allSchemaEvents projections the per-event path used, so the
+        // shapes match. Skipped entirely when no listener is subscribed (avoid the
+        // per-commit allocation in the common no-subscriber case) or when the
+        // transaction produced no data/schema facts (an empty/idle commit, or one
+        // that produced only collisions — collisions keep their own channel).
+        if (this.transactionCommitListeners.size > 0 && (allDataEvents.length + allSchemaEvents.length) > 0) {
+            this.emitTransactionCommit({
+                dataEvents: allDataEvents.map(({ moduleName, event }) => this.toDataChangeEvent(moduleName, event)),
+                schemaEvents: allSchemaEvents.map(({ moduleName, event }) => this.toSchemaChangeEvent(moduleName, event)),
+            });
+        }
+    }
+    /**
+     * Deliver one grouped {@link TransactionCommitBatch} to each transaction-commit
+     * listener. A throwing listener is isolated so it cannot break delivery to the
+     * others or the commit (mirrors {@link emitDataEvent}).
+     */
+    emitTransactionCommit(batch) {
+        log('Emitting transaction-commit batch: %d data events, %d schema events', batch.dataEvents.length, batch.schemaEvents.length);
+        for (const listener of this.transactionCommitListeners) {
+            try {
+                listener(batch);
+            }
+            catch (e) {
+                errorLog('Transaction-commit listener error: %O', e);
+            }
+        }
     }
     /**
      * Discard all batched events (called on rollback).
@@ -323,11 +518,14 @@ export class DatabaseEventEmitter {
         this.isBatching = false;
         const discardedData = this.batchedDataEvents.length + this.dataEventLayers.reduce((sum, layer) => sum + layer.length, 0);
         const discardedSchema = this.batchedSchemaEvents.length + this.schemaEventLayers.reduce((sum, layer) => sum + layer.length, 0);
+        const discardedCollision = this.batchedCollisionEvents.length + this.collisionEventLayers.reduce((sum, layer) => sum + layer.length, 0);
         this.batchedDataEvents = [];
         this.batchedSchemaEvents = [];
+        this.batchedCollisionEvents = [];
         this.dataEventLayers = [];
         this.schemaEventLayers = [];
-        log('Discarded %d data events and %d schema events', discardedData, discardedSchema);
+        this.collisionEventLayers = [];
+        log('Discarded %d data events, %d schema events, and %d collision events', discardedData, discardedSchema, discardedCollision);
     }
     /**
      * Begin a new savepoint layer for event batching.
@@ -336,6 +534,7 @@ export class DatabaseEventEmitter {
     beginSavepointLayer() {
         this.dataEventLayers.push([]);
         this.schemaEventLayers.push([]);
+        this.collisionEventLayers.push([]);
         log('Started savepoint event layer (depth: %d)', this.dataEventLayers.length);
     }
     /**
@@ -345,7 +544,8 @@ export class DatabaseEventEmitter {
     rollbackSavepointLayer() {
         const discardedData = this.dataEventLayers.pop();
         const discardedSchema = this.schemaEventLayers.pop();
-        log('Rolled back savepoint event layer, discarded %d data and %d schema events', discardedData?.length ?? 0, discardedSchema?.length ?? 0);
+        const discardedCollision = this.collisionEventLayers.pop();
+        log('Rolled back savepoint event layer, discarded %d data, %d schema, and %d collision events', discardedData?.length ?? 0, discardedSchema?.length ?? 0, discardedCollision?.length ?? 0);
     }
     /**
      * Release the current savepoint layer, merging its events into the parent layer.
@@ -367,7 +567,14 @@ export class DatabaseEventEmitter {
                 : this.batchedSchemaEvents;
             targetSchema.push(...topSchema);
         }
-        log('Released savepoint event layer, merged %d data and %d schema events', topData?.length ?? 0, topSchema?.length ?? 0);
+        const topCollision = this.collisionEventLayers.pop();
+        if (topCollision && topCollision.length > 0) {
+            const targetCollision = this.collisionEventLayers.length > 0
+                ? this.collisionEventLayers[this.collisionEventLayers.length - 1]
+                : this.batchedCollisionEvents;
+            targetCollision.push(...topCollision);
+        }
+        log('Released savepoint event layer, merged %d data, %d schema, and %d collision events', topData?.length ?? 0, topSchema?.length ?? 0, topCollision?.length ?? 0);
     }
     /**
      * Remove all listeners and unhook all modules.
@@ -377,15 +584,22 @@ export class DatabaseEventEmitter {
     removeAllListeners() {
         const dataCount = this.dataListeners.size;
         const schemaCount = this.schemaListeners.size;
-        if (dataCount > 0 || schemaCount > 0) {
-            warnLog('removeAllListeners() called with %d data and %d schema listeners still registered — possible listener leak', dataCount, schemaCount);
+        const collisionCount = this.collisionListeners.size;
+        const txCommitCount = this.transactionCommitListeners.size;
+        if (dataCount > 0 || schemaCount > 0 || collisionCount > 0 || txCommitCount > 0) {
+            warnLog('removeAllListeners() called with %d data, %d schema, %d collision, and %d transaction-commit listeners still registered — possible listener leak', dataCount, schemaCount, collisionCount, txCommitCount);
         }
         this.dataListeners.clear();
         this.schemaListeners.clear();
+        this.collisionListeners.clear();
+        this.transactionCommitListeners.clear();
         this.batchedDataEvents = [];
         this.batchedSchemaEvents = [];
+        this.batchedCollisionEvents = [];
         this.dataEventLayers = [];
         this.schemaEventLayers = [];
+        this.collisionEventLayers = [];
+        this.collisionCounts.clear();
         this.isBatching = false;
         // Unhook all module emitters
         for (const [, subs] of this.moduleSubscriptions) {