@syncular/server 0.22.0 → 0.23.0

package/dist/sqlite-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';
 /**
  * SQLite server storage over the shared synchronous driver.
  *
@@ -12,10 +14,22 @@ import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './author
 import { syncError } from './errors.js';
 import { assertPhysicalColumns, commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { collectCommitWindowPage, deserializePushResult, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
+import { collectCommitWindowPage, deserializePushResult, placeholders, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
 import { isSqliteConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
+function toStoredCheckpoint(record) {
+    return {
+        partition: record.partition,
+        name: record.name,
+        schemaVersion: record.schema_version,
+        state: record.state,
+        watermark: record.watermark,
+        ownerEpoch: record.owner_epoch,
+        observedRows: record.observed_rows,
+        updatedAtMs: record.updated_at_ms,
+    };
+}
 function toStoredReaction(record) {
     return {
         idempotencyKey: record.idempotency_key,
@@ -45,12 +59,15 @@ function toStoredReaction(record) {
 class SqliteTransaction {
     #storage;
     #partition;
+    /** Schema version this transaction writes; rides every appended commit row. */
+    #writerVersion;
     #open = true;
     #pushApplySavepoint = false;
     #release;
-    constructor(storage, partition, release) {
+    constructor(storage, partition, writerVersion, release) {
         this.#storage = storage;
         this.#partition = partition;
+        this.#writerVersion = writerVersion;
         this.#release = release;
         storage.db.exec('BEGIN IMMEDIATE');
     }
@@ -95,6 +112,21 @@ class SqliteTransaction {
         this.#storage.db.exec('SAVEPOINT syncular_push_candidate');
         this.#pushApplySavepoint = true;
     }
+    async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
+        this.#assertOpen();
+        const result = this.#storage.db
+            .query(`UPDATE sync_backfill_checkpoints
+            SET watermark=?, observed_rows=?, updated_at_ms=?
+          WHERE partition=? AND name=? AND owner_epoch=?`)
+            .run(watermark, observedRows, nowMs, this.#partition, name, ownerEpoch);
+        return Number(result.changes) === 1;
+    }
+    readServeGate(runningSchemaVersion) {
+        this.#assertOpen();
+        // Same shared connection: this read runs inside this transaction's
+        // BEGIN IMMEDIATE, so the gate and the write share one transaction.
+        return this.#storage.readServeGate(this.#partition, runningSchemaVersion);
+    }
     async commitRejectedPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
         if (!this.#pushApplySavepoint) {
@@ -146,7 +178,7 @@ class SqliteTransaction {
             .get(p);
         const commitSeq = (row?.max_commit_seq ?? 0) + 1;
         db.query('UPDATE sync_partitions SET max_commit_seq=? WHERE partition=?').run(commitSeq, p);
-        db.query('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms) VALUES (?,?,?,?,?,?)').run(p, commitSeq, commit.clientId, commit.clientCommitId, commit.actorId, commit.createdAtMs);
+        db.query('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)').run(p, commitSeq, commit.clientId, commit.clientCommitId, commit.actorId, commit.createdAtMs, this.#writerVersion);
         commit.changes.forEach((change, idx) => {
             db.query('INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)').run(p, commitSeq, idx, change.table, change.rowId, change.op === 'upsert' ? 1 : 2, change.rowVersion ?? null, JSON.stringify(change.scopes), change.payload ?? null);
             if (change.op === 'delete') {
@@ -247,6 +279,30 @@ export class SqliteServerStorage {
         if (!clientColumns.some((column) => column.name === 'wire_version')) {
             this.db.exec('ALTER TABLE sync_clients ADD COLUMN wire_version INTEGER NOT NULL DEFAULT 1');
         }
+        const commitColumns = this.db
+            .query('PRAGMA table_info("sync_commits")')
+            .all();
+        if (!commitColumns.some((column) => column.name === 'writer_version')) {
+            // Nullable by design: an old writer omits the column and the trigger's
+            // explicit NULL test rejects it. `ADD COLUMN NOT NULL` is unavailable in
+            // SQLite, and a default would hand old writers a passing value.
+            this.db.exec('ALTER TABLE sync_commits ADD COLUMN writer_version INTEGER');
+        }
+        // The fence is database-side: an old binary's INSERT never reaches JS. An
+        // absent `sync_writer_fence` row makes the WHEN clause false, so a
+        // partition with no barrier behaves exactly as before.
+        this.db.exec(`CREATE TRIGGER IF NOT EXISTS sync_commits_writer_fence
+BEFORE INSERT ON sync_commits
+FOR EACH ROW
+WHEN EXISTS (
+  SELECT 1 FROM sync_writer_fence
+   WHERE partition = NEW.partition
+     AND (NEW.writer_version IS NULL
+          OR NEW.writer_version < required_writer_version)
+)
+BEGIN
+  SELECT RAISE(ABORT, 'sync.storage.writer_fence_rejected');
+END`);
     }
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name) {
@@ -256,10 +312,24 @@ export class SqliteServerStorage {
         }
         return table;
     }
-    async ensureSchema(schema) {
+    async ensureSchema(schema, checkpoints) {
         // Memoized fast path: same instance, same schema version.
         if (this.#schemaVersion === schema.version)
             return;
+        // 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 = this.db
+            .query(`SELECT partition, name FROM sync_backfill_checkpoints
+          WHERE schema_version=? AND state<>'activated'`)
+            .all(schema.version)
+            .filter((row) => !declarations.some((declaration) => declaration.partition === row.partition &&
+            declaration.name === row.name));
+        if (incomplete.length > 0) {
+            throw new StorageQueryError('sync.storage.checkpoint_incomplete');
+        }
         this.db.exec(SCHEMA_META_DDL_SQLITE);
         const marker = this.db
             .query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1')
@@ -340,36 +410,50 @@ export class SqliteServerStorage {
                     existingIndexes.set(table.name, new Set(indexes.map((index) => index.name)));
                 }
             }
-            this.db.exec('BEGIN IMMEDIATE');
-            try {
-                for (const tableName of retiredTables) {
-                    this.db
-                        .query('DELETE FROM sync_row_scopes WHERE tbl=?')
-                        .run(tableName);
+            // The migration rewrites application rows (`#rewriteRows`) with no
+            // commit log entry. Serialize it through the same writer queue as
+            // pushes and prune (`#serializeWrite`) rather than trusting the
+            // migration as privileged; `BEGIN IMMEDIATE` then owns SQLite's writer
+            // lock for the whole rewrite.
+            await this.#serializeWrite(() => {
+                this.db.exec('BEGIN IMMEDIATE');
+                try {
+                    for (const tableName of retiredTables) {
+                        this.db
+                            .query('DELETE FROM sync_row_scopes WHERE tbl=?')
+                            .run(tableName);
+                        this.db
+                            .query('DELETE FROM sync_blob_refs WHERE tbl=?')
+                            .run(tableName);
+                        this.db.exec(dropTableDdl(tableName));
+                    }
+                    for (const statement of schemaDdl(schema, existing, 'sqlite', existingIndexes)) {
+                        this.db.exec(statement);
+                    }
+                    for (const table of schema.tables.values()) {
+                        const oldLayout = layouts[table.name];
+                        const plan = rewritePlan(table, oldLayout, existing.get(table.name));
+                        if (!plan.migrate && !plan.backfill)
+                            continue;
+                        this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
+                    }
                     this.db
-                        .query('DELETE FROM sync_blob_refs WHERE tbl=?')
-                        .run(tableName);
-                    this.db.exec(dropTableDdl(tableName));
-                }
-                for (const statement of schemaDdl(schema, existing, 'sqlite', existingIndexes)) {
-                    this.db.exec(statement);
+                        .query('INSERT INTO sync_schema_meta(id, schema_version, layouts) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET schema_version=excluded.schema_version, layouts=excluded.layouts')
+                        .run(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 ?? []) {
+                        this.#installCheckpoint(declaration.partition, declaration.name, declaration.schemaVersion, installedAtMs);
+                    }
+                    this.db.exec('COMMIT');
                 }
-                for (const table of schema.tables.values()) {
-                    const oldLayout = layouts[table.name];
-                    const plan = rewritePlan(table, oldLayout, existing.get(table.name));
-                    if (!plan.migrate && !plan.backfill)
-                        continue;
-                    this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
+                catch (error) {
+                    this.db.exec('ROLLBACK');
+                    throw error;
                 }
-                this.db
-                    .query('INSERT INTO sync_schema_meta(id, schema_version, layouts) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET schema_version=excluded.schema_version, layouts=excluded.layouts')
-                    .run(schema.version, layoutsOf(schema));
-                this.db.exec('COMMIT');
-            }
-            catch (error) {
-                this.db.exec('ROLLBACK');
-                throw error;
-            }
+            });
         }
         this.#tables = schema.tables;
         this.#schemaVersion = schema.version;
@@ -485,7 +569,7 @@ export class SqliteServerStorage {
         });
         await previous;
         try {
-            return new SqliteTransaction(this, partition, release);
+            return new SqliteTransaction(this, partition, this.#schemaVersion ?? 0, release);
         }
         catch (error) {
             release();
@@ -513,7 +597,7 @@ export class SqliteServerStorage {
             .get(partition);
         return row?.max_commit_seq ?? 0;
     }
-    async queryAuthoritative(partition, query) {
+    async queryAuthoritative(partition, query, checkpoints) {
         if (this.#tables === undefined) {
             throw new Error('ensureSchema(schema) must run before registered queries');
         }
@@ -528,6 +612,14 @@ export class SqliteServerStorage {
         try {
             this.db.exec('BEGIN');
             open = true;
+            // RFC 0007: evaluate the gate on this connection after BEGIN. SQLite is
+            // single-writer and the shared connection serializes writers, so the
+            // gate read and the query read cannot straddle a migration.
+            const runningVersion = this.#schemaVersion ?? 0;
+            const gate = await this.readServeGate(partition, runningVersion);
+            const refusal = serveGateRefusal(gate, runningVersion, checkpoints);
+            if (refusal !== undefined)
+                throw serveNotReadyError(refusal);
             const rows = this.db
                 .query(prepared.sql)
                 .all(...prepared.params);
@@ -616,6 +708,177 @@ export class SqliteServerStorage {
             .get(partition, createdBeforeMs);
         return row?.seq ?? 0;
     }
+    async readServeGate(partition, runningSchemaVersion) {
+        const marker = this.db
+            .query('SELECT schema_version FROM sync_schema_meta WHERE id=1')
+            .get();
+        const epoch = this.db
+            .query('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
+            .get(partition);
+        const pending = this.db
+            .query(`SELECT partition, name FROM sync_backfill_checkpoints
+          WHERE schema_version=? AND state<>'activated'`)
+            .all(runningSchemaVersion);
+        return {
+            storedSchemaVersion: marker?.schema_version ?? 0,
+            logEpoch: epoch?.log_epoch,
+            pending: pending.map((row) => ({
+                partition: row.partition,
+                name: row.name,
+            })),
+        };
+    }
+    async readCheckpoints(partition) {
+        return this.db
+            .query(`SELECT partition, name, schema_version, state, watermark,
+                owner_epoch, observed_rows, updated_at_ms
+           FROM sync_backfill_checkpoints WHERE partition=? ORDER BY name`)
+            .all(partition)
+            .map(toStoredCheckpoint);
+    }
+    /**
+     * Insert the `declared` row and raise the fence, inside 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.
+     */
+    #installCheckpoint(partition, name, schemaVersion, nowMs) {
+        this.db
+            .query(`INSERT INTO sync_backfill_checkpoints(
+           partition, name, schema_version, state, watermark,
+           owner_epoch, observed_rows, updated_at_ms)
+         VALUES (?,?,?,'declared',0,0,0,?)
+         ON CONFLICT(partition, name) DO NOTHING`)
+            .run(partition, name, schemaVersion, nowMs);
+        this.db
+            .query(`INSERT INTO sync_writer_fence(partition, required_writer_version)
+         VALUES (?,?)
+         ON CONFLICT(partition) DO UPDATE SET
+           required_writer_version=max(
+             sync_writer_fence.required_writer_version,
+             excluded.required_writer_version)`)
+            .run(partition, schemaVersion);
+    }
+    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.
+        return this.#serializeWrite(() => {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                this.#installCheckpoint(partition, name, schemaVersion, nowMs);
+                const row = this.db
+                    .query(`SELECT partition, name, schema_version, state, watermark,
+                    owner_epoch, observed_rows, updated_at_ms
+               FROM sync_backfill_checkpoints WHERE partition=? AND name=?`)
+                    .get(partition, name);
+                if (row === null)
+                    throw new StorageQueryError('sync.storage.checkpoint_not_declared');
+                this.db.exec('COMMIT');
+                return toStoredCheckpoint(row);
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+        });
+    }
+    async activateCheckpoint(partition, name, ownerEpoch, watermark, sources, nowMs) {
+        return this.#serializeWrite(() => {
+            // `BEGIN IMMEDIATE` is SQLite's partition write lock; the same writer
+            // lock a push takes. Nothing may observe activation without the fence.
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                const fence = this.db
+                    .query('SELECT required_writer_version FROM sync_writer_fence WHERE partition=?')
+                    .get(partition);
+                const checkpoint = this.db
+                    .query('SELECT schema_version FROM sync_backfill_checkpoints WHERE partition=? AND name=?')
+                    .get(partition, name);
+                if (fence === null ||
+                    checkpoint === null ||
+                    fence.required_writer_version < checkpoint.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 = this.#hasSourceChangesAbove(partition, sources, watermark);
+                if (coverage !== 'clean') {
+                    this.db.exec('ROLLBACK');
+                    return coverage === 'changed' ? 'stale' : 'unverifiable';
+                }
+                const updated = this.db
+                    .query(`UPDATE sync_backfill_checkpoints
+                SET state='activated', watermark=?, updated_at_ms=?
+              WHERE partition=? AND name=? AND owner_epoch=?
+                AND state<>'activated'`)
+                    .run(watermark, nowMs, partition, name, ownerEpoch);
+                this.db.exec('COMMIT');
+                return Number(updated.changes) === 1 ? 'activated' : 'stale';
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+        });
+    }
+    async claimCheckpoint(partition, name, schemaVersion, nowMs) {
+        return this.#serializeWrite(() => {
+            const claimed = this.db
+                .query(`UPDATE sync_backfill_checkpoints
+              SET owner_epoch=owner_epoch+1,
+                  state=CASE WHEN state='declared' THEN 'backfilling' ELSE state END,
+                  schema_version=?, updated_at_ms=?
+            WHERE partition=? AND name=? AND state<>'activated'
+        RETURNING partition, name, schema_version, state, watermark,
+                  owner_epoch, observed_rows, updated_at_ms`)
+                .get(schemaVersion, nowMs, partition, name);
+            if (claimed === null) {
+                throw new StorageQueryError('sync.storage.checkpoint_not_declared');
+            }
+            return toStoredCheckpoint(claimed);
+        });
+    }
+    async advanceCheckpoint(partition, name, ownerEpoch, watermark, observedRows, nowMs) {
+        return this.#serializeWrite(() => {
+            const result = this.db
+                .query(`UPDATE sync_backfill_checkpoints
+              SET watermark=?, observed_rows=?, updated_at_ms=?
+            WHERE partition=? AND name=? AND owner_epoch=?`)
+                .run(watermark, observedRows, nowMs, partition, name, ownerEpoch);
+            return Number(result.changes) === 1;
+        });
+    }
+    async sourceCoverageSeq(partition, tables) {
+        if (tables.length === 0)
+            return 0;
+        const row = this.db
+            .query(`SELECT max(commit_seq) AS seq FROM sync_changes
+          WHERE partition=? AND tbl IN (${placeholders(tables.length)})`)
+            .get(partition, ...tables);
+        return row?.seq ?? 0;
+    }
+    #hasSourceChangesAbove(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 = this.db
+            .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
+            .get(partition)?.horizon_seq ?? 0;
+        if (tables.length === 0)
+            return 'clean';
+        const hit = this.db
+            .query(`SELECT 1 AS hit FROM sync_changes
+          WHERE partition=? AND tbl IN (${placeholders(tables.length)})
+            AND commit_seq>? LIMIT 1`)
+            .get(partition, ...tables, seq);
+        if (hit !== null && hit !== undefined)
+            return 'changed';
+        return horizon > seq ? 'unverifiable' : 'clean';
+    }
+    async hasSourceChangesAbove(partition, tables, seq) {
+        return this.#hasSourceChangesAbove(partition, tables, seq);
+    }
     async getRow(partition, table, rowId) {
         const record = this.db
             .query(selectRowSql(this.table(table), 'sqlite'))

package/dist/storage-errors.d.ts

@@ -9,7 +9,7 @@ export declare class StorageConstraintError extends Error {
     constructor(cause: unknown, opIndex?: number);
 }
 /** Stable, privacy-safe failures for trusted server storage queries. */
-export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor';
+export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete';
 /**
  * Host-only query error. Messages never include identifiers, values, SQL,
  * paths, or row data; callers branch on `code`, never message text.

package/dist/storage-errors.js

@@ -19,6 +19,10 @@ const STORAGE_QUERY_MESSAGES = {
     'sync.storage.prune_epoch_mismatch': 'partition log epoch changed; recompute retention inputs',
     'sync.storage.partition_unregistered': 'pruning requires a registered partition',
     'sync.storage.invalid_prune_cursor': 'pruning requires a non-negative safe integer cursor and a non-empty log epoch',
+    'sync.storage.checkpoint_not_declared': 'checkpoint claim requires a declared, not yet activated row',
+    'sync.storage.checkpoint_unsupported': 'this storage backend cannot declare backfill checkpoints',
+    'sync.storage.checkpoint_fence_missing': 'checkpoint activation requires the writer fence raised at declaration',
+    'sync.storage.checkpoint_incomplete': 'a declared backfill checkpoint is not activated and this caller did not declare it',
     'sync.storage.scan_requires_scope': 'scope-indexed row scans require at least one scope variable',
     'sync.storage.index_not_found': 'trusted row lookup requires a declared relational index',
     'sync.storage.index_not_materialized': 'trusted row lookup requires a materialized relational table',

package/dist/storage.d.ts

@@ -28,6 +28,72 @@ export interface CommitPruneResult {
     readonly horizonSeq: number;
     readonly removedCommits: number;
 }
+/** RFC 0007 backfill lifecycle. `activated` is terminal within a schema version. */
+export type CheckpointState = 'declared' | 'backfilling' | 'activated';
+/**
+ * Host-owned checkpoint installation carried on `ensureSchema`: the schema
+ * bump, the `declared` row, and the raised writer fence commit together.
+ */
+export interface CheckpointDeclaration {
+    readonly partition: string;
+    readonly name: string;
+    readonly schemaVersion: number;
+}
+/** One host-storage backfill checkpoint row. Never a synced application row. */
+export interface StoredCheckpoint {
+    readonly partition: string;
+    readonly name: string;
+    readonly schemaVersion: number;
+    readonly state: CheckpointState;
+    /** Highest source `commit_seq` the projection was derived from. */
+    readonly watermark: number;
+    /** Monotonic claim counter; a batch is stale when it does not match. */
+    readonly ownerEpoch: number;
+    readonly observedRows: number;
+    readonly updatedAtMs: number;
+}
+/**
+ * RFC 0007 serve-gate token, read inside the transaction that produces the
+ * result. `storedSchemaVersion` is the published marker; `logEpoch` is the
+ * partition's log generation, so a restore that presents V -> other -> V is
+ * still distinguishable. `pending` names every incomplete declared checkpoint
+ * at the running schema version, across partitions.
+ */
+export interface ServeGate {
+    readonly storedSchemaVersion: number;
+    readonly logEpoch: string | undefined;
+    readonly pending: readonly {
+        readonly partition: string;
+        readonly name: string;
+    }[];
+}
+/** Why `serveGate` refuses, or `undefined` when this request may serve. */
+export type ServeGateRefusal = {
+    readonly kind: 'schema';
+    readonly stored: number;
+    readonly running: number;
+} | {
+    readonly kind: 'checkpoint';
+    readonly partition: string;
+    readonly name: string;
+} | {
+    /** The token changed between two reads: a restore rotated the epoch. */
+    readonly kind: 'epoch';
+};
+/**
+ * Evaluate the RFC 0007 predicate against a gate token. A process that
+ * declares the pending checkpoint may serve while it backfills; any other
+ * process is refused, and a database newer than the running build is always
+ * refused.
+ */
+export declare function serveGateRefusal(gate: ServeGate, runningSchemaVersion: number, checkpoints: readonly CheckpointDeclaration[] | undefined): ServeGateRefusal | undefined;
+/**
+ * RFC 0007: compare two gate tokens read around a data read. The token binds
+ * the published schema version and the partition log epoch, so a restore that
+ * presents V → other → V is distinguishable. Returns a refusal when either
+ * changed across the read.
+ */
+export declare function serveGateTokenChanged(before: ServeGate, after: ServeGate): ServeGateRefusal | undefined;
 /** The current stored state of a synced row. */
 export interface StoredRow {
     readonly rowId: string;
@@ -352,6 +418,21 @@ export interface StorageTransaction {
      * first writer wins; callers read the canonical value after commit.
      */
     putPushResult(clientId: string, clientCommitId: string, result: StoredPushResult): Promise<void>;
+    /**
+     * Advance this partition's checkpoint only while `owner_epoch` still
+     * matches, so the owner-epoch CAS rides inside the caller's transaction.
+     * The host calls this from `processPushOperationsWithTrace`'s operation
+     * builder: the backfill is an ordinary server-authoritative write, and this
+     * CAS commits with that write's row versions and commit-log append. False
+     * means abort and write nothing, rather than a throw for a superseded owner.
+     */
+    advanceCheckpoint(name: string, ownerEpoch: number, watermark: number, observedRows: number, nowMs: number): Promise<boolean>;
+    /**
+     * RFC 0007 serve gate on the caller's own connection, for write paths that
+     * already hold the partition lock: the gate and the write share one
+     * transaction, so a migration cannot interleave between them.
+     */
+    readServeGate(runningSchemaVersion: number): Promise<ServeGate>;
     /**
      * Blob reference index (§5.9.4) — ADDITIVE, optional. Set the blobIds a
      * row currently references (empty = clear), replacing any prior entries
@@ -379,7 +460,7 @@ export interface ServerStorage {
      * before binding a public port; protocol handlers still call this method
      * lazily as a defensive backstop.
      */
-    ensureSchema(schema: CompiledSchema): Promise<void>;
+    ensureSchema(schema: CompiledSchema, checkpoints?: readonly CheckpointDeclaration[]): Promise<void>;
     /** Create or refresh the authenticated partition registry row (§2.1). */
     touchPartition(partition: string, authenticatedAtMs: number, initialLogEpoch: string): Promise<PartitionRegistryEntry>;
     /** Rotate log continuity after restore and discard stale cursor records. */
@@ -413,6 +494,50 @@ export interface ServerStorage {
     pruneCommitsThrough(partition: string, query: CommitPruneQuery): Promise<CommitPruneResult>;
     /** Newest commitSeq created strictly before the timestamp; 0 if none. */
     getCommitSeqBefore(partition: string, createdBeforeMs: number): Promise<number>;
+    /** Every declared backfill checkpoint for the partition, ordered by name. */
+    readCheckpoints(partition: string): Promise<StoredCheckpoint[]>;
+    /**
+     * RFC 0007 serve gate: read the published schema version, the partition's
+     * log epoch, and every incomplete declared checkpoint at
+     * `runningSchemaVersion`. Never memoized; the serve paths call it per
+     * request so an already-serving process notices a migration.
+     */
+    readServeGate(partition: string, runningSchemaVersion: number): Promise<ServeGate>;
+    /**
+     * Atomically take ownership of a declared or backfilling checkpoint. Increments
+     * `owner_epoch` and moves `declared` to `backfilling`. Throws
+     * `sync.storage.checkpoint_not_declared` when no claimable row exists (absent,
+     * or already `activated`).
+     */
+    claimCheckpoint(partition: string, name: string, schemaVersion: number, nowMs: number): Promise<StoredCheckpoint>;
+    /**
+     * Advance the watermark only while `owner_epoch` still matches. Returns false
+     * for a superseded owner; the stale case never throws.
+     */
+    advanceCheckpoint(partition: string, name: string, ownerEpoch: number, watermark: number, observedRows: number, nowMs: number): Promise<boolean>;
+    /** Highest commitSeq carrying a change to one of `tables`; 0 when none. */
+    sourceCoverageSeq(partition: string, tables: readonly string[]): Promise<number>;
+    /**
+     * Whether any source change sits above `seq`. `unverifiable` when the pruning
+     * horizon has passed `seq`, so the history that would answer the question is
+     * gone; a pruned window is never reported as `clean`.
+     */
+    hasSourceChangesAbove(partition: string, tables: readonly string[], seq: number): Promise<'clean' | 'changed' | 'unverifiable'>;
+    /**
+     * Install the barrier: insert the checkpoint in `declared` and raise
+     * `required_writer_version` for the partition in one transaction. The fence
+     * is raised at declaration, before any backfill work, so old writers are
+     * rejected for the whole backfill window. Idempotent on an existing declared
+     * or backfilling row.
+     */
+    declareCheckpoint(partition: string, name: string, schemaVersion: number, nowMs: number): Promise<StoredCheckpoint>;
+    /**
+     * Activate a declared checkpoint under the partition write lock. Refuses when
+     * the fence is not already raised at the checkpoint's schema version, when a
+     * source change sits above `watermark` (`stale`), or when the pruning horizon
+     * has passed `watermark` (`unverifiable`). `activated` is terminal.
+     */
+    activateCheckpoint(partition: string, name: string, ownerEpoch: number, watermark: number, sources: readonly string[], nowMs: number): Promise<'activated' | 'stale' | 'unverifiable'>;
     getRow(partition: string, table: string, rowId: string): Promise<StoredRow | undefined>;
     /**
      * Idempotency lookup (§2.3). Throws `SyncError sync.idempotency_cache_miss`
@@ -462,7 +587,7 @@ export interface ServerStorage {
      * transaction to finish on a single-connection executor, and runs
      * concurrently on a pool-backed one.
      */
-    queryAuthoritative?(partition: string, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
+    queryAuthoritative?(partition: string, query: AuthoritativeQueryRequest, checkpoints?: readonly CheckpointDeclaration[]): Promise<AuthoritativeQueryResult>;
     /**
      * Optional trusted-host exact lookup through a declared relational index.
      * This capability is outside client scope/subscription authorization and

package/dist/storage.js

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