@syncular/server 0.15.46 → 0.15.48

package/src/sqlite-bun.ts

@@ -0,0 +1,53 @@
+import { SqliteBlobStore as SharedSqliteBlobStore } from './sqlite-blob-store';
+import { BunSqliteDatabase } from './sqlite-bun-driver';
+import type { SqliteDatabase } from './sqlite-driver';
+import { type SqliteImageBuilder, writeSqliteImage } from './sqlite-image';
+import { SqliteLeaseStore as SharedSqliteLeaseStore } from './sqlite-lease-store';
+import { SqliteSegmentStore as SharedSqliteSegmentStore } from './sqlite-segment-store';
+import { SqliteServerStorage as SharedSqliteServerStorage } from './sqlite-storage';
+
+function database(value: SqliteDatabase | string): SqliteDatabase {
+  return typeof value === 'string' ? new BunSqliteDatabase(value) : value;
+}
+
+export class SqliteServerStorage extends SharedSqliteServerStorage {
+  constructor(value: SqliteDatabase | string = ':memory:') {
+    super(database(value));
+  }
+}
+
+export class SqliteSegmentStore extends SharedSqliteSegmentStore {
+  constructor(
+    value: SqliteDatabase | string = ':memory:',
+    options?: { ttlMs?: number },
+  ) {
+    super(database(value), options);
+  }
+}
+
+export class SqliteBlobStore extends SharedSqliteBlobStore {
+  constructor(value: SqliteDatabase | string = ':memory:') {
+    super(database(value));
+  }
+}
+
+export class SqliteLeaseStore extends SharedSqliteLeaseStore {
+  constructor(
+    value: SqliteDatabase | string = ':memory:',
+    options?: { readonly leaseId?: () => string },
+  ) {
+    super(database(value), options);
+  }
+}
+
+export const buildSqliteImage: SqliteImageBuilder = (input) => {
+  const db = new BunSqliteDatabase();
+  try {
+    writeSqliteImage(db, input);
+    return db.serialize();
+  } finally {
+    db.close();
+  }
+};
+
+export { BunSqliteDatabase } from './sqlite-bun-driver';

package/src/sqlite-dialect.ts

