@syncular/server 0.15.47 → 0.16.1

package/dist/sqlite-storage.js

@@ -1,3 +1,5 @@
+import { validateCommitPruneQuery } from './prune.js';
+import { StorageQueryError } from './storage-errors.js';
 /**
  * SQLite server storage over the shared synchronous driver.
  *
@@ -199,7 +201,7 @@ export class SqliteServerStorage {
     /** Set by `ensureSchema`: app-table lookup for the relational row store. */
     #tables;
     #schemaVersion;
-    async #serializeReactionWrite(operation) {
+    async #serializeWrite(operation) {
         const previous = this.#transactionTail;
         let release;
         this.#transactionTail = new Promise((resolve) => {
@@ -219,6 +221,12 @@ export class SqliteServerStorage {
         }
         this.db = db;
         this.db.exec(SQLITE_DDL);
+        const clientColumns = this.db
+            .query('PRAGMA table_info("sync_clients")')
+            .all();
+        if (!clientColumns.some((column) => column.name === 'wire_version')) {
+            this.db.exec('ALTER TABLE sync_clients ADD COLUMN wire_version INTEGER NOT NULL DEFAULT 1');
+        }
     }
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name) {
@@ -294,6 +302,74 @@ export class SqliteServerStorage {
         this.#tables = schema.tables;
         this.#schemaVersion = schema.version;
     }
+    async touchPartition(partition, authenticatedAtMs, initialLogEpoch) {
+        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);
+        if (row === null)
+            throw new Error('partition registry write did not persist');
+        return {
+            partition,
+            logEpoch: row.log_epoch,
+            epochRequired: row.epoch_required === 1,
+            lastAuthenticatedAtMs: row.last_authenticated_at_ms,
+        };
+    }
+    async rotatePartitionLogEpoch(partition, logEpoch, authenticatedAtMs) {
+        if (logEpoch.length === 0)
+            throw new Error('log epoch must be non-empty');
+        return this.#serializeWrite(() => {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                this.db
+                    .query(`INSERT INTO sync_partition_registry(
+               partition, log_epoch, epoch_required, last_authenticated_at_ms
+             ) VALUES (?,?,1,?)
+             ON CONFLICT(partition) DO UPDATE SET
+               log_epoch=excluded.log_epoch,
+               epoch_required=1,
+               last_authenticated_at_ms=excluded.last_authenticated_at_ms`)
+                    .run(partition, logEpoch, authenticatedAtMs);
+                this.db
+                    .query('DELETE FROM sync_clients WHERE partition=?')
+                    .run(partition);
+                this.db.exec('COMMIT');
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+            return {
+                partition,
+                logEpoch,
+                epochRequired: true,
+                lastAuthenticatedAtMs: authenticatedAtMs,
+            };
+        });
+    }
+    async listPartitionRegistry() {
+        return this.db
+            .query(`SELECT partition, log_epoch, epoch_required, last_authenticated_at_ms
+           FROM sync_partition_registry ORDER BY partition`)
+            .all()
+            .map((row) => ({
+            partition: row.partition,
+            logEpoch: row.log_epoch,
+            epochRequired: row.epoch_required === 1,
+            lastAuthenticatedAtMs: row.last_authenticated_at_ms,
+        }));
+    }
     /**
      * Migration rewrite: keyset-paged walk of a row table. When `oldLayout` is
      * given every payload re-encodes under
@@ -369,7 +445,7 @@ export class SqliteServerStorage {
         if (this.#tables === undefined) {
             throw new Error('ensureSchema(schema) must run before registered queries');
         }
-        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.sql, query.params, query.tables, this.#tables), partition);
+        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
         const previous = this.#transactionTail;
         let release;
         this.#transactionTail = new Promise((resolve) => {
@@ -399,6 +475,11 @@ export class SqliteServerStorage {
             release();
         }
     }
+    async getPartitionLogEpoch(partition) {
+        return this.db
+            .query('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
+            .get(partition)?.log_epoch;
+    }
     async getHorizonSeq(partition) {
         const row = this.db
             .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
@@ -406,24 +487,52 @@ export class SqliteServerStorage {
         return row?.horizon_seq ?? 0;
     }
     async setHorizonSeq(partition, seq) {
-        this.db
-            .query('INSERT OR IGNORE INTO sync_partitions(partition) VALUES (?)')
-            .run(partition);
-        this.db
-            .query('UPDATE sync_partitions SET horizon_seq=? WHERE partition=?')
-            .run(seq, partition);
+        await this.#serializeWrite(() => {
+            this.db
+                .query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
+        ON CONFLICT(partition) DO UPDATE SET horizon_seq=max(horizon_seq,excluded.horizon_seq)`)
+                .run(partition, seq);
+        });
     }
-    async pruneCommitsThrough(partition, seq) {
-        const removed = this.db
-            .query('DELETE FROM sync_commits WHERE partition=? AND commit_seq<=?')
-            .run(partition, seq);
-        this.db
-            .query('DELETE FROM sync_changes WHERE partition=? AND commit_seq<=?')
-            .run(partition, seq);
-        this.db
-            .query('DELETE FROM sync_change_scopes WHERE partition=? AND commit_seq<=?')
-            .run(partition, seq);
-        return Number(removed.changes);
+    async pruneCommitsThrough(partition, query) {
+        validateCommitPruneQuery(query);
+        return this.#serializeWrite(() => {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                const epoch = this.db
+                    .query('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
+                    .get(partition)?.log_epoch;
+                if (epoch !== query.logEpoch)
+                    throw new StorageQueryError('sync.storage.prune_epoch_mismatch');
+                const previousHorizonSeq = this.db
+                    .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
+                    .get(partition)?.horizon_seq ?? 0;
+                const horizonSeq = Math.max(previousHorizonSeq, query.throughSeq);
+                this.db
+                    .query(`INSERT INTO sync_partitions(partition, horizon_seq) VALUES (?,?)
+          ON CONFLICT(partition) DO UPDATE SET horizon_seq=excluded.horizon_seq`)
+                    .run(partition, horizonSeq);
+                const removed = this.db
+                    .query('DELETE FROM sync_commits WHERE partition=? AND commit_seq<=?')
+                    .run(partition, horizonSeq);
+                this.db
+                    .query('DELETE FROM sync_changes WHERE partition=? AND commit_seq<=?')
+                    .run(partition, horizonSeq);
+                this.db
+                    .query('DELETE FROM sync_change_scopes WHERE partition=? AND commit_seq<=?')
+                    .run(partition, horizonSeq);
+                this.db.exec('COMMIT');
+                return {
+                    previousHorizonSeq,
+                    horizonSeq,
+                    removedCommits: Number(removed.changes),
+                };
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+        });
     }
     async getCommitSeqBefore(partition, createdBeforeMs) {
         const row = this.db
@@ -453,7 +562,7 @@ export class SqliteServerStorage {
     async claimReactions(partition, query) {
         if (query.types.length === 0 || query.limit <= 0)
             return [];
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const typeParams = query.types.map(() => '?').join(',');
             const records = this.db
                 .query(`UPDATE sync_reactions
@@ -479,7 +588,7 @@ export class SqliteServerStorage {
         });
     }
     async completeReaction(partition, idempotencyKey, leaseOwner, completedAtMs) {
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const result = this.db
                 .query(`UPDATE sync_reactions
             SET status='completed', completed_at_ms=?,
@@ -491,7 +600,7 @@ export class SqliteServerStorage {
         });
     }
     async extendReactionLease(partition, idempotencyKey, leaseOwner, leaseExpiresAtMs) {
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const result = this.db
                 .query(`UPDATE sync_reactions SET lease_expires_at_ms=?
           WHERE partition=? AND idempotency_key=?
@@ -502,7 +611,7 @@ export class SqliteServerStorage {
     }
     async failReaction(partition, idempotencyKey, update) {
         const retry = update.retryAtMs !== undefined;
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const result = this.db
                 .query(`UPDATE sync_reactions
             SET status=?, available_at_ms=?, last_failure=?,
@@ -514,7 +623,7 @@ export class SqliteServerStorage {
         });
     }
     async retryReaction(partition, idempotencyKey, nowMs) {
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const result = this.db
                 .query(`UPDATE sync_reactions
             SET status='pending', attempts=0, available_at_ms=?,
@@ -552,7 +661,7 @@ export class SqliteServerStorage {
     async pruneReactions(partition, query) {
         if (query.limit <= 0)
             return { completed: 0, deadLetter: 0 };
-        return this.#serializeReactionWrite(() => {
+        return this.#serializeWrite(() => {
             const records = this.db
                 .query(`DELETE FROM sync_reactions
             WHERE partition=? AND idempotency_key IN (
@@ -659,13 +768,14 @@ export class SqliteServerStorage {
     }
     async getClientRecord(partition, clientId) {
         const record = this.db
-            .query('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? AND client_id=?')
+            .query('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? AND client_id=?')
             .get(partition, clientId);
         if (record === null)
             return undefined;
         return {
             clientId: record.client_id,
             actorId: record.actor_id,
+            wireVersion: record.wire_version,
             cursor: record.cursor,
             updatedAtMs: record.updated_at_ms,
             subscriptions: JSON.parse(record.subscriptions),
@@ -673,8 +783,14 @@ export class SqliteServerStorage {
     }
     async putClientRecord(partition, record) {
         this.db
-            .query('INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?)')
-            .run(partition, record.clientId, record.actorId, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs);
+            .query('INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)')
+            .run(partition, record.clientId, record.actorId, record.wireVersion, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs);
+    }
+    async getActiveClientCursorFloor(partition, cutoffMs) {
+        const row = this.db
+            .query('SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?')
+            .get(partition, cutoffMs);
+        return row.cursor;
     }
     async listClientCursors(partition) {
         const records = this.db
@@ -719,11 +835,12 @@ export class SqliteServerStorage {
     // -- admin/console read surface --------------------------------------------
     async listClientRecords(partition) {
         const records = this.db
-            .query('SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? ORDER BY updated_at_ms DESC')
+            .query('SELECT client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? ORDER BY updated_at_ms DESC')
             .all(partition);
         return records.map((record) => ({
             clientId: record.client_id,
             actorId: record.actor_id,
+            wireVersion: record.wire_version,
             cursor: record.cursor,
             updatedAtMs: record.updated_at_ms,
             subscriptions: JSON.parse(record.subscriptions),
@@ -800,12 +917,6 @@ export class SqliteServerStorage {
         };
     }
     async listPartitions() {
-        // Union: the registry row appears on first commit, the client row on
-        // first pull — a partition with only one of the two still shows up.
-        const rows = this.db
-            .query(`SELECT partition FROM sync_partitions
-         UNION SELECT partition FROM sync_clients ORDER BY partition`)
-            .all();
-        return rows.map((r) => r.partition);
+        return (await this.listPartitionRegistry()).map((entry) => entry.partition);
     }
 }

package/dist/storage-errors.d.ts

@@ -9,7 +9,7 @@ export declare class StorageConstraintError extends Error {
     constructor(cause: unknown, opIndex?: number);
 }
 /** Stable, privacy-safe failures for trusted server storage queries. */
