@quereus/quereus 2.9.0 → 3.0.0

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

@@ -0,0 +1,58 @@
+/**
+ * Database.watch infrastructure — registration, post-commit firing,
+ * schema-change invalidation, and txn-id minting.
+ *
+ * Watchers are the second consumer of `DeltaExecutor`. Unlike assertions,
+ * they run **after** commit (the change log is still alive, the
+ * connections have all committed), and handler errors are logged but
+ * never roll the commit back.
+ */
+import { type SqlValue } from '../common/types.js';
+import type { ChangeScope, Subscription, WatchHandler } from '../planner/analysis/change-scope.js';
+import type { Database } from './database.js';
+/**
+ * Database internals the watcher manager needs. Mirrors
+ * `AssertionEvaluatorContext` — keeps the manager testable without the
+ * full `Database`.
+ */
+export interface WatcherManagerContext {
+    readonly schemaManager: Database['schemaManager'];
+    readonly optimizer: Database['optimizer'];
+    getChangedBaseTables(): Set<string>;
+    getChangedTuples(base: string, columnIndices: readonly number[], pkIndices: readonly number[]): SqlValue[][];
+    registerCaptureSpec(baseTable: string, spec: {
+        extraColumns: ReadonlySet<number>;
+    }): () => void;
+    _findTable(tableName: string, schemaName?: string): ReturnType<Database['_findTable']>;
+}
+/**
+ * Manages all `Database.watch` subscriptions for a single `Database`.
+ */
+export declare class WatcherManager {
+    private readonly ctx;
+    private readonly executor;
+    private readonly active;
+    private nextTxnIdCounter;
+    private currentTxnId;
+    private unsubscribeSchemaChanges;
+    constructor(ctx: WatcherManagerContext);
+    private subscribeToSchemaChanges;
+    /**
+     * Register a watcher. Validates the scope synchronously, registers
+     * capture demand, and produces a `Subscription` handle whose
+     * `unsubscribe()` releases all resources.
+     */
+    watch(scope: ChangeScope, handler: WatchHandler): Subscription;
+    /** Fire all subscriptions impacted by the current commit. Errors from
+     *  any single subscription's apply are logged and swallowed.
+     *
+     *  Must be called by the TransactionManager after a successful commit
+     *  but before the change log is cleared. */
+    runPostCommit(): Promise<void>;
+    dispose(): void;
+    private disposeActive;
+    private invalidateForTable;
+    private mintTxnId;
+    private nextNonce;
+}
+//# sourceMappingURL=database-watchers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database-watchers.d.ts","sourceRoot":"","sources":["../../../src/core/database-watchers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAQ/D,OAAO,KAAK,EACX,WAAW,EAEX,YAAY,EACZ,YAAY,EACZ,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAM9C;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAE1C,oBAAoB,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,EAAE,EAAE,CAAC;IAC7G,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,MAAM,IAAI,CAAC;IAChG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;CACvF;AAcD;;GAEG;AACH,qBAAa,cAAc;IAOd,OAAO,CAAC,QAAQ,CAAC,GAAG;IANhC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,wBAAwB,CAA6B;gBAEhC,GAAG,EAAE,qBAAqB;IAevD,OAAO,CAAC,wBAAwB;IAUhC;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY;IAmD9D;;;;gDAI4C;IACtC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAepC,OAAO,IAAI,IAAI;IAWf,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,SAAS;CAKjB"}

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

