@quereus/quereus 3.3.0 → 4.0.0

package/dist/src/vtab/backing-host.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Backing-host capability: the module-neutral, privileged surface a virtual
+ * table module exposes so the engine can host a materialized view's backing
+ * table inside it. Resolved per table via
+ * {@link VirtualTableModule.getBackingHost} — presence of that method is the
+ * capability (mirrors `getMappingAdvertisements`). The memory module is the
+ * default and reference implementation (`vtab/memory/module.ts`).
+ *
+ * ## Cost contract
+ *
+ * A backing host MUST provide PK-ordered storage with O(log n) keyed
+ * upsert / delete / point-lookup AND an ordered prefix-range scan (seek to a
+ * leading-PK equality prefix, walk in PK order, early-terminate when the
+ * prefix stops matching). This is what keeps every bounded-delta maintenance
+ * arm (`delete-by-prefix` included) and the covering-UNIQUE prefix lookup
+ * module-agnostic. A module that cannot provide the ordered prefix scan must
+ * NOT advertise the capability — the engine does not gate per maintenance arm.
+ *
+ * ## Effective-change reporting
+ *
+ * Reporting the EFFECTIVE per-row changes from {@link BackingHost.applyMaintenance}
+ * is part of the contract, not an optimization: the MV-over-MV cascade routes
+ * each returned {@link BackingRowChange} back through `maintainRowTime`, so
+ * over- or under-reporting corrupts consumer MVs. Fidelity cuts both ways: an op
+ * that changes nothing — a `delete` of an absent key, a **value-identical
+ * `upsert`** (see {@link MaintenanceOp}) — reports nothing, so a no-op maintenance
+ * write fires no cascade and, for a change-logged (synced) backing, produces no
+ * change-log entry (no echo).
+ *
+ * ## Transactionality
+ *
+ * `applyMaintenance` writes the connection's PENDING transaction state;
+ * commit/rollback ride the registered {@link VirtualTableConnection}'s
+ * `begin/commit/rollback/savepoint` surface (already generic), so the backing
+ * delta commits/rolls-back in lockstep with the source write under the
+ * Database's coordinated commit.
+ *
+ * ## Read-only to user DML — engine-owned
+ *
+ * A maintained table's rows are derived; nothing but the privileged surface may
+ * write them. This is enforced by the **engine**, not owed by the host module:
+ * the planner rewrites user DML naming a maintained table to **write-through**
+ * against the body's base source (the three DML builders' view-mutation dispatch
+ * + the resolved-schema backstop), and the runtime DML executor carries a
+ * READONLY backstop that rejects any mutation plan whose target still carries a
+ * derivation (`runtime/emit/dml-executor.ts` `assertNotMaintainedTableTarget`) —
+ * the second net catching a plan-time mis-dispatch before it can silently
+ * diverge the derived contents. The privileged surface (`applyMaintenance` /
+ * `replaceContents` and the reconcile / rehydrate-refill paths) bypasses both by
+ * construction: it never routes through the DML executor. A host module
+ * therefore implements no user-DML permission check of its own; direct
+ * programmatic `update()` calls on the backing by an embedder are the same trust
+ * level as holding this privileged surface and are out of engine scope.
+ *
+ * ## Constraint validation — split by shape
+ *
+ * Declared CHECK and child-side FK constraints on a maintained table are
+ * per-ROW properties and are validated by the **engine** at the maintenance
+ * boundary: the attach core's bulk scan over the reconciled contents
+ * (create-fill / attach — `validateDeclaredConstraintsOverContents` in
+ * `runtime/emit/materialized-view-helpers.ts`) and the per-row derived-row
+ * validator over each maintenance delta (`core/derived-row-validator.ts`,
+ * applied by the maintenance manager before the cascade). A host module
+ * implements none of that itself.
+ *
+ * Declared secondary (non-PK) UNIQUE constraints are COLLISION-shaped — a
+ * property of a pair of rows under the host's own key/collation machinery —
+ * and are enforced by the **host**, exactly where its DML UNIQUE enforcement
+ * already lives: after applying an `applyMaintenance` batch, the host checks
+ * each written (insert/update) image against the batch's final effective
+ * contents for a different-PK row matching the constraint (NULLs distinct,
+ * partial predicates honored, per-column collations, conflict action forced to
+ * ABORT — a derivation write carries no user OR clause and must never evict),
+ * throwing the maintained-table-attributed CONSTRAINT error
+ * (`maintainedTableUniqueViolationError`). Post-batch is load-bearing: a
+ * `replace-all` diff applies upserts before deletes, so a per-op check would
+ * false-positive when the derived set moves a unique value between primary
+ * keys. Checking only written images is complete because pre-existing contents
+ * already satisfied the constraint (DML / ADD CONSTRAINT enforced it), so any
+ * colliding pair includes a written image. See the memory host's
+ * `enforceSecondaryUniqueOnMaintenance` (reference) and the store host's
+ * `StoreTable.enforceSecondaryUniqueForMaintenance`. `replaceContents` remains
+ * validation-free (PK identity aside): create/import (`materializeView`) carries
+ * MV-sugar backings, which declare no constraints, and the refresh path
+ * (`rebuildBacking`) only calls `replaceContents` when the maintained table
+ * declares no applicable CHECK/FK — a constraint-bearing refresh instead routes
+ * through `applyMaintenance('replace-all')` + the engine's bulk
+ * `validateDeclaredConstraintsOverContents` scan (the stale-refresh
+ * re-validation path), so `replaceContents` never has constraints to validate.
+ *
+ * ## Concurrency
+ *
+ * The engine adds no latching around the privileged surface: each host owns
+ * its own concurrency discipline under the {@link VtabConcurrencyMode} its
+ * module declares (the memory host's pending layer is private to the
+ * connection and mutated synchronously, so it needs none).
+ *
+ * ## Replicable-determinism requirement
+ *
+ * {@link BackingHost.requiresReplicableDerivations} is an **opt-in capability
+ * declaration** consumed by the engine **only at create**: a host whose backing
+ * replicates across peers (the future sync-store) sets it so the create-time MV
+ * gate rejects any non-REPLICABLE **function** OR **collation** in the derivation
+ * body — a function not asserted bit-identical across platforms/app-versions (see
+ * {@link import('../schema/function.js').BaseFunctionSchema.replicable}), or a
+ * custom collation whose sort/fold governs derived bytes (comparison / ORDER BY /
+ * GROUP BY / DISTINCT / backing key) without being declared `replicable: true`.
+ * Both surfaces can diverge derived bytes across peers' platforms, exactly the
+ * hazard this class prevents; built-in functions AND built-in collations
+ * (`BINARY`/`NOCASE`/`RTRIM`) auto-qualify. The reference hosts (memory, store)
+ * leave it `undefined` ⇒ no requirement ⇒ zero behavior change, so this class is
+ * inert by default. It is **not** escapable by `pragma nondeterministic_schema` —
+ * that lifts the separate, weaker per-database determinism gate; a replicating
+ * host's bit-identity requirement cannot be locally waived without breaking
+ * convergence.
+ */
+import type { Row, SqlValue } from '../common/types.js';
+import type { QuereusError } from '../common/errors.js';
+import type { VirtualTableConnection } from './connection.js';
+import type { BTreeKeyForPrimary } from './memory/types.js';
+/**
+ * A single row-time-maintenance operation applied to an MV backing table's
+ * pending transaction state by {@link BackingHost.applyMaintenance}.
+ *
+ * - `delete-key` removes the row with this full primary key (no-op if absent).
+ * - `upsert` replaces the row sharing this row's PK, or inserts when absent.
+ *   **Value-identical suppression (normative).** When the new row is value-identical
+ *   to the connection's *effective* existing row at that key (pending state layered
+ *   over committed — never committed-only), the host MUST write nothing and report
+ *   nothing: nothing changed, so reporting no {@link BackingRowChange} is what the
+ *   effective-change contract demands, and it is the echo-prevention seam for
+ *   change-logged (synced) backings. Value identity is **byte-faithful** — per-column
+ *   `compareSqlValues` under BINARY (`util/comparison.ts` `rowsValueIdentical`):
+ *   numeric-storage-class tolerant (bigint `5n` ≡ number `5`) but byte-exact for
+ *   text. It is deliberately NOT the column collation: a collation-equal /
+ *   byte-different upsert (e.g. a case-only rewrite under a NOCASE column) is a real
+ *   change that must replace the stored bytes and report an `update` (the column
+ *   collation still governs which existing row the upsert *replaces* — key identity —
+ *   just not the skip). This is intentionally narrower than `replace-all`'s wholesale
+ *   diff below, whose identical-row skip is collation-aware per its own pinned
+ *   semantics (`test/vtab/maintenance-replace-all.spec.ts`).
+ * - `delete-by-prefix` removes **every** row whose leading PK columns equal
+ *   `keyPrefix` (no-op when nothing matches). It replaces a whole prefix-keyed
+ *   *slice* — one base row mapping to many backing rows sharing the base-PK
+ *   prefix. The backing storage is ordered by the composite PK with the base-PK
+ *   columns leading, so the slice is a contiguous range the scan seeks to and
+ *   early-terminates on. The lateral-TVF fan-out arm (`'prefix-delete'`) was its
+ *   original consumer but now applies a keyed diff over the same prefix range
+ *   (`scanEffective` + point ops), so the engine currently produces no
+ *   `delete-by-prefix`; it stays in the contract — implemented by both hosts,
+ *   pinned by `test/vtab/maintenance-prefix-delete.spec.ts` — for future
+ *   prefix-slice consumers (e.g. a fanning-keyed-join arm).
+ * - `replace-all` replaces the backing's **entire** pending-effective contents with
+ *   `rows`, realized as the minimal keyed diff (by backing PK) against the current
+ *   rows: a new key absent from the old set is an `insert`, a present key whose row
+ *   differs is an `update`, an identical row at the same key is skipped (no storage
+ *   churn, no emitted change), and an old key absent from the new set is a `delete`.
+ *   It is the wholesale, **transactional** backing replacement the full-rebuild MV
+ *   arm needs — applied to the *pending* transaction state so it commits/rolls-back
+ *   in lockstep with the source write, unlike the
+ *   {@link BackingHost.replaceContents} CREATE/REFRESH primitive.
+ *
+ * The point ops (`delete-key`/`upsert`) keep a one-source-row → one-backing-row
+ * delta (covering-index, aggregate-residual); `delete-by-prefix` is the
+ * one-source-row → N-backing-rows primitive; `replace-all` is the whole-table
+ * primitive — see `docs/materialized-views.md` § Row-time refresh and
+ * `docs/incremental-maintenance.md` § prefix-delete / § replace-all.
+ */
+export type MaintenanceOp = {
+    kind: 'delete-key';
+    key: BTreeKeyForPrimary;
+} | {
+    kind: 'upsert';
+    row: Row;
+} | {
+    kind: 'delete-by-prefix';
+    keyPrefix: SqlValue[];
+} | {
+    kind: 'replace-all';
+    rows: Row[];
+};
+/**
+ * The *effective* per-row change {@link BackingHost.applyMaintenance} applied
+ * to a backing table's pending state — the same `{ op, oldRow?, newRow? }`
+ * shape the row-time maintenance hook already consumes for a source write. The
+ * host knows each op's before-image (it looks it up to apply the op), so it
+ * reports the realized change without the caller re-reading the backing table.
+ *
+ * This is what drives the **MV-over-MV cascade**: a backing write to MV `B` is itself
+ * a row-write that every MV reading `B`'s backing must see, so the cascade routes each
+ * `BackingRowChange` back through `maintainRowTime(B.backingBase, change)`. It is the
+ * same shape as the inbound source change by design (unify, don't duplicate) — see
+ * `core/database-materialized-views.ts` § cascade. The external-change ingestion
+ * seam (`Database.ingestExternalRowChanges`) consumes the same shape.
+ *
+ * A discriminated union over `op`: an `insert` carries only the new image, a `delete`
+ * only the old, an `update` both. The maintenance hook narrows on `op` rather than
+ * non-null-asserting `oldRow`/`newRow`, so a mis-paired hook site fails at compile time
+ * rather than at runtime.
+ */
+export type BackingRowChange = {
+    op: 'insert';
+    oldRow?: undefined;
+    newRow: Row;
+} | {
+    op: 'delete';
+    oldRow: Row;
+    newRow?: undefined;
+} | {
+    op: 'update';
+    oldRow: Row;
+    newRow: Row;
+};
+/** Scan request for the reads-own-writes effective-state scan. */
+export interface BackingScanRequest {
+    /** Leading-PK equality values to seek to (the ordered-PK contract);
+     *  omit for a full scan in PK order. */
+    equalityPrefix?: SqlValue[];
+    descending?: boolean;
+}
+/**
+ * Privileged per-backing-table surface a backing-host module exposes.
+ * Resolved via {@link VirtualTableModule.getBackingHost}; one instance per
+ * live backing-table incarnation (a drop+recreate yields a NEW host whose
+ * ownsConnection rejects the old incarnation's connections).
+ */
+export interface BackingHost {
+    /** True when `conn` is a live connection to THIS backing-table incarnation. */
+    ownsConnection(conn: VirtualTableConnection): boolean;
+    /** Fresh connection for the current transaction. The caller registers it
+     *  with the Database so coordinated commit/rollback (savepoint-stack replay
+     *  included) covers its pending state in lockstep with the source write. */
+    connect(): VirtualTableConnection;
+    /** Privileged ordered op application into `conn`'s pending transaction
+     *  state: bypasses user-DML read-only enforcement, keeps secondary-index /
+     *  change-tracking bookkeeping, and returns the EFFECTIVE per-row changes
+     *  realized (the cascade contract — no-op ops yield nothing: a value-identical
+     *  `upsert` writes nothing and reports nothing, see {@link MaintenanceOp};
+     *  `replace-all` yields the minimal keyed diff). Later reads on `conn`
+     *  (scanEffective, point lookups) must observe the applied ops
+     *  (reads-own-writes). Declared secondary UNIQUE constraints are enforced
+     *  post-batch against the final effective contents, throwing the
+     *  maintained-table-attributed CONSTRAINT error on a collision (see
+     *  § Constraint validation above). */
+    applyMaintenance(conn: VirtualTableConnection, ops: readonly MaintenanceOp[]): Promise<BackingRowChange[]>;
+    /** Atomically replace the COMMITTED contents with `rows` (create-fill /
+     *  refresh). Throws `onDuplicateKey()` (or a generic CONSTRAINT) on a
+     *  duplicate PK among `rows`. Concurrent readers see pre- or post-swap
+     *  state, never partial. */
+    replaceContents(rows: readonly Row[], onDuplicateKey?: () => QuereusError): Promise<void>;
+    /** Reads-own-writes scan over `conn`'s effective state (pending transaction
+     *  state layered over committed), in PK order, honoring `equalityPrefix`
+     *  as a seek + early-terminate prefix range. */
+    scanEffective(conn: VirtualTableConnection, req: BackingScanRequest): AsyncIterable<Row>;
+    /** When true, the engine validates at create that every function AND every
+     *  collation in a materialized-view / derivation body hosted here is REPLICABLE
+     *  (declared bit-identical across peers/platforms/app-versions — builtin
+     *  functions and builtin collations `BINARY`/`NOCASE`/`RTRIM` auto-qualify). A
+     *  host whose backing replicates (the sync-store) demands it so a
+     *  platform-dependent UDF or custom collation cannot diverge peers. The collation
+     *  check covers both the body's fold/order/key sites and the backing key's
+     *  declared collations. Absent/false ⇒ no requirement (memory, store) ⇒ zero
+     *  behavior change. NOT escapable by `pragma nondeterministic_schema` — that
+     *  lifts the per-database determinism gate, a separate and weaker concern; a
+     *  replicating host's bit-identity requirement cannot be locally waived without
+     *  breaking convergence.
+     *
+     *  **Eager-resolution invariant (NORMATIVE).** A host that declares this flag
+     *  MUST resolve via {@link VirtualTableModule.getBackingHost} at
+     *  maintenance-plan-build time — i.e. eagerly, BEFORE any
+     *  {@link VirtualTableModule.ensureBackingForAttach}. The replicable gate runs
+     *  at MV registration (`registerMaterializedView`), which on the
+     *  `alter table … set maintained` attach path fires BEFORE the late-backing seam
+     *  (the attach core resolves the host leniently via `tryResolveBackingHost` there
+     *  and skips the gate when no host resolves — sound ONLY because a demanding host
+     *  resolves eagerly). A host MAY materialize its physical/durable store late, but
+     *  its host *capability surface* — the object carrying this flag — must resolve
+     *  eagerly. Violating this (a host that both defers `getBackingHost` to
+     *  `ensureBackingForAttach` AND demands replicable) would let a non-replicable
+     *  body slip the gate; the attach core's defensive guard
+     *  (`attachMaintainedDerivation` in `runtime/emit/materialized-view-helpers.ts`)
+     *  converts that into a loud INTERNAL error rather than a silent
+     *  convergence-breaking hole. */
+    readonly requiresReplicableDerivations?: boolean;
+}
+//# sourceMappingURL=backing-host.d.ts.map

