@quereus/quereus 3.3.0 → 4.0.0

package/dist/src/core/database.js

@@ -7,11 +7,12 @@ import { BUILTIN_FUNCTIONS } from '../func/builtins/index.js';
 import { createScalarFunction, createAggregateFunction } from '../func/registration.js';
 import { FunctionFlags } from '../common/constants.js';
 import { MemoryTableModule } from '../vtab/memory/module.js';
-import { BINARY_COLLATION, NOCASE_COLLATION, RTRIM_COLLATION } from '../util/comparison.js';
+import { BINARY_COLLATION, NOCASE_COLLATION, RTRIM_COLLATION, normalizeCollationName } from '../util/comparison.js';
 import { BUILTIN_NORMALIZERS } from '../util/key-serializer.js';
 import { Parser } from '../parser/parser.js';
 import { buildBlock } from '../planner/building/block.js';
 import { emitPlanNode } from '../runtime/emitters.js';
+import { refreshMaintainedTable } from '../runtime/emit/materialized-view.js';
 import { Scheduler } from '../runtime/scheduler.js';
 import { createStrictRowContextMap, wrapTableContextsStrict } from '../runtime/strict-fork.js';
 import { BuildTimeDependencyTracker } from '../planner/planning-context.js';
@@ -23,6 +24,7 @@ import { EmissionContext } from '../runtime/emission-context.js';
 import { Optimizer, DEFAULT_TUNING } from '../planner/optimizer.js';
 import { registerBuiltinWindowFunctions } from '../func/builtins/builtin-window-functions.js';
 import { DatabaseOptionsManager } from './database-options.js';
+import { MAINTENANCE_REBUILD_ROW_THRESHOLD } from '../planner/cost/index.js';
 import { DeclaredSchemaManager } from '../schema/declared-schema-manager.js';
 import { DeferredConstraintQueue } from '../runtime/deferred-constraint-queue.js';
 import { registerType as registerTypeInRegistry } from '../types/registry.js';
@@ -31,8 +33,10 @@ import { rowToObject } from './utils.js';
 import { wrapAsyncIterator } from '../util/async-iterator.js';
 import { DatabaseEventEmitter, } from './database-events.js';
 import { TransactionManager } from './database-transaction.js';
+import { ingestExternalRowChangeBatch } from './database-external-changes.js';
 import { AssertionEvaluator } from './database-assertions.js';
 import { WatcherManager } from './database-watchers.js';
+import { MaterializedViewManager } from './database-materialized-views.js';
 import { tryGetEventEmitter } from '../vtab/events.js';
 import { Table } from './table-handle.js';
 const log = createLogger('core:database');
