@syncular/server 0.15.47 → 0.16.1

package/src/sqlite-storage.ts

@@ -1,3 +1,6 @@
+import { validateCommitPruneQuery } from './prune';
+import { StorageQueryError } from './storage-errors';
+import type { CommitPruneQuery, CommitPruneResult } from './storage';
 /**
  * SQLite server storage over the shared synchronous driver.
  *
@@ -62,6 +65,7 @@ import type {
   IndexRowScanQuery,
   NewCommit,
   NewReaction,
+  PartitionRegistryEntry,
   PrunedReactionCounts,
   ReactionClaimQuery,
   ReactionFailure,
@@ -389,7 +393,7 @@ export class SqliteServerStorage implements ServerStorage {
   #tables: ReadonlyMap<string, CompiledTable> | undefined;
   #schemaVersion: number | undefined;
 
-  async #serializeReactionWrite<T>(operation: () => T): Promise<T> {
+  async #serializeWrite<T>(operation: () => T): Promise<T> {
     const previous = this.#transactionTail;
     let release!: () => void;
     this.#transactionTail = new Promise<void>((resolve) => {
@@ -409,6 +413,14 @@ export class SqliteServerStorage implements ServerStorage {
     }
     this.db = db;
     this.db.exec(SQLITE_DDL);
+    const clientColumns = this.db
+      .query<{ name: string }, []>('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`. */
@@ -504,6 +516,106 @@ export class SqliteServerStorage implements ServerStorage {
     this.#schemaVersion = schema.version;
   }
 
