@quereus/quereus 4.3.1 → 4.4.0

package/dist/src/core/database.js

@@ -31,6 +31,7 @@ import { registerType as registerTypeInRegistry } from '../types/registry.js';
 import { getParameterTypes } from './param.js';
 import { rowToObject } from './utils.js';
 import { wrapAsyncIterator } from '../util/async-iterator.js';
+import { Latches } from '../util/latches.js';
 import { DatabaseEventEmitter, } from './database-events.js';
 import { TransactionManager } from './database-transaction.js';
 import { ingestExternalRowChangeBatch } from './database-external-changes.js';
@@ -88,13 +89,28 @@ export class Database {
     /** 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,
+     *  optional REPLICABLE and ORDER-PRESERVING assertions. 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}). */
+     *  (see {@link _isCollationReplicable}). `orderPreserving` (same shape) is consulted
+     *  by persistent stores before seeking a byte range or advertising byte order as
+     *  collation order (see {@link _isCollationOrderPreserving}). */
     collations = new Map();
+    /** Lazily-bound {@link getCollationResolver} closure — created once so callers can
+     *  compare resolver identity, while still reading the live `collations` map. */
+    collationResolver;
+    /** Lazily-bound {@link getKeyNormalizerResolver} closure — same identity/liveness
+     *  contract as {@link collationResolver}. */
+    keyNormalizerResolver;
+    /**
+     * Per-database latch registry — serializes commit / collapse / consolidate /
+     * destroy / schema-change work by string key *within this database*. Scoped to
+     * the `Database` instance (not process-global) so two databases never contend
+     * on the same key. Memory-table managers reach it via `this.db.latches`.
+     */
+    latches = new Latches();
     constructor() {
         this.schemaManager = new SchemaManager(this);
         this.declaredSchemaManager = new DeclaredSchemaManager();
@@ -211,6 +227,18 @@ export class Database {
                 log('Default column nullability changed to: %s', value);
             }
         });
