@syncular/server 0.0.1-72 → 0.0.1-73

package/dist/dialect/base.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @syncular/server - Base Server Sync Dialect
+ *
+ * Abstract base class that implements shared query methods for all
+ * database-specific sync dialect implementations.
+ */
+import type { ScopeValues, StoredScopes, SyncOp } from '@syncular/core';
+import type { Kysely, RawBuilder, Transaction } from 'kysely';
+import type { SyncChangeRow, SyncCommitRow, SyncCoreDb } from '../schema';
+import type { DbExecutor, ServerSyncDialect } from './types';
+/**
+ * Abstract base class for server sync dialects.
+ *
+ * Implements methods that are identical across dialects (pure SQL with no
+ * dialect-specific syntax) and methods that differ only in trivial SQL
+ * fragments (IN vs ANY, jsonb casts). Dialect-specific fragments are
+ * provided via small abstract hook methods.
+ *
+ * Genuinely different methods (DDL, transaction control, scope filtering,
+ * compaction, streaming) remain abstract for each dialect to implement.
+ */
+export declare abstract class BaseServerSyncDialect implements ServerSyncDialect {
+    abstract readonly name: string;
+    abstract readonly supportsForUpdate: boolean;
+    abstract readonly supportsSavepoints: boolean;
+    /**
+     * Build a SQL fragment for "column IN/= list of numbers".
+     * SQLite: `IN (1, 2, 3)` via sql.join
+     * Postgres: `= ANY(ARRAY[1,2,3]::bigint[])`
+     */
+    protected abstract buildNumberListFilter(values: number[]): RawBuilder<unknown>;
+    /**
+     * Build a SQL fragment for "column IN/= list of strings".
+     * SQLite: `IN ('a', 'b')` via sql.join
+     * Postgres: `= ANY(ARRAY['a','b']::text[])`
+     */
+    protected abstract buildStringListFilter(values: string[]): RawBuilder<unknown>;
+    abstract ensureSyncSchema<DB extends SyncCoreDb>(db: Kysely<DB>): Promise<void>;
+    abstract ensureConsoleSchema?<DB extends SyncCoreDb>(db: Kysely<DB>): Promise<void>;
+    abstract executeInTransaction<DB extends SyncCoreDb, T>(db: Kysely<DB>, fn: (executor: DbExecutor<DB>) => Promise<T>): Promise<T>;
+    abstract setRepeatableRead<DB extends SyncCoreDb>(trx: DbExecutor<DB>): Promise<void>;
+    abstract readChangesForCommits<DB extends SyncCoreDb>(db: DbExecutor<DB>, args: {
+        commitSeqs: number[];
+        table: string;
+        scopes: ScopeValues;
+        partitionId?: string;
+    }): Promise<SyncChangeRow[]>;
+    abstract readIncrementalPullRows<DB extends SyncCoreDb>(db: DbExecutor<DB>, args: {
+        table: string;
+        scopes: ScopeValues;
+        cursor: number;
+        limitCommits: number;
+        partitionId?: string;
+    }): Promise<Array<{
+        commit_seq: number;
+        actor_id: string;
+        created_at: string;
+        change_id: number;
+        table: string;
+        row_id: string;
+        op: SyncOp;
+        row_json: unknown | null;
+        row_version: number | null;
+        scopes: StoredScopes;
+    }>>;
+    abstract compactChanges<DB extends SyncCoreDb>(db: DbExecutor<DB>, args: {
+        fullHistoryHours: number;
+    }): Promise<number>;
+    abstract scopesToDb(scopes: StoredScopes): unknown;
+    abstract dbToArray(value: unknown): string[];
+    abstract arrayToDb(values: string[]): unknown;
+    readMaxCommitSeq<DB extends SyncCoreDb>(db: Kysely<DB> | Transaction<DB>, options?: {
+        partitionId?: string;
+    }): Promise<number>;
+    readMinCommitSeq<DB extends SyncCoreDb>(db: Kysely<DB> | Transaction<DB>, options?: {
+        partitionId?: string;
+    }): Promise<number>;
+    readAffectedTablesFromChanges<DB extends SyncCoreDb>(db: Kysely<DB> | Transaction<DB>, commitSeq: number, options?: {
+        partitionId?: string;
+    }): Promise<string[]>;
+    dbToScopes(value: unknown): StoredScopes;
+    readCommitSeqsForPull<DB extends SyncCoreDb>(db: Kysely<DB> | Transaction<DB>, args: {
+        cursor: number;
+        limitCommits: number;
+        tables: string[];
+        partitionId?: string;
+    }): Promise<number[]>;
+    readCommits<DB extends SyncCoreDb>(db: Kysely<DB> | Transaction<DB>, commitSeqs: number[], options?: {
+        partitionId?: string;
+    }): Promise<SyncCommitRow[]>;
+    recordClientCursor<DB extends SyncCoreDb>(db: Kysely<DB> | Transaction<DB>, args: {
+        partitionId?: string;
+        clientId: string;
+        actorId: string;
+        cursor: number;
+        effectiveScopes: ScopeValues;
+    }): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/dialect/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/dialect/base.ts"],"names":[],"mappings":"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"}

package/dist/dialect/base.js

@@ -0,0 +1,112 @@
+/**
+ * @syncular/server - Base Server Sync Dialect
+ *
+ * Abstract base class that implements shared query methods for all
+ * database-specific sync dialect implementations.
+ */
+import { sql } from 'kysely';
+import { coerceIsoString, coerceNumber, parseScopes } from './helpers';
+/**
+ * Abstract base class for server sync dialects.
+ *
+ * Implements methods that are identical across dialects (pure SQL with no
+ * dialect-specific syntax) and methods that differ only in trivial SQL
+ * fragments (IN vs ANY, jsonb casts). Dialect-specific fragments are
+ * provided via small abstract hook methods.
+ *
+ * Genuinely different methods (DDL, transaction control, scope filtering,
+ * compaction, streaming) remain abstract for each dialect to implement.
+ */
+export class BaseServerSyncDialect {
+    // ===========================================================================
+    // Concrete methods (identical SQL across dialects)
+    // ===========================================================================
+    async readMaxCommitSeq(db, options) {
+        const partitionId = options?.partitionId ?? 'default';
+        const res = await sql `
+      SELECT max(commit_seq) as max_seq
+      FROM sync_commits
+      WHERE partition_id = ${partitionId}
+    `.execute(db);
+        return coerceNumber(res.rows[0]?.max_seq) ?? 0;
+    }
+    async readMinCommitSeq(db, options) {
+        const partitionId = options?.partitionId ?? 'default';
+        const res = await sql `
+      SELECT min(commit_seq) as min_seq
+      FROM sync_commits
+      WHERE partition_id = ${partitionId}
+    `.execute(db);
+        return coerceNumber(res.rows[0]?.min_seq) ?? 0;
+    }
+    async readAffectedTablesFromChanges(db, commitSeq, options) {
+        const partitionId = options?.partitionId ?? 'default';
+        const res = await sql `
+      SELECT DISTINCT "table"
+      FROM sync_changes
+      WHERE commit_seq = ${commitSeq}
+        AND partition_id = ${partitionId}
+    `.execute(db);
+        return res.rows
+            .map((r) => r.table)
+            .filter((t) => typeof t === 'string' && t.length > 0);
+    }
+    dbToScopes(value) {
+        return parseScopes(value);
+    }
+    // ===========================================================================
+    // Concrete methods using hooks (trivial dialect diffs)
+    // ===========================================================================
+    async readCommitSeqsForPull(db, args) {
+        const partitionId = args.partitionId ?? 'default';
+        if (args.tables.length === 0)
+            return [];
+        const tablesFilter = this.buildStringListFilter(args.tables);
+        const res = await sql `
+      SELECT DISTINCT commit_seq
+      FROM sync_table_commits
+      WHERE partition_id = ${partitionId}
+        AND "table" ${tablesFilter}
+        AND commit_seq > ${args.cursor}
+      ORDER BY commit_seq ASC
+      LIMIT ${args.limitCommits}
+    `.execute(db);
+        return res.rows
+            .map((r) => coerceNumber(r.commit_seq))
+            .filter((n) => typeof n === 'number' && Number.isFinite(n) && n > args.cursor);
+    }
+    async readCommits(db, commitSeqs, options) {
+        const partitionId = options?.partitionId ?? 'default';
+        if (commitSeqs.length === 0)
+            return [];
+        const seqsFilter = this.buildNumberListFilter(commitSeqs);
+        const res = await sql `
+      SELECT commit_seq, actor_id, created_at, result_json
+      FROM sync_commits
+      WHERE commit_seq ${seqsFilter}
+        AND partition_id = ${partitionId}
+      ORDER BY commit_seq ASC
+    `.execute(db);
+        return res.rows.map((row) => ({
+            commit_seq: coerceNumber(row.commit_seq) ?? 0,
+            actor_id: row.actor_id,
+            created_at: coerceIsoString(row.created_at),
+            result_json: row.result_json ?? null,
+        }));
+    }
+    async recordClientCursor(db, args) {
+        const partitionId = args.partitionId ?? 'default';
+        const now = new Date().toISOString();
+        const scopesJson = JSON.stringify(args.effectiveScopes);
+        await sql `
+      INSERT INTO sync_client_cursors (partition_id, client_id, actor_id, cursor, effective_scopes, updated_at)
+      VALUES (${partitionId}, ${args.clientId}, ${args.actorId}, ${args.cursor}, ${scopesJson}, ${now})
+      ON CONFLICT(partition_id, client_id) DO UPDATE SET
+        actor_id = ${args.actorId},
+        cursor = ${args.cursor},
+        effective_scopes = ${scopesJson},
+        updated_at = ${now}
+    `.execute(db);
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/dialect/base.js.map

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

package/dist/dialect/helpers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @syncular/server - Shared dialect helpers
+ *
+ * Pure helper functions used by all server sync dialect implementations.
+ */
+import type { StoredScopes } from '@syncular/core';
+export declare function coerceNumber(value: unknown): number | null;
+export declare function coerceIsoString(value: unknown): string;
+export declare function parseScopes(value: unknown): StoredScopes;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/dialect/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/dialect/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAU1D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAItD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAkCxD"}

package/dist/dialect/helpers.js

@@ -0,0 +1,59 @@
+/**
+ * @syncular/server - Shared dialect helpers
+ *
+ * Pure helper functions used by all server sync dialect implementations.
+ */
+export function coerceNumber(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'bigint')
+        return Number.isFinite(Number(value)) ? Number(value) : null;
+    if (typeof value === 'string') {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : null;
+    }
+    return null;
+}
+export function coerceIsoString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Date)
+        return value.toISOString();
+    return String(value);
+}
+export function parseScopes(value) {
+    if (value === null || value === undefined)
+        return {};
+    if (typeof value === 'object' && !Array.isArray(value)) {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (typeof v === 'string') {
+                result[k] = v;
+            }
+        }
+        return result;
+    }
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === 'object' &&
+                parsed !== null &&
+                !Array.isArray(parsed)) {
+                const result = {};
+                for (const [k, v] of Object.entries(parsed)) {
+                    if (typeof v === 'string') {
+                        result[k] = v;
+                    }
+                }
+                return result;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return {};
+}
+//# sourceMappingURL=helpers.js.map

