@syncular/server 0.22.0 → 0.23.0

package/package.json

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

package/src/admin.ts

@@ -22,6 +22,7 @@ import { DEFAULT_RETENTION, type RetentionPolicy } from './prune';
 import { compileSchema, type ServerSchema } from './schema';
 import type { SegmentStore, SegmentStoreStats } from './segment-store';
 import type {
+  CheckpointDeclaration,
   ClientRecord,
   CommitMetadata,
   ReactionStatus,
@@ -157,6 +158,8 @@ export interface SyncularAdminOptions {
    * a storage instance that has not served a sync request yet.
    */
   readonly schema?: ServerSchema;
+  /** RFC 0007: declarations `inspectRow` carries into `ensureSchema`. */
+  readonly checkpoints?: readonly CheckpointDeclaration[];
   /** The event ring feeding the event tail. Absent ⇒ `events()` is empty. */
   readonly ring?: RingBufferEvents;
   readonly segments?: SegmentStore;
@@ -218,6 +221,7 @@ function toAdminClient(
 export class SyncularAdmin {
   readonly #storage: ServerStorage;
   readonly #schema?: ServerSchema;
+  readonly #checkpoints?: readonly CheckpointDeclaration[];
   readonly #ring?: RingBufferEvents;
   readonly #segments?: SegmentStore;
   readonly #blobs?: BlobStore;
@@ -228,6 +232,8 @@ export class SyncularAdmin {
   constructor(options: SyncularAdminOptions) {
     this.#storage = options.storage;
     if (options.schema !== undefined) this.#schema = options.schema;
+    if (options.checkpoints !== undefined)
+      this.#checkpoints = options.checkpoints;
     if (options.ring !== undefined) this.#ring = options.ring;
     if (options.segments !== undefined) this.#segments = options.segments;
     if (options.blobs !== undefined) this.#blobs = options.blobs;
@@ -248,6 +254,9 @@ export class SyncularAdmin {
     return new SyncularAdmin({
       storage: config.storage,
       schema: config.schema,
+      ...(config.checkpoints !== undefined
+        ? { checkpoints: config.checkpoints }
+        : {}),
       segments: config.segments,
       ...(config.blobs !== undefined ? { blobs: config.blobs } : {}),
       ...(config.leases !== undefined ? { leases: config.leases.store } : {}),
@@ -352,7 +361,10 @@ export class SyncularAdmin {
       'storage',
     );
     if (this.#schema !== undefined) {
-      await this.#storage.ensureSchema(compileSchema(this.#schema));
+      await this.#storage.ensureSchema(
+        compileSchema(this.#schema),
+        this.#checkpoints,
+      );
     }
     const row = await read(partition, table, rowId);
     if (row === undefined) {

package/src/blob-handlers.ts

@@ -233,7 +233,7 @@ async function downloadBlob(
   const schema = compileSchema(ctx.schema);
   // A blob download can hit a fresh storage instance before any sync
   // request has run (Workers): make sure the row tables exist first.
-  await ctx.storage.ensureSchema(schema);
+  await ctx.storage.ensureSchema(schema, ctx.checkpoints);
   const rows = await listRows.call(ctx.storage, ctx.partition, blobId);
   let authorized = false;
   for (const row of rows) {

package/src/context.ts

@@ -19,6 +19,7 @@ import type {
 } from './signed-url';
 import type { SqliteImageBuilder } from './sqlite-image';
 import type {
+  CheckpointDeclaration,
   PartitionRegistryEntry,
   ServerStorage,
   StoredCommit,
@@ -96,6 +97,13 @@ export interface RealtimeNotifier {
 export interface SyncServerConfig {
   readonly schema: ServerSchema;
   readonly storage: ServerStorage;
+  /**
+   * RFC 0007: the backfill checkpoints this host installs. Every readiness
+   * path carries this set into `ensureSchema`. A process that omits it
+   * declares nothing, and the storage refuses to serve a partition whose
+   * stored state shows a checkpoint that is not activated.
+   */
+  readonly checkpoints?: readonly CheckpointDeclaration[];
   readonly segments: SegmentStore;
   /**
    * Blob store (§5.9). Absent ⇒ blobs unsupported: a table with a

package/src/d1-storage.ts

@@ -90,6 +90,7 @@ import {
 import type {
   AuthoritativeQueryRequest,
   AuthoritativeQueryResult,
+  CheckpointDeclaration,
   ClientCursorInfo,
   ClientRecord,
   ClientSubscription,
@@ -111,8 +112,10 @@ import type {
   ScopeActivityQuery,
   ScopeCommitActivity,
   ServerStorage,
+  ServeGate,
   StorageTransaction,
   StoredCommit,
+  StoredCheckpoint,
   StoredPushResult,
   StoredReaction,
   StoredRow,
@@ -447,6 +450,31 @@ class D1Transaction implements StorageTransaction {
     this.#pushApplyCheckpoint = this.#buffer.length;
   }
 
+  advanceCheckpoint(
+    _name: string,
+    _ownerEpoch: number,
+    _watermark: number,
+    _observedRows: number,
+    _nowMs: number,
+  ): Promise<boolean> {
+    // D1 installs no fence and declares no checkpoints in this release.
+    return Promise.reject(
+      new StorageQueryError('sync.storage.checkpoint_unsupported'),
+    );
+  }
+
+  async readServeGate(_runningSchemaVersion: number): Promise<ServeGate> {
+    this.#assertOpen();
+    const marker = await this.#db
+      .prepare('SELECT schema_version FROM sync_schema_meta WHERE id=1')
+      .first<{ schema_version: number }>();
+    return {
+      storedSchemaVersion: marker?.schema_version ?? 0,
+      logEpoch: undefined,
+      pending: [],
+    };
+  }
+
   async commitRejectedPushResult(
     clientId: string,
     clientCommitId: string,
@@ -834,7 +862,15 @@ export class D1ServerStorage implements ServerStorage {
     return table;
   }
 
-  async ensureSchema(schema: CompiledSchema): Promise<void> {
+  async ensureSchema(
+    schema: CompiledSchema,
+    checkpoints?: readonly CheckpointDeclaration[],
+  ): Promise<void> {
+    if (checkpoints !== undefined && checkpoints.length > 0) {
+      // No database-side fence can be installed atomically with schema
+      // visibility here; refuse instead of accepting a weaker guarantee.
+      throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+    }
     if (this.#schemaVersion === schema.version) {
       await this.#schemaDatabase().batch([]);
       return;
@@ -1427,7 +1463,11 @@ export class D1ServerStorage implements ServerStorage {
   async queryAuthoritative(
     partition: string,
     query: AuthoritativeQueryRequest,
+    _checkpoints?: readonly CheckpointDeclaration[],
   ): Promise<AuthoritativeQueryResult> {
+    // D1 declares no checkpoints. `#schemaDatabase` prepends a guard that
+    // re-checks the published marker inside this same batch, so condition 2
+    // is already evaluated with the query (§2.4 D1 schema readiness).
     const db = this.#schemaDatabase();
     if (this.#tables === undefined) {
       throw new Error(
@@ -1591,6 +1631,108 @@ export class D1ServerStorage implements ServerStorage {
     return row?.seq ?? 0;
   }
 
+  async readCheckpoints(_partition: string): Promise<StoredCheckpoint[]> {
+    // D1 supports no declared backfill checkpoints in this release: migrations
+    // run out of band and no database-side fence can be installed atomically
+    // with schema visibility. No checkpoint row can exist.
+    return [];
+  }
+
+  async readServeGate(
+    partition: string,
+    _runningSchemaVersion: number,
+  ): Promise<ServeGate> {
+    // D1 has no checkpoints. The published marker is the only gate input;
+    // `#schemaDatabase` already re-checks it per protected batch.
+    const marker = await this.#db
+      .prepare('SELECT schema_version FROM sync_schema_meta WHERE id=1')
+      .first<{ schema_version: number }>();
+    return {
+      storedSchemaVersion: marker?.schema_version ?? 0,
+      logEpoch: await this.getPartitionLogEpoch(partition),
+      pending: [],
+    };
+  }
+
+  async declareCheckpoint(
+    _partition: string,
+    _name: string,
+    _schemaVersion: number,
+    _nowMs: number,
+  ): Promise<StoredCheckpoint> {
+    throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+  }
+
+  async activateCheckpoint(
+    _partition: string,
+    _name: string,
+    _ownerEpoch: number,
+    _watermark: number,
+    _sources: readonly string[],
+    _nowMs: number,
+  ): Promise<'activated' | 'stale' | 'unverifiable'> {
+    throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+  }
+
+  async claimCheckpoint(
+    _partition: string,
+    _name: string,
+    _schemaVersion: number,
+    _nowMs: number,
+  ): Promise<StoredCheckpoint> {
+    throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+  }
+
+  async advanceCheckpoint(
+    _partition: string,
+    _name: string,
+    _ownerEpoch: number,
+    _watermark: number,
+    _observedRows: number,
+    _nowMs: number,
+  ): Promise<boolean> {
+    throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+  }
+
+  async sourceCoverageSeq(
+    partition: string,
+    tables: readonly string[],
+  ): Promise<number> {
+    if (tables.length === 0) return 0;
+    const tableParams = tables.map(() => '?').join(',');
+    const row = await this.#db
+      .prepare(
+        `SELECT max(commit_seq) AS seq FROM sync_changes
+          WHERE partition=? AND tbl IN (${tableParams})`,
+      )
+      .bind(partition, ...tables)
+      .first<{ seq: number | null }>();
+    return row?.seq ?? 0;
+  }
+
+  async hasSourceChangesAbove(
+    partition: string,
+    tables: readonly string[],
+    seq: number,
+  ): Promise<'clean' | 'changed' | 'unverifiable'> {
+    // Read the horizon before the window scan: a horizon past `seq` means the
+    // history that would answer the question is gone, so an empty scan proves
+    // nothing and must not be reported as `clean`.
+    const horizon = await this.getHorizonSeq(partition);
+    if (tables.length === 0) return 'clean';
+    const tableParams = tables.map(() => '?').join(',');
+    const hit = await this.#db
+      .prepare(
+        `SELECT 1 AS hit FROM sync_changes
+          WHERE partition=? AND tbl IN (${tableParams}) AND commit_seq>?
+          LIMIT 1`,
+      )
+      .bind(partition, ...tables, seq)
+      .first<{ hit: number }>();
+    if (hit !== null) return 'changed';
+    return horizon > seq ? 'unverifiable' : 'clean';
+  }
+
   async getRow(
     partition: string,
     table: string,

package/src/errors.ts

@@ -167,6 +167,16 @@ export const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>> = {
     recommendedAction: 'retryLater',
     httpStatus: 500,
   },
+  // §2.4 on a non-D1 backend: the server refuses while a declared backfill
+  // checkpoint is incomplete or the database is newer than the running build.
+  // Formerly host-only; promoted to the §10.2 catalogue so an in-flight
+  // request can be refused with a distinguishable identity.
+  'sync.schema_not_ready': {
+    category: 'internal',
+    retryable: true,
+    recommendedAction: 'retryLater',
+    httpStatus: 503,
+  },
   'sync.too_many_operations': {
     category: 'invalid-request',
     retryable: false,

package/src/handler.ts

@@ -51,10 +51,17 @@ import {
   subscriptionSection,
 } from './pull';
 import { type ProcessedPushCommit, processPushCommitWithTrace } from './push';
+import { serveNotReadyError } from './readiness';
 import type { CompiledSchema } from './schema';
 import { compileSchema } from './schema';
 import { computeEffective, type ResolvedScopes } from './scopes';
-import type { ClientSubscription, PartitionRegistryEntry } from './storage';
+import { StorageQueryError } from './storage-errors';
+import {
+  type ClientSubscription,
+  type PartitionRegistryEntry,
+  serveGateRefusal,
+  serveGateTokenChanged,
+} from './storage';
 
 interface RequestPlan {
   readonly wireVersion: number;
@@ -709,13 +716,64 @@ async function createStreamCore(
   const schema = compileSchema(ctx.schema);
   // Relational row tables: create/
   // migrate on first contact; memoized per storage instance thereafter.
-  await ctx.storage.ensureSchema(schema);
+  try {
+    await ctx.storage.ensureSchema(schema, ctx.checkpoints);
+  } catch (error) {
+    if (
+      error instanceof StorageQueryError &&
+      error.code === 'sync.storage.checkpoint_incomplete'
+    ) {
+      const refusal = serveGateRefusal(
+        await ctx.storage.readServeGate(ctx.partition, schema.version),
+        schema.version,
+        ctx.checkpoints,
+      );
+      throw refusal !== undefined ? serveNotReadyError(refusal) : error;
+    }
+    throw error;
+  }
+  // RFC 0007 serve gate: re-read stored state on every request so an
+  // already-serving process notices a migration or a newly declared
+  // checkpoint. Read after `touchAuthenticatedPartition` establishes the
+  // partition's log epoch, so the entry token is the epoch this request
+  // serves under. Nothing has escaped at this point; the push transaction
+  // re-evaluates the gate under the partition lock.
   const registry = await touchAuthenticatedPartition(ctx);
+  const gate = await ctx.storage.readServeGate(ctx.partition, schema.version);
+  const refusal = serveGateRefusal(gate, schema.version, ctx.checkpoints);
+  if (refusal !== undefined) throw serveNotReadyError(refusal);
   const plan = await planRequest(request, ctx, schema, registry);
-  if (events === undefined) return streamResponse(plan, ctx, schema);
   const report: RequestReport = { outcome: 'ok' };
+  // RFC 0007 read-verify-refuse for the streamed read path: the generator
+  // builds the whole response (its data reads) before yielding the first
+  // frame, then compares the gate token across those reads. Nothing escapes
+  // before the verification, and the buffered size is bounded by the request's
+  // pull limits and the server's inline segment cap. Every request verifies,
+  // including a mixed push+pull: a write that already applied when the token
+  // changed is durable and replayable under the same commit id / idempotency
+  // key, so refusing the request is safe (proved in the serve-gate lane).
+  const verified = async function* (): AsyncGenerator<Uint8Array> {
+    const buffered: Uint8Array[] = [];
+    for await (const chunk of streamResponse(plan, ctx, schema, report)) {
+      buffered.push(chunk);
+    }
+    const after = await ctx.storage.readServeGate(
+      ctx.partition,
+      schema.version,
+    );
+    const changed = serveGateTokenChanged(gate, after);
+    const afterRefusal = serveGateRefusal(
+      after,
+      schema.version,
+      ctx.checkpoints,
+    );
+    if (afterRefusal !== undefined) throw serveNotReadyError(afterRefusal);
+    if (changed !== undefined) throw serveNotReadyError(changed);
+    for (const chunk of buffered) yield chunk;
+  };
+  if (events === undefined) return verified();
   return instrumentedStream(
-    streamResponse(plan, ctx, schema, report),
+    verified(),
     ctx,
     events,
     plan,

package/src/operations.ts

@@ -415,22 +415,26 @@ export function registerRemoteQuery<Params>(
           'selected SQL has no generated relation plan; regenerate queries',
         );
       }
-      await ctx.storage.ensureSchema(schema);
+      await ctx.storage.ensureSchema(schema, ctx.checkpoints);
       const prefix = 'SELECT * FROM (';
       let result;
       try {
-        result = await ctx.storage.queryAuthoritative(ctx.partition, {
-          plan: {
-            sql: `${prefix}${selectedSql}) AS "_syncular_registered_query" LIMIT ?`,
-            relations: plan.relations.map((relation) => ({
-              ...relation,
-              start: relation.start + prefix.length,
-              end: relation.end + prefix.length,
-            })),
+        result = await ctx.storage.queryAuthoritative(
+          ctx.partition,
+          {
+            plan: {
+              sql: `${prefix}${selectedSql}) AS "_syncular_registered_query" LIMIT ?`,
+              relations: plan.relations.map((relation) => ({
+                ...relation,
+                start: relation.start + prefix.length,
+                end: relation.end + prefix.length,
+              })),
+            },
+            params: [...descriptor.bind(params), options.maxRows + 1],
+            tables: descriptor.tables,
           },
-          params: [...descriptor.bind(params), options.maxRows + 1],
-          tables: descriptor.tables,
-        });
+          ctx.checkpoints,
+        );
       } catch (error) {
         if (error instanceof SyncError) throw error;
         throw syncError(
@@ -603,7 +607,7 @@ export function registerRemoteCommand<Input>(
       }
       const resolved: ResolvedScopes = { ok: true, allowed };
       const schema = compileSchema(ctx.schema);
-      await ctx.storage.ensureSchema(schema);
+      await ctx.storage.ensureSchema(schema, ctx.checkpoints);
       const processed = await processPushOperationsWithTrace(
         ctx,
         schema,