@lunora/sql-store 1.0.0-alpha.9 → 1.0.0-alpha.91

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -83,7 +83,8 @@ seam from the root); consumers import everything from the root `@lunora/sql-stor
 - Migration runners (each takes `(exec, schema, dialect)`, or `(exec, dialect)`
   for CDC): `runSqlGlobalTableMigrations`, `runSqlAggregateMigrations`,
   `runSqlRankMigrations`, `runSqlSearchMigrations`, `runSqlCdcMigration`.
-- CDC log helpers: `readSqlCdcChanges`, `trimSqlCdcChanges`.
+- CDC log helpers: `readSqlCdcChanges`, `readSqlCdcChangedTables`,
+  `readSqlCdcFloor`, `sweepSqlCdcRetention`.
 - Value codec building blocks a dialect reuses for `encode`/`decode`:
   `sqliteEncode`, `sqliteDecode`, `decodeBigint`, `tryJsonParse`,
   `effectiveColumnKind`.

package/dist/dialect.d.mts

@@ -5,20 +5,45 @@ interface SqlRunResult {
   rowsAffected: number;
 }
 /**
-* The async SQL surface the store core consumes. Satisfied by a
-* `D1Session`/`D1Client` (D1), a `node:sqlite` adapter (tests), or a
-* Hyperdrive-backed `postgres`/`pg`/`mysql2` driver (PlanetScale).
-*
-* `all` runs a row-returning statement (incl. `... RETURNING ...`); `run` runs a
-* write and reports `rowsAffected` — the matched-rows count that drives the
-* MySQL optimistic-concurrency guard (which has no `RETURNING`).
-*
-* Note: companion writes (aggregate/rank/FTS/CDC) run as separate sequential
-* statements after the row write on every engine, so they share D1's
-* at-least-once caveat — there is no cross-statement transaction here.
-*/
+ * The async SQL surface the store core consumes. Satisfied by a
+ * `D1Session`/`D1Client` (D1), a `node:sqlite` adapter (tests), or a
+ * Hyperdrive-backed `postgres`/`pg`/`mysql2` driver (PlanetScale).
+ *
+ * `all` runs a row-returning statement (incl. `... RETURNING ...`); `run` runs a
+ * write and reports `rowsAffected` — the matched-rows count that drives the
+ * MySQL optimistic-concurrency guard (which has no `RETURNING`).
+ *
+ * Note: companion writes (aggregate/rank/FTS/CDC) run as separate sequential
+ * statements after the row write on every engine, so they share D1's
+ * at-least-once caveat — there is no cross-statement transaction here.
+ */
 interface SqlExec {
   all: (sql: string, params: ReadonlyArray<unknown>) => Promise<Record<string, unknown>[]>;
+  /**
+   * Optional: run several write statements as one round trip instead of
+   * `run()` called once per statement in sequence. Statements MUST be
+   * mutually independent — an implementation MAY reorder or parallelize
+   * across elements, so callers must never rely on array order between
+   * elements (e.g. a purge-then-insert pair belongs in separate sequential
+   * `queryRun`/`run` calls, not one `batch`).
+   *
+   * Absent, the store core falls back to its historical sequential `run()`
+   * loop, so an exec that doesn't implement this keeps working unchanged.
+   *
+   * D1's `client.batch` executes the whole array atomically (all-or-nothing)
+   * in one request, preserving array order — an actual atomicity improvement
+   * over the sequential fallback, not just a round-trip one. The Hyperdrive
+   * `postgres`/`pg` adapters instead dispatch every statement concurrently
+   * (`Promise.all`) over the same connection/pool rather than awaiting each
+   * in turn — still "at-least-once, non-atomic" like the fallback, but no
+   * longer serialized one full RTT at a time, and with no ordering between
+   * elements. Safe only for statements whose effects don't depend on each
+   * other (distinct-keyed rows), which is what every current caller batches.
+   */
+  batch?: (statements: ReadonlyArray<{
+    params: ReadonlyArray<unknown>;
+    sql: string;
+  }>) => Promise<void>;
   run: (sql: string, params: ReadonlyArray<unknown>) => Promise<SqlRunResult>;
 }
 /** Everything engine-specific the store core needs. One value per engine; `sqliteDialect` (in `@lunora/d1`) is the reference, Postgres/MySQL live in `@lunora/hyperdrive/global`. */
@@ -26,19 +51,19 @@ interface SqlDialect {
   /** Affected-rows extractor for the OCC fallback when `supportsReturning` is false (MySQL). */
   affectedRows?: (result: SqlRunResult) => number;
   /**
-  * Storage SQL column type for a validator `kind`. SQLite affinity
-  * (`TEXT`/`INTEGER`/`REAL`/`BLOB`); Postgres `TEXT`/`DOUBLE PRECISION`/
-  * `BOOLEAN`/`JSONB`/`BYTEA`; MySQL `VARCHAR(255)`/`TEXT`/`DOUBLE`/
-  * `TINYINT(1)`/`JSON`/`LONGBLOB`.
-  */
+   * Storage SQL column type for a validator `kind`. SQLite affinity
+   * (`TEXT`/`INTEGER`/`REAL`/`BLOB`); Postgres `TEXT`/`DOUBLE PRECISION`/
+   * `BOOLEAN`/`JSONB`/`BYTEA`; MySQL `VARCHAR(255)`/`TEXT`/`DOUBLE`/
+   * `TINYINT(1)`/`JSON`/`LONGBLOB`.
+   */
   columnType: (kind: string | undefined) => string;
   /**
-  * Engine SQL types for the **internal companion tables** (aggregate / rank /
-  * CDC), which are built from raw SQL types, not validator kinds. SQLite uses
-  * `TEXT`/`REAL`/`INTEGER`/`BLOB` and `INTEGER PRIMARY KEY AUTOINCREMENT`;
-  * Postgres `TEXT`/`DOUBLE PRECISION`/`INTEGER`/`BYTEA` + `BIGSERIAL`; MySQL
-  * needs a bounded `VARCHAR` key, `DOUBLE`, `LONGBLOB`, `AUTO_INCREMENT`.
-  */
+   * Engine SQL types for the **internal companion tables** (aggregate / rank /
+   * CDC), which are built from raw SQL types, not validator kinds. SQLite uses
+   * `TEXT`/`REAL`/`INTEGER`/`BLOB` and `INTEGER PRIMARY KEY AUTOINCREMENT`;
+   * Postgres `TEXT`/`DOUBLE PRECISION`/`INTEGER`/`BYTEA` + `BIGSERIAL`; MySQL
+   * needs a bounded `VARCHAR` key, `DOUBLE`, `LONGBLOB`, `AUTO_INCREMENT`.
+   */
   companionTypes: {
     autoincrementPrimaryKey: string;
     integer: string;
@@ -46,9 +71,19 @@ interface SqlDialect {
     real: string;
     text: string;
   };
-  /** Map a stored value back to its JS form, by effective validator `kind` (inverse of `encode`). */
+  /**
+   * Map a stored value back to its JS form, by effective validator `kind`
+   * (inverse of `encode`). NOTE: currently **unused** by the store core, which
+   * hard-codes `sqliteDecode` in `decodeGlobalRow` on every engine. Kept on the
+   * seam for a future engine-native codec; an override here does not run today.
+   */
   decode: (value: unknown, kind: string | undefined) => unknown;
-  /** Map a JS value to its bound storage form (boolean→1/0, bigint→string, object→JSON on SQLite; mostly native on PG). */
+  /**
+   * Map a JS value to its bound storage form (boolean→1/0, bigint→string,
+   * object→JSON on SQLite). NOTE: currently **unused** by the store core, which
+   * hard-codes `sqliteEncode` as `serializeColumnValue` on every engine. Kept on
+   * the seam for a future engine-native codec; an override here does not run today.
+   */
   encode: (value: unknown) => unknown;
   /** The framework columns every global table carries — the `id` primary key and `_creationTime` — as `{ name, type }` so the DDL builder can quote each name through the engine's dialect. */
   frameworkColumns: () => ReadonlyArray<{
@@ -56,27 +91,90 @@ interface SqlDialect {
     type: string;
   }>;
   /**
-  * Optional: the key-prefix length an indexed column of this `kind` needs.
-  * MySQL/InnoDB can't index a `TEXT`/`LONGTEXT`/`BLOB` column without a prefix
-  * (the store appends `(&lt;n>)` to the column reference); SQLite/Postgres index
-  * text columns directly and omit this hook (or return `undefined`). `kind` is
-  * the column's effective validator kind.
-  */
+   * Optional: the key-prefix length an indexed column of this `kind` needs.
+   * MySQL/InnoDB can't index a `TEXT`/`LONGTEXT`/`BLOB` column without a prefix
+   * (the store appends `(<n>)` to the column reference); SQLite/Postgres index
+   * text columns directly and omit this hook (or return `undefined`). `kind` is
+   * the column's effective validator kind.
+   */
   indexKeyPrefix?: (kind: string | undefined) => number | undefined;
   /** True when an `error` thrown by a write is a UNIQUE-constraint breach (mapped to a 409 ConflictError). */
   isUniqueViolation: (error: unknown) => boolean;
+  /**
+   * Most columns one table may carry on this engine, framework columns
+   * included. Omit it and the DDL builder does not check — the right answer
+   * for an engine whose ceiling is high enough that no real schema reaches it.
+   *
+   * Declared because the ceilings differ by more than an order of magnitude:
+   * D1 runs Workerd's SQLite build, which caps a table at 100 columns, where
+   * Postgres allows 1,600 and MySQL 4,096. A fixed number here would either
+   * miss the D1 failure or reject schemas the other two engines run happily.
+   */
+  maxTableColumns?: number;
   /** A short engine tag for diagnostics/branching (`"sqlite" | "postgres" | "mysql"`). The store core selects drizzle's matching dialect for rendering off this. */
   readonly name: "mysql" | "postgres" | "sqlite";
+  /**
+   * Optional: the engine's own full-text index, opted into per search index
+   * with `.searchIndex({ strategy: "native" })`.
+   *
+   * Only Postgres supplies one today (`tsvector` + GIN + `to_tsquery`). It
+   * scales sublinearly where the portable inverted companion aggregates every
+   * matching token row, but it ranks with the engine's formula rather than the
+   * shared scorer — which is why it is opt-in and why the parity suite asserts
+   * matching, not order, for indexes that use it.
+   *
+   * Recall still matches the portable path: the stored form is built from the
+   * tokens Lunora's analyzer already produced, under a configuration that adds
+   * no stemming or stopwords of the engine's own.
+   *
+   * Every member returns a *statement*, not a fragment, so no engine grammar
+   * reaches the store core: Postgres matches with `@@` against a `tsvector`
+   * column while MySQL would use `MATCH … AGAINST` against a text column, and
+   * both fit here without the caller knowing which.
+   */
+  nativeTextSearch?: {
+    /** DDL for the companion table holding the engine's indexed form, keyed by document id. */
+    createCompanion: (companion: string, keyType: string) => SQL;
+    /** DDL for the indexes that make the match fast. */
+    createIndexes: (companion: string) => SQL[];
+    /** Replace one document's row, given its already-analyzed token stream. */
+    indexDocument: (companion: string, id: string, analyzed: string) => SQL;
+    /** The `WHERE` predicate matching a query's analyzed terms, final term as a prefix. */
+    matches: (companion: string, terms: ReadonlyArray<string>) => SQL;
+    /** The `ORDER BY` expression, best first. */
+    rank: (companion: string, terms: ReadonlyArray<string>) => SQL;
+  };
+  /**
+   * True when the engine ships SQLite's FTS5 module, which decides whether a
+   * search index is stored as an FTS5 shadow or as the portable inverted
+   * companion.
+   *
+   * A static property of the engine, so it is declared rather than probed:
+   * the previous `CREATE VIRTUAL TABLE` capability probe spent a round trip
+   * (and an error in the database's log) on every fresh connection to
+   * rediscover something the dialect already knows. Tests that want the
+   * portable layout override this instead of intercepting SQL strings.
+   */
+  supportsFts5: boolean;
   /** True when the engine supports `UPDATE/DELETE ... RETURNING` (SQLite/PG yes, MySQL no → use `affectedRows`). */
   supportsReturning: boolean;
   /**
-  * The catalog probe for whether a physical `table` exists — backs the opt-in
-  * companion-table (`__agg_`/`__rank_`) existence checks. Returns a drizzle
-  * {@link SQL} (a non-empty result ⇒ the table exists) so it renders through
-  * the same per-engine path as every other statement, never a hand-built
-  * placeholder string. SQLite reads `sqlite_master`; Postgres/MySQL read
-  * `information_schema.tables`.
-  */
+   * The catalog probe for whether a physical `table` exists — backs the opt-in
+   * companion-table (`__agg_`/`__rank_`) existence checks. Returns a drizzle
+   * {@link SQL} (a non-empty result ⇒ the table exists) so it renders through
+   * the same per-engine path as every other statement, never a hand-built
+   * placeholder string. SQLite reads `sqlite_master`; Postgres/MySQL read
+   * `information_schema.tables`.
+   */
   tableExists: (table: string) => SQL;
+  /**
+   * Optional: btree operator class appended to an indexed text column so a
+   * `LIKE 'prefix%'` scan can use the index whatever the database collation.
+   * Postgres needs `text_pattern_ops` (a default `text_ops` btree built under
+   * e.g. `en_US.UTF-8` is useless to `LIKE`); SQLite and MySQL index prefix
+   * matches off the plain index and omit this. Only the search companion's
+   * token index reads it.
+   */
+  textPatternOperatorClass?: string;
 }
 export { SqlDialect, SqlExec, SqlRunResult };

package/dist/dialect.d.ts

@@ -5,20 +5,45 @@ interface SqlRunResult {
   rowsAffected: number;
 }
 /**
-* The async SQL surface the store core consumes. Satisfied by a
-* `D1Session`/`D1Client` (D1), a `node:sqlite` adapter (tests), or a
-* Hyperdrive-backed `postgres`/`pg`/`mysql2` driver (PlanetScale).
-*
-* `all` runs a row-returning statement (incl. `... RETURNING ...`); `run` runs a
-* write and reports `rowsAffected` — the matched-rows count that drives the
-* MySQL optimistic-concurrency guard (which has no `RETURNING`).
-*
-* Note: companion writes (aggregate/rank/FTS/CDC) run as separate sequential
-* statements after the row write on every engine, so they share D1's
-* at-least-once caveat — there is no cross-statement transaction here.
-*/
+ * The async SQL surface the store core consumes. Satisfied by a
+ * `D1Session`/`D1Client` (D1), a `node:sqlite` adapter (tests), or a
+ * Hyperdrive-backed `postgres`/`pg`/`mysql2` driver (PlanetScale).
+ *
+ * `all` runs a row-returning statement (incl. `... RETURNING ...`); `run` runs a
+ * write and reports `rowsAffected` — the matched-rows count that drives the
+ * MySQL optimistic-concurrency guard (which has no `RETURNING`).
+ *
+ * Note: companion writes (aggregate/rank/FTS/CDC) run as separate sequential
+ * statements after the row write on every engine, so they share D1's
+ * at-least-once caveat — there is no cross-statement transaction here.
+ */
 interface SqlExec {
   all: (sql: string, params: ReadonlyArray<unknown>) => Promise<Record<string, unknown>[]>;
+  /**
+   * Optional: run several write statements as one round trip instead of
+   * `run()` called once per statement in sequence. Statements MUST be
+   * mutually independent — an implementation MAY reorder or parallelize
+   * across elements, so callers must never rely on array order between
+   * elements (e.g. a purge-then-insert pair belongs in separate sequential
+   * `queryRun`/`run` calls, not one `batch`).
+   *
+   * Absent, the store core falls back to its historical sequential `run()`
+   * loop, so an exec that doesn't implement this keeps working unchanged.
+   *
+   * D1's `client.batch` executes the whole array atomically (all-or-nothing)
+   * in one request, preserving array order — an actual atomicity improvement
+   * over the sequential fallback, not just a round-trip one. The Hyperdrive
+   * `postgres`/`pg` adapters instead dispatch every statement concurrently
+   * (`Promise.all`) over the same connection/pool rather than awaiting each
+   * in turn — still "at-least-once, non-atomic" like the fallback, but no
+   * longer serialized one full RTT at a time, and with no ordering between
+   * elements. Safe only for statements whose effects don't depend on each
+   * other (distinct-keyed rows), which is what every current caller batches.
+   */
+  batch?: (statements: ReadonlyArray<{
+    params: ReadonlyArray<unknown>;
+    sql: string;
+  }>) => Promise<void>;
   run: (sql: string, params: ReadonlyArray<unknown>) => Promise<SqlRunResult>;
 }
 /** Everything engine-specific the store core needs. One value per engine; `sqliteDialect` (in `@lunora/d1`) is the reference, Postgres/MySQL live in `@lunora/hyperdrive/global`. */
@@ -26,19 +51,19 @@ interface SqlDialect {
   /** Affected-rows extractor for the OCC fallback when `supportsReturning` is false (MySQL). */
   affectedRows?: (result: SqlRunResult) => number;
   /**
-  * Storage SQL column type for a validator `kind`. SQLite affinity
-  * (`TEXT`/`INTEGER`/`REAL`/`BLOB`); Postgres `TEXT`/`DOUBLE PRECISION`/
-  * `BOOLEAN`/`JSONB`/`BYTEA`; MySQL `VARCHAR(255)`/`TEXT`/`DOUBLE`/
-  * `TINYINT(1)`/`JSON`/`LONGBLOB`.
-  */
+   * Storage SQL column type for a validator `kind`. SQLite affinity
+   * (`TEXT`/`INTEGER`/`REAL`/`BLOB`); Postgres `TEXT`/`DOUBLE PRECISION`/
+   * `BOOLEAN`/`JSONB`/`BYTEA`; MySQL `VARCHAR(255)`/`TEXT`/`DOUBLE`/
+   * `TINYINT(1)`/`JSON`/`LONGBLOB`.
+   */
   columnType: (kind: string | undefined) => string;
   /**
-  * Engine SQL types for the **internal companion tables** (aggregate / rank /
-  * CDC), which are built from raw SQL types, not validator kinds. SQLite uses
-  * `TEXT`/`REAL`/`INTEGER`/`BLOB` and `INTEGER PRIMARY KEY AUTOINCREMENT`;
-  * Postgres `TEXT`/`DOUBLE PRECISION`/`INTEGER`/`BYTEA` + `BIGSERIAL`; MySQL
-  * needs a bounded `VARCHAR` key, `DOUBLE`, `LONGBLOB`, `AUTO_INCREMENT`.
-  */
+   * Engine SQL types for the **internal companion tables** (aggregate / rank /
+   * CDC), which are built from raw SQL types, not validator kinds. SQLite uses
+   * `TEXT`/`REAL`/`INTEGER`/`BLOB` and `INTEGER PRIMARY KEY AUTOINCREMENT`;
+   * Postgres `TEXT`/`DOUBLE PRECISION`/`INTEGER`/`BYTEA` + `BIGSERIAL`; MySQL
+   * needs a bounded `VARCHAR` key, `DOUBLE`, `LONGBLOB`, `AUTO_INCREMENT`.
+   */
   companionTypes: {
     autoincrementPrimaryKey: string;
     integer: string;
@@ -46,9 +71,19 @@ interface SqlDialect {
     real: string;
     text: string;
   };
-  /** Map a stored value back to its JS form, by effective validator `kind` (inverse of `encode`). */
+  /**
+   * Map a stored value back to its JS form, by effective validator `kind`
+   * (inverse of `encode`). NOTE: currently **unused** by the store core, which
+   * hard-codes `sqliteDecode` in `decodeGlobalRow` on every engine. Kept on the
+   * seam for a future engine-native codec; an override here does not run today.
+   */
   decode: (value: unknown, kind: string | undefined) => unknown;
-  /** Map a JS value to its bound storage form (boolean→1/0, bigint→string, object→JSON on SQLite; mostly native on PG). */
+  /**
+   * Map a JS value to its bound storage form (boolean→1/0, bigint→string,
+   * object→JSON on SQLite). NOTE: currently **unused** by the store core, which
+   * hard-codes `sqliteEncode` as `serializeColumnValue` on every engine. Kept on
+   * the seam for a future engine-native codec; an override here does not run today.
+   */
   encode: (value: unknown) => unknown;
   /** The framework columns every global table carries — the `id` primary key and `_creationTime` — as `{ name, type }` so the DDL builder can quote each name through the engine's dialect. */
   frameworkColumns: () => ReadonlyArray<{
@@ -56,27 +91,90 @@ interface SqlDialect {
     type: string;
   }>;
   /**
-  * Optional: the key-prefix length an indexed column of this `kind` needs.
-  * MySQL/InnoDB can't index a `TEXT`/`LONGTEXT`/`BLOB` column without a prefix
-  * (the store appends `(&lt;n>)` to the column reference); SQLite/Postgres index
-  * text columns directly and omit this hook (or return `undefined`). `kind` is
-  * the column's effective validator kind.
-  */
+   * Optional: the key-prefix length an indexed column of this `kind` needs.
+   * MySQL/InnoDB can't index a `TEXT`/`LONGTEXT`/`BLOB` column without a prefix
+   * (the store appends `(<n>)` to the column reference); SQLite/Postgres index
+   * text columns directly and omit this hook (or return `undefined`). `kind` is
+   * the column's effective validator kind.
+   */
   indexKeyPrefix?: (kind: string | undefined) => number | undefined;
   /** True when an `error` thrown by a write is a UNIQUE-constraint breach (mapped to a 409 ConflictError). */
   isUniqueViolation: (error: unknown) => boolean;
+  /**
+   * Most columns one table may carry on this engine, framework columns
+   * included. Omit it and the DDL builder does not check — the right answer
+   * for an engine whose ceiling is high enough that no real schema reaches it.
+   *
+   * Declared because the ceilings differ by more than an order of magnitude:
+   * D1 runs Workerd's SQLite build, which caps a table at 100 columns, where
+   * Postgres allows 1,600 and MySQL 4,096. A fixed number here would either
+   * miss the D1 failure or reject schemas the other two engines run happily.
+   */
+  maxTableColumns?: number;
   /** A short engine tag for diagnostics/branching (`"sqlite" | "postgres" | "mysql"`). The store core selects drizzle's matching dialect for rendering off this. */
   readonly name: "mysql" | "postgres" | "sqlite";
+  /**
+   * Optional: the engine's own full-text index, opted into per search index
+   * with `.searchIndex({ strategy: "native" })`.
+   *
+   * Only Postgres supplies one today (`tsvector` + GIN + `to_tsquery`). It
+   * scales sublinearly where the portable inverted companion aggregates every
+   * matching token row, but it ranks with the engine's formula rather than the
+   * shared scorer — which is why it is opt-in and why the parity suite asserts
+   * matching, not order, for indexes that use it.
+   *
+   * Recall still matches the portable path: the stored form is built from the
+   * tokens Lunora's analyzer already produced, under a configuration that adds
+   * no stemming or stopwords of the engine's own.
+   *
+   * Every member returns a *statement*, not a fragment, so no engine grammar
+   * reaches the store core: Postgres matches with `@@` against a `tsvector`
+   * column while MySQL would use `MATCH … AGAINST` against a text column, and
+   * both fit here without the caller knowing which.
+   */
+  nativeTextSearch?: {
+    /** DDL for the companion table holding the engine's indexed form, keyed by document id. */
+    createCompanion: (companion: string, keyType: string) => SQL;
+    /** DDL for the indexes that make the match fast. */
+    createIndexes: (companion: string) => SQL[];
+    /** Replace one document's row, given its already-analyzed token stream. */
+    indexDocument: (companion: string, id: string, analyzed: string) => SQL;
+    /** The `WHERE` predicate matching a query's analyzed terms, final term as a prefix. */
+    matches: (companion: string, terms: ReadonlyArray<string>) => SQL;
+    /** The `ORDER BY` expression, best first. */
+    rank: (companion: string, terms: ReadonlyArray<string>) => SQL;
+  };
+  /**
+   * True when the engine ships SQLite's FTS5 module, which decides whether a
+   * search index is stored as an FTS5 shadow or as the portable inverted
+   * companion.
+   *
+   * A static property of the engine, so it is declared rather than probed:
+   * the previous `CREATE VIRTUAL TABLE` capability probe spent a round trip
+   * (and an error in the database's log) on every fresh connection to
+   * rediscover something the dialect already knows. Tests that want the
+   * portable layout override this instead of intercepting SQL strings.
+   */
+  supportsFts5: boolean;
   /** True when the engine supports `UPDATE/DELETE ... RETURNING` (SQLite/PG yes, MySQL no → use `affectedRows`). */
   supportsReturning: boolean;
   /**
-  * The catalog probe for whether a physical `table` exists — backs the opt-in
-  * companion-table (`__agg_`/`__rank_`) existence checks. Returns a drizzle
-  * {@link SQL} (a non-empty result ⇒ the table exists) so it renders through
-  * the same per-engine path as every other statement, never a hand-built
-  * placeholder string. SQLite reads `sqlite_master`; Postgres/MySQL read
-  * `information_schema.tables`.
-  */
+   * The catalog probe for whether a physical `table` exists — backs the opt-in
+   * companion-table (`__agg_`/`__rank_`) existence checks. Returns a drizzle
+   * {@link SQL} (a non-empty result ⇒ the table exists) so it renders through
+   * the same per-engine path as every other statement, never a hand-built
+   * placeholder string. SQLite reads `sqlite_master`; Postgres/MySQL read
+   * `information_schema.tables`.
+   */
   tableExists: (table: string) => SQL;
+  /**
+   * Optional: btree operator class appended to an indexed text column so a
+   * `LIKE 'prefix%'` scan can use the index whatever the database collation.
+   * Postgres needs `text_pattern_ops` (a default `text_ops` btree built under
+   * e.g. `en_US.UTF-8` is useless to `LIKE`); SQLite and MySQL index prefix
+   * matches off the plain index and omit this. Only the search companion's
+   * token index reads it.
+   */
+  textPatternOperatorClass?: string;
 }
 export { SqlDialect, SqlExec, SqlRunResult };

package/dist/dialect.mjs

@@ -1 +0,0 @@
-