package/dist/dialect/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/dialect/helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,UAAU,YAAY,CAAC,KAAc,EAAiB;IAC1D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5E,IAAI,OAAO,KAAK,KAAK,QAAQ;QAC3B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC;AAAA,CACb;AAED,MAAM,UAAU,eAAe,CAAC,KAAc,EAAU;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;IACtD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AAAA,CACtB;AAED,MAAM,UAAU,WAAW,CAAC,KAAc,EAAgB;IACxD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,MAAM,GAAiB,EAAE,CAAC;QAChC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YACtE,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC1B,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAChB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACjC,IACE,OAAO,MAAM,KAAK,QAAQ;gBAC1B,MAAM,KAAK,IAAI;gBACf,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EACtB,CAAC;gBACD,MAAM,MAAM,GAAiB,EAAE,CAAC;gBAChC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CACjC,MAAiC,CAClC,EAAE,CAAC;oBACF,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;wBAC1B,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;oBAChB,CAAC;gBACH,CAAC;gBACD,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AAAA,CACX"}

package/dist/dialect/index.d.ts

@@ -1,5 +1,7 @@
 /**
  * @syncular/server - Dialect exports
  */
+export * from './base';
+export * from './helpers';
 export * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/dialect/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dialect/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dialect/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/dialect/index.js

