@syncular/server 0.21.1 → 0.23.0

package/dist/postgres-storage.js

@@ -1,9 +1,11 @@
 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';
-import { commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -17,7 +19,14 @@ import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js'
  *   - `sync_row_scopes_pk (partition, tbl, var, value, row_id)` — same shape
  *     for `scanRows`, ordered by `row_id`.
  * Both are the PRIMARY KEY, so they are the clustering/covering index for
- * their table. No secondary index is needed for the hot path.
+ * their table.
+ *
+ * `sync_row_scopes_by_row (partition, tbl, row_id)` is the one secondary
+ * scope index: `writeRowOn` and `deleteRow` replace a row's scope entries
+ * with a `(partition, tbl, row_id)` predicate, and `row_id` is the LAST
+ * column of the inverted PRIMARY KEY, so without this index that predicate
+ * scans the table's whole scope range on every row written (a bulk import
+ * costs one such scan per row).
  *
  * Blob reference index (§5.9.4) — parity with the SQLite dialect's
  * `sync_blob_refs`:
@@ -46,10 +55,13 @@ CREATE TABLE IF NOT EXISTS sync_row_scopes(
   var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
   PRIMARY KEY(partition, tbl, var, value, row_id)
 );
+CREATE INDEX IF NOT EXISTS sync_row_scopes_by_row
+  ON sync_row_scopes(partition, tbl, row_id);
 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
@@ -113,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]);
@@ -124,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,
@@ -332,15 +422,31 @@ 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) {
-        this.#client = client;
+    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
+        // out with Promise.all must not interleave them, so every statement
+        // issued through this transaction is chained on one FIFO — the same
+        // shape as `SqliteServerStorage.queryAuthoritative`.
+        let tail = Promise.resolve();
+        this.#client = {
+            query: (text, params) => {
+                const run = tail.then(() => client.query(text, params));
+                tail = run.then(() => undefined, () => undefined);
+                return run;
+            },
+        };
         this.#partition = partition;
+        this.#writerVersion = writerVersion;
         this.#resolveTable = resolveTable;
         this.#resolve = resolve;
         this.#reject = reject;
@@ -417,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) {
@@ -469,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++) {
@@ -593,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) {
@@ -602,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
@@ -615,6 +774,60 @@ export class PostgresServerStorage {
         if (stored !== undefined && stored > schema.version) {
             throw new Error(`stored schema version ${stored} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
         }
+        if (stored !== undefined && stored === schema.version) {
+            // Version equality is not layout equality: a marker written by another
+            // build at the same version describes rows the running codec cannot
+            // decode. Compare the stored layouts instead of trusting the number.
+            const storedLayouts = parseLayouts(typeof marker.rows[0]?.layouts === 'string'
+                ? marker.rows[0].layouts
+                : undefined);
+            const configuredLayouts = parseLayouts(layoutsOf(schema));
+            let mismatch;
+            for (const [tableName, columns] of Object.entries(configuredLayouts)) {
+                const storedTable = storedLayouts[tableName];
+                const columnCount = Math.max(columns.length, storedTable?.length ?? 0);
+                for (let index = 0; index < columnCount; index++) {
+                    const expected = columns[index];
+                    const actual = storedTable?.[index];
+                    if (expected !== undefined &&
+                        actual !== undefined &&
+                        actual.name === expected.name &&
+                        actual.type === expected.type &&
+                        actual.nullable === expected.nullable) {
+                        continue;
+                    }
+                    mismatch = `table ${JSON.stringify(tableName)} column ${JSON.stringify(expected?.name ?? actual?.name ?? '')}`;
+                    break;
+                }
+                if (mismatch !== undefined)
+                    break;
+            }
+            if (mismatch === undefined) {
+                for (const tableName of Object.keys(storedLayouts)) {
+                    if (!(tableName in configuredLayouts)) {
+                        mismatch = `table ${JSON.stringify(tableName)}`;
+                        break;
+                    }
+                }
+            }
+            if (mismatch !== undefined) {
+                throw new Error(`stored schema layouts disagree with the configured schema at version ${schema.version} (${mismatch}) — refusing to serve a database whose stored rows the running code cannot decode`);
+            }
+            // The persisted layouts describe the codec's app columns only: read the
+            // physical tables so a same-version database missing a
+            // storage-internal column is refused at startup instead of failing at
+            // the first write. Resolve through `to_regclass`, which follows the
+            // session's `search_path` exactly as the unqualified row queries do —
+            // `current_schema()` names only the first existing schema, so it would
+            // reject a table that resolves later in the path.
+            for (const table of schema.tables.values()) {
+                const { rows } = await this.#exec.query(`SELECT attribute.attname AS column_name
+           FROM pg_attribute attribute
+           WHERE attribute.attrelid = to_regclass($1)
+             AND attribute.attnum > 0 AND NOT attribute.attisdropped`, [table.name]);
+                assertPhysicalColumns(table, new Set(rows.map((r) => r.column_name)));
+            }
+        }
         if (stored === undefined || stored < schema.version) {
             // Introspect existing app tables, apply the migration subset
             // (CREATE TABLE / ADD COLUMN / rebuild indexes), then rewrite stored
@@ -627,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()) {
@@ -680,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;
@@ -759,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;
@@ -777,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 {
@@ -834,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/pull.js

@@ -108,7 +108,7 @@ async function signedUrlFields(ctx, limits, segmentId, digest, now) {
         nowMs: now,
     });
 }
-function segmentRefFrame(record, extra) {
+function segmentRefFrame(record, scopeDigest, extra) {
     return {
         type: 'SEGMENT_REF',
         segmentId: record.segmentId,
@@ -117,7 +117,11 @@ function segmentRefFrame(record, extra) {
         byteLength: record.byteLength,
         rowCount: record.rowCount,
         asOfCommitSeq: record.asOfCommitSeq,
-        scopeDigest: record.scopeDigest,
+        // The frame reports the digest THIS subscription is authorized under. A
+        // stored entry can carry several digests when identical content was
+        // published under different scopes (§5.1), and the record's primary
+        // digest is not necessarily the caller's (§5.5).
+        scopeDigest,
         ...(record.rowCursor !== null ? { rowCursor: record.rowCursor } : {}),
         ...(record.nextRowCursor !== null
             ? { nextRowCursor: record.nextRowCursor }
@@ -156,7 +160,7 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
             bytes: existing.byteLength,
             rows: existing.rowCount,
         });
-        yield segmentRefFrame(existing, await signedUrlFields(ctx, limits, existing.segmentId, digest, now));
+        yield segmentRefFrame(existing, digest, await signedUrlFields(ctx, limits, existing.segmentId, digest, now));
         return true;
     }
     // Eligibility probe (§5.3): image only when the snapshot exceeds one
@@ -253,7 +257,7 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
         bytes: record.byteLength,
         rows: record.rowCount,
     });
-    yield segmentRefFrame(record, await signedUrlFields(ctx, limits, record.segmentId, digest, clockOf(ctx)()));
+    yield segmentRefFrame(record, digest, await signedUrlFields(ctx, limits, record.segmentId, digest, clockOf(ctx)()));
     return true;
 }
 async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace, logEpoch) {
@@ -331,7 +335,7 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
                 bytes: record.byteLength,
                 rows: record.rowCount,
             });
-            yield segmentRefFrame(record, await signedUrlFields(ctx, limits, record.segmentId, digest, now));
+            yield segmentRefFrame(record, digest, await signedUrlFields(ctx, limits, record.segmentId, digest, now));
         }
         if (!hasMore)
             return { complete: true, rowCursor: null };

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,
+            }));
+}