package/dist/src/vtab/backing-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backing-host.d.ts","sourceRoot":"","sources":["../../../src/vtab/backing-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,MAAM,aAAa,GACtB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,kBAAkB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC;AAExC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC;AAE9C,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IAClC;4CACwC;IACxC,cAAc,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,+EAA+E;IAC/E,cAAc,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IACtD;;gFAE4E;IAC5E,OAAO,IAAI,sBAAsB,CAAC;IAClC;;;;;;;;;;0CAUsC;IACtC,gBAAgB,CAAC,IAAI,EAAE,sBAAsB,EAAE,GAAG,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC3G;;;gCAG4B;IAC5B,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F;;oDAEgD;IAChD,aAAa,CAAC,IAAI,EAAE,sBAAsB,EAAE,GAAG,EAAE,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCA4BiC;IACjC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACjD"}

package/dist/src/vtab/backing-host.js

@@ -0,0 +1,118 @@
+/**
+ * Backing-host capability: the module-neutral, privileged surface a virtual
+ * table module exposes so the engine can host a materialized view's backing
+ * table inside it. Resolved per table via
+ * {@link VirtualTableModule.getBackingHost} — presence of that method is the
+ * capability (mirrors `getMappingAdvertisements`). The memory module is the
+ * default and reference implementation (`vtab/memory/module.ts`).
+ *
+ * ## Cost contract
+ *
+ * A backing host MUST provide PK-ordered storage with O(log n) keyed
+ * upsert / delete / point-lookup AND an ordered prefix-range scan (seek to a
+ * leading-PK equality prefix, walk in PK order, early-terminate when the
+ * prefix stops matching). This is what keeps every bounded-delta maintenance
+ * arm (`delete-by-prefix` included) and the covering-UNIQUE prefix lookup
+ * module-agnostic. A module that cannot provide the ordered prefix scan must
+ * NOT advertise the capability — the engine does not gate per maintenance arm.
+ *
+ * ## Effective-change reporting
+ *
+ * Reporting the EFFECTIVE per-row changes from {@link BackingHost.applyMaintenance}
+ * is part of the contract, not an optimization: the MV-over-MV cascade routes
+ * each returned {@link BackingRowChange} back through `maintainRowTime`, so
+ * over- or under-reporting corrupts consumer MVs. Fidelity cuts both ways: an op
+ * that changes nothing — a `delete` of an absent key, a **value-identical
+ * `upsert`** (see {@link MaintenanceOp}) — reports nothing, so a no-op maintenance
+ * write fires no cascade and, for a change-logged (synced) backing, produces no
+ * change-log entry (no echo).
+ *
+ * ## Transactionality
+ *
+ * `applyMaintenance` writes the connection's PENDING transaction state;
+ * commit/rollback ride the registered {@link VirtualTableConnection}'s
+ * `begin/commit/rollback/savepoint` surface (already generic), so the backing
+ * delta commits/rolls-back in lockstep with the source write under the
+ * Database's coordinated commit.
+ *
+ * ## Read-only to user DML — engine-owned
+ *
+ * A maintained table's rows are derived; nothing but the privileged surface may
+ * write them. This is enforced by the **engine**, not owed by the host module:
+ * the planner rewrites user DML naming a maintained table to **write-through**
+ * against the body's base source (the three DML builders' view-mutation dispatch
+ * + the resolved-schema backstop), and the runtime DML executor carries a
+ * READONLY backstop that rejects any mutation plan whose target still carries a
+ * derivation (`runtime/emit/dml-executor.ts` `assertNotMaintainedTableTarget`) —
+ * the second net catching a plan-time mis-dispatch before it can silently
+ * diverge the derived contents. The privileged surface (`applyMaintenance` /
+ * `replaceContents` and the reconcile / rehydrate-refill paths) bypasses both by
+ * construction: it never routes through the DML executor. A host module
+ * therefore implements no user-DML permission check of its own; direct
+ * programmatic `update()` calls on the backing by an embedder are the same trust
+ * level as holding this privileged surface and are out of engine scope.
+ *
+ * ## Constraint validation — split by shape
+ *
+ * Declared CHECK and child-side FK constraints on a maintained table are
+ * per-ROW properties and are validated by the **engine** at the maintenance
+ * boundary: the attach core's bulk scan over the reconciled contents
+ * (create-fill / attach — `validateDeclaredConstraintsOverContents` in
+ * `runtime/emit/materialized-view-helpers.ts`) and the per-row derived-row
+ * validator over each maintenance delta (`core/derived-row-validator.ts`,
+ * applied by the maintenance manager before the cascade). A host module
+ * implements none of that itself.
+ *
+ * Declared secondary (non-PK) UNIQUE constraints are COLLISION-shaped — a
+ * property of a pair of rows under the host's own key/collation machinery —
+ * and are enforced by the **host**, exactly where its DML UNIQUE enforcement
+ * already lives: after applying an `applyMaintenance` batch, the host checks
+ * each written (insert/update) image against the batch's final effective
+ * contents for a different-PK row matching the constraint (NULLs distinct,
+ * partial predicates honored, per-column collations, conflict action forced to
+ * ABORT — a derivation write carries no user OR clause and must never evict),
+ * throwing the maintained-table-attributed CONSTRAINT error
+ * (`maintainedTableUniqueViolationError`). Post-batch is load-bearing: a
+ * `replace-all` diff applies upserts before deletes, so a per-op check would
+ * false-positive when the derived set moves a unique value between primary
+ * keys. Checking only written images is complete because pre-existing contents
+ * already satisfied the constraint (DML / ADD CONSTRAINT enforced it), so any
+ * colliding pair includes a written image. See the memory host's
+ * `enforceSecondaryUniqueOnMaintenance` (reference) and the store host's
+ * `StoreTable.enforceSecondaryUniqueForMaintenance`. `replaceContents` remains
+ * validation-free (PK identity aside): create/import (`materializeView`) carries
+ * MV-sugar backings, which declare no constraints, and the refresh path
+ * (`rebuildBacking`) only calls `replaceContents` when the maintained table
+ * declares no applicable CHECK/FK — a constraint-bearing refresh instead routes
+ * through `applyMaintenance('replace-all')` + the engine's bulk
+ * `validateDeclaredConstraintsOverContents` scan (the stale-refresh
+ * re-validation path), so `replaceContents` never has constraints to validate.
+ *
+ * ## Concurrency
+ *
+ * The engine adds no latching around the privileged surface: each host owns
+ * its own concurrency discipline under the {@link VtabConcurrencyMode} its
+ * module declares (the memory host's pending layer is private to the
+ * connection and mutated synchronously, so it needs none).
+ *
+ * ## Replicable-determinism requirement
+ *
+ * {@link BackingHost.requiresReplicableDerivations} is an **opt-in capability
+ * declaration** consumed by the engine **only at create**: a host whose backing
+ * replicates across peers (the future sync-store) sets it so the create-time MV
+ * gate rejects any non-REPLICABLE **function** OR **collation** in the derivation
+ * body — a function not asserted bit-identical across platforms/app-versions (see
+ * {@link import('../schema/function.js').BaseFunctionSchema.replicable}), or a
+ * custom collation whose sort/fold governs derived bytes (comparison / ORDER BY /
+ * GROUP BY / DISTINCT / backing key) without being declared `replicable: true`.
+ * Both surfaces can diverge derived bytes across peers' platforms, exactly the
+ * hazard this class prevents; built-in functions AND built-in collations
+ * (`BINARY`/`NOCASE`/`RTRIM`) auto-qualify. The reference hosts (memory, store)
+ * leave it `undefined` ⇒ no requirement ⇒ zero behavior change, so this class is
+ * inert by default. It is **not** escapable by `pragma nondeterministic_schema` —
+ * that lifts the separate, weaker per-database determinism gate; a replicating
+ * host's bit-identity requirement cannot be locally waived without breaking
+ * convergence.
+ */
+export {};
+//# sourceMappingURL=backing-host.js.map

