@syncular/server 0.22.0 → 0.23.0

package/dist/postgres-storage.js

@@ -1,5 +1,7 @@
 import { validateCommitPruneQuery } from './prune.js';
 import { StorageQueryError } from './storage-errors.js';
+import { serveGateRefusal } from './storage.js';
+import { serveNotReadyError } from './readiness.js';
 import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
@@ -59,6 +61,7 @@ CREATE TABLE IF NOT EXISTS sync_commits(
   partition TEXT NOT NULL, commit_seq BIGINT NOT NULL,
   client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,
   actor_id TEXT NOT NULL, created_at_ms BIGINT NOT NULL,
+  writer_version BIGINT,
   PRIMARY KEY(partition, commit_seq)
 );
 CREATE INDEX IF NOT EXISTS sync_commits_by_time
@@ -122,6 +125,20 @@ CREATE TABLE IF NOT EXISTS sync_tombstones(
   commit_seq BIGINT NOT NULL,
   PRIMARY KEY(partition, tbl, row_id)
 );
+CREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(
+  partition TEXT NOT NULL, name TEXT NOT NULL,
+  schema_version INTEGER NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('declared','backfilling','activated')),
+  watermark BIGINT NOT NULL DEFAULT 0,
+  owner_epoch BIGINT NOT NULL DEFAULT 0,
+  observed_rows BIGINT NOT NULL DEFAULT 0,
+  updated_at_ms BIGINT NOT NULL,
+  PRIMARY KEY(partition, name)
+);
+CREATE TABLE IF NOT EXISTS sync_writer_fence(
+  partition TEXT PRIMARY KEY,
+  required_writer_version INTEGER NOT NULL
+);
 `;
 async function lockPartitionOn(client, partition) {
     const locked = await client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1 FOR UPDATE', [partition]);
@@ -133,12 +150,76 @@ async function lockPartitionOn(client, partition) {
     ON CONFLICT (partition) DO NOTHING`, [partition]);
     await client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1 FOR UPDATE', [partition]);
 }
+/**
+ * Insert the `declared` row and raise the fence, on the caller's open
+ * transaction. Shared by `declareCheckpoint` and the `ensureSchema`
+ * migration so the schema bump and the fence commit together. Never lowers a
+ * fence and never re-declares an existing row.
+ */
+async function installCheckpointOn(client, partition, name, schemaVersion, nowMs) {
+    await client.query(`INSERT INTO sync_backfill_checkpoints(
+       partition, name, schema_version, state, watermark,
+       owner_epoch, observed_rows, updated_at_ms)
+     VALUES ($1,$2,$3,'declared',0,0,0,$4)
+     ON CONFLICT (partition, name) DO NOTHING`, [partition, name, schemaVersion, nowMs]);
+    await client.query(`INSERT INTO sync_writer_fence(partition, required_writer_version)
+     VALUES ($1,$2)
+     ON CONFLICT (partition) DO UPDATE SET
+       required_writer_version=GREATEST(
+         sync_writer_fence.required_writer_version,
+         EXCLUDED.required_writer_version)`, [partition, schemaVersion]);
+}
+/** RFC 0007 serve gate on either the pool or a transaction's client. */
+async function readServeGateOn(client, partition, runningSchemaVersion) {
+    const marker = await client.query('SELECT schema_version FROM sync_schema_meta WHERE id=1');
+    const epoch = await client.query('SELECT log_epoch FROM sync_partition_registry WHERE partition=$1', [partition]);
+    const pending = await client.query(`SELECT partition, name FROM sync_backfill_checkpoints
+      WHERE schema_version=$1 AND state<>'activated'`, [runningSchemaVersion]);
+    return {
+        storedSchemaVersion: marker.rows[0] === undefined
+            ? 0
+            : asNumber(marker.rows[0].schema_version),
+        logEpoch: epoch.rows[0]?.log_epoch,
+        pending: pending.rows.map((row) => ({
+            partition: row.partition,
+            name: row.name,
+        })),
+    };
+}
+async function hasSourceChangesAboveOn(client, partition, tables, seq) {
+    // 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 client.query('SELECT horizon_seq FROM sync_partitions WHERE partition=$1', [partition]);
+    const horizonSeq = horizon.rows[0] === undefined ? 0 : asNumber(horizon.rows[0].horizon_seq);
+    if (tables.length === 0)
+        return 'clean';
+    const tableParams = tables.map((_, index) => `$${index + 2}`).join(',');
+    const hit = await client.query(`SELECT 1 AS hit FROM sync_changes
+      WHERE partition=$1 AND tbl IN (${tableParams}) AND commit_seq>$${tables.length + 2}
+      LIMIT 1`, [partition, ...tables, seq]);
+    if (hit.rows[0] !== undefined)
+        return 'changed';
+    return horizonSeq > seq ? 'unverifiable' : 'clean';
+}
 function toBase64(bytes) {
     return Buffer.from(bytes).toString('base64');
 }
 function fromBase64(text) {
     return new Uint8Array(Buffer.from(text, 'base64'));
 }