+  async touchPartition(
+    partition: string,
+    authenticatedAtMs: number,
+    initialLogEpoch: string,
+  ): Promise<PartitionRegistryEntry> {
+    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<
+        {
+          log_epoch: string;
+          epoch_required: number;
+          last_authenticated_at_ms: number;
+        },
+        [string]
+      >(
+        `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: string,
+    logEpoch: string,
+    authenticatedAtMs: number,
+  ): Promise<PartitionRegistryEntry> {
+    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(): Promise<PartitionRegistryEntry[]> {
+    return this.db
+      .query<
+        {
+          partition: string;
+          log_epoch: string;
+          epoch_required: number;
+          last_authenticated_at_ms: number;
+        },
+        []
+      >(
+        `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
@@ -616,7 +728,7 @@ export class SqliteServerStorage implements ServerStorage {
     }
     const prepared = bindAuthoritativePartition(
       prepareAuthoritativeQuery(
-        query.sql,
+        query.plan,
         query.params,
         query.tables,
         this.#tables,
@@ -654,6 +766,14 @@ export class SqliteServerStorage implements ServerStorage {
     }
   }
 
+  async getPartitionLogEpoch(partition: string): Promise<string | undefined> {
+    return this.db
+      .query<{ log_epoch: string }, [string]>(
+        'SELECT log_epoch FROM sync_partition_registry WHERE partition=?',
+      )
+      .get(partition)?.log_epoch;
+  }
+
   async getHorizonSeq(partition: string): Promise<number> {
     const row = this.db
       .query<{ horizon_seq: number }, [string]>(
@@ -664,27 +784,62 @@ export class SqliteServerStorage implements ServerStorage {
   }
 
   async setHorizonSeq(partition: string, seq: number): Promise<void> {
-    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: string, seq: number): Promise<number> {
-    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: string,
+    query: CommitPruneQuery,
+  ): Promise<CommitPruneResult> {
+    validateCommitPruneQuery(query);
+    return this.#serializeWrite(() => {
+      this.db.exec('BEGIN IMMEDIATE');
+      try {
+        const epoch = this.db
+          .query<{ log_epoch: string }, [string]>(
+            '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<{ horizon_seq: number }, [string]>(
+              '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(
@@ -738,7 +893,7 @@ export class SqliteServerStorage implements ServerStorage {
     query: ReactionClaimQuery,
   ): Promise<StoredReaction[]> {
     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<SqliteReactionRecord, (string | number)[]>(
@@ -786,7 +941,7 @@ export class SqliteServerStorage implements ServerStorage {
     leaseOwner: string,
     completedAtMs: number,
   ): Promise<boolean> {
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const result = this.db
         .query(
           `UPDATE sync_reactions
@@ -806,7 +961,7 @@ export class SqliteServerStorage implements ServerStorage {
     leaseOwner: string,
     leaseExpiresAtMs: number,
   ): Promise<boolean> {
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const result = this.db
         .query(
           `UPDATE sync_reactions SET lease_expires_at_ms=?
@@ -824,7 +979,7 @@ export class SqliteServerStorage implements ServerStorage {
     update: ReactionFailureUpdate,
   ): Promise<boolean> {
     const retry = update.retryAtMs !== undefined;
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const result = this.db
         .query(
           `UPDATE sync_reactions
@@ -850,7 +1005,7 @@ export class SqliteServerStorage implements ServerStorage {
     idempotencyKey: string,
     nowMs: number,
   ): Promise<boolean> {
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const result = this.db
         .query(
           `UPDATE sync_reactions
@@ -905,7 +1060,7 @@ export class SqliteServerStorage implements ServerStorage {
     query: ReactionPruneQuery,
   ): Promise<PrunedReactionCounts> {
     if (query.limit <= 0) return { completed: 0, deadLetter: 0 };
-    return this.#serializeReactionWrite(() => {
+    return this.#serializeWrite(() => {
       const records = this.db
         .query<
           { status: 'completed' | 'dead-letter' },
@@ -1077,19 +1232,21 @@ export class SqliteServerStorage implements ServerStorage {
         {
           client_id: string;
           actor_id: string;
+          wire_version: number;
           cursor: number;
           subscriptions: string;
           updated_at_ms: number;
         },
         [string, string]
       >(
-        'SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? AND client_id=?',
+        '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) as ClientSubscription[],
@@ -1102,18 +1259,31 @@ export class SqliteServerStorage implements ServerStorage {
   ): Promise<void> {
     this.db
       .query(
-        'INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?)',
+        '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: string,
+    cutoffMs: number,
+  ): Promise<number | null> {
+    const row = this.db
+      .query<{ cursor: number | null }, [string, number]>(
+        'SELECT MIN(cursor) AS cursor FROM sync_clients WHERE partition=? AND updated_at_ms>=?',
+      )
+      .get(partition, cutoffMs);
+    return row!.cursor;
+  }
+
   async listClientCursors(partition: string): Promise<ClientCursorInfo[]> {
     const records = this.db
       .query<
@@ -1187,18 +1357,20 @@ export class SqliteServerStorage implements ServerStorage {
         {
           client_id: string;
           actor_id: string;
+          wire_version: number;
           cursor: number;
           subscriptions: string;
           updated_at_ms: number;
         },
         [string]
       >(
-        'SELECT client_id, actor_id, cursor, subscriptions, updated_at_ms FROM sync_clients WHERE partition=? ORDER BY updated_at_ms DESC',
+        '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) as ClientSubscription[],
@@ -1324,14 +1496,6 @@ export class SqliteServerStorage implements ServerStorage {
   }
 
   async listPartitions(): Promise<string[]> {
-    // 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<{ partition: string }, []>(
-        `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/src/storage-errors.ts

@@ -19,10 +19,19 @@ export type StorageQueryErrorCode =
   | 'sync.storage.index_not_found'
   | 'sync.storage.index_not_materialized'
   | 'sync.storage.index_value_count_mismatch'
-  | 'sync.storage.invalid_limit';
+  | 'sync.storage.invalid_limit'
+  | 'sync.storage.prune_epoch_mismatch'
+  | 'sync.storage.partition_unregistered'
+  | 'sync.storage.invalid_prune_cursor';
 
 const STORAGE_QUERY_MESSAGES: Readonly<Record<StorageQueryErrorCode, string>> =
   {
+    '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':

package/src/storage.ts

@@ -1,3 +1,4 @@
+import type { AuthoritativeRelationPlan } from './authoritative-query';
 /**
  * Storage interface (defined by the SPEC's needs, implementation-agnostic).
  *
@@ -19,6 +20,17 @@
 import type { PushOperationResult, RowValue, ScopeMap } from '@syncular/core';
 import type { CompiledSchema } from './schema';
 
+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;
@@ -164,6 +176,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;
@@ -220,6 +234,14 @@ export interface ClientCursorInfo {
   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;
@@ -271,7 +293,7 @@ export type AuthoritativeQueryValue =
 
 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[];
@@ -397,16 +419,38 @@ export interface ServerStorage {
    */
   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,
@@ -516,7 +560,12 @@ export interface ServerStorage {
     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[]>;
 
   /**
@@ -551,10 +600,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?(
@@ -572,7 +619,7 @@ export interface ServerStorage {
   ): Promise<
     { 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. */