@syncular/server 0.21.1 → 0.23.0

package/dist/storage.d.ts

@@ -28,6 +28,72 @@ export interface CommitPruneResult {
     readonly horizonSeq: number;
     readonly removedCommits: number;
 }
+/** RFC 0007 backfill lifecycle. `activated` is terminal within a schema version. */
+export type CheckpointState = 'declared' | 'backfilling' | 'activated';
+/**
+ * Host-owned checkpoint installation carried on `ensureSchema`: the schema
+ * bump, the `declared` row, and the raised writer fence commit together.
+ */
+export interface CheckpointDeclaration {
+    readonly partition: string;
+    readonly name: string;
+    readonly schemaVersion: number;
+}
+/** One host-storage backfill checkpoint row. Never a synced application row. */
+export interface StoredCheckpoint {
+    readonly partition: string;
+    readonly name: string;
+    readonly schemaVersion: number;
+    readonly state: CheckpointState;
+    /** Highest source `commit_seq` the projection was derived from. */
+    readonly watermark: number;
+    /** Monotonic claim counter; a batch is stale when it does not match. */
+    readonly ownerEpoch: number;
+    readonly observedRows: number;
+    readonly updatedAtMs: number;
+}
+/**
+ * RFC 0007 serve-gate token, read inside the transaction that produces the
+ * result. `storedSchemaVersion` is the published marker; `logEpoch` is the
+ * partition's log generation, so a restore that presents V -> other -> V is
+ * still distinguishable. `pending` names every incomplete declared checkpoint
+ * at the running schema version, across partitions.
+ */
+export interface ServeGate {
+    readonly storedSchemaVersion: number;
+    readonly logEpoch: string | undefined;
+    readonly pending: readonly {
+        readonly partition: string;
+        readonly name: string;
+    }[];
+}
+/** Why `serveGate` refuses, or `undefined` when this request may serve. */
+export type ServeGateRefusal = {
+    readonly kind: 'schema';
+    readonly stored: number;
+    readonly running: number;
+} | {
+    readonly kind: 'checkpoint';
+    readonly partition: string;
+    readonly name: string;
+} | {
+    /** The token changed between two reads: a restore rotated the epoch. */
+    readonly kind: 'epoch';
+};
+/**
+ * Evaluate the RFC 0007 predicate against a gate token. A process that
+ * declares the pending checkpoint may serve while it backfills; any other
+ * process is refused, and a database newer than the running build is always
+ * refused.
+ */
+export declare function serveGateRefusal(gate: ServeGate, runningSchemaVersion: number, checkpoints: readonly CheckpointDeclaration[] | undefined): ServeGateRefusal | undefined;
+/**
+ * RFC 0007: compare two gate tokens read around a data read. The token binds
+ * the published schema version and the partition log epoch, so a restore that
+ * presents V → other → V is distinguishable. Returns a refusal when either
+ * changed across the read.
+ */
+export declare function serveGateTokenChanged(before: ServeGate, after: ServeGate): ServeGateRefusal | undefined;
 /** The current stored state of a synced row. */
 export interface StoredRow {
     readonly rowId: string;
@@ -352,6 +418,21 @@ export interface StorageTransaction {
      * first writer wins; callers read the canonical value after commit.
      */
     putPushResult(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<void>;
+    /**
+     * Advance this partition's checkpoint only while `owner_epoch` still
+     * matches, so the owner-epoch CAS rides inside the caller's transaction.
+     * The host calls this from `processPushOperationsWithTrace`'s operation
+     * builder: the backfill is an ordinary server-authoritative write, and this
+     * CAS commits with that write's row versions and commit-log append. False
+     * means abort and write nothing, rather than a throw for a superseded owner.
+     */
+    advanceCheckpoint(name: string, ownerEpoch: number, watermark: number, observedRows: number, nowMs: number): Promise<boolean>;
+    /**
+     * RFC 0007 serve gate on the caller's own connection, for write paths that
+     * already hold the partition lock: the gate and the write share one
+     * transaction, so a migration cannot interleave between them.
+     */
+    readServeGate(runningSchemaVersion: number): Promise<ServeGate>;
     /**
      * Blob reference index (§5.9.4) — ADDITIVE, optional. Set the blobIds a
      * row currently references (empty = clear), replacing any prior entries
@@ -379,7 +460,7 @@ export interface ServerStorage {
      * before binding a public port; protocol handlers still call this method
      * lazily as a defensive backstop.
      */
-    ensureSchema(schema: CompiledSchema): Promise<void>;
+    ensureSchema(schema: CompiledSchema, checkpoints?: readonly CheckpointDeclaration[]): 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. */
@@ -388,6 +469,19 @@ export interface ServerStorage {
     listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
     /** Read continuity without refreshing authenticated activity. */
     getPartitionLogEpoch(partition: string): Promise<string | undefined>;
+    /**
+     * Open a storage transaction. This is the raw primitive, not a command
+     * boundary: it acquires NO partition write lock. In-tree SQLite begins
+     * `IMMEDIATE`, so a hand-rolled command on SQLite happens to be serialized
+     * against a concurrent push; PostgreSQL's `BEGIN` takes no row lock, so the
+     * same command races a push on Postgres and a SQLite-only test conceals it.
+     *
+     * A trusted command must therefore run through `registerRemoteCommand`,
+     * which builds after `lockPartitionForPush` and the idempotency recheck and
+     * shares the committed transaction, or call `lockPartitionForPush` before
+     * its first authority, version, or replay read. SSP2 request handling does
+     * this for you; only host-authored commands choose.
+     */
     begin(partition: string): Promise<StorageTransaction>;
     getMaxCommitSeq(partition: string): Promise<number>;
     getHorizonSeq(partition: string): Promise<number>;
@@ -400,6 +494,50 @@ export interface ServerStorage {
     pruneCommitsThrough(partition: string, query: CommitPruneQuery): Promise<CommitPruneResult>;
     /** Newest commitSeq created strictly before the timestamp; 0 if none. */
     getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
+    /** Every declared backfill checkpoint for the partition, ordered by name. */
+    readCheckpoints(partition: string): Promise<StoredCheckpoint[]>;
+    /**
+     * RFC 0007 serve gate: read the published schema version, the partition's
+     * log epoch, and every incomplete declared checkpoint at
+     * `runningSchemaVersion`. Never memoized; the serve paths call it per
+     * request so an already-serving process notices a migration.
+     */
+    readServeGate(partition: string, runningSchemaVersion: number): Promise<ServeGate>;
+    /**
+     * Atomically take ownership of a declared or backfilling checkpoint. Increments
+     * `owner_epoch` and moves `declared` to `backfilling`. Throws
+     * `sync.storage.checkpoint_not_declared` when no claimable row exists (absent,
+     * or already `activated`).
+     */
+    claimCheckpoint(partition: string, name: string, schemaVersion: number, nowMs: number): Promise<StoredCheckpoint>;
+    /**
+     * Advance the watermark only while `owner_epoch` still matches. Returns false
+     * for a superseded owner; the stale case never throws.
+     */
+    advanceCheckpoint(partition: string, name: string, ownerEpoch: number, watermark: number, observedRows: number, nowMs: number): Promise<boolean>;
+    /** Highest commitSeq carrying a change to one of `tables`; 0 when none. */
+    sourceCoverageSeq(partition: string, tables: readonly string[]): Promise<number>;
+    /**
+     * Whether any source change sits above `seq`. `unverifiable` when the pruning
+     * horizon has passed `seq`, so the history that would answer the question is
+     * gone; a pruned window is never reported as `clean`.
+     */
+    hasSourceChangesAbove(partition: string, tables: readonly string[], seq: number): Promise<'clean' | 'changed' | 'unverifiable'>;
+    /**
+     * Install the barrier: insert the checkpoint in `declared` and raise
+     * `required_writer_version` for the partition in one transaction. The fence
+     * is raised at declaration, before any backfill work, so old writers are
+     * rejected for the whole backfill window. Idempotent on an existing declared
+     * or backfilling row.
+     */
+    declareCheckpoint(partition: string, name: string, schemaVersion: number, nowMs: number): Promise<StoredCheckpoint>;
+    /**
+     * Activate a declared checkpoint under the partition write lock. Refuses when
+     * the fence is not already raised at the checkpoint's schema version, when a
+     * source change sits above `watermark` (`stale`), or when the pruning horizon
+     * has passed `watermark` (`unverifiable`). `activated` is terminal.
+     */
+    activateCheckpoint(partition: string, name: string, ownerEpoch: number, watermark: number, sources: readonly string[], nowMs: number): Promise<'activated' | 'stale' | 'unverifiable'>;
     getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
     /**
      * Idempotency lookup (§2.3). Throws `SyncError sync.idempotency_cache_miss`
@@ -436,8 +574,20 @@ export interface ServerStorage {
      * Optional registered-query capability. The implementation MUST replace
      * every generated app-table relation with a partition-filtered relation and
      * return rows plus maxCommitSeq from one consistent database snapshot.
+     *
+     * The storage serializes this call behind an open transaction on a
+     * single-connection executor (SQLite, PGlite). A validator runs inside the
+     * push transaction, so on that executor a validator that calls
+     * `queryAuthoritative` waits on the transaction it is already inside and
+     * the push never completes. A pool-backed executor (`pg`, `Bun.sql`) hands
+     * the call a second connection instead: the validator does not deadlock,
+     * but it reads committed state without the candidate write. On either
+     * executor read candidate state through the whole-commit `CommitValidator`
+     * reader (§6.8). A call made from any other context waits for the open
+     * transaction to finish on a single-connection executor, and runs
+     * concurrently on a pool-backed one.
      */
-    queryAuthoritative?(partition: string, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
+    queryAuthoritative?(partition: string, query: AuthoritativeQueryRequest, checkpoints?: readonly CheckpointDeclaration[]): Promise<AuthoritativeQueryResult>;
     /**
      * Optional trusted-host exact lookup through a declared relational index.
      * This capability is outside client scope/subscription authorization and

package/dist/storage.js

@@ -1 +1,40 @@
-export {};
+/**
+ * Evaluate the RFC 0007 predicate against a gate token. A process that
+ * declares the pending checkpoint may serve while it backfills; any other
+ * process is refused, and a database newer than the running build is always
+ * refused.
+ */
+export function serveGateRefusal(gate, runningSchemaVersion, checkpoints) {
+    if (gate.storedSchemaVersion > runningSchemaVersion) {
+        return {
+            kind: 'schema',
+            stored: gate.storedSchemaVersion,
+            running: runningSchemaVersion,
+        };
+    }
+    for (const pending of gate.pending) {
+        const declared = (checkpoints ?? []).some((declaration) => declaration.partition === pending.partition &&
+            declaration.name === pending.name);
+        if (!declared) {
+            return {
+                kind: 'checkpoint',
+                partition: pending.partition,
+                name: pending.name,
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * RFC 0007: compare two gate tokens read around a data read. The token binds
+ * the published schema version and the partition log epoch, so a restore that
+ * presents V → other → V is distinguishable. Returns a refusal when either
+ * changed across the read.
+ */
+export function serveGateTokenChanged(before, after) {
+    if (before.storedSchemaVersion !== after.storedSchemaVersion ||
+        before.logEpoch !== after.logEpoch) {
+        return { kind: 'epoch' };
+    }
+    return undefined;
+}

package/dist/validate.d.ts

@@ -95,7 +95,19 @@ export interface ValidateCommitInput {
  * staged, but before commit-log/idempotency append and transaction commit.
  */
 export type CommitValidator = (input: ValidateCommitInput) => void | Promise<void>;
-/** Ambient context a validator may consult (§6.7). */
+/**
+ * Ambient context a validator may consult (§6.7).
+ *
+ * A validator runs inside the push transaction. On a single-connection
+ * executor (SQLite, PGlite) the storage serializes authoritative queries
+ * behind that transaction, so a validator that calls `queryAuthoritative`
+ * waits for the transaction it is already inside and the push never
+ * completes. On a pool-backed executor (`pg`, `Bun.sql`) the query takes a
+ * second connection and returns committed state without the candidate write.
+ * Either way a rule that must read rows belongs in the whole-commit
+ * `CommitValidator`, whose reader runs get and scan operations on the same
+ * transaction (§6.8).
+ */
 export interface ValidateContext {
     /** Host-authenticated actor (§1.1) performing the write. */
     readonly actorId: string;
@@ -110,6 +122,13 @@ export interface ValidateContext {
  * any other error is treated as a rejection with a generic
  * `sync.constraint_violation` code (a validator SHOULD throw
  * `ValidationRejection` to control the code). MUST NOT mutate the row.
+ *
+ * The hook runs inside the push transaction and cannot read candidate rows
+ * from an authoritative query: on a single-connection executor
+ * `queryAuthoritative` serializes behind that transaction and the push never
+ * completes, and on a pool-backed executor it reads committed state without
+ * the candidate write. Read rows with the whole-commit `CommitValidator`
+ * reader instead (§6.8).
  */
 export type Validator = (op: ValidateOperation, ctx: ValidateContext) => void | Promise<void>;
 /** Table name → validator (§6.7). Absent tables are unvalidated. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.21.1",
+  "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.21.1"
+    "@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,