@syncular/server 0.22.0 → 0.24.0

package/dist/postgres-storage.d.ts

@@ -1,7 +1,7 @@
 import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
 import { type PgExecutor } from './pg-executor.js';
 import type { CompiledSchema, CompiledTable } from './schema.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, StoredCheckpoint, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 /**
  * Schema DDL. Applied by `PostgresServerStorage.migrate()` (idempotent).
  *
@@ -31,7 +31,7 @@ import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorI
  *     set, §5.9.5) as an index range, never a scan. `postgres-explain
  *     .test.ts` asserts an `Index` node here too.
  */
-export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT 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 BOOLEAN NOT NULL DEFAULT FALSE,\n  last_authenticated_at_ms BIGINT 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 BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT 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 BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\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 BIGINT 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 JSONB 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 JSONB NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,\n  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,\n  last_failure JSONB,\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 BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nALTER TABLE sync_clients\n  ADD COLUMN IF NOT EXISTS wire_version INTEGER NOT NULL DEFAULT 1;\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 BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id)\n);\n";
+export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT 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 BOOLEAN NOT NULL DEFAULT FALSE,\n  last_authenticated_at_ms BIGINT 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 BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT NOT NULL,\n  writer_version BIGINT,\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 BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\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 BIGINT 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 JSONB 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 JSONB NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,\n  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,\n  last_failure JSONB,\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 BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nALTER TABLE sync_clients\n  ADD COLUMN IF NOT EXISTS wire_version INTEGER NOT NULL DEFAULT 1;\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 BIGINT 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 BIGINT NOT NULL DEFAULT 0,\n  owner_epoch BIGINT NOT NULL DEFAULT 0,\n  observed_rows BIGINT NOT NULL DEFAULT 0,\n  updated_at_ms BIGINT 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";
 export declare class PostgresServerStorage implements ServerStorage {
     #private;
     constructor(exec: PgExecutor);
@@ -39,7 +39,7 @@ export declare class PostgresServerStorage implements ServerStorage {
     migrate(): Promise<void>;
     /** 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[]>;
@@ -53,12 +53,20 @@ export declare class PostgresServerStorage implements ServerStorage {
      */
     begin(partition: string): Promise<StorageTransaction>;
     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>;
+    readCheckpoints(partition: string): Promise<StoredCheckpoint[]>;
+    readServeGate(partition: string, runningSchemaVersion: number): Promise<ServeGate>;
+    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[]>;

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 { 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 { assertPhysicalColumns, assertStoredLayouts, 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';
@@ -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,
@@ -338,16 +419,31 @@ async function getPushResultOn(q, partition, clientId, clientCommitId) {
         throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
     }
 }
+/** Run one partition-bound registered query and the cursor read on `client`. */
+async function queryAuthoritativeOn(client, partition, prepared) {
+    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 {
+        rows: result.rows,
+        maxCommitSeq: cursor.rows[0] === undefined
+            ? 0
+            : asNumber(cursor.rows[0].max_commit_seq),
+    };
+}
 class PostgresTransaction {
     #client;
     #partition;
+    /** Storage-owned relation rewrite, bound to this transaction's partition. */
+    #prepareQuery;
+    /** 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, prepareQuery, 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,7 +459,9 @@ class PostgresTransaction {
             },
         };
         this.#partition = partition;
+        this.#writerVersion = writerVersion;
         this.#resolveTable = resolveTable;
+        this.#prepareQuery = prepareQuery;
         this.#resolve = resolve;
         this.#reject = reject;
     }
@@ -433,12 +531,36 @@ class PostgresTransaction {
         this.#assertOpen();
         return scanRowsByIndexOn(this.#client, this.#resolveTable(query.table), this.#partition, query);
     }
+    queryAuthoritative(query) {
+        this.#assertOpen();
+        // Runs on this transaction's pinned client, so the read observes every
+        // staged row and never waits for a second pool connection.
+        return queryAuthoritativeOn(this.#client, this.#partition, this.#prepareQuery(query));
+    }
     async lockPartitionForPush() {
         this.#assertOpen();
         await lockPartitionOn(this.#client, this.#partition);
         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 +613,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 +738,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 +770,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
@@ -638,57 +795,32 @@ export class PostgresServerStorage {
             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'
+            assertStoredLayouts(schema, 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 —
+            // 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
+                const { rows } = await this.#exec.query(`SELECT attribute.attname AS name,
+                  format_type(attribute.atttypid, attribute.atttypmod) AS type,
+                  attribute.attnotnull AS not_null,
+                  (SELECT key.position::int
+                     FROM pg_index pk,
+                          unnest(pk.indkey::int2[]) WITH ORDINALITY
+                            AS key(attnum, position)
+                    WHERE pk.indrelid = attribute.attrelid AND pk.indisprimary
+                      AND key.attnum = attribute.attnum) AS pk
            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)));
+                assertPhysicalColumns(table, rows.map((row) => ({
+                    name: row.name,
+                    type: row.type,
+                    notNull: row.not_null,
+                    primaryKeyPosition: row.pk ?? 0,
+                })), 'postgres');
             }
         }
         if (stored === undefined || stored < schema.version) {
@@ -703,6 +835,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 +899,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 +985,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), (query) => this.#prepareAuthoritativeQuery(partition, query), resolveScope, rejectScope);
             resolveReady(tx);
             // Hold the transaction open until commit()/rollback() settles `scope`.
             await scope;
@@ -853,21 +1003,26 @@ 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) {
+    #prepareAuthoritativeQuery(partition, query) {
         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 bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
+    }
+    async queryAuthoritative(partition, query, checkpoints) {
+        const prepared = this.#prepareAuthoritativeQuery(partition, query);
         return this.#exec.transaction(async (client) => {
             await client.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
-            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 {
-                rows: result.rows,
-                maxCommitSeq: cursor.rows[0] === undefined
-                    ? 0
-                    : asNumber(cursor.rows[0].max_commit_seq),
-            };
+            // 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);
+            return queryAuthoritativeOn(client, partition, prepared);
         });
     }
     async getPartitionLogEpoch(partition) {
@@ -910,6 +1065,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);
     }