@@ -0,0 +1,206 @@
+/**
+ * Database.watch infrastructure — registration, post-commit firing,
+ * schema-change invalidation, and txn-id minting.
+ *
+ * Watchers are the second consumer of `DeltaExecutor`. Unlike assertions,
+ * they run **after** commit (the change log is still alive, the
+ * connections have all committed), and handler errors are logged but
+ * never roll the commit back.
+ */
+import { createLogger } from '../common/logger.js';
+import { QuereusError } from '../common/errors.js';
+import { StatusCode } from '../common/types.js';
+import { DeltaExecutor, subscriptionFromChangeScope, } from '../runtime/delta-executor.js';
+const log = createLogger('core:watchers');
+const warnLog = log.extend('warn');
+/**
+ * Manages all `Database.watch` subscriptions for a single `Database`.
+ */
+export class WatcherManager {
+    ctx;
+    executor;
+    active = new Map();
+    nextTxnIdCounter = 0;
+    currentTxnId = '';
+    unsubscribeSchemaChanges = null;
+    constructor(ctx) {
+        this.ctx = ctx;
+        const executorCtx = {
+            getChangedBaseTables: () => ctx.getChangedBaseTables(),
+            getChangedTuples: (base, cols, pk) => ctx.getChangedTuples(base, cols, pk),
+            getRowCount: (base) => {
+                const [schemaName, tableName] = base.split('.');
+                const table = ctx._findTable(tableName, schemaName);
+                return table?.estimatedRows;
+            },
+            deltaPerRowFallbackRatio: ctx.optimizer.tuning.deltaPerRowFallbackRatio,
+        };
+        this.executor = new DeltaExecutor(executorCtx);
+        this.subscribeToSchemaChanges();
+    }
+    subscribeToSchemaChanges() {
+        const notifier = this.ctx.schemaManager.getChangeNotifier();
+        this.unsubscribeSchemaChanges = notifier.addListener((event) => {
+            if (event.type === 'table_removed' || event.type === 'table_modified') {
+                const fqName = `${event.schemaName}.${event.objectName}`.toLowerCase();
+                this.invalidateForTable(fqName);
+            }
+        });
+    }
+    /**
+     * Register a watcher. Validates the scope synchronously, registers
+     * capture demand, and produces a `Subscription` handle whose
+     * `unsubscribe()` releases all resources.
+     */
+    watch(scope, handler) {
+        if (scope.unboundParameters.length > 0) {
+            throw new QuereusError(`watch: scope has unbound parameters [${scope.unboundParameters.join(', ')}]; call bindParameters(scope, params) first`, StatusCode.MISUSE);
+        }
+        const id = mintSubscriptionId(scope, this.nextNonce());
+        const tables = new Set();
+        for (const w of scope.watches) {
+            tables.add(`${w.table.schema}.${w.table.table}`.toLowerCase());
+        }
+        const helperCtx = {
+            resolveTable: (qname) => {
+                const table = this.ctx._findTable(qname.table, qname.schema);
+                if (!table)
+                    return undefined;
+                return {
+                    columnIndexMap: table.columnIndexMap,
+                    pkIndices: table.primaryKeyDefinition.map(d => d.index),
+                };
+            },
+            registerCaptureSpec: (base, spec) => this.ctx.registerCaptureSpec(base, spec),
+            getCurrentTxnId: () => this.currentTxnId,
+        };
+        const { subscription, captureDisposers } = subscriptionFromChangeScope(scope, handler, id, helperCtx);
+        const disposeFromExecutor = this.executor.register(subscription);
+        const entry = {
+            id,
+            tables,
+            disposeFromExecutor,
+            captureDisposers,
+            disposed: false,
+        };
+        this.active.set(id, entry);
+        const isDead = scope.watches.length === 0
+            && scope.nonDeterministicSources.length === 0;
+        if (isDead) {
+            warnLog('Registered dead subscription %s (no watches and no non-deterministic sources)', id);
+        }
+        return {
+            id,
+            unsubscribe: () => this.disposeActive(entry),
+        };
+    }
+    /** Fire all subscriptions impacted by the current commit. Errors from
+     *  any single subscription's apply are logged and swallowed.
+     *
+     *  Must be called by the TransactionManager after a successful commit
+     *  but before the change log is cleared. */
+    async runPostCommit() {
+        if (this.active.size === 0)
+            return;
+        this.currentTxnId = this.mintTxnId();
+        try {
+            await this.executor.runAll();
+        }
+        catch (err) {
+            // subscriptionFromChangeScope swallows handler errors; this catch
+            // is defensive — if the kernel itself throws (e.g. a missing PK
+            // triggers a fallback log), don't propagate into the commit path.
+            log('Post-commit watcher run threw: %O', err);
+        }
+        finally {
+            this.currentTxnId = '';
+        }
+    }
+    dispose() {
+        if (this.unsubscribeSchemaChanges) {
+            this.unsubscribeSchemaChanges();
+            this.unsubscribeSchemaChanges = null;
+        }
+        for (const entry of [...this.active.values()]) {
+            this.disposeActive(entry);
+        }
+        this.executor.disposeAll();
+    }
+    disposeActive(entry) {
+        if (entry.disposed)
+            return;
+        entry.disposed = true;
+        this.active.delete(entry.id);
+        entry.disposeFromExecutor();
+        for (const d of entry.captureDisposers) {
+            try {
+                d();
+            }
+            catch (err) {
+                log('Capture-spec disposer for %s threw: %O', entry.id, err);
+            }
+        }
+        entry.captureDisposers.length = 0;
+    }
+    invalidateForTable(fqName) {
+        const toDispose = [];
+        for (const entry of this.active.values()) {
+            if (entry.tables.has(fqName))
+                toDispose.push(entry);
+        }
+        for (const entry of toDispose) {
+            warnLog('Invalidating subscription %s due to schema change on %s', entry.id, fqName);
+            this.disposeActive(entry);
+        }
+    }
+    mintTxnId() {
+        this.nextTxnIdCounter += 1;
+        return `txn:${this.nextTxnIdCounter}`;
+    }
+    nextNonce() {
+        // Plain Math.random is fine here — we only need uniqueness within a
+        // process, not crypto-grade entropy.
+        return Math.random().toString(36).slice(2, 10);
+    }
+}
+/**
+ * Hash a scope into a stable id. The id mixes a canonical serialization
+ * of the watch shape (so two subscriptions for the same scope hash to
+ * the same prefix) with a random nonce (so the id is unique per
+ * registration). Format: `watch:<base32-hash>:<nonce>`.
+ */
+function mintSubscriptionId(scope, nonce) {
+    const canonical = canonicalizeScope(scope);
+    const hash = djb2Base32(canonical);
+    return `watch:${hash}:${nonce}`;
+}
+function canonicalizeScope(scope) {
+    const parts = [];
+    for (const w of scope.watches) {
+        parts.push(`${w.table.schema}.${w.table.table}`);
+        parts.push(w.columns === 'all' ? '*' : [...w.columns].sort().join(','));
+        parts.push(JSON.stringify(w.scope));
+    }
+    for (const n of scope.nonDeterministicSources)
+        parts.push(JSON.stringify(n));
+    for (const p of scope.unboundParameters)
+        parts.push(String(p));
+    return parts.join('|');
+}
+/** djb2 hash → 6 base32 chars. Fast, no crypto guarantees needed. */
+function djb2Base32(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+    }
+    const u = h >>> 0;
+    const alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
+    let out = '';
+    let n = u;
+    for (let i = 0; i < 6; i++) {
+        out = alphabet[n & 31] + out;
+        n = n >>> 5;
+    }
+    return out;
+}
+//# sourceMappingURL=database-watchers.js.map

