@syncular/server 0.37.0 → 0.38.0

package/dist/d1-storage.js

@@ -1,6 +1,7 @@
 var _a;
 import { validateCommitPruneQuery } from './prune.js';
 import { StorageQueryError } from './storage-errors.js';
+import { PARTITION_TOUCH_INTERVAL_MS } from './storage.js';
 /**
  * Cloudflare D1 server storage for Workers deployments.
  *
@@ -45,7 +46,7 @@ import { StorageQueryError } from './storage-errors.js';
 import { decodeRow } from '@syncular/core';
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertAppendOnlyMigration, 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, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertAppendOnlyMigration, 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, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, ERASE_SCOPE_VALUE_HISTORY_SQLITE_SQL, eraseScopeValueHistoryParams, LIST_SCOPE_VALUE_ROWS_SQLITE_SQL, serializePushResult, sqliteDdlStatements, toStoredChange, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
@@ -833,7 +834,8 @@ export class D1ServerStorage {
                         .prepare(`PRAGMA table_info(${quoteIdent(table.name)})`)
                         .all();
                     const indexes = await this.#db
-                        .prepare(`PRAGMA index_list(${quoteIdent(table.name)})`)
+                        .prepare(SQLITE_TABLE_INDEXES_SQL)
+                        .bind(table.name)
                         .all();
                     // Validate the old codec before any application DDL or row rewrite.
                     rewritePlan(table, sourceLayouts[table.name], columns.results.length > 0
@@ -852,9 +854,7 @@ export class D1ServerStorage {
                         },
                         indexes: {
                             ...state.indexes,
-                            [table.name]: indexes.results
-                                .filter((index) => index.origin === 'c')
-                                .map((index) => index.name),
+                            [table.name]: sqliteIndexSignatures(indexes.results),
                         },
                     }, [])))
                         break;
@@ -864,9 +864,9 @@ export class D1ServerStorage {
                     name,
                     new Set(names),
                 ]));
-                const indexes = new Map(Object.entries(state.indexes).map(([name, names]) => [
+                const indexes = new Map(Object.entries(state.indexes).map(([name, signatures]) => [
                     name,
-                    new Set(names),
+                    new Map(Object.entries(signatures)),
                 ]));
                 const rewrites = tables.flatMap((table) => {
                     const plan = rewritePlan(table, sourceLayouts[table.name], columns.get(table.name));
@@ -1068,19 +1068,24 @@ export class D1ServerStorage {
         if (initialLogEpoch.length === 0) {
             throw new Error('initial log epoch must be non-empty');
         }
-        await this.#db
-            .prepare(`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`)
-            .bind(partition, initialLogEpoch, authenticatedAtMs)
-            .run();
-        const row = await this.#db
+        const select = this.#db
             .prepare(`SELECT log_epoch, epoch_required, last_authenticated_at_ms
            FROM sync_partition_registry WHERE partition=?`)
-            .bind(partition)
-            .first();
+            .bind(partition);
+        let row = await select.first();
+        if (row === null ||
+            authenticatedAtMs - row.last_authenticated_at_ms >=
+                PARTITION_TOUCH_INTERVAL_MS) {
+            await this.#db
+                .prepare(`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`)
+                .bind(partition, initialLogEpoch, authenticatedAtMs)
+                .run();
+            row = await select.first();
+        }
         if (row === null)
             throw new Error('partition registry write did not persist');
         return {

package/dist/postgres-storage.js

@@ -1,11 +1,11 @@
 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';
 import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
-import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, LATEST_SCOPED_CHANGE_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowBatchSql, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, prefetchRowsSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, LATEST_SCOPED_CHANGE_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, SYNC_COLUMN_VERSIONS_COLUMN, SYNC_PARTITION_COLUMN, SYNC_PAYLOAD_COLUMN, SYNC_ROW_ID_COLUMN, SYNC_SCOPES_COLUMN, SYNC_VERSION_COLUMN, scanRowBatchSql, scanRowPageSql, indexSignature, schemaDdl, selectRowScopesSql, selectRowSql, prefetchRowsSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective, sha256Hex } from './scopes.js';
 import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -1013,7 +1013,19 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
                         // indexes (PRIMARY KEY, UNIQUE constraints) can only be removed
                         // through their constraint, so DROP INDEX on them would abort
                         // the migration transaction.
-                        const indexes = await client.query(`SELECT index_class.relname AS index_name
+                        const indexes = await client.query(`SELECT index_class.relname AS index_name,
+                      index_meta.indisunique AS is_unique,
+                      index_meta.indpred IS NOT NULL AS is_partial,
+                      ARRAY(
+                        SELECT attribute.attname::text
+                          FROM unnest(index_meta.indkey::int2[])
+                               WITH ORDINALITY AS key(attnum, ord)
+                          LEFT JOIN pg_catalog.pg_attribute AS attribute
+                            ON attribute.attrelid = table_class.oid
+                           AND attribute.attnum = key.attnum
+                         WHERE key.ord <= index_meta.indnkeyatts
+                         ORDER BY key.ord
+                      ) AS columns
                  FROM pg_catalog.pg_class AS table_class
                  JOIN pg_catalog.pg_namespace AS namespace
                    ON namespace.oid = table_class.relnamespace
@@ -1029,7 +1041,10 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
                       FROM pg_catalog.pg_constraint AS owning_constraint
                      WHERE owning_constraint.conindid = index_meta.indexrelid
                   )`, [table.name]);
-                        existingIndexes.set(table.name, new Set(indexes.rows.map((index) => index.index_name)));
+                        existingIndexes.set(table.name, new Map(indexes.rows.map((index) => [
+                            index.index_name,
+                            indexSignature(index.columns, index.is_unique, index.is_partial),
+                        ])));
                     }
                 }
                 for (const tableName of retiredTables) {
@@ -1081,13 +1096,18 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`,
         if (initialLogEpoch.length === 0) {
             throw new Error('initial log epoch must be non-empty');
         }
-        const { rows } = await this.#exec.query(`INSERT INTO sync_partition_registry(
-         partition, log_epoch, last_authenticated_at_ms
-       ) VALUES ($1,$2,$3)
-       ON CONFLICT(partition) DO UPDATE SET
-         last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms
-       RETURNING log_epoch, epoch_required, last_authenticated_at_ms`, [partition, initialLogEpoch, authenticatedAtMs]);
-        const row = rows[0];
+        let row = (await this.#exec.query(`SELECT log_epoch, epoch_required, last_authenticated_at_ms
+           FROM sync_partition_registry WHERE partition=$1`, [partition])).rows[0];
+        if (row === undefined ||
+            authenticatedAtMs - asNumber(row.last_authenticated_at_ms) >=
+                PARTITION_TOUCH_INTERVAL_MS) {
+            row = (await this.#exec.query(`INSERT INTO sync_partition_registry(
+             partition, log_epoch, last_authenticated_at_ms
+           ) VALUES ($1,$2,$3)
+           ON CONFLICT(partition) DO UPDATE SET
+             last_authenticated_at_ms=EXCLUDED.last_authenticated_at_ms
+           RETURNING log_epoch, epoch_required, last_authenticated_at_ms`, [partition, initialLogEpoch, authenticatedAtMs])).rows[0];
+        }
         if (row === undefined)
             throw new Error('partition registry write did not persist');
         return {

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;
 /**
@@ -367,9 +386,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 +397,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) {
@@ -860,9 +921,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 +937,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 +956,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';
@@ -375,11 +375,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
@@ -446,17 +444,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 {

package/dist/storage.d.ts

@@ -283,6 +283,8 @@ export interface ClientCursorInfo {
     readonly updatedAtMs: number;
 }
 /** Durable partition identity refreshed after host authentication (§2.1). */
