@syncular/server 0.37.0 → 0.39.0

package/dist/relational-rows.d.ts

@@ -48,7 +48,7 @@
  *   NOT NULL per the schema.
  */
 import { type RowColumn, type RowValue } from '@syncular/core';
-import type { CompiledSchema, CompiledTable, IndexSchema } from './schema.js';
+import type { CompiledSchema, CompiledTable, IndexSchema, ServerIndexSchema } from './schema.js';
 import type { StoredRow } from './storage.js';
 export type RelationalDialect = 'sqlite' | 'postgres';
 export declare const SYNC_PARTITION_COLUMN = "_sync_partition";
@@ -119,8 +119,8 @@ export declare function createTableDdl(table: CompiledTable, dialect: Relational
 export declare function addColumnDdl(table: CompiledTable, existingColumns: ReadonlySet<string>, dialect: RelationalDialect): string[];
 /**
  * Ownership marker for server-created projection indexes. A version bump
- * rebuilds declared indexes by dropping every index Syncular owns and
- * re-creating the declared set; this prefix is what marks an index as
+ * drops every index Syncular owns whose definition changed or was removed
+ * and creates the missing ones; this prefix is what marks an index as
  * Syncular-owned, so operator-added tuning indexes survive bumps. Portable
  * identifier validation reserves the `sync_` prefix for the server storage
  * namespace, which keeps user and operator index names out of it.
@@ -134,13 +134,32 @@ export declare const SYNC_INDEX_PREFIX = "sync_ix_";
  */
 export declare function physicalIndexName(declaredName: string): string;
 /**
- * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes. These use
- * the declared columns with a leading server partition column. Cross-table
- * index-name uniqueness is the user's schema concern, as it is client-side.
- * Server-side the physical name carries the {@link SYNC_INDEX_PREFIX}
- * ownership marker.
+ * Physical name of one server-only index. The name carries a fingerprint of
+ * the definition, so a changed definition is a different index and the bump
+ * diff needs no catalog comparison of predicates.
  */
-export declare function createIndexDdl(table: CompiledTable): string[];
+export declare function physicalServerIndexName(index: ServerIndexSchema): string;
+/**
+ * Canonical shape of one physical index, as read from the catalog and as
+ * declared: kind, then the key columns in order (`null` for an expression).
+ * Two indexes with one signature are interchangeable.
+ */
+export declare function indexSignature(columns: readonly (string | null)[], unique: boolean, partial: boolean): string;
+/**
+ * One statement that lists a table's free-standing SQLite indexes with their
+ * key columns in order (bind the table name). `origin='c'` excludes
+ * constraint-owned indexes, which only their constraint can remove. Feed the
+ * rows to {@link sqliteIndexSignatures}.
+ */
+export declare const SQLITE_TABLE_INDEXES_SQL = "SELECT il.name AS name, il.\"unique\" AS is_unique, il.partial AS is_partial, ii.name AS column_name\n  FROM pragma_index_list(?) AS il\n  JOIN pragma_index_info(il.name) AS ii\n WHERE il.origin='c'\n ORDER BY il.name, ii.seqno";
+export interface SqliteTableIndexRow {
+    readonly name: string;
+    readonly is_unique: number;
+    readonly is_partial: number;
+    readonly column_name: string | null;
+}
+/** Index name to {@link indexSignature} for the rows of one table. */
+export declare function sqliteIndexSignatures(rows: readonly SqliteTableIndexRow[]): Record<string, string>;
 /** Idempotent removal of one Syncular-owned relational projection index. */
 export declare function dropIndexDdl(indexName: string): string;
 /**
@@ -157,8 +176,12 @@ export declare function toSqlValue(column: RowColumn, value: RowValue, dialect:
  * statement, so they cannot drift.
  */
 export declare function upsertValues(table: CompiledTable, partition: string, row: StoredRow, dialect: RelationalDialect): unknown[];
-/** Upsert statement text (bind with `upsertValues`). */
-export declare function upsertSql(table: CompiledTable, dialect: RelationalDialect): string;
+/**
+ * Upsert statement text (bind with `upsertValues`). PostgreSQL takes `rows`
+ * rows in one statement, bound as consecutive `upsertValues` lists; their
+ * row ids must be distinct.
+ */
+export declare function upsertSql(table: CompiledTable, dialect: RelationalDialect, rows?: number): string;
 /**
  * SELECT one stored row. Aliased to the legacy record shape
  * (`row_id`/`server_version`/`scopes`/`payload`) so the existing
@@ -227,17 +250,19 @@ export declare function scanRowPageSql(table: CompiledTable, valueCount: number,
 export declare function commitWindowPageSql(valueCount: number, dialect: RelationalDialect): string;
 /**
  * PostgreSQL set-based form of `scanRowPageSql`: one statement answers the
- * page of every subscription scanning `table` in a pull. `$2` is a JSON array
- * of `{i, tbl, var, vals, after, lim}` records; each record runs the same
- * index-first candidate subquery through a LATERAL join, so every
- * subscription keeps its own keyset cursor and LIMIT. Rows arrive ordered
- * by (i, row_id).
+ * page of every subscription scanning any table in a pull. `$2` is a JSON
+ * array of `{i, tbl, var, vals, after, lim}` records; each record runs the
+ * same index-first candidate subquery through a LATERAL join, so every
+ * subscription keeps its own keyset cursor and LIMIT. The candidate side is
+ * table-agnostic (a spec names its table), so the statement joins the row
+ * table once per table present in the batch through a UNION ALL branch that
+ * keeps only its own candidates. Rows arrive ordered by (i, row_id).
  *
  * Params: [partition, specs (JSON text)]. The specs bind as text before
  * the JSONB cast, so a driver that JSON-encodes a string bound to a `jsonb`
  * parameter (Bun.sql) cannot turn the array into a JSON string.
  */
-export declare function scanRowBatchSql(table: CompiledTable): string;
+export declare function scanRowBatchSql(tables: readonly CompiledTable[]): string;
 /**
  * PostgreSQL set-based form of `commitWindowPageSql`: one statement answers
  * the window page of every subscription in a pull, across all tables. `$2`
@@ -344,10 +369,10 @@ export declare function migratePayload(oldLayout: readonly StoredColumnLayout[],
  */
 export declare function selectRowsForRewriteSql(table: CompiledTable, dialect: RelationalDialect): string;
 /**
- * Rewrite one row during a migration: refresh the projection columns (when
+ * SQLite/D1: rewrite one row during a migration: refresh the projection columns (when
  * materialized) and the payload. Bind with `rewriteValues`.
  */
-export declare function rewriteRowSql(table: CompiledTable, dialect: RelationalDialect): string;
+export declare function rewriteRowSql(table: CompiledTable): string;
 /** Bind values for `rewriteRowSql` from the (already migrated) payload. */
 export declare function rewriteValues(table: CompiledTable, partition: string, rowId: string, payload: Uint8Array, dialect: RelationalDialect): unknown[];
 /**
@@ -367,9 +392,10 @@ export declare function rewritePlan(table: CompiledTable, oldLayout: readonly St
 /**
  * Every DDL statement to bring a database from the introspected relational
  * projections to `schema`: CREATE TABLE for absent tables, ADD COLUMN for
- * missing columns, and rebuild declared secondary indexes. Rebuilding during
- * a version bump supports DROP INDEX and same-name index replacement without
- * requiring historical index definitions in the stored column-layout marker.
+ * missing columns, and the secondary-index diff. An existing Syncular-owned
+ * index stays when the declaration still wants its physical name with the
+ * same {@link indexSignature}; every other owned index is dropped and every
+ * missing one is created, so a bump rebuilds only changed or new indexes.
  *
  * The drop set is limited to Syncular-owned indexes: physical names carrying
  * {@link SYNC_INDEX_PREFIX}, plus bare declared names (databases whose
@@ -377,4 +403,4 @@ export declare function rewritePlan(table: CompiledTable, oldLayout: readonly St
  * scheme through this rule). Operator-added tuning indexes keep their own
  * names and survive every bump.
  */
-export declare function schemaDdl(schema: CompiledSchema, existingColumnsByTable: ReadonlyMap<string, ReadonlySet<string>>, dialect: RelationalDialect, existingIndexesByTable?: ReadonlyMap<string, ReadonlySet<string>>): string[];
+export declare function schemaDdl(schema: CompiledSchema, existingColumnsByTable: ReadonlyMap<string, ReadonlySet<string>>, dialect: RelationalDialect, existingIndexesByTable?: ReadonlyMap<string, ReadonlyMap<string, string>>): string[];

package/dist/relational-rows.js

@@ -302,8 +302,8 @@ export function addColumnDdl(table, existingColumns, dialect) {
 }
 /**
  * Ownership marker for server-created projection indexes. A version bump
- * rebuilds declared indexes by dropping every index Syncular owns and
- * re-creating the declared set; this prefix is what marks an index as
+ * drops every index Syncular owns whose definition changed or was removed
+ * and creates the missing ones; this prefix is what marks an index as
  * Syncular-owned, so operator-added tuning indexes survive bumps. Portable
  * identifier validation reserves the `sync_` prefix for the server storage
  * namespace, which keeps user and operator index names out of it.
@@ -332,23 +332,84 @@ export function physicalIndexName(declaredName) {
     return `${SYNC_INDEX_PREFIX}${fnv1a64Hex(declaredName)}`;
 }
 /**
- * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes. These use
- * the declared columns with a leading server partition column. Cross-table
+ * Physical name of one server-only index. The name carries a fingerprint of
+ * the definition, so a changed definition is a different index and the bump
+ * diff needs no catalog comparison of predicates.
+ */
+export function physicalServerIndexName(index) {
+    const fingerprint = fnv1a64Hex(JSON.stringify([index.columns, index.where ?? null])).slice(0, 8);
+    const readable = `${SYNC_INDEX_PREFIX}${index.name}_${fingerprint}`;
+    if (new TextEncoder().encode(readable).length <= 63)
+        return readable;
+    return `${SYNC_INDEX_PREFIX}${fnv1a64Hex(index.name)}_${fingerprint}`;
+}
+/**
+ * Canonical shape of one physical index, as read from the catalog and as
+ * declared: kind, then the key columns in order (`null` for an expression).
+ * Two indexes with one signature are interchangeable.
+ */
+export function indexSignature(columns, unique, partial) {
+    return `${unique ? 'unique' : 'index'}${partial ? ' partial' : ''}(${columns.map((column) => column ?? '?').join(',')})`;
+}
+/**
+ * One statement that lists a table's free-standing SQLite indexes with their
+ * key columns in order (bind the table name). `origin='c'` excludes
+ * constraint-owned indexes, which only their constraint can remove. Feed the
+ * rows to {@link sqliteIndexSignatures}.
+ */
+export const SQLITE_TABLE_INDEXES_SQL = `SELECT il.name AS name, il."unique" AS is_unique, il.partial AS is_partial, ii.name AS column_name
+  FROM pragma_index_list(?) AS il
+  JOIN pragma_index_info(il.name) AS ii
+ WHERE il.origin='c'
+ ORDER BY il.name, ii.seqno`;
+/** Index name to {@link indexSignature} for the rows of one table. */
+export function sqliteIndexSignatures(rows) {
+    const shapes = new Map();
+    for (const row of rows) {
+        const shape = shapes.get(row.name) ?? {
+            unique: row.is_unique === 1,
+            partial: row.is_partial === 1,
+            columns: [],
+        };
+        shape.columns.push(row.column_name);
+        shapes.set(row.name, shape);
+    }
+    return Object.fromEntries([...shapes].map(([name, shape]) => [
+        name,
+        indexSignature(shape.columns, shape.unique, shape.partial),
+    ]));
+}
+/**
+ * The table's declared and server-only indexes. Declared indexes use the
+ * declared columns with a leading server partition column. Cross-table
  * index-name uniqueness is the user's schema concern, as it is client-side.
  * Server-side the physical name carries the {@link SYNC_INDEX_PREFIX}
  * ownership marker.
  */
-export function createIndexDdl(table) {
+function desiredIndexes(table) {
     // User indexes name app columns — nothing to index without the projection.
     if (!table.materialize)
         return [];
-    return table.indexes.map((index) => {
-        const unique = index.unique ? 'UNIQUE ' : '';
-        const columns = [SYNC_PARTITION_COLUMN, ...index.columns]
-            .map((column) => quoteIdent(column))
-            .join(', ');
-        return `CREATE ${unique}INDEX IF NOT EXISTS ${quoteIdent(physicalIndexName(index.name))} ON ${quoteIdent(table.name)} (${columns})`;
-    });
+    return [
+        ...table.indexes.map((index) => {
+            const unique = index.unique === true;
+            const columns = [SYNC_PARTITION_COLUMN, ...index.columns];
+            const name = physicalIndexName(index.name);
+            return {
+                name,
+                signature: indexSignature(columns, unique, false),
+                ddl: `CREATE ${unique ? 'UNIQUE ' : ''}INDEX IF NOT EXISTS ${quoteIdent(name)} ON ${quoteIdent(table.name)} (${columns.map((column) => quoteIdent(column)).join(', ')})`,
+            };
+        }),
+        ...table.serverIndexes.map((index) => {
+            const name = physicalServerIndexName(index);
+            return {
+                name,
+                signature: undefined,
+                ddl: `CREATE INDEX IF NOT EXISTS ${quoteIdent(name)} ON ${quoteIdent(table.name)} (${index.columns.map((column) => quoteIdent(column)).join(', ')})${index.where === undefined ? '' : ` WHERE ${index.where}`}`,
+            };
+        }),
+    ];
 }
 /** Idempotent removal of one Syncular-owned relational projection index. */
 export function dropIndexDdl(indexName) {
@@ -403,24 +464,22 @@ export function upsertValues(table, partition, row, dialect) {
         row.columnVersions ?? null,
     ];
 }
-function placeholderList(count, dialect) {
-    if (dialect === 'sqlite')
-        return new Array(count).fill('?').join(',');
-    const out = [];
-    for (let i = 1; i <= count; i++)
-        out.push(`$${i}`);
-    return out.join(',');
-}
-/** Upsert statement text (bind with `upsertValues`). */
-export function upsertSql(table, dialect) {
+/**
+ * Upsert statement text (bind with `upsertValues`). PostgreSQL takes `rows`
+ * rows in one statement, bound as consecutive `upsertValues` lists; their
+ * row ids must be distinct.
+ */
+export function upsertSql(table, dialect, rows = 1) {
     const names = tableColumnNames(table);
     const quoted = names.map((name) => quoteIdent(name)).join(', ');
-    const values = placeholderList(names.length, dialect);
+    const values = dialect === 'sqlite'
+        ? `(${new Array(names.length).fill('?').join(',')})`
+        : Array.from({ length: rows }, (_, row) => `(${names.map((_, column) => `$${row * names.length + column + 1}`).join(',')})`).join(',');
     const updates = names
         .slice(2) // partition + row id are the conflict key
         .map((name) => `${quoteIdent(name)}=excluded.${quoteIdent(name)}`)
         .join(', ');
-    return `INSERT INTO ${quoteIdent(table.name)} (${quoted}) VALUES (${values})
+    return `INSERT INTO ${quoteIdent(table.name)} (${quoted}) VALUES ${values}
      ON CONFLICT (${quoteIdent(SYNC_PARTITION_COLUMN)}, ${quoteIdent(SYNC_ROW_ID_COLUMN)}) DO UPDATE SET ${updates}`;
 }
 /**
@@ -550,26 +609,40 @@ export function commitWindowPageSql(valueCount, dialect) {
 }
 /**
  * PostgreSQL set-based form of `scanRowPageSql`: one statement answers the
- * page of every subscription scanning `table` in a pull. `$2` is a JSON array
- * of `{i, tbl, var, vals, after, lim}` records; each record runs the same
- * index-first candidate subquery through a LATERAL join, so every
- * subscription keeps its own keyset cursor and LIMIT. Rows arrive ordered
- * by (i, row_id).
+ * page of every subscription scanning any table in a pull. `$2` is a JSON
+ * array of `{i, tbl, var, vals, after, lim}` records; each record runs the
+ * same index-first candidate subquery through a LATERAL join, so every
+ * subscription keeps its own keyset cursor and LIMIT. The candidate side is
+ * table-agnostic (a spec names its table), so the statement joins the row
+ * table once per table present in the batch through a UNION ALL branch that
+ * keeps only its own candidates. Rows arrive ordered by (i, row_id).
  *
  * Params: [partition, specs (JSON text)]. The specs bind as text before
  * the JSONB cast, so a driver that JSON-encodes a string bound to a `jsonb`
  * parameter (Bun.sql) cannot turn the array into a JSON string.
  */
-export function scanRowBatchSql(table) {
-    return `SELECT s.i AS sub, c.row_id AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions
-     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, vals text[], after text, lim int)
-     CROSS JOIN LATERAL (SELECT DISTINCT row_id FROM sync_row_scopes
-       WHERE partition=$1 AND tbl=s.tbl AND var=s.var AND value=ANY(s.vals)
-         AND row_id>s.after
-       ORDER BY row_id LIMIT s.lim) c
-     LEFT JOIN ${quoteIdent(table.name)} r
-       ON r.${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND r.${quoteIdent(SYNC_ROW_ID_COLUMN)}=c.row_id
-     ORDER BY s.i, c.row_id`;
+export function scanRowBatchSql(tables) {
+    // One branch per table, each keeping only its own candidates and selecting
+    // the same meta columns so the caller decodes one row shape.
+    const projection = tables
+        .map((table) => {
+        const quoted = quoteIdent(table.name);
+        return `SELECT c.sub AS sub, c.row_id AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions
+       FROM cand c
+       LEFT JOIN ${quoted} r
+         ON r.${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND r.${quoteIdent(SYNC_ROW_ID_COLUMN)}=c.row_id
+      WHERE c.tbl='${table.name.replaceAll("'", "''")}'`;
+    })
+        .join('\n     UNION ALL ');
+    return `WITH cand AS (
+       SELECT s.i AS sub, c.row_id AS row_id, s.tbl AS tbl
+         FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, tbl text, var text, vals text[], after text, lim int)
+         CROSS JOIN LATERAL (SELECT DISTINCT row_id FROM sync_row_scopes
+           WHERE partition=$1 AND tbl=s.tbl AND var=s.var AND value=ANY(s.vals)
+             AND row_id>s.after
+           ORDER BY row_id LIMIT s.lim) c)
+     ${projection}
+     ORDER BY sub, row_id`;
 }
 /**
  * PostgreSQL set-based form of `commitWindowPageSql`: one statement answers
@@ -802,23 +875,17 @@ export function selectRowsForRewriteSql(table, dialect) {
      LIMIT ${p[2]}`;
 }
 /**
- * Rewrite one row during a migration: refresh the projection columns (when
+ * SQLite/D1: rewrite one row during a migration: refresh the projection columns (when
  * materialized) and the payload. Bind with `rewriteValues`.
  */
-export function rewriteRowSql(table, dialect) {
-    const sets = [];
-    let i = 1;
-    if (table.materialize) {
-        for (const column of table.columns) {
-            sets.push(`${quoteIdent(column.name)}=${dialect === 'sqlite' ? '?' : `$${i}`}`);
-            i++;
-        }
-    }
-    sets.push(`${quoteIdent(SYNC_PAYLOAD_COLUMN)}=${dialect === 'sqlite' ? '?' : `$${i}`}`);
-    i++;
-    const wherePartition = dialect === 'sqlite' ? '?' : `$${i}`;
-    const whereRowId = dialect === 'sqlite' ? '?' : `$${i + 1}`;
-    return `UPDATE ${quoteIdent(table.name)} SET ${sets.join(', ')} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=${wherePartition} AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=${whereRowId}`;
+export function rewriteRowSql(table) {
+    const sets = [
+        ...(table.materialize
+            ? table.columns.map((column) => `${quoteIdent(column.name)}=?`)
+            : []),
+        `${quoteIdent(SYNC_PAYLOAD_COLUMN)}=?`,
+    ];
+    return `UPDATE ${quoteIdent(table.name)} SET ${sets.join(', ')} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=? AND ${quoteIdent(SYNC_ROW_ID_COLUMN)}=?`;
 }
 /** Bind values for `rewriteRowSql` from the (already migrated) payload. */
 export function rewriteValues(table, partition, rowId, payload, dialect) {
@@ -860,9 +927,10 @@ export function rewritePlan(table, oldLayout, physicalColumnsBefore) {
 /**
  * Every DDL statement to bring a database from the introspected relational
  * projections to `schema`: CREATE TABLE for absent tables, ADD COLUMN for
- * missing columns, and rebuild declared secondary indexes. Rebuilding during
- * a version bump supports DROP INDEX and same-name index replacement without
- * requiring historical index definitions in the stored column-layout marker.
+ * missing columns, and the secondary-index diff. An existing Syncular-owned
+ * index stays when the declaration still wants its physical name with the
+ * same {@link indexSignature}; every other owned index is dropped and every
+ * missing one is created, so a bump rebuilds only changed or new indexes.
  *
  * The drop set is limited to Syncular-owned indexes: physical names carrying
  * {@link SYNC_INDEX_PREFIX}, plus bare declared names (databases whose
@@ -875,12 +943,18 @@ export function schemaDdl(schema, existingColumnsByTable, dialect, existingIndex
     const creates = [];
     for (const table of schema.tables.values()) {
         const existing = existingColumnsByTable.get(table.name);
+        const desired = desiredIndexes(table);
         if (existing === undefined) {
             creates.push(createTableDdl(table, dialect));
         }
         else {
             const declared = new Set(table.indexes.map((index) => index.name));
-            for (const indexName of existingIndexesByTable.get(table.name) ?? []) {
+            for (const [indexName, signature] of existingIndexesByTable.get(table.name) ?? []) {
+                const want = desired.find((index) => index.name === indexName);
+                if (want !== undefined &&
+                    (want.signature === undefined || want.signature === signature)) {
+                    continue;
+                }
                 if (indexName.startsWith(SYNC_INDEX_PREFIX) ||
                     declared.has(indexName)) {
                     drops.push(dropIndexDdl(indexName));
@@ -888,7 +962,7 @@ export function schemaDdl(schema, existingColumnsByTable, dialect, existingIndex
             }
             creates.push(...addColumnDdl(table, existing, dialect));
         }
-        creates.push(...createIndexDdl(table));
+        creates.push(...desired.map((index) => index.ddl));
     }
     // Every drop precedes every create: an index name moving between tables in
     // one bump must release the global (SQLite) index namespace before the

package/dist/schema.d.ts

@@ -20,6 +20,21 @@ export interface IndexSchema {
     readonly columns: readonly string[];
     readonly unique?: boolean;
 }
+/**
+ * A server-only index on a table's relational projection. Unlike a declared
+ * {@link IndexSchema}, it never reaches a client, and its `columns` are the
+ * physical columns as written: Syncular does not prepend `_sync_partition`.
+ * Name `_sync_partition` and `_sync_row_id` explicitly where an index should
+ * lead with them. The index is never unique, because uniqueness is enforced
+ * per partition. `where` is the predicate of a partial index, in SQL that
+ * the server's dialect accepts. Creating or changing one requires a schema
+ * version bump, like every index.
+ */
+export interface ServerIndexSchema {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly where?: string;
+}
 /** One declared reference (§6.11). Absent `onDelete` means `RESTRICT`. */
 export interface ReferenceSchema {
     readonly column: string;
@@ -54,6 +69,8 @@ export interface TableSchema {
     readonly scopes: readonly ScopePatternSpec[];
     /** User indexes (optional) — created on the server's relational tables. */
     readonly indexes?: readonly IndexSchema[];
+    /** Server-only indexes (optional); names share the namespace of `indexes`. */
+    readonly serverIndexes?: readonly ServerIndexSchema[];
     /** Declared references (§6.11). Optional so pre-reference schemas stay
      * valid; the reference index over each child column is declared in
      * `indexes` (typegen emits it). */
@@ -94,6 +111,8 @@ export interface CompiledTable {
     readonly scopePatterns: readonly CompiledScopePattern[];
     /** User indexes (validated: unique names, existing columns). */
     readonly indexes: readonly IndexSchema[];
+    /** Server-only indexes (validated like `indexes`). */
+    readonly serverIndexes: readonly ServerIndexSchema[];
     /** Outgoing declared references (§6.11), resolved to column indices. */
     readonly references: readonly CompiledReference[];
     /** Incoming declared references: child rows to reach on a parent delete. */

package/dist/schema.js

@@ -68,6 +68,27 @@ export function compileSchema(schema) {
                 }
             }
         }
+        const serverIndexes = table.serverIndexes ?? [];
+        for (const index of serverIndexes) {
+            validatePortableRelationalIdentifier(`table ${table.name}: server index`, index.name);
+            if (indexNames.has(index.name)) {
+                throw new Error(`table ${table.name}: duplicate index ${JSON.stringify(index.name)}`);
+            }
+            indexNames.add(index.name);
+            if (index.columns.length === 0) {
+                throw new Error(`table ${table.name}: server index ${JSON.stringify(index.name)} must name at least one column`);
+            }
+            for (const column of index.columns) {
+                if (!columnIndex.has(column) &&
+                    column !== '_sync_partition' &&
+                    column !== '_sync_row_id') {
+                    throw new Error(`table ${table.name}: server index ${JSON.stringify(index.name)} names unknown column ${JSON.stringify(column)}`);
+                }
+            }
+            if (index.where !== undefined && index.where.trim().length === 0) {
+                throw new Error(`table ${table.name}: server index ${JSON.stringify(index.name)} has an empty where predicate`);
+            }
+        }
         const primaryKeyIndex = columnIndex.get(table.primaryKey);
         if (primaryKeyIndex === undefined) {
             throw new Error(`table ${table.name}: primary key ${JSON.stringify(table.primaryKey)} is not a column`);
@@ -142,6 +163,7 @@ export function compileSchema(schema) {
             primaryKeyIndex,
             scopePatterns,
             indexes,
+            serverIndexes,
             references,
             referencedBy: [],
             materialize,

package/dist/sqlite-bun-driver.js

@@ -11,7 +11,7 @@ export class BunSqliteDatabase {
         this.native.exec(sql);
     }
     run(sql, bindings = []) {
-        return this.native.run(sql, [...bindings]);
+        return this.native.query(sql).run(...bindings);
     }
     query(sql) {
         const statement = this.native.query(sql);

package/dist/sqlite-node-driver.d.ts

@@ -1,6 +1,7 @@
 import { DatabaseSync } from 'node:sqlite';
 import type { SqliteDatabase, SqliteRunResult, SqliteStatement, SqliteValue } from './sqlite-driver.js';
 export declare class NodeSqliteDatabase implements SqliteDatabase {
+    #private;
     readonly native: DatabaseSync;
     constructor(path?: string);
     exec(sql: string): void;

package/dist/sqlite-node-driver.js

@@ -1,4 +1,4 @@
-import { DatabaseSync } from 'node:sqlite';
+import { DatabaseSync, } from 'node:sqlite';
 function bind(value) {
     return typeof value === 'boolean' ? (value ? 1 : 0) : value;
 }
@@ -7,6 +7,8 @@ function row(value) {
 }
 export class NodeSqliteDatabase {
     native;
+    /** Prepared statements by SQL text, as `bun:sqlite`'s `query` keeps them. */
+    #statements = new Map();
     constructor(path = ':memory:') {
         this.native = new DatabaseSync(path);
     }
@@ -14,10 +16,18 @@ export class NodeSqliteDatabase {
         this.native.exec(sql);
     }
     run(sql, bindings = []) {
-        return this.native.prepare(sql).run(...bindings.map(bind));
+        return this.#prepare(sql).run(...bindings.map(bind));
+    }
+    #prepare(sql) {
+        let statement = this.#statements.get(sql);
+        if (statement === undefined) {
+            statement = this.native.prepare(sql);
+            this.#statements.set(sql, statement);
+        }
+        return statement;
     }
     query(sql) {
-        const statement = this.native.prepare(sql);
+        const statement = this.#prepare(sql);
         return {
             run: (...params) => statement.run(...params.map(bind)),
             get: (...params) => row(statement.get(...params.map(bind))),

package/dist/sqlite-storage.js

@@ -1,7 +1,7 @@
 import { retainRollbackFailure, rollbackAfterError } from './storage-errors.js';
 import { validateCommitPruneQuery } from './prune.js';
 import { StorageQueryError } from './storage-errors.js';
-import { serveGateRefusal } from './storage.js';
+import { PARTITION_TOUCH_INTERVAL_MS, serveGateRefusal } from './storage.js';
 import { serveNotReadyError } from './readiness.js';
 /**
  * SQLite server storage over the shared synchronous driver.
@@ -13,7 +13,7 @@ import { serveNotReadyError } from './readiness.js';
  */
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, LATEST_SCOPED_CHANGE_SEQ_SQLITE_SQL, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowPageSql, schemaDdl, SQLITE_TABLE_INDEXES_SQL, sqliteIndexSignatures, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { collectCommitWindowPage, deserializePushResult, ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL, eraseScopeValueHistoryParams, LIST_SCOPE_VALUE_ROWS_SQLITE_SQL, placeholders, SQLITE_DDL, serializePushResult, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
@@ -364,8 +364,6 @@ END`);
             // rewrite stored rows (payload re-encode for layout changes, and/or
             // projection backfill for flipped-on materialization). One
             // transaction: a failed bump leaves no half-state.
-            const layouts = parseLayouts(marker?.layouts);
-            const retiredTables = retiredTableNames(schema, layouts);
             const existing = new Map();
             const existingIndexes = new Map();
             for (const table of schema.tables.values()) {
@@ -375,11 +373,9 @@ END`);
                     .all();
                 if (columns.length > 0) {
                     existing.set(table.name, new Set(columns.map((c) => c.name)));
-                    const indexes = this.db
-                        .query(`PRAGMA index_list("${escapedTableName}")`)
-                        .all()
-                        .filter((index) => index.origin === 'c');
-                    existingIndexes.set(table.name, new Set(indexes.map((index) => index.name)));
+                    existingIndexes.set(table.name, new Map(Object.entries(sqliteIndexSignatures(this.db
+                        .query(SQLITE_TABLE_INDEXES_SQL)
+                        .all(table.name)))));
                 }
             }
             // The migration rewrites application rows (`#rewriteRows`) with no
@@ -390,6 +386,21 @@ END`);
             await this.#serializeWrite(() => {
                 this.db.exec('BEGIN IMMEDIATE');
                 try {
+                    // Another process sharing the database may have bumped between the
+                    // marker read above and the writer lock; the locked marker decides
+                    // (SPEC "Schema upgrade writer fence").
+                    const locked = this.db
+                        .query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1')
+                        .get();
+                    if (locked !== null && locked.schema_version > schema.version) {
+                        throw new Error(`stored schema version ${locked.schema_version} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
+                    }
+                    if (locked !== null && locked.schema_version === schema.version) {
+                        this.db.exec('COMMIT');
+                        return;
+                    }
+                    const layouts = parseLayouts(locked?.layouts);
+                    const retiredTables = retiredTableNames(schema, layouts);
                     for (const tableName of retiredTables) {
                         this.db
                             .query('DELETE FROM sync_row_scopes WHERE tbl=?')
@@ -446,17 +457,21 @@ END`);
         if (initialLogEpoch.length === 0) {
             throw new Error('initial log epoch must be non-empty');
         }
-        this.db
-            .query(`INSERT INTO sync_partition_registry(
-           partition, log_epoch, last_authenticated_at_ms
-         ) VALUES (?,?,?)
-         ON CONFLICT(partition) DO UPDATE SET
-           last_authenticated_at_ms=excluded.last_authenticated_at_ms`)
-            .run(partition, initialLogEpoch, authenticatedAtMs);
-        const row = this.db
-            .query(`SELECT log_epoch, epoch_required, last_authenticated_at_ms
-           FROM sync_partition_registry WHERE partition=?`)
-            .get(partition);
+        const select = this.db.query(`SELECT log_epoch, epoch_required, last_authenticated_at_ms
+         FROM sync_partition_registry WHERE partition=?`);
+        let row = select.get(partition);
+        if (row === null ||
+            authenticatedAtMs - row.last_authenticated_at_ms >=
+                PARTITION_TOUCH_INTERVAL_MS) {
+            this.db
+                .query(`INSERT INTO sync_partition_registry(
+             partition, log_epoch, last_authenticated_at_ms
+           ) VALUES (?,?,?)
+           ON CONFLICT(partition) DO UPDATE SET
+             last_authenticated_at_ms=excluded.last_authenticated_at_ms`)
+                .run(partition, initialLogEpoch, authenticatedAtMs);
+            row = select.get(partition);
+        }
         if (row === null)
             throw new Error('partition registry write did not persist');
         return {
@@ -519,7 +534,7 @@ END`);
      */
     #rewriteRows(table, oldLayout) {
         const select = selectRowsForRewriteSql(table, 'sqlite');
-        const update = this.db.query(rewriteRowSql(table, 'sqlite'));
+        const update = this.db.query(rewriteRowSql(table));
         const BATCH = 500;
         let afterPartition = '';
         let afterRowId = '';