package/dist/src/core/database-watchers.js.map

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

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

@@ -21,6 +21,9 @@ import { type LogicalType } from '../types/logical-type.js';
 import { type DatabaseDataChangeEvent, type DatabaseSchemaChangeEvent, type DataChangeSubscriptionOptions, type SchemaChangeSubscriptionOptions } from './database-events.js';
 import { type TransactionManagerContext } from './database-transaction.js';
 import { type AssertionEvaluatorContext } from './database-assertions.js';
+import { type WatcherManagerContext } from './database-watchers.js';
+import type { ChangeScope, Subscription, WatchHandler } from '../planner/analysis/change-scope.js';
+import { Table } from './table-handle.js';
 /** Result from _buildPlan containing both the plan tree and its schema dependencies. */
 export interface BuildPlanResult {
     plan: BlockNode;
@@ -30,7 +33,7 @@ export interface BuildPlanResult {
  * Represents a connection to an Quereus database (in-memory in this port).
  * Manages schema, prepared statements, virtual tables, and functions.
  */
-export declare class Database implements TransactionManagerContext, AssertionEvaluatorContext {
+export declare class Database implements TransactionManagerContext, AssertionEvaluatorContext, WatcherManagerContext {
     readonly schemaManager: SchemaManager;
     readonly declaredSchemaManager: DeclaredSchemaManager;
     private isOpen;
@@ -53,6 +56,8 @@ export declare class Database implements TransactionManagerContext, AssertionEva
     private readonly transactionManager;
     /** Assertion evaluation */
     private readonly assertionEvaluator;
+    /** Post-commit watcher dispatch */
+    private readonly watcherManager;
     /** Per-database collation registry — comparator + optional key normalizer.
      *  The normalizer is required for index participation; comparator-only
      *  collations may still be used in ORDER BY but cannot back a compound index. */
@@ -62,6 +67,19 @@ export declare class Database implements TransactionManagerContext, AssertionEva
     getChangedBaseTables(): Set<string>;
     /** Get changed PK tuples for a specific base table */
     getChangedKeyTuples(base: string): SqlValue[][];
+    /**
+     * Get changed value tuples projected onto `columnIndices` for a specific
+     * base table. The columns must have been registered for capture via
+     * `registerCaptureSpec` (PK columns are always captured implicitly).
+     */
+    getChangedTuples(base: string, columnIndices: readonly number[], pkIndices: readonly number[]): SqlValue[][];
+    /**
+     * Register projection capture demand for a base table. Returns a dispose
+     * handle that removes the spec when called.
+     */
+    registerCaptureSpec(baseTable: string, spec: {
+        extraColumns: ReadonlySet<number>;
+    }): () => void;
     /**
      * Prepares an SQL statement for execution.
      *
@@ -339,10 +357,13 @@ export declare class Database implements TransactionManagerContext, AssertionEva
     getInstructionTracer(): InstructionTracer | undefined;
     _queueDeferredConstraintRow(baseTable: string, constraintName: string, row: Row, descriptor: RowDescriptor, evaluator: (ctx: RuntimeContext) => OutputValue, connectionId?: string, contextRow?: Row, contextDescriptor?: RowDescriptor): void;
     runDeferredRowConstraints(): Promise<void>;
-    /** Public API used by DML emitters to record changes */
-    _recordInsert(baseTable: string, newKey: SqlValue[]): void;
-    _recordDelete(baseTable: string, oldKey: SqlValue[]): void;
-    _recordUpdate(baseTable: string, oldKey: SqlValue[], newKey: SqlValue[]): void;
+    /** Public API used by DML emitters to record changes. The full row plus
+     *  PK column indices are passed so the change capture can project the
+     *  columns that any active DeltaExecutor subscription has registered
+     *  demand for. */
+    _recordInsert(baseTable: string, newRow: Row, pkIndices: readonly number[]): void;
+    _recordDelete(baseTable: string, oldRow: Row, pkIndices: readonly number[]): void;
+    _recordUpdate(baseTable: string, oldRow: Row, newRow: Row, pkIndices: readonly number[]): void;
     /** Create a named savepoint, returning its depth index */
     _createSavepoint(name: string): number;
     /** Release a named savepoint (merges layers down to target), returns target depth */
@@ -397,6 +418,36 @@ export declare class Database implements TransactionManagerContext, AssertionEva
      * @returns A Statement with debug capabilities.
      */
     prepareDebug(sql: string, debug: DebugOptions): Statement;
+    /**
+     * Returns a public handle to a table for inspection and per-table event
+     * subscription. Returns `undefined` if the table does not exist or its
+     * owning module is not registered.
+     *
+     * The returned {@link Table} is a snapshot: its `schema` reference is
+     * frozen at acquisition time. If the table is dropped or recreated, the
+     * handle keeps the original schema, but no further events for that name
+     * will arrive. Re-acquire after schema changes if you need fresh state.
+     *
+     * After {@link Database.close}, the handle's event emitter reference
+     * remains valid (the module instance outlives the database) but the
+     * database-level aggregator is unhooked, so local subscriptions on the
+     * module emitter still fire only as long as the module itself remains
+     * active.
+     *
+     * @param schemaName The schema name ('main', 'temp', or an attached
+     *   schema). Pass `undefined` to use the current default schema.
+     * @param tableName  The table name (case-insensitive resolution).
+     *
+     * @example
+     * ```typescript
+     * const table = db.getTable('main', 'users');
+     * const tableEmitter = table?.getEventEmitter();
+     * const off = tableEmitter?.onDataChange?.((event) => {
+     *   if (event.tableName === 'users') console.log(event);
+     * });
+     * ```
+     */
+    getTable(schemaName: string | undefined, tableName: string): Table | undefined;
     /**
      * Disconnects and removes all active connections.
      * Called during database close.
@@ -404,5 +455,27 @@ export declare class Database implements TransactionManagerContext, AssertionEva
     private disconnectAllConnections;
     private checkOpen;
     runGlobalAssertions(): Promise<void>;
+    /**
+     * Subscribe to changes described by a {@link ChangeScope}.
+     *
+     * The watcher fires its handler **after** a transaction commits (mirrors
+     * assertion COMMIT eval), once per commit, with all matching watches in
+     * a single {@link WatchEvent}. Handler errors are caught and logged —
+     * they do not roll the commit back (assertions own that contract).
+     *
+     * Validation is synchronous:
+     * - Throws if `scope.unboundParameters` is non-empty (caller must
+     *   `bindParameters(scope, params)` first).
+     * - Throws if any referenced table or column does not exist in the
+     *   current schema.
+     *
+     * If the table or any column the scope mentions is later dropped or
+     * altered, the subscription is **invalidated and disposed**; re-subscribe
+     * to continue watching.
+     *
+     * @returns A {@link Subscription} handle whose `unsubscribe()` is
+     *   idempotent and releases capture-spec demand.
+     */
+    watch(scope: ChangeScope, handler: WatchHandler): Subscription;
 }
 //# sourceMappingURL=database.d.ts.map

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

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

package/dist/src/core/database.js

@@ -32,6 +32,9 @@ import { wrapAsyncIterator } from '../util/async-iterator.js';
 import { DatabaseEventEmitter, } from './database-events.js';
 import { TransactionManager } from './database-transaction.js';
 import { AssertionEvaluator } from './database-assertions.js';
+import { WatcherManager } from './database-watchers.js';
+import { tryGetEventEmitter } from '../vtab/events.js';
+import { Table } from './table-handle.js';
 const log = createLogger('core:database');
 const errorLog = log.extend('error');
 /** Parse a comma-separated schema path string into an array of trimmed, non-empty names. */
@@ -41,19 +44,6 @@ function parseSchemaPath(pathString) {
     const parts = pathString.split(',').map(s => s.trim()).filter(s => s.length > 0);
     return parts.length > 0 ? parts : undefined;
 }
-/** Extract a VTableEventEmitter from a module if it supports one. */
-function tryGetEventEmitter(module) {
-    const asSource = module;
-    if (typeof asSource.getEventEmitter !== 'function')
-        return undefined;
-    const emitter = asSource.getEventEmitter();
-    if (!emitter || typeof emitter !== 'object')
-        return undefined;
-    const typed = emitter;
-    if (typeof typed.onDataChange !== 'function' && typeof typed.onSchemaChange !== 'function')
-        return undefined;
-    return emitter;
-}
 /**
  * Represents a connection to an Quereus database (in-memory in this port).
  * Manages schema, prepared statements, virtual tables, and functions.
@@ -81,6 +71,8 @@ export class Database {
     transactionManager;
     /** Assertion evaluation */
     assertionEvaluator;
+    /** Post-commit watcher dispatch */
+    watcherManager;
     /** Per-database collation registry — comparator + optional key normalizer.
      *  The normalizer is required for index participation; comparator-only
      *  collations may still be used in ORDER BY but cannot back a compound index. */
@@ -103,6 +95,7 @@ export class Database {
         // Initialize transaction manager and assertion evaluator
         this.transactionManager = new TransactionManager(this);
         this.assertionEvaluator = new AssertionEvaluator(this);
+        this.watcherManager = new WatcherManager(this);
         // Set up option change listeners
         this.setupOptionListeners();
     }
@@ -128,6 +121,21 @@ export class Database {
     getChangedKeyTuples(base) {
         return this.transactionManager.getChangedKeyTuples(base);
     }
+    /**
+     * Get changed value tuples projected onto `columnIndices` for a specific
+     * base table. The columns must have been registered for capture via
+     * `registerCaptureSpec` (PK columns are always captured implicitly).
+     */
+    getChangedTuples(base, columnIndices, pkIndices) {
+        return this.transactionManager.getChangedTuples(base, columnIndices, pkIndices);
+    }
+    /**
+     * Register projection capture demand for a base table. Returns a dispose
+     * handle that removes the spec when called.
+     */
+    registerCaptureSpec(baseTable, spec) {
+        return this.transactionManager.registerCaptureSpec(baseTable, spec);
+    }
     /** @internal Set up listeners for option changes */
     setupOptionListeners() {
         // Register core database options with their change handlers
@@ -668,6 +676,8 @@ export class Database {
         this.statements.clear();
         // Clean up assertion evaluator (unsubscribe schema change listener, clear plan cache)
         this.assertionEvaluator.dispose();
+        // Clean up watcher manager (dispose all subscriptions + schema listener)
+        this.watcherManager.dispose();
         // Clear schemas, ensuring VTabs are potentially disconnected
         // This will also call destroy on VTabs via SchemaManager.clearAll -> schema.clearTables -> schemaManager.dropTable
         this.schemaManager.clearAll();
@@ -991,15 +1001,18 @@ export class Database {
     _inCoordinatedCommit() {
         return this.transactionManager.isInCoordinatedCommit();
     }
-    /** Public API used by DML emitters to record changes */
-    _recordInsert(baseTable, newKey) {
-        this.transactionManager.recordInsert(baseTable, newKey);
+    /** Public API used by DML emitters to record changes. The full row plus
+     *  PK column indices are passed so the change capture can project the
+     *  columns that any active DeltaExecutor subscription has registered
+     *  demand for. */
+    _recordInsert(baseTable, newRow, pkIndices) {
+        this.transactionManager.recordInsert(baseTable, newRow, pkIndices);
     }
-    _recordDelete(baseTable, oldKey) {
-        this.transactionManager.recordDelete(baseTable, oldKey);
+    _recordDelete(baseTable, oldRow, pkIndices) {
+        this.transactionManager.recordDelete(baseTable, oldRow, pkIndices);
     }
-    _recordUpdate(baseTable, oldKey, newKey) {
-        this.transactionManager.recordUpdate(baseTable, oldKey, newKey);
+    _recordUpdate(baseTable, oldRow, newRow, pkIndices) {
+        this.transactionManager.recordUpdate(baseTable, oldRow, newRow, pkIndices);
     }
     /** Create a named savepoint, returning its depth index */
     _createSavepoint(name) {
@@ -1163,6 +1176,48 @@ export class Database {
     _findTable(tableName, dbName) {
         return this.schemaManager.findTable(tableName, dbName);
     }
+    /**
+     * Returns a public handle to a table for inspection and per-table event
+     * subscription. Returns `undefined` if the table does not exist or its
+     * owning module is not registered.
+     *
+     * The returned {@link Table} is a snapshot: its `schema` reference is
+     * frozen at acquisition time. If the table is dropped or recreated, the
+     * handle keeps the original schema, but no further events for that name
+     * will arrive. Re-acquire after schema changes if you need fresh state.
+     *
+     * After {@link Database.close}, the handle's event emitter reference
+     * remains valid (the module instance outlives the database) but the
+     * database-level aggregator is unhooked, so local subscriptions on the
+     * module emitter still fire only as long as the module itself remains
+     * active.
+     *
+     * @param schemaName The schema name ('main', 'temp', or an attached
+     *   schema). Pass `undefined` to use the current default schema.
+     * @param tableName  The table name (case-insensitive resolution).
+     *
+     * @example
+     * ```typescript
+     * const table = db.getTable('main', 'users');
+     * const tableEmitter = table?.getEventEmitter();
+     * const off = tableEmitter?.onDataChange?.((event) => {
+     *   if (event.tableName === 'users') console.log(event);
+     * });
+     * ```
+     */
+    getTable(schemaName, tableName) {
+        this.checkOpen();
+        const tableSchema = this.schemaManager.getTable(schemaName, tableName);
+        if (!tableSchema)
+            return undefined;
+        const moduleName = tableSchema.vtabModuleName;
+        if (!moduleName)
+            return undefined;
+        const moduleInfo = this.schemaManager.getModule(moduleName);
+        if (!moduleInfo)
+            return undefined;
+        return new Table(tableSchema, moduleName, moduleInfo.module);
+    }
     /** @internal */
     _findFunction(funcName, nArg) {
         return this.schemaManager.findFunction(funcName, nArg);
@@ -1214,6 +1269,21 @@ export class Database {
                 errorLog(`Error starting transaction on newly registered connection ${connection.connectionId}: %O`, error);
                 // Don't throw here - just log the error to avoid breaking connection registration
             }
+            // Replay the active savepoint stack onto this connection so subsequent
+            // release/rollback-to broadcasts targeting earlier depths are in-range.
+            // Without this, modules that register connections lazily (memory, isolation,
+            // any vtab whose connection appears on first read/write) see an empty stack
+            // while the DB broadcasts depths > 0 — silently no-op'ing on a real depth.
+            const activeDepth = this.transactionManager.getActiveSavepointDepth();
+            for (let depth = 0; depth < activeDepth; depth++) {
+                try {
+                    await connection.createSavepoint(depth);
+                }
+                catch (error) {
+                    errorLog(`Error replaying savepoint depth ${depth} on newly registered connection ${connection.connectionId}: %O`, error);
+                    // Continue replaying remaining depths — see comment above on registration robustness.
+                }
+            }
         }
         else if (this.transactionManager.isEvaluatingDeferredConstraints()) {
             log(`Skipped transaction begin on connection ${connection.connectionId} (evaluating deferred constraints)`);
@@ -1303,6 +1373,36 @@ export class Database {
     async runGlobalAssertions() {
         await this.assertionEvaluator.runGlobalAssertions();
     }
+    /**
+     * Subscribe to changes described by a {@link ChangeScope}.
+     *
+     * The watcher fires its handler **after** a transaction commits (mirrors
+     * assertion COMMIT eval), once per commit, with all matching watches in
+     * a single {@link WatchEvent}. Handler errors are caught and logged —
+     * they do not roll the commit back (assertions own that contract).
+     *
+     * Validation is synchronous:
+     * - Throws if `scope.unboundParameters` is non-empty (caller must
+     *   `bindParameters(scope, params)` first).
+     * - Throws if any referenced table or column does not exist in the
+     *   current schema.
+     *
+     * If the table or any column the scope mentions is later dropped or
+     * altered, the subscription is **invalidated and disposed**; re-subscribe
+     * to continue watching.
+     *
+     * @returns A {@link Subscription} handle whose `unsubscribe()` is
+     *   idempotent and releases capture-spec demand.
+     */
+    watch(scope, handler) {
+        this.checkOpen();
+        return this.watcherManager.watch(scope, handler);
+    }
+    /** @internal Invoked by the TransactionManager after a successful commit
+     *  and before the change log is cleared. */
+    async runPostCommitWatchers() {
+        await this.watcherManager.runPostCommit();
+    }
     /** @internal Invalidate cached assertion plan (called on DROP ASSERTION) */
     invalidateAssertionCache(name) {
         this.assertionEvaluator.invalidateAssertion(name);