-export type StorageQueryErrorCode = 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit';
+export type StorageQueryErrorCode = 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor';
 /**
  * Host-only query error. Messages never include identifiers, values, SQL,
  * paths, or row data; callers branch on `code`, never message text.

package/dist/storage-errors.js

@@ -12,6 +12,9 @@ export class StorageConstraintError extends Error {
     }
 }
 const STORAGE_QUERY_MESSAGES = {
+    'sync.storage.prune_epoch_mismatch': 'partition log epoch changed; recompute retention inputs',
+    'sync.storage.partition_unregistered': 'pruning requires a registered partition',
+    'sync.storage.invalid_prune_cursor': 'pruning requires a non-negative safe integer cursor and a non-empty log epoch',
     'sync.storage.scan_requires_scope': 'scope-indexed row scans require at least one scope variable',
     'sync.storage.index_not_found': 'trusted row lookup requires a declared relational index',
     'sync.storage.index_not_materialized': 'trusted row lookup requires a materialized relational table',

package/dist/storage.d.ts

@@ -1,3 +1,4 @@
+import type { AuthoritativeRelationPlan } from './authoritative-query.js';
 /**
  * Storage interface (defined by the SPEC's needs, implementation-agnostic).
  *
@@ -18,6 +19,15 @@
  */
 import type { PushOperationResult, RowValue, ScopeMap } from '@syncular/core';
 import type { CompiledSchema } from './schema.js';