@@ -1,5 +1,7 @@
 /**
  * @syncular/server - Dialect exports
  */
+export * from './base';
+export * from './helpers';
 export * from './types';
 //# sourceMappingURL=index.js.map

package/dist/dialect/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dialect/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dialect/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.0.1-72",
+  "version": "0.0.1-73",
   "description": "Server-side sync engine with push/pull, pruning, and snapshot support",
   "license": "MIT",
   "author": "Benjamin Kniffler",

package/src/dialect/base.ts

@@ -0,0 +1,262 @@
+/**
+ * @syncular/server - Base Server Sync Dialect
+ *
+ * Abstract base class that implements shared query methods for all
+ * database-specific sync dialect implementations.
+ */
+
+import type { ScopeValues, StoredScopes, SyncOp } from '@syncular/core';
+import type { Kysely, RawBuilder, Transaction } from 'kysely';
+import { sql } from 'kysely';
+import type { SyncChangeRow, SyncCommitRow, SyncCoreDb } from '../schema';
+import { coerceIsoString, coerceNumber, parseScopes } from './helpers';
+import type { DbExecutor, ServerSyncDialect } from './types';
+
+/**
+ * Abstract base class for server sync dialects.
+ *
+ * Implements methods that are identical across dialects (pure SQL with no
+ * dialect-specific syntax) and methods that differ only in trivial SQL
+ * fragments (IN vs ANY, jsonb casts). Dialect-specific fragments are
+ * provided via small abstract hook methods.
+ *
+ * Genuinely different methods (DDL, transaction control, scope filtering,
+ * compaction, streaming) remain abstract for each dialect to implement.
+ */
+export abstract class BaseServerSyncDialect implements ServerSyncDialect {
+  abstract readonly name: string;
+  abstract readonly supportsForUpdate: boolean;
+  abstract readonly supportsSavepoints: boolean;
+
+  // ===========================================================================
+  // Abstract SQL fragment hooks
+  // ===========================================================================
+
+  /**
+   * Build a SQL fragment for "column IN/= list of numbers".
+   * SQLite: `IN (1, 2, 3)` via sql.join
+   * Postgres: `= ANY(ARRAY[1,2,3]::bigint[])`
+   */
+  protected abstract buildNumberListFilter(
+    values: number[]
+  ): RawBuilder<unknown>;
+
+  /**
+   * Build a SQL fragment for "column IN/= list of strings".
+   * SQLite: `IN ('a', 'b')` via sql.join
+   * Postgres: `= ANY(ARRAY['a','b']::text[])`
+   */
+  protected abstract buildStringListFilter(
+    values: string[]
+  ): RawBuilder<unknown>;
+
+  // ===========================================================================
+  // Abstract methods (genuinely different implementations)
+  // ===========================================================================
+
+  abstract ensureSyncSchema<DB extends SyncCoreDb>(
+    db: Kysely<DB>
+  ): Promise<void>;
+
+  abstract ensureConsoleSchema?<DB extends SyncCoreDb>(
+    db: Kysely<DB>
+  ): Promise<void>;
+
+  abstract executeInTransaction<DB extends SyncCoreDb, T>(
+    db: Kysely<DB>,
+    fn: (executor: DbExecutor<DB>) => Promise<T>
+  ): Promise<T>;
+
+  abstract setRepeatableRead<DB extends SyncCoreDb>(
+    trx: DbExecutor<DB>
+  ): Promise<void>;
+
+  abstract readChangesForCommits<DB extends SyncCoreDb>(
+    db: DbExecutor<DB>,
+    args: {
+      commitSeqs: number[];
+      table: string;
+      scopes: ScopeValues;
+      partitionId?: string;
+    }
+  ): Promise<SyncChangeRow[]>;
+
+  abstract readIncrementalPullRows<DB extends SyncCoreDb>(
+    db: DbExecutor<DB>,
+    args: {
+      table: string;
+      scopes: ScopeValues;
+      cursor: number;
+      limitCommits: number;
+      partitionId?: string;
+    }
+  ): Promise<
+    Array<{
+      commit_seq: number;
+      actor_id: string;
+      created_at: string;
+      change_id: number;
+      table: string;
+      row_id: string;
+      op: SyncOp;
+      row_json: unknown | null;
+      row_version: number | null;
+      scopes: StoredScopes;
+    }>
+  >;
+
+  abstract compactChanges<DB extends SyncCoreDb>(
+    db: DbExecutor<DB>,
+    args: { fullHistoryHours: number }
+  ): Promise<number>;
+
+  abstract scopesToDb(scopes: StoredScopes): unknown;
+  abstract dbToArray(value: unknown): string[];
+  abstract arrayToDb(values: string[]): unknown;
+
+  // ===========================================================================
+  // Concrete methods (identical SQL across dialects)
+  // ===========================================================================
+
+  async readMaxCommitSeq<DB extends SyncCoreDb>(
+    db: Kysely<DB> | Transaction<DB>,
+    options?: { partitionId?: string }
+  ): Promise<number> {
+    const partitionId = options?.partitionId ?? 'default';
+    const res = await sql<{ max_seq: unknown }>`
+      SELECT max(commit_seq) as max_seq
+      FROM sync_commits
+      WHERE partition_id = ${partitionId}
+    `.execute(db);
+
+    return coerceNumber(res.rows[0]?.max_seq) ?? 0;
+  }
+
+  async readMinCommitSeq<DB extends SyncCoreDb>(
+    db: Kysely<DB> | Transaction<DB>,
+    options?: { partitionId?: string }
+  ): Promise<number> {
+    const partitionId = options?.partitionId ?? 'default';
+    const res = await sql<{ min_seq: unknown }>`
+      SELECT min(commit_seq) as min_seq
+      FROM sync_commits
+      WHERE partition_id = ${partitionId}
+    `.execute(db);
+
+    return coerceNumber(res.rows[0]?.min_seq) ?? 0;
+  }
+
+  async readAffectedTablesFromChanges<DB extends SyncCoreDb>(
+    db: Kysely<DB> | Transaction<DB>,
+    commitSeq: number,
+    options?: { partitionId?: string }
+  ): Promise<string[]> {
+    const partitionId = options?.partitionId ?? 'default';
+    const res = await sql<{ table: string }>`
+      SELECT DISTINCT "table"
+      FROM sync_changes
+      WHERE commit_seq = ${commitSeq}
+        AND partition_id = ${partitionId}
+    `.execute(db);
+
+    return res.rows
+      .map((r) => r.table)
+      .filter((t): t is string => typeof t === 'string' && t.length > 0);
+  }
+
+  dbToScopes(value: unknown): StoredScopes {
+    return parseScopes(value);
+  }
+
+  // ===========================================================================
+  // Concrete methods using hooks (trivial dialect diffs)
+  // ===========================================================================
+
+  async readCommitSeqsForPull<DB extends SyncCoreDb>(
+    db: Kysely<DB> | Transaction<DB>,
+    args: {
+      cursor: number;
+      limitCommits: number;
+      tables: string[];
+      partitionId?: string;
+    }
+  ): Promise<number[]> {
+    const partitionId = args.partitionId ?? 'default';
+    if (args.tables.length === 0) return [];
+
+    const tablesFilter = this.buildStringListFilter(args.tables);
+
+    const res = await sql<{ commit_seq: unknown }>`
+      SELECT DISTINCT commit_seq
+      FROM sync_table_commits
+      WHERE partition_id = ${partitionId}
+        AND "table" ${tablesFilter}
+        AND commit_seq > ${args.cursor}
+      ORDER BY commit_seq ASC
+      LIMIT ${args.limitCommits}
+    `.execute(db);
+
+    return res.rows
+      .map((r) => coerceNumber(r.commit_seq))
+      .filter(
+        (n): n is number =>
+          typeof n === 'number' && Number.isFinite(n) && n > args.cursor
+      );
+  }
+
+  async readCommits<DB extends SyncCoreDb>(
+    db: Kysely<DB> | Transaction<DB>,
+    commitSeqs: number[],
+    options?: { partitionId?: string }
+  ): Promise<SyncCommitRow[]> {
+    const partitionId = options?.partitionId ?? 'default';
+    if (commitSeqs.length === 0) return [];
+
+    const seqsFilter = this.buildNumberListFilter(commitSeqs);
+
+    const res = await sql<{
+      commit_seq: unknown;
+      actor_id: string;
+      created_at: unknown;
+      result_json: unknown | null;
+    }>`
+      SELECT commit_seq, actor_id, created_at, result_json
+      FROM sync_commits
+      WHERE commit_seq ${seqsFilter}
+        AND partition_id = ${partitionId}
+      ORDER BY commit_seq ASC
+    `.execute(db);
+
+    return res.rows.map((row) => ({
+      commit_seq: coerceNumber(row.commit_seq) ?? 0,
+      actor_id: row.actor_id,
+      created_at: coerceIsoString(row.created_at),
+      result_json: row.result_json ?? null,
+    }));
+  }
+
+  async recordClientCursor<DB extends SyncCoreDb>(
+    db: Kysely<DB> | Transaction<DB>,
+    args: {
+      partitionId?: string;
+      clientId: string;
+      actorId: string;
+      cursor: number;
+      effectiveScopes: ScopeValues;
+    }
+  ): Promise<void> {
+    const partitionId = args.partitionId ?? 'default';
+    const now = new Date().toISOString();
+    const scopesJson = JSON.stringify(args.effectiveScopes);
+
+    await sql`
+      INSERT INTO sync_client_cursors (partition_id, client_id, actor_id, cursor, effective_scopes, updated_at)
+      VALUES (${partitionId}, ${args.clientId}, ${args.actorId}, ${args.cursor}, ${scopesJson}, ${now})
+      ON CONFLICT(partition_id, client_id) DO UPDATE SET
+        actor_id = ${args.actorId},
+        cursor = ${args.cursor},
+        effective_scopes = ${scopesJson},
+        updated_at = ${now}
+    `.execute(db);
+  }
+}