+/** Longest age of `lastAuthenticatedAtMs` that `touchPartition` leaves unwritten. */
+export declare const PARTITION_TOUCH_INTERVAL_MS = 60000;
 export interface PartitionRegistryEntry {
     readonly partition: string;
     readonly logEpoch: string;
@@ -526,7 +528,12 @@ export interface ServerStorage {
      * lazily as a defensive backstop.
      */
     ensureSchema(schema: CompiledSchema, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
-    /** Create or refresh the authenticated partition registry row (§2.1). */
+    /**
+     * Create or refresh the authenticated partition registry row (§2.1). A
+     * row whose `lastAuthenticatedAtMs` is less than
+     * {@link PARTITION_TOUCH_INTERVAL_MS} behind `authenticatedAtMs` is read
+     * back without a write, so a request that only reads takes no write lock.
+     */
     touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
     /** Rotate log continuity after restore and discard stale cursor records. */
     rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;

package/dist/storage.js

@@ -38,3 +38,6 @@ export function serveGateTokenChanged(before, after) {
     }
     return undefined;
 }
+/** Durable partition identity refreshed after host authentication (§2.1). */
+/** Longest age of `lastAuthenticatedAtMs` that `touchPartition` leaves unwritten. */
+export const PARTITION_TOUCH_INTERVAL_MS = 60_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.37.0"
+    "@syncular/core": "0.38.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"