+export interface CommitPruneQuery {
+    readonly logEpoch: string;
+    readonly throughSeq: number;
+}
+export interface CommitPruneResult {
+    readonly previousHorizonSeq: number;
+    readonly horizonSeq: number;
+    readonly removedCommits: number;
+}
 /** The current stored state of a synced row. */
 export interface StoredRow {
     readonly rowId: string;
@@ -144,6 +154,8 @@ export interface ClientSubscription {
 export interface ClientRecord {
     readonly clientId: string;
     readonly actorId: string;
+    /** SSP2 version last accepted from this client; selects realtime deltas. */
+    readonly wireVersion: number;
     /** Minimum `nextCursor` across the last pull's active subscriptions. */
     readonly cursor: number;
     readonly updatedAtMs: number;
@@ -195,6 +207,13 @@ export interface ClientCursorInfo {
     readonly cursor: number;
     readonly updatedAtMs: number;
 }
+/** Durable partition identity refreshed after host authentication (§2.1). */
+export interface PartitionRegistryEntry {
+    readonly partition: string;
+    readonly logEpoch: string;
+    readonly epochRequired: boolean;
+    readonly lastAuthenticatedAtMs: number;
+}
 /**
  * Commit-log metadata (no change payloads) for the admin/console read
  * surface. `changeCount` is the number of changes the commit carries;
@@ -235,7 +254,7 @@ export interface ScopeActivityQuery {
 export type AuthoritativeQueryValue = string | number | bigint | boolean | Uint8Array | null;
 export interface AuthoritativeQueryRequest {
     /** Generated, positional SQLite-family SQL. It never comes from the request. */
-    readonly sql: string;
+    readonly plan: AuthoritativeRelationPlan;
     readonly params: readonly AuthoritativeQueryValue[];
     /** Generated dependency set, used to validate and partition every relation. */
     readonly tables: readonly string[];
@@ -340,15 +359,24 @@ export interface ServerStorage {
      * lazily as a defensive backstop.
      */
     ensureSchema(schema: CompiledSchema): Promise<void>;
+    /** Create or refresh the authenticated partition registry row (§2.1). */
+    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>;
+    /** Registry entries ordered by partition for maintenance loops. */
+    listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
+    /** Read continuity without refreshing authenticated activity. */
+    getPartitionLogEpoch(partition: string): Promise<string | undefined>;
     begin(partition: string): Promise<StorageTransaction>;
     getMaxCommitSeq(partition: string): Promise<number>;
     getHorizonSeq(partition: string): Promise<number>;
+    /** Monotonic within the current epoch; use atomic pruning for maintenance. */
     setHorizonSeq(partition: string, seq: number): Promise<void>;
     /**
-     * Deletes commits with `commitSeq <= seq` (log, changes, scope index).
-     * Returns the number of commits removed (ops observability).
+     * Atomically verifies the log epoch, advances the horizon monotonically,
+     * and removes log/change/scope records through the effective horizon.
      */
-    pruneCommitsThrough(partition: string, seq: number): Promise<number>;
+    pruneCommitsThrough(partition: string, query: CommitPruneQuery): Promise<CommitPruneResult>;
     /** Newest commitSeq created strictly before the timestamp; 0 if none. */
     getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
     getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
@@ -397,7 +425,9 @@ export interface ServerStorage {
     scanRowsByIndex?(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;
     getClientRecord(partition: string, clientId: string): Promise<ClientRecord | undefined>;
     putClientRecord(partition: string, record: ClientRecord): Promise<void>;
-    /** Cursor records feeding the §4.6 retention watermark. */
+    /** Minimum cursor with updatedAtMs >= cutoff; null when none are active. */
+    getActiveClientCursorFloor(partition: string, cutoffMs: number): Promise<number | null>;
+    /** Cursor records for client listings and administrative counts. */
     listClientCursors(partition: string): Promise<ClientCursorInfo[]>;
     /**
      * Blob reference index reads (§5.9.4) — ADDITIVE, optional (mirrors the
@@ -427,10 +457,8 @@ export interface ServerStorage {
      * change scope index (never a log scan).
      * `getRowScopes`: the (table, rowId) row's current server_version and
      * stored scopes without decoding its payload — the row inspector.
-     * `listPartitions`: every partition this storage holds state for — the
-     * union of the partition registry (commit log counters) and client
-     * records, sorted. Powers the console's fleet view / partition picker;
-     * deliberately NOT partition-scoped (the one cross-partition read).
+     * `listPartitions`: the partition-only compatibility view of
+     * `listPartitionRegistry`, sorted.
      */
     listClientRecords?(partition: string): Promise<ClientRecord[]>;
     listCommitMetadata?(partition: string, query: CommitMetadataQuery): Promise<CommitMetadata[]>;
@@ -439,7 +467,7 @@ export interface ServerStorage {
         serverVersion: number;
         scopes: Record<string, string>;
     } | undefined>;
-    listPartitions?(): Promise<string[]>;
+    listPartitions(): Promise<string[]>;
 }
 /** A row referencing a blob, with the scopes needed to authorize download. */
 export interface BlobReferencingRow {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.15.47",
+  "version": "0.16.1",
   "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.15.47"
+    "@syncular/core": "0.16.1"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/admin.ts

@@ -396,12 +396,10 @@ export class SyncularAdmin {
     const nowMs = this.#clock();
     const maxCommitSeq = await this.#storage.getMaxCommitSeq(partition);
     const horizonSeq = await this.#storage.getHorizonSeq(partition);
-    const cursors = await this.#storage.listClientCursors(partition);
-    const activeCursors = cursors
-      .filter((c) => c.updatedAtMs >= nowMs - this.#retention.activeWindowMs)
-      .map((c) => c.cursor);
-    const activeCursorFloor =
-      activeCursors.length > 0 ? Math.min(...activeCursors) : null;
+    const activeCursorFloor = await this.#storage.getActiveClientCursorFloor(
+      partition,
+      nowMs - this.#retention.activeWindowMs,
+    );
     const cursorFloor = activeCursorFloor ?? Number.MAX_SAFE_INTEGER;
     const forcedSeq = await this.#storage.getCommitSeqBefore(
       partition,
@@ -520,17 +518,11 @@ export class SyncularAdmin {
     };
   }
 
-  /**
-   * Every partition the storage knows (commit log + client records) — the
-   * fleet-view backing and the console's partition picker. Fails loud when
-   * the backend omits the optional `listPartitions`.
-   */
+  /** Every authenticated partition in the storage-backed registry. */
   async listPartitions(): Promise<string[]> {
-    const list = required(
-      this.#storage.listPartitions?.bind(this.#storage),
-      'storage',
+    return (await this.#storage.listPartitionRegistry()).map(
+      (entry) => entry.partition,
     );
-    return list();
   }
 
   /**