+        this.options.registerOption('ddl_transaction_policy', {
+            type: 'string',
+            defaultValue: 'permissive',
+            description: 'Whether module-dispatching DDL (CREATE/DROP TABLE/INDEX, ALTER TABLE) is allowed inside an explicit transaction: "permissive" (default; schema changes may escape the transaction, as today) or "strict" (refuse such DDL inside a transaction unless the module declares ddlTransactionality=transactional).',
+            onChange: (event) => {
+                const value = event.newValue;
+                if (value !== 'permissive' && value !== 'strict') {
+                    throw new QuereusError(`Invalid ddl_transaction_policy value: ${value}. Must be "permissive" or "strict"`, StatusCode.ERROR);
+                }
+                log('DDL transaction policy changed to: %s', value);
+            }
+        });
         this.options.registerOption('default_collation', {
             type: 'string',
             defaultValue: 'BINARY',
@@ -301,14 +329,21 @@ export class Database {
     registerDefaultCollations() {
         // Register the built-in collations into per-instance registry, paired
         // 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
+        // `replicable: true` — the built-ins are pure JS string operations (a code-point
+        // scan, 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 });
+        //
+        // Also stamped `orderPreserving: true`: each built-in comparator orders its
+        // operands' NORMALIZED forms by Unicode CODE POINT (BINARY's normalizer is the
+        // identity, NOCASE's is `toLowerCase()`, RTRIM's an ASCII-space right-trim), and
+        // code-point order IS the order a memcmp of those forms' UTF-8 bytes produces —
+        // see {@link import('../util/comparison.js').compareCodePoints} and
+        // {@link _isCollationOrderPreserving}.
+        this.collations.set('BINARY', { comparator: BINARY_COLLATION, normalizer: BUILTIN_NORMALIZERS.BINARY, replicable: true, orderPreserving: true });
+        this.collations.set('NOCASE', { comparator: NOCASE_COLLATION, normalizer: BUILTIN_NORMALIZERS.NOCASE, replicable: true, orderPreserving: true });
+        this.collations.set('RTRIM', { comparator: RTRIM_COLLATION, normalizer: BUILTIN_NORMALIZERS.RTRIM, replicable: true, orderPreserving: true });
         log("Default collations registered (BINARY, NOCASE, RTRIM)");
     }
     /**
@@ -361,7 +396,9 @@ export class Database {
         throwIfAborted(options?.signal);
         const stmt = this.prepare(sql, params);
         try {
-            return await stmt.get(params, options);
+            // Params were already bound (and their types inferred) by prepare();
+            // don't re-pass them or stmt.get() would rebind + re-validate every value.
+            return await stmt.get(undefined, options);
         }
         finally {
             await stmt.finalize();
@@ -1076,11 +1113,12 @@ export class Database {
         this.optimizer.updateTuning(tuning);
     }
     /**
-     * Registers a user-defined collation sequence.
+     * Registers a user-defined collation sequence. `NOCASE` and `RTRIM` may be replaced;
+     * `BINARY` may not (see {@link getCollationResolver}) and throws `MisuseError`.
      * @param name The name of the collation sequence (case-insensitive).
      * @param func The comparison function (a, b) => number (-1, 0, 1).
      * @param optionsOrNormalizer Either a bare key normalizer (the legacy positional
-     *   form) or an options object `{ normalizer?, replicable? }`:
+     *   form) or an options object `{ normalizer?, replicable?, orderPreserving? }`:
      *   - `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
@@ -1090,6 +1128,16 @@ export class Database {
      *     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).
+     *   - `orderPreserving` — assert the normalizer preserves ORDER, not merely
+     *     equality: for all strings `x`, `y`,
+     *     `sign(func(x, y)) === sign(memcmp(utf8(normalizer(x)), utf8(normalizer(y))))`.
+     *     This is strictly stronger than the equality promise `normalizer` alone makes.
+     *     Persistent stores physically order rows by the normalized key bytes, so they
+     *     may only seek a byte range — or advertise byte order as collation order — for
+     *     a collation carrying this assertion; without it they fall back to a full scan
+     *     plus a comparator-accurate residual filter (correct, just slower). Defaults to
+     *     `false` — correctness over speed for a custom collation (built-ins auto-qualify).
+     *     See {@link _isCollationOrderPreserving}.
      * @example
      * // Example: Create a custom collation for phone numbers
      * db.registerCollation('PHONENUMBER', (a, b) => {
@@ -1102,10 +1150,31 @@ export class Database {
      * // A locale-independent custom collation a replicating backing can host:
      * db.registerCollation('CODEPOINT', cmp, { replicable: true });
      *
+     * // A normalizer whose byte order matches its comparator, so store range seeks stay:
+     * db.registerCollation('NOSPACE', cmp, { normalizer: s => s.replace(/ /g, ''), orderPreserving: true });
+     *
      * // Then use it in SQL:
      * // SELECT * FROM contacts ORDER BY phone COLLATE PHONENUMBER;
      * // CREATE INDEX phone_idx ON contacts(phone COLLATE PHONENUMBER);
      */
+    // NOTE: registration is not retroactive. Comparators and key normalizers are
+    // resolved once, at comparator-construction time (index build, plan emission), so a
+    // collation registered — or re-registered with a different comparator/normalizer —
+    // after a structure was built does not rebuild it. A statement emitted *after* the
+    // re-registration does see the new one. Register collations before creating tables
+    // and indexes that name them. If retroactive re-registration ever needs to be
+    // supported, invalidate dependent indexes and cached plans here: the collation
+    // dependency `EmissionContext` records only drives an existence check before
+    // execution (`validateCapturedSchemaObjects`), which warns — it does not invalidate.
+    //
+    // NOTE: `orderPreserving` is stated against UTF-8 memcmp of the normalized forms, and the
+    // built-ins hold it for every WELL-FORMED string. It is unachievable for unpaired
+    // surrogates, which have no UTF-8 encoding at all (`TextEncoder` folds each to U+FFFD);
+    // the persistent store therefore REFUSES to key them (`quereus-store`'s `encodeText`
+    // raises), so no value a store-backed table can hold falls outside the assertion. Memory
+    // tables still accept them, which is why comparators must stay total there. A custom
+    // collation that compares with JS `<`/`>` orders by UTF-16 code unit and must NOT claim
+    // the assertion; use {@link import('../util/comparison.js').compareCodePoints}.
     registerCollation(name, func, optionsOrNormalizer) {
         this.checkOpen();
         if (typeof name !== 'string' || !name) {
@@ -1115,16 +1184,18 @@ export class Database {
             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.
+        // sites unchanged, `replicable` and `orderPreserving` default to false); an object
+        // reads its fields; any other non-undefined third arg is a misused legacy normalizer.
         let normalizer;
         let replicable = false;
+        let orderPreserving = false;
         if (typeof optionsOrNormalizer === 'function') {
             normalizer = optionsOrNormalizer;
         }
         else if (typeof optionsOrNormalizer === 'object' && optionsOrNormalizer !== null) {
             normalizer = optionsOrNormalizer.normalizer;
             replicable = optionsOrNormalizer.replicable === true;
+            orderPreserving = optionsOrNormalizer.orderPreserving === true;
         }
         else if (optionsOrNormalizer !== undefined) {
             throw new MisuseError('registerCollation: normalizer must be a function when supplied');
@@ -1132,7 +1203,12 @@ export class Database {
         if (normalizer !== undefined && typeof normalizer !== 'function') {
             throw new MisuseError('registerCollation: normalizer must be a function when supplied');
         }
-        const upperName = name.toUpperCase();
+        const upperName = normalizeCollationName(name);
+        if (upperName === 'BINARY') {
+            // Resolvers fast-path BINARY to the built-in comparator, so an override could
+            // never take effect uniformly — reject rather than silently half-apply it.
+            throw new MisuseError('registerCollation: BINARY cannot be overridden');
+        }
         if (this.collations.has(upperName)) {
             log('Overwriting existing collation: %s', upperName);
         }
@@ -1141,8 +1217,22 @@ export class Database {
             entry.normalizer = normalizer;
         if (replicable)
             entry.replicable = true;
+        if (orderPreserving)
+            entry.orderPreserving = true;
         this.collations.set(upperName, entry);
-        log('Registered collation: %s%s%s', upperName, normalizer !== undefined ? ' (with normalizer)' : '', replicable ? ' (replicable)' : '');
+        log('Registered collation: %s%s%s%s', upperName, normalizer !== undefined ? ' (with normalizer)' : '', replicable ? ' (replicable)' : '', orderPreserving ? ' (order-preserving)' : '');
+    }
+    /**
+     * True iff `name` names a collation this connection can resolve — a built-in
+     * (BINARY/NOCASE/RTRIM) or one registered via {@link registerCollation}. The
+     * DDL-time counterpart of {@link getCollationResolver} that returns a boolean
+     * instead of throwing; used to gate an explicit column COLLATE against the
+     * connection's registry (see `validateCollationForType`). Names are normalized
+     * (trim + uppercase) here and in {@link _getCollation}, so whitespace / case
+     * variants resolve identically.
+     */
+    isCollationRegistered(name) {
+        return normalizeCollationName(name) === 'BINARY' || this._getCollation(name) !== undefined;
     }
     /**
      * Registers a custom logical type.
@@ -1205,23 +1295,92 @@ export class Database {
     getInstructionTracer() {
         return this.instructionTracer;
     }
+    /**
+     * The canonical way to turn a collation name into a comparison function for this
+     * database. Every comparator-construction site should route through this rather
+     * than the deprecated process-global registry in `util/comparison.ts`, so a
+     * collation registered with {@link registerCollation} is actually honored.
+     *
+     * The returned resolver:
+     * - has stable identity across calls (bound once) and reads the live per-database
+     *   registry, so a collation registered *after* the resolver was handed out is
+     *   visible to later calls;
+     * - resolves names case-insensitively (and tolerates surrounding whitespace);
+     * - **throws** `QuereusError` (`no such collation sequence: X`) on an unknown name.
+     *   An unresolvable collation is never downgraded to BINARY: byte-order results
+     *   would be silently wrong for ORDER BY, UNIQUE, and index seeks alike;
+     * - fast-paths the exact name `BINARY`. `BINARY` cannot be overridden — this is
+     *   the fast path's correctness precondition, enforced by {@link registerCollation}
+     *   rejecting it. Any other built-in — including `NOCASE` and `RTRIM` — can be
+     *   overridden per database.
+     *
+     * It performs no `checkOpen()` check: it runs on hot comparator-construction paths,
+     * and reading the registry of a closed database is harmless.
+     */
+    getCollationResolver() {
+        if (this.collationResolver === undefined) {
+            this.collationResolver = (collationName) => {
+                if (collationName === 'BINARY')
+                    return BINARY_COLLATION;
+                const func = this._getCollation(collationName);
+                if (!func) {
+                    throw new QuereusError(`no such collation sequence: ${collationName}`, StatusCode.ERROR);
+                }
+                return func;
+            };
+        }
+        return this.collationResolver;
+    }
+    /**
+     * The canonical way to turn a collation name into a **key normalizer** for this
+     * database — the hash-keyed counterpart of {@link getCollationResolver}. Every
+     * operator that buckets rows by a text key (GROUP BY, window PARTITION BY, bloom /
+     * hash join keys, AS OF partitioning) must resolve through this, so that grouping
+     * and comparison agree on which rows are equal.
+     *
+     * Same contract as {@link getCollationResolver}: stable identity, reads the live
+     * registry, no `checkOpen()`, and **no silent fallback**.
+     *
+     * - `undefined` or the exact name `BINARY` → the identity normalizer. `BINARY`
+     *   cannot be overridden ({@link registerCollation} rejects it), which is this fast
+     *   path's correctness precondition.
+     * - A registered collation carrying a normalizer → that normalizer.
+     * - A registered collation with **no** normalizer → throws. A comparator-only
+     *   collation can order rows but cannot bucket them; guessing a normalizer would
+     *   split or merge groups the comparator disagrees with.
+     * - An unregistered name → throws `no such collation sequence: X`.
+     */
+    getKeyNormalizerResolver() {
+        if (this.keyNormalizerResolver === undefined) {
+            this.keyNormalizerResolver = (collationName) => {
+                if (!collationName || collationName === 'BINARY')
+                    return BUILTIN_NORMALIZERS.BINARY;
+                const normalizer = this._getCollationNormalizer(collationName);
+                if (normalizer)
+                    return normalizer;
+                if (!this._getCollation(collationName)) {
+                    throw new QuereusError(`no such collation sequence: ${collationName}`, StatusCode.ERROR);
+                }
+                throw new QuereusError(`collation ${collationName} has no key normalizer; grouping and hash-join keys require one — pass { normalizer } to registerCollation`, StatusCode.ERROR);
+            };
+        }
+        return this.keyNormalizerResolver;
+    }
     /** @internal Gets a registered collation function */
     _getCollation(name) {
-        return this.collations.get(name.toUpperCase())?.comparator;
+        return this.collations.get(normalizeCollationName(name))?.comparator;
     }
-    /** @internal Gets the registered key normalizer for a collation, falling back
-     *  to the built-in normalizer for `BINARY` / `NOCASE` / `RTRIM` if the
-     *  collation has no explicit normalizer registered. Returns `undefined` for
-     *  comparator-only user-defined collations. */
+    /** @internal Gets the registered key normalizer for a collation. Returns `undefined`
+     *  both for an unregistered name and for a comparator-only collation — the two are
+     *  distinguished, and turned into errors, by {@link getKeyNormalizerResolver}.
+     *
+     *  There is deliberately no built-in fallback: an embedder that re-registers `NOCASE`
+     *  with a custom comparator and no normalizer must get a loud error, not the built-in
+     *  lowercase normalizer, which would partition strings differently from their
+     *  comparator. The built-ins are seeded *with* their normalizers in
+     *  `registerDefaultCollations()`, so a fresh database loses nothing. */
     _getCollationNormalizer(name) {
-        const upper = name.toUpperCase();
-        const entry = this.collations.get(upper);
-        if (entry?.normalizer !== undefined)
-            return entry.normalizer;
-        // Built-in fallback: even an entry that lost its normalizer (shouldn't
-        // happen for built-ins, but defends against external mutation) still
-        // resolves to the canonical built-in normalizer.
-        return BUILTIN_NORMALIZERS[upper];
+        return this.collations.get(normalizeCollationName(name))?.normalizer;
     }
     /** @internal True iff the named collation is asserted REPLICABLE — bit-identical
      *  across peers/platforms/app-versions. Built-ins are stamped `replicable` at
@@ -1231,7 +1390,28 @@ export class Database {
      *  replicable-collation gate when the backing host declares
      *  `requiresReplicableDerivations`. */
     _isCollationReplicable(name) {
-        return this.collations.get(name.toUpperCase())?.replicable === true;
+        return this.collations.get(normalizeCollationName(name))?.replicable === true;
+    }
+    /** @internal True iff the named collation is asserted ORDER-PRESERVING: for all strings
+     *  `x`, `y`, `sign(comparator(x, y))` equals
+     *  `sign(memcmp(utf8(normalizer(x)), utf8(normalizer(y))))`. Strictly stronger than the
+     *  equality-partition promise a bare normalizer makes — a normalizer may agree with the
+     *  comparator on equality while disagreeing on order.
+     *
+     *  Built-ins are stamped `orderPreserving` at registration; a custom collation opts in
+     *  with `orderPreserving: true`. An unregistered name, or a comparator-only collation
+     *  (no normalizer, hence no key bytes at all), returns `false` defensively.
+     *
+     *  Consumed by persistent stores, which physically order rows by normalized key bytes:
+     *  a byte-range seek, or an advertisement that byte order *is* collation order, is sound
+     *  only under this assertion. Without it the store full-scans and lets its
+     *  comparator-accurate residual filter decide — slower, never wrong. */
+    _isCollationOrderPreserving(name) {
+        const entry = this.collations.get(normalizeCollationName(name));
+        // The assertion is *about* the normalizer, so it is vacuous without one; a
+        // comparator-only collation cannot key a persisted structure anyway (the store
+        // rejects it at DDL time), and answering `true` here would be a trap.
+        return entry?.orderPreserving === true && entry.normalizer !== undefined;
     }
     _queueDeferredConstraintRow(baseTable, constraintName, row, descriptor, evaluator, connectionId, contextRow, contextDescriptor) {
         this.deferredConstraints.enqueue(baseTable, constraintName, row, descriptor, evaluator, connectionId, contextRow, contextDescriptor);
@@ -1661,6 +1841,18 @@ export class Database {
             }
         }
     }
+    /**
+     * @internal Force-removes one connection by id.
+     * Unlike unregisterConnection, this bypasses the implicit transaction deferral —
+     * the caller has established that this specific connection is definitively stale.
+     */
+    removeConnection(connectionId) {
+        const connection = this.activeConnections.get(connectionId);
+        if (connection) {
+            this.activeConnections.delete(connectionId);
+            log(`Removed stale connection ${connectionId} for table ${connection.tableName}`);
+        }
+    }
     /**
      * @internal Gets all active connections for a specific table.
      * @param tableName The name of the table
@@ -1735,6 +1927,31 @@ export class Database {
     _isFkRestrictSuppressed() {
         return this._fkRestrictSuppressed;
     }
+    /** @internal FK cascade re-entry flag — see {@link _setFkCascadeReentry}. */
+    _fkCascadeReentry = false;
+    /** @internal Marks that the DML currently re-entering the executor is one of
+     *  Quereus's own FK cascade child writes (cascade DELETE / UPDATE, SET NULL,
+     *  SET DEFAULT — physical or lens), not a direct user DML on the child table.
+     *  Set only for the duration of each cascade child write by
+     *  `withFkCascadeReentry` in `runtime/foreign-key-actions.ts`, so a host vtab
+     *  module can distinguish a cascade re-entry from a user write on the same
+     *  child and suppress redundant child-side FK re-validation only for the
+     *  former. Independent of {@link _setFkRestrictSuppressed} (a cascade path may
+     *  legitimately have both semantics in play). Returns the prior value so the
+     *  caller restores it in a `finally` — nesting-safe: an inner cascade restores
+     *  to the outer's `true`, the outermost to `false`, and a thrown cascade cannot
+     *  latch the flag on. Nothing inside Quereus reads it; it exposes the signal the
+     *  host consumes. */
+    _setFkCascadeReentry(value) {
+        const prior = this._fkCascadeReentry;
+        this._fkCascadeReentry = value;
+        return prior;
+    }
+    /** @internal Whether the current DML re-entry is a Quereus FK cascade child
+     *  write — see {@link _setFkCascadeReentry}. */
+    _isFkCascadeReentry() {
+        return this._fkCascadeReentry;
+    }
     /**
      * Subscribe to changes described by a {@link ChangeScope}.
      *
@@ -1823,7 +2040,7 @@ export class Database {
      * 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
+     * context. See `docs/mv-ingestion.md` § External row-change
      * ingestion for the full contract.
      *
      * Returns the collected commit-time global-assertion violations. With the
@@ -1877,7 +2094,7 @@ export class Database {
      * 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
+     * are no maintained tables. See `docs/mv-ingestion.md` § Converging all
      * materialized views.
      */
     async refreshAllMaterializedViews() {
@@ -1934,30 +2151,33 @@ export class Database {
      *  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);
+     *  `deferred` is the optional per-statement deferred-rebuild set (a `'full-rebuild'`
+     *  plan is marked dirty in it, no per-row apply) and `residualBatch` the optional
+     *  per-statement residual key batch (the residual arms accumulate their deduped
+     *  affected binding keys into it, no per-row recompute); both drain once at the
+     *  end-of-statement {@link _flushDeferredMaintenance}. The DML generator owns them;
+     *  cold callers omit them (and only ever name inverse-projection MVs — the one
+     *  per-row-immediate arm — so the inline per-change fallback is at worst a safe,
+     *  unamortized apply). */
+    async _maintainRowTimeCoveringStructures(sourceBase, change, cache, deferred, residualBatch) {
+        await this.materializedViewManager.maintainRowTime(sourceBase, change, cache, deferred, residualBatch);
+    }
+    /** @internal Drain the per-statement deferred maintenance at the end-of-statement
+     *  boundary: recompute every accumulated residual key once per distinct key, rebuild
+     *  every dirtied full-rebuild covering MV exactly once, and cascade each delta onward
+     *  (MV-over-MV). The DML generator calls this after the row loop and before releasing
+     *  the statement-atomicity savepoint, so a failed recompute/rebuild rolls the whole
+     *  statement back. `cache` is the same per-statement {@link BackingConnectionCache}
+     *  the row loop used. See `database-materialized-views.ts` § flushDeferredMaintenance. */
+    async _flushDeferredMaintenance(deferred, residualBatch, cache) {
+        await this.materializedViewManager.flushDeferredMaintenance(deferred, residualBatch, 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. */
+     *  auto-index) — see `docs/mv-constraints.md` § Covering structures. */
     _findRowTimeCoveringStructure(schemaName, tableName, uc) {
         return this.materializedViewManager.findRowTimeCoveringStructure(schemaName, tableName, uc);
     }