+function toStoredCheckpoint(record) {
+    return {
+        partition: record.partition,
+        name: record.name,
+        schemaVersion: asNumber(record.schema_version),
+        state: record.state,
+        watermark: asNumber(record.watermark),
+        ownerEpoch: asNumber(record.owner_epoch),
+        observedRows: asNumber(record.observed_rows),
+        updatedAtMs: asNumber(record.updated_at_ms),
+    };
+}
 function toStoredReaction(record) {
     return {
         idempotencyKey: record.idempotency_key,
@@ -341,13 +422,15 @@ async function getPushResultOn(q, partition, clientId, clientCommitId) {
 class PostgresTransaction {
     #client;
     #partition;
+    /** Schema version this transaction writes; rides every appended commit row. */
+    #writerVersion;
     #resolveTable;
     #open = true;
     #pushApplySavepoint = false;
     /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
     #resolve;
     #reject;
-    constructor(client, partition, resolveTable, resolve, reject) {
+    constructor(client, partition, writerVersion, resolveTable, resolve, reject) {
         // One pinned connection carries one statement at a time: node-postgres
         // warns about a concurrently issued second query today and rejects it in
         // node-postgres 9. A whole-commit validator that fans independent reads
@@ -363,6 +446,7 @@ class PostgresTransaction {
             },
         };
         this.#partition = partition;
+        this.#writerVersion = writerVersion;
         this.#resolveTable = resolveTable;
         this.#resolve = resolve;
         this.#reject = reject;
@@ -439,6 +523,24 @@ class PostgresTransaction {
         await this.#client.query('SAVEPOINT syncular_push_candidate');
         this.#pushApplySavepoint = true;
     }
+    async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
+        this.#assertOpen();
+        // `RETURNING`: the affected-row check must not depend on a driver's
+        // `rowCount` for a statement with no result rows. Bun.sql's canonical
+        // adapter derives `rowCount` from the returned rows, so a bare UPDATE
+        // reports 0 and the CAS would never advance on a real Bun.sql host.
+        const result = await this.#client.query(`UPDATE sync_backfill_checkpoints
+          SET watermark=$1, observed_rows=$2, updated_at_ms=$3
+        WHERE partition=$4 AND name=$5 AND owner_epoch=$6
+        RETURNING name`, [watermark, observedRows, nowMs, this.#partition, name, ownerEpoch]);
+        return result.rows.length === 1;
+    }
+    readServeGate(runningSchemaVersion) {
+        this.#assertOpen();
+        // The transaction's own client: the gate and the write share one
+        // transaction, so a migration cannot interleave between them.
+        return readServeGateOn(this.#client, this.#partition, runningSchemaVersion);
+    }
     async commitRejectedPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
         if (!this.#pushApplySavepoint) {
@@ -491,14 +593,15 @@ class PostgresTransaction {
            SET max_commit_seq = sync_partitions.max_commit_seq + 1
          RETURNING max_commit_seq
        )
-       INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms)
-       SELECT $1, max_commit_seq, $2, $3, $4, $5 FROM allocated
+       INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version)
+       SELECT $1, max_commit_seq, $2, $3, $4, $5, $6 FROM allocated
        RETURNING commit_seq`, [
             p,
             commit.clientId,
             commit.clientCommitId,
             commit.actorId,
             commit.createdAtMs,
+            this.#writerVersion,
         ]);
         const commitSeq = asNumber(rows[0]?.commit_seq);
         for (let idx = 0; idx < commit.changes.length; idx++) {
@@ -615,6 +718,29 @@ export class PostgresServerStorage {
         for (const statement of statements) {
             await this.#exec.query(statement);
         }
+        await this.#exec.query('ALTER TABLE sync_commits ADD COLUMN IF NOT EXISTS writer_version BIGINT');
+        // Database-side fence: an old binary's INSERT never reaches JS. An absent
+        // `sync_writer_fence` row makes the EXISTS false, so a partition with no
+        // barrier behaves exactly as before. Sent as separate statements because
+        // the dollar-quoted body contains `;`.
+        await this.#exec.query(`CREATE OR REPLACE FUNCTION syncular_writer_fence()
+RETURNS trigger AS $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM sync_writer_fence
+     WHERE partition = NEW.partition
+       AND (NEW.writer_version IS NULL
+            OR NEW.writer_version < required_writer_version)
+  ) THEN
+    RAISE EXCEPTION 'sync.storage.writer_fence_rejected';
+  END IF;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql`);
+        await this.#exec.query('DROP TRIGGER IF EXISTS sync_commits_writer_fence ON sync_commits');
+        await this.#exec.query(`CREATE TRIGGER sync_commits_writer_fence
+BEFORE INSERT ON sync_commits
+FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
     }
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name) {
@@ -624,11 +750,22 @@ export class PostgresServerStorage {
         }
         return table;
     }
-    async ensureSchema(schema) {
+    async ensureSchema(schema, checkpoints) {
         // Memoized fast path: same instance, same schema version.
         if (this.#schemaVersion === schema.version)
             return;
         await this.migrate();
+        // The barrier reads stored state: a checkpoint at this schema version that
+        // is not activated and that this caller did not declare means this process
+        // must not serve. An omitted or empty declaration set declares nothing and
+        // is refused here, never treated as a bypass.
+        const declarations = checkpoints ?? [];
+        const incomplete = await this.#exec.query(`SELECT partition, name FROM sync_backfill_checkpoints
+        WHERE schema_version=$1 AND state<>'activated'`, [schema.version]);
+        if (incomplete.rows.some((row) => !declarations.some((declaration) => declaration.partition === row.partition &&
+            declaration.name === row.name))) {
+            throw new StorageQueryError('sync.storage.checkpoint_incomplete');
+        }
         await this.#exec.query(SCHEMA_META_DDL_POSTGRES);
         const marker = await this.#exec.query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1');
         const stored = marker.rows[0] === undefined
@@ -703,6 +840,17 @@ export class PostgresServerStorage {
                 : undefined);
             const retiredTables = retiredTableNames(schema, layouts);
             await this.#exec.transaction(async (client) => {
+                // RFC 0007 migration barrier: `LOCK TABLE ... EXCLUSIVE` is the FIRST
+                // statement, before any read, DDL, rewrite, marker or checkpoint
+                // install. EXCLUSIVE conflicts with the ROW SHARE that every writer's
+                // `lockPartitionOn` takes (`SELECT … FOR UPDATE`) and with the ROW
+                // EXCLUSIVE of its allocation (`UPDATE sync_partitions` / `INSERT … ON
+                // CONFLICT DO UPDATE`), so an unaware old writer blocks at its first
+                // statement with no cooperation; plain `SELECT` (ACCESS SHARE) still
+                // works. The lock order is acyclic: the migration holds nothing else
+                // when it takes this lock, so a writer already inside completes while
+                // the migration waits.
+                await client.query('LOCK TABLE sync_partitions IN EXCLUSIVE MODE');
                 const existing = new Map();
                 const existingIndexes = new Map();
                 for (const table of schema.tables.values()) {
@@ -756,6 +904,13 @@ export class PostgresServerStorage {
                 await client.query(`INSERT INTO sync_schema_meta(id, schema_version, layouts) VALUES (1, $1, $2)
            ON CONFLICT (id) DO UPDATE
              SET schema_version=EXCLUDED.schema_version, layouts=EXCLUDED.layouts`, [schema.version, layoutsOf(schema)]);
+                // The host's declared checkpoints install in the schema-bump
+                // transaction, so no observer sees the bumped marker without the
+                // fence, or the fence without its declaration row.
+                const installedAtMs = Date.now();
+                for (const declaration of checkpoints ?? []) {
+                    await installCheckpointOn(client, declaration.partition, declaration.name, declaration.schemaVersion, installedAtMs);
+                }
             });
         }
         this.#tables = schema.tables;
@@ -835,7 +990,7 @@ export class PostgresServerStorage {
         });
         const done = this.#exec
             .transaction(async (client) => {
-            const tx = new PostgresTransaction(client, partition, (name) => this.table(name), resolveScope, rejectScope);
+            const tx = new PostgresTransaction(client, partition, this.#schemaVersion ?? 0, (name) => this.table(name), resolveScope, rejectScope);
             resolveReady(tx);
             // Hold the transaction open until commit()/rollback() settles `scope`.
             await scope;
@@ -853,13 +1008,22 @@ export class PostgresServerStorage {
         const { rows } = await this.#exec.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [partition]);
         return rows[0] === undefined ? 0 : asNumber(rows[0].max_commit_seq);
     }
-    async queryAuthoritative(partition, query) {
+    async queryAuthoritative(partition, query, checkpoints) {
         if (this.#tables === undefined) {
             throw new Error('ensureSchema(schema) must run before registered queries');
         }
         const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
         return this.#exec.transaction(async (client) => {
             await client.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
+            // RFC 0007: evaluate the gate inside this pinned snapshot, so a
+            // migration or an epoch rotation cannot land between the gate read and
+            // the query's own read. The registered-query path uses the pinned
+            // snapshot, not a request-entry check.
+            const runningVersion = this.#schemaVersion ?? 0;
+            const gate = await readServeGateOn(client, partition, runningVersion);
+            const refusal = serveGateRefusal(gate, runningVersion, checkpoints);
+            if (refusal !== undefined)
+                throw serveNotReadyError(refusal);
             const result = await client.query(postgresPlaceholders(prepared.sql), prepared.params);
             const cursor = await client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [partition]);
             return {
@@ -910,6 +1074,102 @@ export class PostgresServerStorage {
         const seq = rows[0]?.seq;
         return seq === null || seq === undefined ? 0 : asNumber(seq);
     }
+    async readCheckpoints(partition) {
+        const { rows } = await this.#exec.query(`SELECT partition, name, schema_version, state, watermark,
+              owner_epoch, observed_rows, updated_at_ms
+         FROM sync_backfill_checkpoints WHERE partition=$1 ORDER BY name`, [partition]);
+        return rows.map(toStoredCheckpoint);
+    }
+    async readServeGate(partition, runningSchemaVersion) {
+        return readServeGateOn(this.#exec, partition, runningSchemaVersion);
+    }
+    async declareCheckpoint(partition, name, schemaVersion, nowMs) {
+        // One transaction: the checkpoint becomes visible and the fence that
+        // protects it is raised together. The fence is raised at declaration, not
+        // at activation, so old writers are rejected for the whole backfill.
+        //
+        // RFC 0007 lock decision: this transaction writes only the checkpoint and
+        // fence rows, no application rows and no schema marker, so it does not
+        // take the migration table lock or a partition lock. The fence it raises is
+        // enforced by the `sync_commits` trigger on every append from the commit
+        // of this transaction onward; a writer that committed before the fence was
+        // visible is pre-barrier by the design's own "from declaration onward"
+        // rule, not a bypass of it.
+        return this.#exec.transaction(async (client) => {
+            await installCheckpointOn(client, partition, name, schemaVersion, nowMs);
+            const { rows } = await client.query(`SELECT partition, name, schema_version, state, watermark,
+                owner_epoch, observed_rows, updated_at_ms
+           FROM sync_backfill_checkpoints WHERE partition=$1 AND name=$2`, [partition, name]);
+            const row = rows[0];
+            if (row === undefined) {
+                throw new StorageQueryError('sync.storage.checkpoint_not_declared');
+            }
+            return toStoredCheckpoint(row);
+        });
+    }
+    async activateCheckpoint(partition, name, ownerEpoch, watermark, sources, nowMs) {
+        return this.#exec.transaction(async (client) => {
+            // The same `SELECT … FOR UPDATE` partition row lock that
+            // `lockPartitionForPush` takes; a bare `BEGIN` would race a push.
+            await lockPartitionOn(client, partition);
+            const fence = await client.query('SELECT required_writer_version FROM sync_writer_fence WHERE partition=$1', [partition]);
+            const checkpoint = await client.query('SELECT schema_version FROM sync_backfill_checkpoints WHERE partition=$1 AND name=$2', [partition, name]);
+            const fenceRow = fence.rows[0];
+            const checkpointRow = checkpoint.rows[0];
+            if (fenceRow === undefined ||
+                checkpointRow === undefined ||
+                asNumber(fenceRow.required_writer_version) <
+                    asNumber(checkpointRow.schema_version)) {
+                // The barrier is not installed. Activating would certify a state old
+                // writers can still decay; refuse instead of silently proceeding.
+                throw new StorageQueryError('sync.storage.checkpoint_fence_missing');
+            }
+            const coverage = await hasSourceChangesAboveOn(client, partition, sources, watermark);
+            if (coverage !== 'clean') {
+                return coverage === 'changed' ? 'stale' : 'unverifiable';
+            }
+            const updated = await client.query(`UPDATE sync_backfill_checkpoints
+            SET state='activated', watermark=$1, updated_at_ms=$2
+          WHERE partition=$3 AND name=$4 AND owner_epoch=$5
+            AND state<>'activated'
+          RETURNING partition`, [watermark, nowMs, partition, name, ownerEpoch]);
+            return updated.rows.length === 1 ? 'activated' : 'stale';
+        });
+    }
+    async claimCheckpoint(partition, name, schemaVersion, nowMs) {
+        // The UPDATE's own row lock serializes concurrent claims; owner_epoch+1
+        // is evaluated under it, so two claimers never observe the same epoch.
+        const { rows } = await this.#exec.query(`UPDATE sync_backfill_checkpoints
+          SET owner_epoch=owner_epoch+1,
+              state=CASE WHEN state='declared' THEN 'backfilling' ELSE state END,
+              schema_version=$1, updated_at_ms=$2
+        WHERE partition=$3 AND name=$4 AND state<>'activated'
+    RETURNING partition, name, schema_version, state, watermark,
+              owner_epoch, observed_rows, updated_at_ms`, [schemaVersion, nowMs, partition, name]);
+        if (rows[0] === undefined) {
+            throw new StorageQueryError('sync.storage.checkpoint_not_declared');
+        }
+        return toStoredCheckpoint(rows[0]);
+    }
+    async advanceCheckpoint(partition, name, ownerEpoch, watermark, observedRows, nowMs) {
+        const result = await this.#exec.query(`UPDATE sync_backfill_checkpoints
+          SET watermark=$1, observed_rows=$2, updated_at_ms=$3
+        WHERE partition=$4 AND name=$5 AND owner_epoch=$6
+        RETURNING name`, [watermark, observedRows, nowMs, partition, name, ownerEpoch]);
+        return result.rows.length === 1;
+    }
+    async sourceCoverageSeq(partition, tables) {
+        if (tables.length === 0)
+            return 0;
+        const tableParams = tables.map((_, index) => `$${index + 2}`).join(',');
+        const { rows } = await this.#exec.query(`SELECT max(commit_seq) AS seq FROM sync_changes
+        WHERE partition=$1 AND tbl IN (${tableParams})`, [partition, ...tables]);
+        const seq = rows[0]?.seq;
+        return seq === null || seq === undefined ? 0 : asNumber(seq);
+    }
+    hasSourceChangesAbove(partition, tables, seq) {
+        return hasSourceChangesAboveOn(this.#exec, partition, tables, seq);
+    }
     getRow(partition, table, rowId) {
         return getRowOn(this.#exec, this.table(table), partition, rowId);
     }

package/dist/push.js

@@ -24,7 +24,9 @@ import { emitEvent } from './events.js';
 import { prepareReactions, toNewReactions, } from './reactions.js';
 import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes.js';
 import { decodeColumnVersions, encodeColumnVersions } from './relational-rows.js';
+import { serveGateRefusal } from './storage.js';
 import { StorageConstraintError } from './storage-errors.js';
+import { serveNotReadyError } from './readiness.js';
 import { CommitValidationRejection, toValidateRow, ValidationRejection, } from './validate.js';
 /**
  * Extract the blobIds a decoded row references through its `blob_ref`
@@ -864,6 +866,15 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
             throw new Error('storage transaction does not support serialized push apply, atomic rejection finalization, and configured durable reactions');
         }
         await lockPartitionForPush();
+        // RFC 0007: evaluate the gate on this transaction's own connection while
+        // the partition lock is held, so the migration check and the write share
+        // one transaction and no migration can interleave in between.
+        const gate = await tx.readServeGate(schema.version);
+        const refusal = serveGateRefusal(gate, schema.version, ctx.checkpoints);
+        if (refusal !== undefined) {
+            await tx.rollback();
+            throw serveNotReadyError(refusal);
+        }
         // The optimistic lookup above may have raced another delivery. Re-check
         // only after acquiring partition serialization and before any operation
         // read, validation, merge, or staged write. The re-check runs on the
@@ -1015,6 +1026,13 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
             }
         }
         if (ctx.realtime !== undefined && changes.length > 0) {
+            // RFC 0007 fanout decision: the notification carries the durable commit
+            // entry itself (this commit's `changes`), not a projection read or a pull
+            // window, so fanning it out before the request's buffered read-verify can
+            // never serve a mixed result. Each peer's next pull is gated at the
+            // storage seam; a refused mixed push+pull is safe because the push is
+            // durable and replayable under its commit id. This is commit-entry
+            // durability, not gate inheritance.
             await ctx.realtime.notifyCommit(partition, {
                 commitSeq,
                 createdAtMs,

package/dist/readiness.d.ts

@@ -7,8 +7,10 @@
  * a structured failure that cannot be confused with request authentication.
  */
 import type { SyncServerConfig } from './context.js';
+import { type SyncError } from './errors.js';
+import type { ServeGateRefusal } from './storage.js';
 export declare const SYNC_SERVER_READINESS_ERROR_CODE: "sync.schema_not_ready";
-export type SyncServerReadinessPhase = 'schema_compile' | 'storage_migration';
+export type SyncServerReadinessPhase = 'schema_compile' | 'storage_migration' | 'backfill_checkpoint';
 export declare class SyncServerReadinessError extends Error {
     readonly name = "SyncServerReadinessError";
     readonly code: "sync.schema_not_ready";
@@ -27,4 +29,9 @@ export declare class SyncServerReadinessError extends Error {
  * exposes only a stable code, phase, and schema version; operators can inspect
  * `cause` locally for the table/column or storage diagnostic.
  */
-export declare function ensureSyncServerReady(config: Pick<SyncServerConfig, 'schema' | 'storage'>): Promise<void>;
+export declare function ensureSyncServerReady(config: Pick<SyncServerConfig, 'schema' | 'storage' | 'checkpoints'>): Promise<void>;
+/**
+ * RFC 0007: refuse a serve path that observed a closed gate. The projection
+ * name travels in structured details, never in the message.
+ */
+export declare function serveNotReadyError(refusal: ServeGateRefusal): SyncError;

package/dist/readiness.js

@@ -1,3 +1,4 @@
+import { syncError } from './errors.js';
 import { compileSchema } from './schema.js';
 export const SYNC_SERVER_READINESS_ERROR_CODE = 'sync.schema_not_ready';
 export class SyncServerReadinessError extends Error {
@@ -31,13 +32,37 @@ export async function ensureSyncServerReady(config) {
         });
     }
     try {
-        await config.storage.ensureSchema(compiled);
+        await config.storage.ensureSchema(compiled, config.checkpoints);
     }
     catch (cause) {
+        // RFC 0007: a declared-but-incomplete checkpoint is a barrier refusal, not
+        // an ordinary migration failure — hosts distinguish it by `phase` while the
+        // client-visible identity stays `sync.schema_not_ready`.
+        const phase = cause?.code ===
+            'sync.storage.checkpoint_incomplete'
+            ? 'backfill_checkpoint'
+            : 'storage_migration';
         throw new SyncServerReadinessError({
-            phase: 'storage_migration',
+            phase,
             schemaVersion: config.schema.version,
             cause,
         });
     }
 }
+/**
+ * RFC 0007: refuse a serve path that observed a closed gate. The projection
+ * name travels in structured details, never in the message.
+ */
+export function serveNotReadyError(refusal) {
+    return syncError(SYNC_SERVER_READINESS_ERROR_CODE, 'server schema is not ready for this request', refusal.kind === 'checkpoint'
+        ? JSON.stringify({
+            partition: refusal.partition,
+            projection: refusal.name,
+        })
+        : refusal.kind === 'epoch'
+            ? JSON.stringify({ logEpochChanged: true })
+            : JSON.stringify({
+                storedSchemaVersion: refusal.stored,
+                runningSchemaVersion: refusal.running,
+            }));
+}

package/dist/realtime.js

@@ -446,7 +446,26 @@ export class RealtimeSession {
             // begin its next round as soon as END *arrives* (§8.7 rule 3), so
             // in-flight must end with the send, not with generator cleanup.
             const iterator = stream[Symbol.asyncIterator]();
-            let step = await iterator.next();
+            let step;
+            try {
+                step = await iterator.next();
+            }
+            catch (error) {
+                // The buffered read-verify refusal is thrown on the generator's first
+                // `next()`, before any chunk is yielded (the generator builds the whole
+                // response, then verifies). Nothing has escaped, so it is delivered as
+                // the same §8.4 ERROR frame HTTP returns rather than a silent close. A
+                // throw after the first chunk still takes the §8.7 violation path.
+                if (error instanceof DecodeError || error instanceof SyncError) {
+                    const sync = error instanceof SyncError
+                        ? error
+                        : syncError(error.code, error.message);
+                    finishRound();
+                    await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
+                    return;
+                }
+                throw error;
+            }
             while (!step.done) {
                 const chunk = step.value;
                 step = await iterator.next();

package/dist/segment-download.js

@@ -136,6 +136,14 @@ async function downloadSegment(ctx, request) {
         throw syncError('sync.invalid_subscription', 'invalid requested scopes (§3.2)');
     }
     const publication = candidates[candidates.length - 1];
+    // RFC 0007: a descriptor minted before this partition declared a backfill
+    // checkpoint is not a complete window once the projection becomes
+    // checkpointed. SPEC §9 mints segments per schema version, so refuse and
+    // let the client re-pull for a fresh descriptor.
+    const checkpoints = await ctx.storage.readCheckpoints(ctx.partition);
+    if (checkpoints.some((checkpoint) => checkpoint.schemaVersion > publication.schemaVersion)) {
+        throw syncError('sync.segment_expired', 'segment predates the partition backfill checkpoint — re-pull (§5.1)');
+    }
     return {
         // The returned record is projected onto the selected publication, so its
         // `scopeDigests`/`publications` compatibility view cannot union a grant

package/dist/sqlite-dialect.d.ts

@@ -36,7 +36,7 @@ import type { StoredChange, StoredCommit, StoredPushResult, StoredRow } from './
  * inverted index. Declared here so every SQLite-family storage (and D1,
  * which applies this same DDL) keeps the same plan shape as Postgres.
  */
-export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq INTEGER NOT NULL DEFAULT 0,\n  horizon_seq INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n  partition TEXT PRIMARY KEY,\n  log_epoch TEXT NOT NULL,\n  epoch_required INTEGER NOT NULL DEFAULT 0,\n  last_authenticated_at_ms INTEGER NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE INDEX IF NOT EXISTS sync_row_scopes_by_row\n  ON sync_row_scopes(partition, tbl, row_id);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n  row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result TEXT NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n  last_failure TEXT,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  wire_version INTEGER NOT NULL DEFAULT 1,\n  cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n  updated_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id)\n);\n";
+export declare const SQLITE_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq INTEGER NOT NULL DEFAULT 0,\n  horizon_seq INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n  partition TEXT PRIMARY KEY,\n  log_epoch TEXT NOT NULL,\n  epoch_required INTEGER NOT NULL DEFAULT 0,\n  last_authenticated_at_ms INTEGER NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE INDEX IF NOT EXISTS sync_row_scopes_by_row\n  ON sync_row_scopes(partition, tbl, row_id);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,\n  writer_version INTEGER,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq INTEGER NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op INTEGER NOT NULL,\n  row_version INTEGER, scopes TEXT NOT NULL, payload BLOB,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result TEXT NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq INTEGER NOT NULL, created_at_ms INTEGER NOT NULL,\n  available_at_ms INTEGER NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms INTEGER, completed_at_ms INTEGER,\n  last_failure TEXT,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  wire_version INTEGER NOT NULL DEFAULT 1,\n  cursor INTEGER NOT NULL, subscriptions TEXT NOT NULL,\n  updated_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  commit_seq INTEGER NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(\n  partition TEXT NOT NULL, name TEXT NOT NULL,\n  schema_version INTEGER NOT NULL,\n  state TEXT NOT NULL CHECK(state IN ('declared','backfilling','activated')),\n  watermark INTEGER NOT NULL DEFAULT 0,\n  owner_epoch INTEGER NOT NULL DEFAULT 0,\n  observed_rows INTEGER NOT NULL DEFAULT 0,\n  updated_at_ms INTEGER NOT NULL,\n  PRIMARY KEY(partition, name)\n);\nCREATE TABLE IF NOT EXISTS sync_writer_fence(\n  partition TEXT PRIMARY KEY,\n  required_writer_version INTEGER NOT NULL\n);\n";
 /** Split the DDL into individual statements (D1 applies them one by one). */
 export declare function sqliteDdlStatements(): string[];
 /** `?,?,…` for an `IN (…)` clause of `count` positional parameters. */

package/dist/sqlite-dialect.js

@@ -41,6 +41,7 @@ CREATE TABLE IF NOT EXISTS sync_commits(
   partition TEXT NOT NULL, commit_seq INTEGER NOT NULL,
   client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,
   actor_id TEXT NOT NULL, created_at_ms INTEGER NOT NULL,
+  writer_version INTEGER,
   PRIMARY KEY(partition, commit_seq)
 );
 CREATE INDEX IF NOT EXISTS sync_commits_by_time
@@ -102,6 +103,20 @@ CREATE TABLE IF NOT EXISTS sync_tombstones(
   commit_seq INTEGER NOT NULL,
   PRIMARY KEY(partition, tbl, row_id)
 );
+CREATE TABLE IF NOT EXISTS sync_backfill_checkpoints(
+  partition TEXT NOT NULL, name TEXT NOT NULL,
+  schema_version INTEGER NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('declared','backfilling','activated')),
+  watermark INTEGER NOT NULL DEFAULT 0,
+  owner_epoch INTEGER NOT NULL DEFAULT 0,
+  observed_rows INTEGER NOT NULL DEFAULT 0,
+  updated_at_ms INTEGER NOT NULL,
+  PRIMARY KEY(partition, name)
+);
+CREATE TABLE IF NOT EXISTS sync_writer_fence(
+  partition TEXT PRIMARY KEY,
+  required_writer_version INTEGER NOT NULL
+);
 `;
 /** Split the DDL into individual statements (D1 applies them one by one). */
 export function sqliteDdlStatements() {

package/dist/sqlite-storage.d.ts

@@ -1,14 +1,14 @@
 import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import { type SqliteDatabase } from './sqlite-driver.js';
-import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, StorageTransaction, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export declare class SqliteServerStorage implements ServerStorage {
     #private;
     readonly db: SqliteDatabase;
     constructor(db?: SqliteDatabase | string);
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name: string): CompiledTable;
-    ensureSchema(schema: CompiledSchema): Promise<void>;
+    ensureSchema(schema: CompiledSchema, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
     touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
     rotatePartitionLogEpoch(partition: string, logEpoch: string, authenticatedAtMs: number): Promise<PartitionRegistryEntry>;
     listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
@@ -16,12 +16,20 @@ export declare class SqliteServerStorage implements ServerStorage {
     /** Internal: write a row + refresh its scope-index entries. */
     writeRow(partition: string, table: string, row: StoredRow): void;
     getMaxCommitSeq(partition: string): Promise<number>;
-    queryAuthoritative(partition: string, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
+    queryAuthoritative(partition: string, query: AuthoritativeQueryRequest, checkpoints?: readonly CheckpointDeclaration[]): Promise<AuthoritativeQueryResult>;
     getPartitionLogEpoch(partition: string): Promise<string | undefined>;
     getHorizonSeq(partition: string): Promise<number>;
     setHorizonSeq(partition: string, seq: number): Promise<void>;
     pruneCommitsThrough(partition: string, query: CommitPruneQuery): Promise<CommitPruneResult>;
     getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
+    readServeGate(partition: string, runningSchemaVersion: number): Promise<ServeGate>;
+    readCheckpoints(partition: string): Promise<StoredCheckpoint[]>;
+    declareCheckpoint(partition: string, name: string, schemaVersion: number, nowMs: number): Promise<StoredCheckpoint>;
+    activateCheckpoint(partition: string, name: string, ownerEpoch: number, watermark: number, sources: readonly string[], nowMs: number): Promise<'activated' | 'stale' | 'unverifiable'>;
+    claimCheckpoint(partition: string, name: string, schemaVersion: number, nowMs: number): Promise<StoredCheckpoint>;
+    advanceCheckpoint(partition: string, name: string, ownerEpoch: number, watermark: number, observedRows: number, nowMs: number): Promise<boolean>;
+    sourceCoverageSeq(partition: string, tables: readonly string[]): Promise<number>;
+    hasSourceChangesAbove(partition: string, tables: readonly string[], seq: number): Promise<'clean' | 'changed' | 'unverifiable'>;
     getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
     getPushResult(partition: string, clientId: string, clientCommitId: string): Promise<StoredPushResult | undefined>;
     claimReactions(partition: string, query: ReactionClaimQuery): Promise<StoredReaction[]>;