package/dist/src/vtab/backing-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backing-host.js","sourceRoot":"","sources":["../../../src/vtab/backing-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG"}

package/dist/src/vtab/best-access-plan.d.ts

@@ -133,6 +133,27 @@ export interface BestAccessPlanResult {
         direction: 'asc' | 'desc';
         strict: boolean;
     };
+    /**
+     * The module honours each index column's declared COLLATION when filtering and
+     * positioning a NON-equality (range / BETWEEN / prefix-range / OR_RANGE) index
+     * seek — i.e. it compares range bounds and early-terminates the walk under the
+     * index collation, not a fixed BINARY comparator.
+     *
+     * Default/absent ⇒ the access-path collation-cover analysis
+     * (`classifyConstraintCover` in `rule-select-access-path.ts`) conservatively
+     * DECLINES a non-BINARY range seek (predicate collation = index collation but not
+     * BINARY) and falls back to a scan + residual, because a BINARY bound filter over
+     * a non-BINARY-ordered window would under-fetch case/space variants.
+     *
+     * When true, that range seek is permitted whenever the predicate's effective
+     * collation equals the index collation (mirroring the equality MATCH arm). Only
+     * modules whose runtime actually threads the index collation into the bound
+     * compare may set this — the in-memory vtab does (`scan-layer.ts` /
+     * `plan-filter.ts`), and so does the store module (its post-fetch row filter
+     * `StoreTable.compareValues` compares every pushed bound under the column's
+     * declared collation via `compareSqlValues`).
+     */
+    honorsCollatedRangeBounds?: boolean;
     /**
      * The access path supports O(log N) seek to the kth row in monotonic
      * order — i.e., LIMIT n OFFSET k can be pushed into the scan instead

package/dist/src/vtab/best-access-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"best-access-plan.d.ts","sourceRoot":"","sources":["../../../src/vtab/best-access-plan.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,IAAI,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhJ;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,qDAAqD;IACrD,YAAY,EAAE,OAAO,CAAC;IACtB,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,IAAI,GAAG,GAAG,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,CAAC;IAC5C,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,IAAI,GAAG,GAAG,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,EAAE,EAAE,YAAY,CAAC;IACjB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;IAChB,oDAAoD;IACpD,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,oDAAoD;IACpD,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,oCAAoC;IACpC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,wDAAwD;IACxD,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,kFAAkF;IAClF,cAAc,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC,kEAAkE;IAClE,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;IACvC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;QAC1B,MAAM,EAAE,OAAO,CAAC;KAChB,CAAC;IAEF;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,MAAM,CAAqC;IAEnD;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,iBAAiB;IAOzD;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,iBAAiB;IAQ/E;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,iBAAiB;IAOnF;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK3B;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAKvC;;OAEG;IACH,iBAAiB,CAAC,cAAc,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAK3D;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI;IAKpD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAK9B;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKzC;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKrC;;OAEG;IACH,cAAc,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAK1D;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,IAAI;IAKtD;;OAEG;IACH,KAAK,IAAI,oBAAoB;CAW7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,oBAAoB,GAC1B,IAAI,CA0FN"}
+{"version":3,"file":"best-access-plan.d.ts","sourceRoot":"","sources":["../../../src/vtab/best-access-plan.ts"],"names":[],"mappings":"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"}

package/dist/src/vtab/best-access-plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"best-access-plan.js","sourceRoot":"","sources":["../../../src/vtab/best-access-plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"best-access-plan.js","sourceRoot":"","sources":["../../../src/vtab/best-access-plan.ts"],"names":[],"mappings":"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"}

package/dist/src/vtab/capabilities.d.ts

@@ -4,15 +4,15 @@ import type { SqlValue, Row, CompareFn } from '../common/types.js';
  * Used for runtime capability discovery and isolation layer decisions.
  */
 export interface ModuleCapabilities {
-    /** Module provides transaction isolation (read-your-own-writes, snapshot reads) */
+    /** Advisory: module provides transaction isolation (read-your-own-writes, snapshot reads). Not engine-consulted. */
     isolation?: boolean;
-    /** Module supports savepoints within transactions */
+    /** Advisory: module supports savepoints within transactions. Not engine-consulted. */
     savepoints?: boolean;
-    /** Module persists data across restarts */
+    /** Advisory: module persists data across restarts. Not engine-consulted. */
     persistent?: boolean;
-    /** Module supports secondary indexes */
+    /** Advisory: module supports secondary indexes. Not engine-consulted. */
     secondaryIndexes?: boolean;
-    /** Module supports range scans (not just point lookups) */
+    /** Advisory: module supports range scans (not just point lookups). Not engine-consulted. */
     rangeScans?: boolean;
     /**
      * Module owns ADD-COLUMN NOT-NULL-backfill semantics and opts out of the

package/dist/src/vtab/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/vtab/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,qDAAqD;IACrD,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;;;;;;;OAiBG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,kCAAkC,CAAC,EAAE,OAAO,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,EAAE,CAAC;IAExC;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAExD;;;;;;OAMG;IACH,kBAAkB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAS,CAAC;IAEhE;;;OAGG;IACH,oBAAoB,IAAI,MAAM,EAAE,CAAC;CACjC"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/vtab/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAUlC,oHAAoH;IACpH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,sFAAsF;IACtF,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;;;;;;;OAiBG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,kCAAkC,CAAC,EAAE,OAAO,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,EAAE,CAAC;IAExC;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAExD;;;;;;OAMG;IACH,kBAAkB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAS,CAAC;IAEhE;;;OAGG;IACH,oBAAoB,IAAI,MAAM,EAAE,CAAC;CACjC"}