package/src/dialect/helpers.ts

@@ -0,0 +1,61 @@
+/**
+ * @syncular/server - Shared dialect helpers
+ *
+ * Pure helper functions used by all server sync dialect implementations.
+ */
+
+import type { StoredScopes } from '@syncular/core';
+
+export function coerceNumber(value: unknown): number | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  if (typeof value === 'bigint')
+    return Number.isFinite(Number(value)) ? Number(value) : null;
+  if (typeof value === 'string') {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+export function coerceIsoString(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (value instanceof Date) return value.toISOString();
+  return String(value);
+}
+
+export function parseScopes(value: unknown): StoredScopes {
+  if (value === null || value === undefined) return {};
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    const result: StoredScopes = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (typeof v === 'string') {
+        result[k] = v;
+      }
+    }
+    return result;
+  }
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value);
+      if (
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        !Array.isArray(parsed)
+      ) {
+        const result: StoredScopes = {};
+        for (const [k, v] of Object.entries(
+          parsed as Record<string, unknown>
+        )) {
+          if (typeof v === 'string') {
+            result[k] = v;
+          }
+        }
+        return result;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return {};
+}

package/src/dialect/index.ts

@@ -2,4 +2,6 @@
  * @syncular/server - Dialect exports
  */
 
+export * from './base';
+export * from './helpers';
 export * from './types';