@@ -65,6 +69,14 @@ export class Database {
      * transaction state, matching SQLite's behavior of serializing writes.
      */
     execMutex = Promise.resolve();
+    /**
+     * Depth of currently-held exec-mutex acquisitions. >0 while a statement
+     * (`exec`/`eval`), an external-change ingest, or an MV-refresh sweep holds the
+     * mutex. Read via {@link _isExecuting} so a re-entrant caller (e.g. a module
+     * `notifyLensDeployment` listener that would itself re-enter the engine) can
+     * detect it must defer rather than deadlock on the held mutex.
+     */
+    execMutexDepth = 0;
     /** Database-level event emitter for unified reactivity */
     eventEmitter = new DatabaseEventEmitter();
     /** Transaction management */
@@ -73,9 +85,15 @@ export class Database {
     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. */
+    /** Materialized-view schema-change staleness tracking */
+    materializedViewManager;
+    /** Per-database collation registry — comparator + optional key normalizer +
+     *  optional REPLICABLE assertion. The normalizer is required for index
+     *  participation; comparator-only collations may still be used in ORDER BY but
+     *  cannot back a compound index. `replicable` (stamped `true` on the built-ins,
+     *  opt-in for a custom collation) is consulted only by the materialized-view
+     *  replicable-collation gate when the backing host demands it
+     *  (see {@link _isCollationReplicable}). */
     collations = new Map();
     constructor() {
         this.schemaManager = new SchemaManager(this);
@@ -96,6 +114,7 @@ export class Database {
         this.transactionManager = new TransactionManager(this);
         this.assertionEvaluator = new AssertionEvaluator(this);
         this.watcherManager = new WatcherManager(this);
+        this.materializedViewManager = new MaterializedViewManager(this);
         // Set up option change listeners
         this.setupOptionListeners();
     }
@@ -192,6 +211,21 @@ export class Database {
                 log('Default column nullability changed to: %s', value);
             }
         });
+        this.options.registerOption('default_collation', {
+            type: 'string',
+            defaultValue: 'BINARY',
+            description: 'Default declared collation for columns with no explicit COLLATE (e.g. "BINARY", "NOCASE", "RTRIM", or any registered collation). Create-time authoring convenience only; the catalog stores concrete collations and persisted DDL always carries an explicit non-BINARY COLLATE.',
+            onChange: (event) => {
+                const value = event.newValue;
+                const normalized = normalizeCollationName(value);
+                // Validate at set time so a typo fails loudly, not at first comparison.
+                // The options framework rolls the value back when onChange throws.
+                if (this._getCollation(normalized) === undefined) {
+                    throw new QuereusError(`Unknown collation '${value}' for default_collation`, StatusCode.ERROR);
+                }
+                log('Default collation changed to: %s', normalized);
+            }
+        });
         this.options.registerOption('schema_path', {
             type: 'string',
             defaultValue: 'main',
@@ -213,13 +247,49 @@ export class Database {
             aliases: ['fk_enforcement'],
             description: 'Enable foreign key constraint enforcement. When omitted, ON DELETE / ON UPDATE default to RESTRICT.',
         });
+        this.options.registerOption('nondeterministic_schema', {
+            type: 'boolean',
+            defaultValue: false,
+            aliases: ['allow_nondeterministic_schema_expressions'],
+            description: 'When true, permit non-deterministic expressions in DEFAULT, CHECK, and GENERATED ALWAYS AS clauses. ' +
+                'Capture happens at the resolved-row frontier in vtab.update(); replay applies module-layer writes without re-evaluating constraints. ' +
+                'Defaults to false (strict rejection) for backward compatibility.',
+            onChange: (event) => {
+                log('nondeterministic_schema changed to: %s', event.newValue);
+            }
+        });
+        this.options.registerOption('materialized_view_rebuild_row_threshold', {
+            type: 'number',
+            defaultValue: MAINTENANCE_REBUILD_ROW_THRESHOLD,
+            description: 'Largest source-row count for which a materialized view whose only sound maintenance ' +
+                'strategy is a full body rebuild is accepted at create. A full-rebuild MV over a larger source ' +
+                'is rejected (every write would re-scan the whole source). Set to 0 to disable the size reject ' +
+                '(accept any size). The check uses the largest participating source for a multi-source body.',
+            onChange: (event) => {
+                // Validate at set time so a bad value fails loudly; the options framework
+                // rolls the value back when onChange throws.
+                const value = event.newValue;
+                if (!Number.isFinite(value) || value < 0) {
+                    throw new QuereusError(`Invalid materialized_view_rebuild_row_threshold ${event.newValue}: must be a non-negative number (0 disables the size reject)`, StatusCode.ERROR);
+                }
+                log('materialized_view_rebuild_row_threshold changed to: %s', value);
+            }
+        });
     }
     /** @internal Registers default built-in SQL functions */
     registerBuiltinFunctions() {
         const mainSchema = this.schemaManager.getMainSchema();
+        // Built-ins auto-qualify as REPLICABLE: Quereus implements its own collation,
+        // case-folding, and numeric formatting, so a deterministic builtin is
+        // bit-identical across peers' JS engines (see BaseFunctionSchema.replicable).
+        // This is the single seam that *knows* a schema is a builtin, so stamping here
+        // auto-qualifies all of them without editing ~100 definitions and without
+        // defaulting UDFs to replicable. Non-deterministic builtins (random, now, …) are
+        // stamped too — harmless, since the determinism gate rejects them first. Spread a
+        // COPY so the shared exported BUILTIN_FUNCTIONS constants are never mutated.
         BUILTIN_FUNCTIONS.forEach(funcDef => {
             try {
-                mainSchema.addFunction(funcDef);
+                mainSchema.addFunction({ ...funcDef, replicable: true });
             }
             catch (e) {
                 errorLog(`Failed to register built-in function ${funcDef.name}/${funcDef.numArgs}: %O`, e);
@@ -230,10 +300,15 @@ export class Database {
     /** @internal Registers default collation sequences */
     registerDefaultCollations() {
         // Register the built-in collations into per-instance registry, paired
-        // with their key normalizers so they can back compound indexes.
-        this.collations.set('BINARY', { comparator: BINARY_COLLATION, normalizer: BUILTIN_NORMALIZERS.BINARY });
-        this.collations.set('NOCASE', { comparator: NOCASE_COLLATION, normalizer: BUILTIN_NORMALIZERS.NOCASE });
-        this.collations.set('RTRIM', { comparator: RTRIM_COLLATION, normalizer: BUILTIN_NORMALIZERS.RTRIM });
+        // with their key normalizers so they can back compound indexes. Stamped
+        // `replicable: true` — the built-ins are pure JS string operations (`<`/`>`,
+        // locale-independent `toLowerCase()`, ASCII-space trim), so they are
+        // bit-identical across peers' JS engines, exactly parallel to why built-in
+        // functions auto-qualify (see registerBuiltinFunctions). This is the single
+        // seam that *knows* a collation is a builtin.
+        this.collations.set('BINARY', { comparator: BINARY_COLLATION, normalizer: BUILTIN_NORMALIZERS.BINARY, replicable: true });
+        this.collations.set('NOCASE', { comparator: NOCASE_COLLATION, normalizer: BUILTIN_NORMALIZERS.NOCASE, replicable: true });
+        this.collations.set('RTRIM', { comparator: RTRIM_COLLATION, normalizer: BUILTIN_NORMALIZERS.RTRIM, replicable: true });
         log("Default collations registered (BINARY, NOCASE, RTRIM)");
     }
     /**
@@ -304,7 +379,32 @@ export class Database {
             releaseMutex = resolve;
         });
         await previousMutex;
-        return releaseMutex;
+        // Mark the mutex held from acquisition until the returned release runs, so a
+        // re-entrant caller can detect it (see _isExecuting). The wrapper decrements
+        // at most once even if release is invoked more than once.
+        this.execMutexDepth++;
+        let released = false;
+        return () => {
+            if (!released) {
+                released = true;
+                this.execMutexDepth--;
+            }
+            releaseMutex();
+        };
+    }
+    /**
+     * True while the exec mutex is held — i.e. a statement (`exec`/`eval`), an
+     * external-change ingest, or an MV-refresh sweep is in flight. A caller that
+     * would re-enter the engine (acquire the mutex again) from inside such a context
+     * — e.g. a `notifyLensDeployment` module listener whose work calls
+     * `ingestExternalRowChanges` — MUST check this and defer that work to run after
+     * the current statement releases the mutex; re-entering synchronously deadlocks
+     * on the chained mutex. Deliberately part of the consumable type surface (kept out
+     * of the internal-only set) so a basis-backing host in another package can make
+     * that defer-vs-await decision.
+     */
+    _isExecuting() {
+        return this.execMutexDepth > 0;
     }
     /**
      * Executes a function with the execution mutex held.
@@ -631,6 +731,88 @@ export class Database {
     hasSchemaListeners() {
         return this.eventEmitter.hasSchemaListeners();
     }
+    /**
+     * @internal Whether the engine must generate/collect data-change events for
+     * this statement — true when any `onDataChange` OR `onTransactionCommit`
+     * listener is registered. The DML executor's auto-event gate consults this so a
+     * consumer subscribed only to the grouped transaction-commit channel still gets
+     * data events collected.
+     */
+    _needsDataEvents() {
+        return this.eventEmitter.needsDataEvents();
+    }
+    /**
+     * @internal Whether the engine must generate/collect schema-change events —
+     * true when any `onSchemaChange` OR `onTransactionCommit` listener is
+     * registered. Companion to {@link _needsDataEvents}; consulted by the schema
+     * manager's auto-event gate.
+     */
+    _needsSchemaEvents() {
+        return this.eventEmitter.needsSchemaEvents();
+    }
+    /**
+     * Subscribe to materialized-view key-coarsening **collision** events — the
+     * operational complement to the create-time key-coarsening warning. A
+     * {@link MaintenanceCollisionEvent} fires whenever row-time maintenance
+     * LWW-merges two distinct source-key tuples under one coarsened backing key K′
+     * (`docs/materialized-views.md` § Coarsened backing keys). Events share the
+     * transaction-batching discipline of the data/schema channels — delivered after
+     * the commit that realized the merge, dropped on rollback.
+     *
+     * @param listener Callback invoked for each committed collision
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const off = db.onMaintenanceCollision((e) => {
+     *   console.warn(`coarsening collision on ${e.schemaName}.${e.tableName} ` +
+     *     `at key ${JSON.stringify(e.key)} (columns: ${e.weakenedColumns.join(', ')})`);
+     * });
+     * ```
+     */
+    onMaintenanceCollision(listener) {
+        this.checkOpen();
+        return this.eventEmitter.onMaintenanceCollision(listener);
+    }
+    /**
+     * Read-only snapshot of the cumulative committed key-coarsening collision
+     * counter, keyed by lowercased qualified `schema.table` of the maintained
+     * table. Reflects only collisions that committed (consistent with event
+     * delivery) and is maintained whether or not a listener was ever subscribed.
+     */
+    getMaterializedViewCollisionStats() {
+        this.checkOpen();
+        return this.eventEmitter.getMaterializedViewCollisionStats();
+    }
+    /**
+     * Subscribe to grouped per-transaction commit batches — the authoritative
+     * "one logical transaction = one group" boundary. A
+     * {@link TransactionCommitBatch} fires **once** per committed transaction,
+     * carrying every data and schema event of that transaction across **all**
+     * tables, in flush order. Unlike the per-event {@link onDataChange} /
+     * {@link onSchemaChange} channels (which this does not replace — it is purely
+     * additive), a single subscription receives the whole transaction as one unit,
+     * which is what a consumer grouping changes by transaction (e.g. assigning one
+     * HLC per transaction) needs. Dropped on rollback; never fires for a
+     * transaction that produced no data/schema events.
+     *
+     * @param listener Callback invoked once per committed transaction
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const off = db.onTransactionCommit((batch) => {
+     *   // All changes of one transaction, across all tables, in order.
+     *   const local = batch.dataEvents.filter((e) => !e.remote);
+     *   console.log(`committed ${local.length} local row changes, ` +
+     *     `${batch.schemaEvents.length} schema changes`);
+     * });
+     * ```
+     */
+    onTransactionCommit(listener) {
+        this.checkOpen();
+        return this.eventEmitter.onTransactionCommit(listener);
+    }
     /**
      * Get the internal event emitter for advanced use cases.
      * @internal
@@ -688,6 +870,8 @@ export class Database {
         this.assertionEvaluator.dispose();
         // Clean up watcher manager (dispose all subscriptions + schema listener)
         this.watcherManager.dispose();
+        // Clean up materialized-view manager (unsubscribe schema listener)
+        this.materializedViewManager.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();
@@ -741,7 +925,7 @@ export class Database {
         this.checkOpen();
         const baseFlags = (options.deterministic ? FunctionFlags.DETERMINISTIC : 0) | FunctionFlags.UTF8;
         const flags = options.flags ?? baseFlags;
-        const schema = createScalarFunction({ name, numArgs: options.numArgs, flags }, func);
+        const schema = createScalarFunction({ name, numArgs: options.numArgs, flags, replicable: options.replicable }, func);
         this.registerFunctionWithErrorHandling('scalar', name, options.numArgs, () => {
             this.schemaManager.getMainSchema().addFunction(schema);
         });
@@ -757,7 +941,7 @@ export class Database {
     createAggregateFunction(name, options, stepFunc, finalFunc) {
         this.checkOpen();
         const flags = options.flags ?? FunctionFlags.UTF8;
-        const schema = createAggregateFunction({ name, numArgs: options.numArgs, flags, initialValue: options.initialState }, stepFunc, finalFunc);
+        const schema = createAggregateFunction({ name, numArgs: options.numArgs, flags, replicable: options.replicable, initialValue: options.initialState }, stepFunc, finalFunc);
         this.registerFunctionWithErrorHandling('aggregate', name, options.numArgs, () => {
             this.schemaManager.getMainSchema().addFunction(schema);
         });
@@ -881,10 +1065,17 @@ export class Database {
      * Registers a user-defined collation sequence.
      * @param name The name of the collation sequence (case-insensitive).
      * @param func The comparison function (a, b) => number (-1, 0, 1).
-     * @param normalizer Optional key normalizer — a function whose output equality
-     *   partitions strings into the same equivalence classes as `func` (modulo
-     *   total ordering). Required to make this collation usable as the key for a
-     *   compound index; ORDER BY / standalone comparisons work without it.
+     * @param optionsOrNormalizer Either a bare key normalizer (the legacy positional
+     *   form) or an options object `{ normalizer?, replicable? }`:
+     *   - `normalizer` — a function whose output equality partitions strings into the
+     *     same equivalence classes as `func` (modulo total ordering). Required to make
+     *     this collation usable as the key for a compound index; ORDER BY / standalone
+     *     comparisons work without it.
+     *   - `replicable` — assert this collation is **bit-identical across peers,
+     *     platforms, and app versions** (not merely deterministic). Consulted only by
+     *     the materialized-view replicable-collation gate when a backing host declares
+     *     `requiresReplicableDerivations`. Defaults to `false` — the conservative
+     *     default for a custom collation (built-ins auto-qualify).
      * @example
      * // Example: Create a custom collation for phone numbers
      * db.registerCollation('PHONENUMBER', (a, b) => {
@@ -894,11 +1085,14 @@ export class Database {
      *   return numA < numB ? -1 : numA > numB ? 1 : 0;
      * }, (s) => s.replace(/\D/g, ''));
      *
+     * // A locale-independent custom collation a replicating backing can host:
+     * db.registerCollation('CODEPOINT', cmp, { replicable: true });
+     *
      * // Then use it in SQL:
      * // SELECT * FROM contacts ORDER BY phone COLLATE PHONENUMBER;
      * // CREATE INDEX phone_idx ON contacts(phone COLLATE PHONENUMBER);
      */
-    registerCollation(name, func, normalizer) {
+    registerCollation(name, func, optionsOrNormalizer) {
         this.checkOpen();
         if (typeof name !== 'string' || !name) {
             throw new MisuseError('registerCollation: name must be a non-empty string');
@@ -906,6 +1100,21 @@ export class Database {
         if (typeof func !== 'function') {
             throw new MisuseError('registerCollation: func must be a function');
         }
+        // A function-typed third arg is the legacy normalizer-only path (existing call
+        // sites unchanged, `replicable` defaults to false); an object reads its fields;
+        // any other non-undefined third arg is a misused legacy normalizer.
+        let normalizer;
+        let replicable = false;
+        if (typeof optionsOrNormalizer === 'function') {
+            normalizer = optionsOrNormalizer;
+        }
+        else if (typeof optionsOrNormalizer === 'object' && optionsOrNormalizer !== null) {
+            normalizer = optionsOrNormalizer.normalizer;
+            replicable = optionsOrNormalizer.replicable === true;
+        }
+        else if (optionsOrNormalizer !== undefined) {
+            throw new MisuseError('registerCollation: normalizer must be a function when supplied');
+        }
         if (normalizer !== undefined && typeof normalizer !== 'function') {
             throw new MisuseError('registerCollation: normalizer must be a function when supplied');
         }
@@ -913,10 +1122,13 @@ export class Database {
         if (this.collations.has(upperName)) {
             log('Overwriting existing collation: %s', upperName);
         }
-        this.collations.set(upperName, normalizer !== undefined
-            ? { comparator: func, normalizer }
-            : { comparator: func });
-        log('Registered collation: %s%s', upperName, normalizer !== undefined ? ' (with normalizer)' : '');
+        const entry = { comparator: func };
+        if (normalizer !== undefined)
+            entry.normalizer = normalizer;
+        if (replicable)
+            entry.replicable = true;
+        this.collations.set(upperName, entry);
+        log('Registered collation: %s%s%s', upperName, normalizer !== undefined ? ' (with normalizer)' : '', replicable ? ' (replicable)' : '');
     }
     /**
      * Registers a custom logical type.
@@ -997,6 +1209,16 @@ export class Database {
         // resolves to the canonical built-in normalizer.
         return BUILTIN_NORMALIZERS[upper];
     }
+    /** @internal True iff the named collation is asserted REPLICABLE — bit-identical
+     *  across peers/platforms/app-versions. Built-ins are stamped `replicable` at
+     *  registration; a custom collation opts in with `replicable: true`. An unknown
+     *  collation returns `false` defensively (an unknown collation in a derivation
+     *  body errors earlier at create). Consumed only by the materialized-view
+     *  replicable-collation gate when the backing host declares
+     *  `requiresReplicableDerivations`. */
+    _isCollationReplicable(name) {
+        return this.collations.get(name.toUpperCase())?.replicable === true;
+    }
     _queueDeferredConstraintRow(baseTable, constraintName, row, descriptor, evaluator, connectionId, contextRow, contextDescriptor) {
         this.deferredConstraints.enqueue(baseTable, constraintName, row, descriptor, evaluator, connectionId, contextRow, contextDescriptor);
     }
@@ -1305,8 +1527,15 @@ export class Database {
     _findFunction(funcName, nArg) {
         return this.schemaManager.findFunction(funcName, nArg);
     }
-    /** @internal */
-    _buildPlan(statements, paramsOrTypes) {
+    /**
+     * @internal Build a fresh top-level {@link PlanningContext} (global → parameter scope,
+     * default schema path, an empty dependency tracker). The shared seam {@link _buildPlan}
+     * builds its planning context from, and a throwaway context the static updateability
+     * surfaces (`func/builtins/schema.ts`) use to plan a view body / run an insertability
+     * probe — whose `schemaDependencies` are discarded (the read TVF already discards the body
+     * plan's), so a fresh tracker per call is correct.
+     */
+    _buildProbeContext(paramsOrTypes) {
         const globalScope = new GlobalScope(this.schemaManager);
         // If we received parameter values, infer their types
         // If we received explicit parameter types, use them as-is
@@ -1317,21 +1546,24 @@ export class Database {
         const parameterScope = new ParameterScope(globalScope, parameterTypes);
         // Get default schema path from options
         const schemaPath = parseSchemaPath(this.options.getStringOption('schema_path'));
-        const schemaDependencies = new BuildTimeDependencyTracker();
-        const ctx = {
+        return {
             db: this,
             schemaManager: this.schemaManager,
             parameters: paramsOrTypes instanceof Map ? {} : (paramsOrTypes ?? {}),
             scope: parameterScope,
             cteNodes: new Map(),
-            schemaDependencies,
+            schemaDependencies: new BuildTimeDependencyTracker(),
             schemaCache: new Map(),
             cteReferenceCache: new Map(),
             outputScopes: new Map(),
             schemaPath
         };
+    }
+    /** @internal */
+    _buildPlan(statements, paramsOrTypes) {
+        const ctx = this._buildProbeContext(paramsOrTypes);
         const plan = buildBlock(ctx, statements);
-        return { plan, schemaDependencies };
+        return { plan, schemaDependencies: ctx.schemaDependencies };
     }
     /**
      * @internal Registers an active VirtualTable connection for transaction management.
@@ -1453,8 +1685,36 @@ export class Database {
         if (!this.isOpen)
             throw new MisuseError("Database is closed");
     }
-    async runGlobalAssertions() {
-        await this.assertionEvaluator.runGlobalAssertions();
+    async runGlobalAssertions(sink) {
+        await this.assertionEvaluator.runGlobalAssertions(sink);
+    }
+    /** @internal Install (or clear, with `null`) the report-mode sink the next
+     *  commit's global-assertion pass collects into instead of throwing. Used by
+     *  the external-row ingestion seam around its implicit commit; see
+     *  {@link ingestExternalRowChanges} and `database-transaction.ts`. */
+    _setPendingCommitAssertionSink(sink) {
+        this.transactionManager.setPendingCommitAssertionSink(sink);
+    }
+    /** @internal Apply-mode RESTRICT suppression flag — see {@link _setFkRestrictSuppressed}. */
+    _fkRestrictSuppressed = false;
+    /** @internal Apply-mode RESTRICT suppression. While set, the parent-side FK
+     *  RESTRICT pre-checks ({@link assertTransitiveRestrictsForParentMutation} and its
+     *  callees) early-return — the trust-the-origin external-row apply path: the origin
+     *  already enforced RESTRICT at its own commit, so re-enforcing it on the receiver
+     *  would wedge the sync stream. Cascade / set-null / set-default propagation is
+     *  unaffected. Set for the duration of an apply batch (mutex held, so no concurrent
+     *  statement observes it) and honored by every nested cascade DML and MV-maintenance
+     *  FK pass. Returns the prior value so the caller restores it in a `finally`
+     *  (supports nesting). */
+    _setFkRestrictSuppressed(value) {
+        const prior = this._fkRestrictSuppressed;
+        this._fkRestrictSuppressed = value;
+        return prior;
+    }
+    /** @internal Whether apply-mode RESTRICT suppression is active — see
+     *  {@link _setFkRestrictSuppressed}. */
+    _isFkRestrictSuppressed() {
+        return this._fkRestrictSuppressed;
     }
     /**
      * Subscribe to changes described by a {@link ChangeScope}.
@@ -1486,6 +1746,210 @@ export class Database {
     async runPostCommitWatchers() {
         await this.watcherManager.runPostCommit();
     }
+    /**
+     * Fire all active watchers whose scope includes `schema.table`, as if the
+     * whole table changed, **without** a local commit. For hosts whose tables
+     * are backed by an external/replicated store (e.g. the optimystic vtab) that
+     * learns of remote writes out-of-band, so the change never touches this
+     * `Database`'s commit change-log and the post-commit watcher path would
+     * otherwise never fire.
+     *
+     * Coarse by design: handlers receive a global (whole-table) {@link WatchEvent}
+     * — `full` watches fire with empty `hits`; `rows`/`rowsByGroup` watches
+     * surface all their registered literal values as possibly-changed; `groups`
+     * fire with empty hits. Over-firing only costs the consumer an extra
+     * re-query; it never misses a change. A no-op when no subscription matches.
+     * Async to mirror the post-commit watcher path (handlers may be async).
+     *
+     * When the host has the actual row images, prefer the precise,
+     * in-transaction {@link ingestExternalRowChanges} seam instead: row-granular
+     * watch hits at commit, plus MV maintenance, assertion evaluation, and
+     * opt-in FK actions.
+     *
+     * @param tableName  The table whose watchers to fire.
+     * @param schemaName Defaults to the current schema
+     *   (`schemaManager.getCurrentSchemaName()`).
+     */
+    async notifyExternalChange(tableName, schemaName) {
+        this.checkOpen();
+        const schema = schemaName ?? this.schemaManager.getCurrentSchemaName();
+        const fqName = `${schema}.${tableName}`.toLowerCase();
+        await this.watcherManager.notifyExternalTableChange(fqName);
+    }
+    /**
+     * Batch ingestion seam for externally-applied row changes: drives the
+     * post-write pipeline — change capture (`Database.watch` post-commit
+     * dispatch + commit-time global assertions), batch-amortized row-time
+     * materialized-view maintenance, and opt-in parent-side FK actions — for
+     * writes the caller has already applied directly to module storage,
+     * bypassing the DML executor. The precise, in-transaction alternative to
+     * the coarse whole-table {@link notifyExternalChange}.
+     *
+     * `changes` is a flat ordered array; same-row changes must appear in event
+     * order (each change's `oldRow` must be the true before-image of *that*
+     * change — the prior change's `newRow`). The FK-actions facet re-reads
+     * post-write merged storage and is order-independent for realistic batch
+     * shapes (see `docs/sync.md` § Transactional Integrity During Sync for the
+     * (E)/(F) exotic-topology caveats). The seam
+     * trusts the origin — it re-validates NOTHING (no CHECK / NOT NULL /
+     * UNIQUE / child-side FK existence), and it does NOT emit module data
+     * events (the external writer owns those, including the `remote` flag).
+     *
+     * Transaction contract: runs inside the caller's active transaction when
+     * one exists (the reported rows must already be visible to a vtab read
+     * within it — the residual/full-rebuild maintenance arms re-read the
+     * source); otherwise begins an implicit transaction it commits at batch
+     * end. The batch's DERIVED effects are atomic via a batch savepoint; a
+     * mid-batch error unwinds them all (the externally-applied storage rows
+     * are NOT unwound by Quereus). Serialized via the exec mutex — do NOT call
+     * from within statement execution or vtab callbacks (deadlock); the
+     * two-arg `_maintainRowTimeCoveringStructures` is the seam for that
+     * context. See `docs/materialized-views.md` § External row-change
+     * ingestion for the full contract.
+     *
+     * Returns the collected commit-time global-assertion violations. With the
+     * default `assertionFailureMode: 'throw'` a violation throws (and rolls the
+     * batch's derived effects back) so the returned list is always empty; with
+     * `'report'` — honored only for the seam-owned implicit transaction with
+     * capture on — a violation is collected and the batch still commits (derived
+     * effects land, watch dispatches), so the returned list names every violated
+     * assertion. Empty in every other case.
+     */
+    async ingestExternalRowChanges(changes, options) {
+        this.checkOpen();
+        return ingestExternalRowChangeBatch(this, changes, options);
+    }
+    /** @internal Compile + register an MV for row-time write-through maintenance.
+     *  Throws on a body that is not row-time maintainable (the mandatory create-time gate). */
+    registerMaterializedView(mv) {
+        this.materializedViewManager.registerMaterializedView(mv);
+    }
+    /** @internal Detach an MV's row-time maintenance plan (DROP path). */
+    unregisterMaterializedView(schemaName, name) {
+        this.materializedViewManager.unregisterMaterializedView(schemaName, name);
+    }
+    /** @internal Force-mark an MV stale: detach its row-time plan and invalidate cached
+     *  backing reads so the next reference re-hits the build-time stale guard
+     *  (ALTER … RENAME propagation failure path). */
+    markMaterializedViewStale(mv) {
+        this.materializedViewManager.markMaterializedViewStale(mv);
+    }
+    /**
+     * Refresh every maintained table (materialized view) in source-dependency
+     * order, bringing each backing current with its sources. The convergence
+     * point after a wholesale external load (e.g. a sync snapshot bootstrap) that
+     * deferred row-time maintenance. Each MV is refreshed through the same
+     * full-rebuild path as `refresh materialized view` (stale revalidation, shape
+     * re-derivation/reshape, row-time re-registration, `stale` clear), so a
+     * bounded-delta MV is full-rebuilt here too — convergence does not depend on
+     * delta replay, and the full rebuild re-reads the complete source through the
+     * vtab regardless of how its rows arrived (out-of-band direct-storage writes
+     * included). MV-over-MV chains converge base-first: refresh is commit-first per
+     * MV, so a base MV's backing is committed before a dependent's body re-reads it.
+     *
+     * NOT atomic across the sweep — the whole sweep is deliberately NOT wrapped in
+     * one explicit transaction (refresh is commit-first per MV, so an enclosing
+     * transaction would not make it atomic anyway). Each MV ensures/commits its own
+     * implicit transaction exactly as the single-MV `refresh` does, so a failure
+     * partway leaves earlier MVs converged; the caller (snapshot bootstrap) retries
+     * the whole load idempotently.
+     *
+     * Serialized via the exec mutex like any statement — do NOT call from within
+     * statement execution or a vtab callback (deadlock; same constraint as
+     * `refresh materialized view` itself). Returns the refreshed MV identifiers
+     * (for coarse watch notification); `[]` (no mutex, no transaction) when there
+     * are no maintained tables. See `docs/materialized-views.md` § Converging all
+     * materialized views.
+     */
+    async refreshAllMaterializedViews() {
+        this.checkOpen();
+        // Build the order BEFORE the mutex: it only reads catalog/plan state, and an
+        // empty catalog must take no mutex and start no transaction.
+        const order = this.materializedViewManager.materializedViewRefreshOrder();
+        if (order.length === 0)
+            return [];
+        const refreshed = [];
+        await this._withMutex(async () => {
+            // Per-MV implicit-transaction scope mirrors `exec`'s per-statement boundary:
+            // each refresh commits independently (commit-first), so a mid-sweep failure
+            // leaves the already-refreshed MVs converged rather than rolling them back.
+            for (const mv of order) {
+                try {
+                    await this._ensureTransaction();
+                    const live = await refreshMaintainedTable(this, mv);
+                    if (this._isImplicitTransaction()) {
+                        await this._commitTransaction();
+                    }
+                    refreshed.push({ schemaName: live.schemaName, name: live.name });
+                }
+                catch (err) {
+                    if (this._isImplicitTransaction()) {
+                        await this._rollbackTransaction();
+                    }
+                    throw err;
+                }
+            }
+        });
+        return refreshed;
+    }
+    /** @internal Cheap synchronous guard for the per-row DML maintenance hook: true
+     *  iff a `row-time` covering structure reads `sourceBase` (lowercased or raw
+     *  `schema.table`). Lets a hot write path skip the maintenance call entirely when
+     *  no row-time MV depends on the written table. */
+    _hasRowTimeCoveringStructures(sourceBase) {
+        return this.materializedViewManager.hasRowTimePlanFor(sourceBase);
+    }
+    /** @internal Synchronously maintain every `row-time` covering structure on
+     *  `sourceBase` for one source row-write, before the writing statement observes
+     *  its own effects. Drives a per-row backing delta through the backing table's
+     *  coordinated transactional connection (reads-own-writes within the txn;
+     *  committed/rolled-back in lockstep with the source write). See
+     *  `database-materialized-views.ts` § row-time write-through.
+     *
+     *  `cache` is the optional per-statement {@link BackingConnectionCache} the DML
+     *  generator threads in so the backing-connection resolution is amortized over the
+     *  whole statement (one scan per backing, not one per source row). The cold
+     *  eviction callers (memory `checkUniqueViaMaterializedView`, store-table.ts) omit
+     *  it and re-resolve the same connection deterministically — the `DatabaseInternal`
+     *  surface deliberately exposes only the two-arg form (a host reporting writes from
+     *  OUTSIDE a statement uses the batch-amortized {@link ingestExternalRowChanges}
+     *  seam instead).
+     *
+     *  `deferred` is the optional per-statement deferred-rebuild set: a `'full-rebuild'`
+     *  plan is marked dirty in it (no per-row apply) and drained once at the
+     *  end-of-statement {@link _flushDeferredRebuilds}. The DML generator owns it; cold
+     *  callers omit it (and never name a full-rebuild MV, which is never a covering
+     *  structure — so an inline rebuild is at worst a safe, unreached fallback). */
+    async _maintainRowTimeCoveringStructures(sourceBase, change, cache, deferred) {
+        await this.materializedViewManager.maintainRowTime(sourceBase, change, cache, deferred);
+    }
+    /** @internal Drain the per-statement deferred full-rebuild set at the
+     *  end-of-statement boundary: rebuild every dirtied full-rebuild covering MV exactly
+     *  once and cascade each rebuild's delta onward (MV-over-MV). The DML generator calls
+     *  this after the row loop and before releasing the statement-atomicity savepoint, so
+     *  a failed rebuild rolls the whole statement back. `cache` is the same per-statement
+     *  {@link BackingConnectionCache} the row loop used. See
+     *  `database-materialized-views.ts` § flushDeferredRebuilds. */
+    async _flushDeferredRebuilds(deferred, cache) {
+        await this.materializedViewManager.flushDeferredRebuilds(deferred, cache);
+    }
+    /** @internal Resolve the linked, `row-time`, enforcement-ready covering MV for a
+     *  UNIQUE constraint on `schema.table`, or `undefined`. Synchronous (a map lookup
+     *  plus name/staleness checks) with an O(1) negative fast path, so the UNIQUE-check
+     *  path can consult it without async overhead. When it returns an MV, conflict
+     *  resolution routes through the covering MV's backing table (in preference to the
+     *  auto-index) — see `docs/materialized-views.md` § Covering structures. */
+    _findRowTimeCoveringStructure(schemaName, tableName, uc) {
+        return this.materializedViewManager.findRowTimeCoveringStructure(schemaName, tableName, uc);
+    }
+    /** @internal Point-look up a row-time covering MV's backing table for rows whose
+     *  backing columns equal `newRow`'s UNIQUE values, returning the conflicting
+     *  **source** PK(s) (excluding `newSourcePk`, the row being written). Reads-own-writes
+     *  through the backing table's coordinated connection. The caller validates each
+     *  candidate against its live source row and applies IGNORE/ABORT/REPLACE. */
+    async _lookupCoveringConflicts(mv, uc, newRow, newSourcePk) {
+        return this.materializedViewManager.lookupCoveringConflicts(mv, uc, newRow, newSourcePk);
+    }
     /** @internal Invalidate cached assertion plan (called on DROP ASSERTION) */
     invalidateAssertionCache(name) {
         this.assertionEvaluator.invalidateAssertion(name);