@@ -1,12 +1,12 @@
 /**
- * Shared SQLite dialect for the two SQLite-family storages: `bun:sqlite`
- * (synchronous, `SqliteServerStorage`) and Cloudflare D1 (async,
- * `D1ServerStorage`). D1 *is* SQLite — same DDL, same statement grammar,
+ * Shared SQLite dialect for synchronous `SqliteServerStorage` on Bun or Node
+ * and asynchronous `D1ServerStorage` on Cloudflare Workers. D1 is SQLite:
+ * same DDL, same statement grammar,
  * same `?` positional placeholders, same `INSERT ... ON CONFLICT` / `INSERT
  * OR IGNORE` upsert idioms — so the schema and the value (de)serialization are
  * genuinely common ground and live here.
  *
- * What is NOT shared: statement *execution*. `bun:sqlite` is sync
+ * What is not shared: statement execution. The server SQLite driver is sync
  * (`db.query(sql).get(...)`) and D1 is async (`await
  * db.prepare(sql).bind(...).all()`); a shared execution layer would have to
  * pick one calling convention and adapt the other, which is uglier than two
@@ -25,7 +25,7 @@ import type {
 } from './storage';
 
 /**
- * Schema DDL — one statement per `;`-delimited chunk. `bun:sqlite` applies
+ * Schema DDL, one statement per `;`-delimited chunk. Native SQLite applies
  * the whole string via `db.exec(SQLITE_DDL)`; D1 applies each statement
  * separately (its `prepare`/`batch` API is one statement per call). Types
  * are SQLite's: `INTEGER`/`TEXT`/`BLOB`. Scopes are stored as JSON `TEXT`
@@ -43,6 +43,12 @@ CREATE TABLE IF NOT EXISTS sync_partitions(
   max_commit_seq INTEGER NOT NULL DEFAULT 0,
   horizon_seq INTEGER NOT NULL DEFAULT 0
 );
+CREATE TABLE IF NOT EXISTS sync_partition_registry(
+  partition TEXT PRIMARY KEY,
+  log_epoch TEXT NOT NULL,
+  epoch_required INTEGER NOT NULL DEFAULT 0,
+  last_authenticated_at_ms INTEGER NOT NULL
+);
 CREATE TABLE IF NOT EXISTS sync_row_scopes(
   partition TEXT NOT NULL, tbl TEXT NOT NULL,
   var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
@@ -96,6 +102,7 @@ CREATE INDEX IF NOT EXISTS sync_reactions_dead_letter
   ON sync_reactions(partition, status, available_at_ms, idempotency_key);
 CREATE TABLE IF NOT EXISTS sync_clients(
   partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,
+  wire_version INTEGER NOT NULL DEFAULT 1,
   cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,
   updated_at_ms INTEGER NOT NULL,
   PRIMARY KEY(partition, client_id)
@@ -246,7 +253,7 @@ export interface SqliteChangeRecord {
   payload: Uint8Array | null;
 }
 
-/** `bun:sqlite` returns `Uint8Array`; D1 returns `ArrayBuffer` for BLOBs. */
+/** Native SQLite returns `Uint8Array`; D1 returns `ArrayBuffer` for BLOBs. */
 export function asUint8Array(value: unknown): Uint8Array {
   if (value instanceof Uint8Array) return value;
   if (value instanceof ArrayBuffer) return new Uint8Array(value);
@@ -280,7 +287,7 @@ export function toStoredChange(record: SqliteChangeRecord): StoredChange {
  * One result row of `commitWindowPageSql` (candidate LEFT JOIN commit meta
  * LEFT JOIN changes): meta/change columns are NULL when the joined row
  * vanished (see the builder's LEFT JOIN contract). `payload` is a BLOB —
- * `bun:sqlite` hands back `Uint8Array`, D1 `ArrayBuffer`; `toStoredChange`
+ * Native SQLite hands back `Uint8Array`, D1 `ArrayBuffer`; `toStoredChange`
  * normalizes via `asUint8Array`.
  */
 export interface SqliteCommitWindowRecord {

package/src/sqlite-driver.ts

@@ -0,0 +1,44 @@
+/** Values accepted by the synchronous SQLite adapters. */
+export type SqliteValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | Uint8Array
+  | null;
+
+/** Result of a SQLite statement that does not return rows. */
+export interface SqliteRunResult {
+  readonly changes: number | bigint;
+  readonly lastInsertRowid: number | bigint;
+}
+
+/** Prepared synchronous SQLite statement used by the server stores. */
+export interface SqliteStatement<Row, Params extends readonly SqliteValue[]> {
+  run(...params: Params): SqliteRunResult;
+  get(...params: Params): Row | null;
+  all(...params: Params): Row[];
+}
+
+/** Runtime-neutral database surface shared by the Bun and Node adapters. */
+export interface SqliteDatabase {
+  exec(sql: string): void;
+  run(sql: string, bindings?: readonly SqliteValue[]): SqliteRunResult;
+  query<
+    Row = Record<string, SqliteValue>,
+    Params extends readonly SqliteValue[] = SqliteValue[],
+  >(
+    sql: string,
+  ): SqliteStatement<Row, Params>;
+  close(): void;
+}
+
+/** Raised when a neutral-runtime import is used without a SQLite adapter. */
+export class SqliteAdapterRequiredError extends Error {
+  override readonly name = 'SqliteAdapterRequiredError';
+  readonly code = 'sync.sqlite_adapter_required';
+
+  constructor() {
+    super('SQLite paths require the @syncular/server/sqlite runtime adapter');
+  }
+}

package/src/sqlite-image.ts

@@ -2,15 +2,15 @@
  * SQLite-image segment generation (SPEC.md §5.3): a complete SQLite
  * database file carrying one table's whole effective-scope snapshot at
  * the bootstrap pin, plus the single-row `_syncular_segment` metadata
- * table. Built in memory on bun:sqlite — dependency-free.
+ * table. Runtime entries provide the concrete SQLite database.
  *
  * Images are NOT byte-deterministic (§5.3): the content address pins the
  * served bytes, and cross-client dedup comes from the segment store's
  * metadata lookup (`SegmentStore.find`), not from hash convergence.
  */
-import { Database } from 'bun:sqlite';
 import { decodeRow, type RowColumn, type RowValue } from '@syncular/core';
 import type { CompiledTable } from './schema';
+import type { SqliteDatabase } from './sqlite-driver';
 import type { StoredRow } from './storage';
 
 /** The §5.6 version column as it appears inside a sqlite image (§5.3). */
@@ -63,62 +63,57 @@ export interface SqliteImageInput {
 /**
  * The §5.3 image-builder capability, injected through
  * `SyncServerConfig.sqliteImageBuilder`. Building an image needs
- * a real SQLite engine (`bun:sqlite` here), which is not available on every
- * runtime — Cloudflare Workers has none. So the core takes the builder as an
- * optional capability rather than importing `bun:sqlite` on the pull path:
- * a Bun/Node host passes `buildSqliteImage`; a Workers host omits it and the
- * pull serves the rows lane (§5.3 clients advertise sqlite as an *accept*,
- * never a requirement — the host chooses the served format from what it can
- * produce; this is a support floor, not a fallback).
+ * a real SQLite engine, which is not available on every runtime. The core
+ * takes the builder as an optional capability rather than importing a driver
+ * on the pull path. A Bun or Node host passes `buildSqliteImage`; a Workers
+ * host omits it and serves the rows lane.
  */
 export type SqliteImageBuilder = (input: SqliteImageInput) => Uint8Array;
 
-/** Build the §5.3 image bytes for a whole-table snapshot. */
-export const buildSqliteImage: SqliteImageBuilder = (input) => {
+/** Populate a §5.3 image database for a whole-table snapshot. */
+export function writeSqliteImage(
+  db: SqliteDatabase,
+  input: SqliteImageInput,
+): void {
   const { table, rows } = input;
   const primaryKey = table.columns[table.primaryKeyIndex]?.name;
-  const db = new Database(':memory:');
+  const columnDefs = table.columns.map((column) => {
+    const notNull = column.nullable ? '' : ' NOT NULL';
+    const pk = column.name === primaryKey ? ' PRIMARY KEY' : '';
+    return `${quoteIdent(column.name)} ${sqlType(column)}${notNull}${pk}`;
+  });
+  columnDefs.push(`${quoteIdent(IMAGE_VERSION_COLUMN)} INTEGER NOT NULL`);
+  db.exec(`CREATE TABLE ${quoteIdent(table.name)} (${columnDefs.join(', ')})`);
+  db.exec(
+    `CREATE TABLE ${IMAGE_METADATA_TABLE} (
+      format INTEGER NOT NULL, "table" TEXT NOT NULL,
+      "schemaVersion" INTEGER NOT NULL, "asOfCommitSeq" INTEGER NOT NULL,
+      "scopeDigest" TEXT NOT NULL, "rowCount" INTEGER NOT NULL)`,
+  );
+  db.query(`INSERT INTO ${IMAGE_METADATA_TABLE} VALUES (1, ?, ?, ?, ?, ?)`).run(
+    table.name,
+    input.schemaVersion,
+    input.asOfCommitSeq,
+    input.scopeDigest,
+    rows.length,
+  );
+  const names = [
+    ...table.columns.map((column) => quoteIdent(column.name)),
+    quoteIdent(IMAGE_VERSION_COLUMN),
+  ];
+  const insert = db.query(
+    `INSERT INTO ${quoteIdent(table.name)} (${names.join(', ')})
+     VALUES (${names.map(() => '?').join(', ')})`,
+  );
+  db.exec('BEGIN');
   try {
-    const columnDefs = table.columns.map((column) => {
-      const notNull = column.nullable ? '' : ' NOT NULL';
-      const pk = column.name === primaryKey ? ' PRIMARY KEY' : '';
-      return `${quoteIdent(column.name)} ${sqlType(column)}${notNull}${pk}`;
-    });
-    columnDefs.push(`${quoteIdent(IMAGE_VERSION_COLUMN)} INTEGER NOT NULL`);
-    db.exec(
-      `CREATE TABLE ${quoteIdent(table.name)} (${columnDefs.join(', ')})`,
-    );
-    db.exec(
-      `CREATE TABLE ${IMAGE_METADATA_TABLE} (
-        format INTEGER NOT NULL, "table" TEXT NOT NULL,
-        "schemaVersion" INTEGER NOT NULL, "asOfCommitSeq" INTEGER NOT NULL,
-        "scopeDigest" TEXT NOT NULL, "rowCount" INTEGER NOT NULL)`,
-    );
-    db.query(
-      `INSERT INTO ${IMAGE_METADATA_TABLE} VALUES (1, ?, ?, ?, ?, ?)`,
-    ).run(
-      table.name,
-      input.schemaVersion,
-      input.asOfCommitSeq,
-      input.scopeDigest,
-      rows.length,
-    );
-    const names = [
-      ...table.columns.map((column) => quoteIdent(column.name)),
-      quoteIdent(IMAGE_VERSION_COLUMN),
-    ];
-    const insert = db.query(
-      `INSERT INTO ${quoteIdent(table.name)} (${names.join(', ')})
-       VALUES (${names.map(() => '?').join(', ')})`,
-    );
-    db.exec('BEGIN');
     for (const row of rows) {
       const values = decodeRow(table.columns, row.payload);
       insert.run(...values.map(toSql), row.serverVersion);
     }
     db.exec('COMMIT');
-    return new Uint8Array(db.serialize());
-  } finally {
-    db.close();
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
   }
-};
+}

package/src/sqlite-lease-store.ts

@@ -1,28 +1,29 @@
 /**
- * SQLite-backed auth-lease store via `bun:sqlite` (§7.3.1 reference store,
- * dependency-free). Bun-specific by design (top-level `bun:sqlite` import),
- * so it lives in its own module — the runtime-neutral `LeaseStore` interface,
- * `LeaseRecord`, and `MemoryLeaseStore` stay in `lease-store.ts` for the
- * Workers/edge core (runtime neutrality is enforced by
- * `test/runtime-neutrality.test.ts`).
+ * SQLite-backed auth-lease store over the shared synchronous driver.
  */
-import { Database } from 'bun:sqlite';
 import type { ScopeMap } from '@syncular/core';
 import type { LeaseIdFactory, LeaseRecord, LeaseStore } from './lease-store';
+import {
+  SqliteAdapterRequiredError,
+  type SqliteDatabase,
+} from './sqlite-driver';
 
 function defaultLeaseId(): string {
   return `lease_${crypto.randomUUID()}`;
 }
 
 export class SqliteLeaseStore implements LeaseStore {
-  readonly db: Database;
+  readonly db: SqliteDatabase;
   readonly #newId: LeaseIdFactory;
 
   constructor(
-    db: Database | string = ':memory:',
+    db: SqliteDatabase | string = ':memory:',
     options?: { readonly leaseId?: LeaseIdFactory },
   ) {
-    this.db = typeof db === 'string' ? new Database(db) : db;
+    if (typeof db === 'string') {
+      throw new SqliteAdapterRequiredError();
+    }
+    this.db = db;
     this.#newId = options?.leaseId ?? defaultLeaseId;
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS sync_leases(

package/src/sqlite-node-driver.ts

@@ -0,0 +1,46 @@
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
+import type {
+  SqliteDatabase,
+  SqliteRunResult,
+  SqliteStatement,
+  SqliteValue,
+} from './sqlite-driver';
+
+function bind(value: SqliteValue): SQLInputValue {
+  return typeof value === 'boolean' ? (value ? 1 : 0) : value;
+}
+
+function row<Row>(value: Record<string, unknown> | undefined): Row | null {
+  return (value ?? null) as Row | null;
+}
+
+export class NodeSqliteDatabase implements SqliteDatabase {
+  readonly native: DatabaseSync;
+
+  constructor(path = ':memory:') {
+    this.native = new DatabaseSync(path);
+  }
+
+  exec(sql: string): void {
+    this.native.exec(sql);
+  }
+
+  run(sql: string, bindings: readonly SqliteValue[] = []): SqliteRunResult {
+    return this.native.prepare(sql).run(...bindings.map(bind));
+  }
+
+  query<Row, Params extends readonly SqliteValue[]>(
+    sql: string,
+  ): SqliteStatement<Row, Params> {
+    const statement = this.native.prepare(sql);
+    return {
+      run: (...params) => statement.run(...params.map(bind)),
+      get: (...params) => row<Row>(statement.get(...params.map(bind))),
+      all: (...params) => statement.all(...params.map(bind)) as Row[],
+    };
+  }
+
+  close(): void {
+    this.native.close();
+  }
+}

package/src/sqlite-node.ts

@@ -0,0 +1,62 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SqliteBlobStore as SharedSqliteBlobStore } from './sqlite-blob-store';
+import type { SqliteDatabase } from './sqlite-driver';
+import { type SqliteImageBuilder, writeSqliteImage } from './sqlite-image';
+import { SqliteLeaseStore as SharedSqliteLeaseStore } from './sqlite-lease-store';
+import { NodeSqliteDatabase } from './sqlite-node-driver';
+import { SqliteSegmentStore as SharedSqliteSegmentStore } from './sqlite-segment-store';
+import { SqliteServerStorage as SharedSqliteServerStorage } from './sqlite-storage';
+
+function database(value: SqliteDatabase | string): SqliteDatabase {
+  return typeof value === 'string' ? new NodeSqliteDatabase(value) : value;
+}
+
+export class SqliteServerStorage extends SharedSqliteServerStorage {
+  constructor(value: SqliteDatabase | string = ':memory:') {
+    super(database(value));
+  }
+}
+
+export class SqliteSegmentStore extends SharedSqliteSegmentStore {
+  constructor(
+    value: SqliteDatabase | string = ':memory:',
+    options?: { ttlMs?: number },
+  ) {
+    super(database(value), options);
+  }
+}
+
+export class SqliteBlobStore extends SharedSqliteBlobStore {
+  constructor(value: SqliteDatabase | string = ':memory:') {
+    super(database(value));
+  }
+}
+
+export class SqliteLeaseStore extends SharedSqliteLeaseStore {
+  constructor(
+    value: SqliteDatabase | string = ':memory:',
+    options?: { readonly leaseId?: () => string },
+  ) {
+    super(database(value), options);
+  }
+}
+
+export const buildSqliteImage: SqliteImageBuilder = (input) => {
+  const directory = mkdtempSync(join(tmpdir(), 'syncular-server-image-'));
+  const path = join(directory, 'segment.db');
+  const db = new NodeSqliteDatabase(path);
+  try {
+    try {
+      writeSqliteImage(db, input);
+    } finally {
+      db.close();
+    }
+    return new Uint8Array(readFileSync(path));
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+};
+
+export { NodeSqliteDatabase } from './sqlite-node-driver';

package/src/sqlite-segment-store.ts

@@ -1,13 +1,6 @@
 /**
- * SQLite-backed segment store via `bun:sqlite` (dev/bench convenience,
- * dependency-free). Bun-specific by design: it imports `bun:sqlite` at the
- * top level, so it lives in its own module — importing it opts into the Bun
- * runtime. The runtime-neutral `SegmentStore` interface, `MemorySegmentStore`,
- * and `segmentIdFor` stay in `segment-store.ts` so the Workers/edge core can
- * import them without pulling in `bun:sqlite` (runtime neutrality is enforced
- * by `test/runtime-neutrality.test.ts`).
+ * SQLite-backed segment store over the shared synchronous driver.
  */
-import { Database } from 'bun:sqlite';
 import {
   DEFAULT_SEGMENT_TTL_MS,
   type SegmentFindKey,
@@ -17,20 +10,28 @@ import {
   type SegmentStoreStats,
   segmentIdFor,
 } from './segment-store';
+import {
+  SqliteAdapterRequiredError,
+  type SqliteDatabase,
+} from './sqlite-driver';
 
 export class SqliteSegmentStore implements SegmentStore {
-  readonly db: Database;
+  readonly db: SqliteDatabase;
   #ttlMs: number;
 
   constructor(
-    db: Database | string = ':memory:',
+    db: SqliteDatabase | string = ':memory:',
     options?: { ttlMs?: number },
   ) {
-    this.db = typeof db === 'string' ? new Database(db) : db;
+    if (typeof db === 'string') {
+      throw new SqliteAdapterRequiredError();
+    }
+    this.db = db;
     this.#ttlMs = options?.ttlMs ?? DEFAULT_SEGMENT_TTL_MS;
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS sync_segments(
         segment_id TEXT PRIMARY KEY, partition TEXT NOT NULL,
+        log_epoch TEXT NOT NULL,
         tbl TEXT NOT NULL, schema_version INTEGER NOT NULL,
         media_type TEXT NOT NULL, scope_digest TEXT NOT NULL,
         as_of_commit_seq INTEGER NOT NULL, row_count INTEGER NOT NULL,
@@ -39,6 +40,14 @@ export class SqliteSegmentStore implements SegmentStore {
         expires_at_ms INTEGER NOT NULL, bytes BLOB NOT NULL
       );
     `);
+    const columns = this.db
+      .query<{ name: string }, []>('PRAGMA table_info(sync_segments)')
+      .all();
+    if (!columns.some((column) => column.name === 'log_epoch')) {
+      this.db.exec(
+        "ALTER TABLE sync_segments ADD COLUMN log_epoch TEXT NOT NULL DEFAULT ''",
+      );
+    }
   }
 
   async put(
@@ -57,14 +66,15 @@ export class SqliteSegmentStore implements SegmentStore {
     this.db
       .query(
         `INSERT OR REPLACE INTO sync_segments(
-          segment_id, partition, tbl, schema_version, media_type,
+          segment_id, partition, log_epoch, tbl, schema_version, media_type,
           scope_digest, as_of_commit_seq, row_count, row_cursor,
           next_row_cursor, byte_length, created_at_ms, expires_at_ms, bytes
-        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+        ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
       )
       .run(
         record.segmentId,
         record.partition,
+        record.logEpoch,
         record.table,
         record.schemaVersion,
         record.mediaType,
@@ -89,6 +99,7 @@ export class SqliteSegmentStore implements SegmentStore {
         {
           segment_id: string;
           partition: string;
+          log_epoch: string;
           tbl: string;
           schema_version: number;
           media_type: string;
@@ -110,6 +121,7 @@ export class SqliteSegmentStore implements SegmentStore {
       record: {
         segmentId: row.segment_id,
         partition: row.partition,
+        logEpoch: row.log_epoch,
         table: row.tbl,
         schemaVersion: row.schema_version,
         mediaType: row.media_type === 'sqlite' ? 'sqlite' : 'rows',
@@ -140,18 +152,19 @@ export class SqliteSegmentStore implements SegmentStore {
           created_at_ms: number;
           expires_at_ms: number;
         },
-        [string, string, number, string, string, number, number]
+        [string, string, string, number, string, string, number, number]
       >(
         `SELECT segment_id, row_count, next_row_cursor, byte_length,
                 created_at_ms, expires_at_ms
          FROM sync_segments
-         WHERE partition=? AND tbl=? AND schema_version=? AND media_type=?
+         WHERE partition=? AND log_epoch=? AND tbl=? AND schema_version=? AND media_type=?
            AND scope_digest=? AND as_of_commit_seq=? AND row_cursor IS NULL
            AND expires_at_ms > ?
          LIMIT 1`,
       )
       .get(
         key.partition,
+        key.logEpoch,
         key.table,
         key.schemaVersion,
         key.mediaType,
@@ -163,6 +176,7 @@ export class SqliteSegmentStore implements SegmentStore {
     return {
       segmentId: row.segment_id,
       partition: key.partition,
+      logEpoch: key.logEpoch,
       table: key.table,
       schemaVersion: key.schemaVersion,
       mediaType: key.mediaType,