@syncular/server 0.21.1 → 0.23.0

package/README.md

@@ -660,14 +660,28 @@ which all three providers accept.
 **Key layout.** Deterministic, so every lookup is a GET/HEAD — never a
 LIST:
 
-- `{keyPrefix}seg/sha256/{hex}` — the segment bytes, verbatim (the
-  object body is exactly the content-addressed bytes, so presigned GETs
-  serve them directly and the client's §5.1 hash check passes). The
-  record metadata rides in object user metadata
-  (`x-amz-meta-syncular-record`, base64url JSON), so `get` is one GET.
+- `{keyPrefix}seg/sha256/{hex}` — the segment bytes, verbatim and
+  immutable (the object body is exactly the content-addressed bytes, so
+  presigned GETs serve them directly and the client's §5.1 hash check
+  passes).
+- `{keyPrefix}rec/sha256/{hex}.json` — the mutable `SegmentRecord`. It
+  carries the `publications` array: one entry per (partition, log epoch,
+  table, schema version, media type, scope digest, pin, cursors) context
+  the content was published under, each with its own TTL. `get` is two
+  GETs (record + bytes). A record written by 0.21 read the metadata from
+  the bytes object's user metadata; `get` still reads that shape and
+  materializes one publication per recorded digest.
 - `{keyPrefix}find/{sha256(reuse key)}.json` — the §5.3 whole-table
   reuse pointer, written only for `rowCursor: null` segments; `find` is
-  one GET plus a HEAD to confirm the segment object still exists.
+  one GET plus a HEAD to confirm the segment object still exists, and it
+  selects the publication the key names.
+
+A host that implements `SegmentStore` itself must return `publications`
+and `scopeDigests` on every `SegmentRecord` (`scopeDigests` is the
+compatibility view over `publications`). Download and `find` select a
+publication matching the caller's partition, live log epoch, and digest;
+they never union digests across contexts. The shared contract suite is
+`test/segment-store-contract.ts`.
 
 **TTL and lifecycle.** Expiry is store-side and authoritative:
 `expiresAtMs` (`put` time + `ttlMs`, default 24 h) is recorded with the

package/dist/admin.d.ts

@@ -21,7 +21,7 @@ import type { LeaseRecord, LeaseStore } from './lease-store.js';
 import { type RetentionPolicy } from './prune.js';
 import { type ServerSchema } from './schema.js';
 import type { SegmentStore, SegmentStoreStats } from './segment-store.js';
-import type { CommitMetadata, ReactionStatus, ScopeCommitActivity, ServerStorage, StoredReaction } from './storage.js';
+import type { CheckpointDeclaration, CommitMetadata, ReactionStatus, ScopeCommitActivity, ServerStorage, StoredReaction } from './storage.js';
 /** A connected/known client as the console sees it (§4.5, §8.1). */
 export interface AdminClient {
     readonly clientId: string;
@@ -139,6 +139,8 @@ export interface SyncularAdminOptions {
      * a storage instance that has not served a sync request yet.
      */
     readonly schema?: ServerSchema;
+    /** RFC 0007: declarations `inspectRow` carries into `ensureSchema`. */
+    readonly checkpoints?: readonly CheckpointDeclaration[];
     /** The event ring feeding the event tail. Absent ⇒ `events()` is empty. */
     readonly ring?: RingBufferEvents;
     readonly segments?: SegmentStore;

package/dist/admin.js

@@ -41,6 +41,7 @@ function toAdminClient(record, active, maxCommitSeq) {
 export class SyncularAdmin {
     #storage;
     #schema;
+    #checkpoints;
     #ring;
     #segments;
     #blobs;
@@ -51,6 +52,8 @@ export class SyncularAdmin {
         this.#storage = options.storage;
         if (options.schema !== undefined)
             this.#schema = options.schema;
+        if (options.checkpoints !== undefined)
+            this.#checkpoints = options.checkpoints;
         if (options.ring !== undefined)
             this.#ring = options.ring;
         if (options.segments !== undefined)
@@ -71,6 +74,9 @@ export class SyncularAdmin {
         return new SyncularAdmin({
             storage: config.storage,
             schema: config.schema,
+            ...(config.checkpoints !== undefined
+                ? { checkpoints: config.checkpoints }
+                : {}),
             segments: config.segments,
             ...(config.blobs !== undefined ? { blobs: config.blobs } : {}),
             ...(config.leases !== undefined ? { leases: config.leases.store } : {}),
@@ -138,7 +144,7 @@ export class SyncularAdmin {
     async inspectRow(partition, table, rowId) {
         const read = required(this.#storage.getRowScopes?.bind(this.#storage), 'storage');
         if (this.#schema !== undefined) {
-            await this.#storage.ensureSchema(compileSchema(this.#schema));
+            await this.#storage.ensureSchema(compileSchema(this.#schema), this.#checkpoints);
         }
         const row = await read(partition, table, rowId);
         if (row === undefined) {

package/dist/blob-handlers.js

@@ -149,7 +149,7 @@ async function downloadBlob(ctx, blobId) {
     const schema = compileSchema(ctx.schema);
     // A blob download can hit a fresh storage instance before any sync
     // request has run (Workers): make sure the row tables exist first.
-    await ctx.storage.ensureSchema(schema);
+    await ctx.storage.ensureSchema(schema, ctx.checkpoints);
     const rows = await listRows.call(ctx.storage, ctx.partition, blobId);
     let authorized = false;
     for (const row of rows) {

package/dist/context.d.ts

@@ -14,7 +14,7 @@ import type { ServerSchema } from './schema.js';
 import type { SegmentStore } from './segment-store.js';
 import type { BlobPresignConfig, BlobUploadPresignConfig, SegmentUrlConfig } from './signed-url.js';
 import type { SqliteImageBuilder } from './sqlite-image.js';
-import type { PartitionRegistryEntry, ServerStorage, StoredCommit } from './storage.js';
+import type { CheckpointDeclaration, PartitionRegistryEntry, ServerStorage, StoredCommit } from './storage.js';
 import type { CommitValidator, ValidatorRegistry } from './validate.js';
 /** SSP2 body content type (§1.1). */
 export declare const SSP2_CONTENT_TYPE = "application/vnd.syncular.sync.v2";
@@ -72,6 +72,13 @@ export interface RealtimeNotifier {
 export interface SyncServerConfig {
     readonly schema: ServerSchema;
     readonly storage: ServerStorage;
+    /**
+     * RFC 0007: the backfill checkpoints this host installs. Every readiness
+     * path carries this set into `ensureSchema`. A process that omits it
+     * declares nothing, and the storage refuses to serve a partition whose
+     * stored state shows a checkpoint that is not activated.
+     */
+    readonly checkpoints?: readonly CheckpointDeclaration[];
     readonly segments: SegmentStore;
     /**
      * Blob store (§5.9). Absent ⇒ blobs unsupported: a table with a

package/dist/d1-storage.d.ts

@@ -1,6 +1,6 @@
 import type { CommitPruneQuery, CommitPruneResult } from './storage.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, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export interface D1PreparedStatement {
     bind(...values: unknown[]): D1PreparedStatement;
     first<T = Record<string, unknown>>(): Promise<T | null>;
@@ -36,7 +36,7 @@ export declare class D1ServerStorage 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>;
     /** Run once per Worker invocation. Resume an incomplete result in another invocation. */
     migrateSchema(schema: CompiledSchema, options?: {
         readonly maxStatements?: number;
@@ -49,12 +49,20 @@ export declare class D1ServerStorage implements ServerStorage {
     listPartitionRegistry(): Promise<PartitionRegistryEntry[]>;
     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/d1-storage.js

@@ -264,6 +264,21 @@ class D1Transaction {
         // write for this partition is already serialized (normally by its DO).
         this.#pushApplyCheckpoint = this.#buffer.length;
     }
+    advanceCheckpoint(_name, _ownerEpoch, _watermark, _observedRows, _nowMs) {
+        // D1 installs no fence and declares no checkpoints in this release.
+        return Promise.reject(new StorageQueryError('sync.storage.checkpoint_unsupported'));
+    }
+    async readServeGate(_runningSchemaVersion) {
+        this.#assertOpen();
+        const marker = await this.#db
+            .prepare('SELECT schema_version FROM sync_schema_meta WHERE id=1')
+            .first();
+        return {
+            storedSchemaVersion: marker?.schema_version ?? 0,
+            logEpoch: undefined,
+            pending: [],
+        };
+    }
     async commitRejectedPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
         const checkpoint = this.#pushApplyCheckpoint;
@@ -527,7 +542,12 @@ export class D1ServerStorage {
         }
         return table;
     }
-    async ensureSchema(schema) {
+    async ensureSchema(schema, checkpoints) {
+        if (checkpoints !== undefined && checkpoints.length > 0) {
+            // No database-side fence can be installed atomically with schema
+            // visibility here; refuse instead of accepting a weaker guarantee.
+            throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+        }
         if (this.#schemaVersion === schema.version) {
             await this.#schemaDatabase().batch([]);
             return;
@@ -972,7 +992,10 @@ export class D1ServerStorage {
             .first();
         return row?.max_commit_seq ?? 0;
     }
-    async queryAuthoritative(partition, query) {
+    async queryAuthoritative(partition, query, _checkpoints) {
+        // D1 declares no checkpoints. `#schemaDatabase` prepends a guard that
+        // re-checks the published marker inside this same batch, so condition 2
+        // is already evaluated with the query (§2.4 D1 schema readiness).
         const db = this.#schemaDatabase();
         if (this.#tables === undefined) {
             throw new Error('ensureSchema(schema) must run before registered queries');
@@ -1086,6 +1109,65 @@ export class D1ServerStorage {
             .first();
         return row?.seq ?? 0;
     }
+    async readCheckpoints(_partition) {
+        // D1 supports no declared backfill checkpoints in this release: migrations
+        // run out of band and no database-side fence can be installed atomically
+        // with schema visibility. No checkpoint row can exist.
+        return [];
+    }
+    async readServeGate(partition, _runningSchemaVersion) {
+        // D1 has no checkpoints. The published marker is the only gate input;
+        // `#schemaDatabase` already re-checks it per protected batch.
+        const marker = await this.#db
+            .prepare('SELECT schema_version FROM sync_schema_meta WHERE id=1')
+            .first();
+        return {
+            storedSchemaVersion: marker?.schema_version ?? 0,
+            logEpoch: await this.getPartitionLogEpoch(partition),
+            pending: [],
+        };
+    }
+    async declareCheckpoint(_partition, _name, _schemaVersion, _nowMs) {
+        throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+    }
+    async activateCheckpoint(_partition, _name, _ownerEpoch, _watermark, _sources, _nowMs) {
+        throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+    }
+    async claimCheckpoint(_partition, _name, _schemaVersion, _nowMs) {
+        throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+    }
+    async advanceCheckpoint(_partition, _name, _ownerEpoch, _watermark, _observedRows, _nowMs) {
+        throw new StorageQueryError('sync.storage.checkpoint_unsupported');
+    }
+    async sourceCoverageSeq(partition, tables) {
+        if (tables.length === 0)
+            return 0;
+        const tableParams = tables.map(() => '?').join(',');
+        const row = await this.#db
+            .prepare(`SELECT max(commit_seq) AS seq FROM sync_changes
+          WHERE partition=? AND tbl IN (${tableParams})`)
+            .bind(partition, ...tables)
+            .first();
+        return row?.seq ?? 0;
+    }
+    async 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 = await this.getHorizonSeq(partition);
+        if (tables.length === 0)
+            return 'clean';
+        const tableParams = tables.map(() => '?').join(',');
+        const hit = await this.#db
+            .prepare(`SELECT 1 AS hit FROM sync_changes
+          WHERE partition=? AND tbl IN (${tableParams}) AND commit_seq>?
+          LIMIT 1`)
+            .bind(partition, ...tables, seq)
+            .first();
+        if (hit !== null)
+            return 'changed';
+        return horizon > seq ? 'unverifiable' : 'clean';
+    }
     async getRow(partition, table, rowId) {
         const db = this.#schemaDatabase();
         const record = await db

package/dist/errors.js

@@ -159,6 +159,16 @@ export const ERROR_CATALOG = {
         recommendedAction: 'retryLater',
         httpStatus: 500,
     },
+    // §2.4 on a non-D1 backend: the server refuses while a declared backfill
+    // checkpoint is incomplete or the database is newer than the running build.
+    // Formerly host-only; promoted to the §10.2 catalogue so an in-flight
+    // request can be refused with a distinguishable identity.
+    'sync.schema_not_ready': {
+        category: 'internal',
+        retryable: true,
+        recommendedAction: 'retryLater',
+        httpStatus: 503,
+    },
     'sync.too_many_operations': {
         category: 'invalid-request',
         retryable: false,

package/dist/handler.js

@@ -16,8 +16,11 @@ import { emitEvent, } from './events.js';
 import { END_FRAME_BYTES, encodeResponseFrame, responseEnvelopeHeader, } from './frame-bytes.js';
 import { ACCEPT_EXTERNAL_ROWS, ACCEPT_INLINE_ROWS, clampPullLimits, subscriptionSection, } from './pull.js';
 import { processPushCommitWithTrace } from './push.js';
+import { serveNotReadyError } from './readiness.js';
 import { compileSchema } from './schema.js';
 import { computeEffective } from './scopes.js';
+import { StorageQueryError } from './storage-errors.js';
+import { serveGateRefusal, serveGateTokenChanged, } from './storage.js';
 function validateResolvedKeys(allowed, schema) {
     for (const key of Object.keys(allowed)) {
         if (!schema.declaredVariables.has(key)) {
@@ -500,13 +503,56 @@ async function createStreamCore(bytes, ctx, events, startedAtMs = 0) {
     const schema = compileSchema(ctx.schema);
     // Relational row tables: create/
     // migrate on first contact; memoized per storage instance thereafter.
-    await ctx.storage.ensureSchema(schema);
+    try {
+        await ctx.storage.ensureSchema(schema, ctx.checkpoints);
+    }
+    catch (error) {
+        if (error instanceof StorageQueryError &&
+            error.code === 'sync.storage.checkpoint_incomplete') {
+            const refusal = serveGateRefusal(await ctx.storage.readServeGate(ctx.partition, schema.version), schema.version, ctx.checkpoints);
+            throw refusal !== undefined ? serveNotReadyError(refusal) : error;
+        }
+        throw error;
+    }
+    // RFC 0007 serve gate: re-read stored state on every request so an
+    // already-serving process notices a migration or a newly declared
+    // checkpoint. Read after `touchAuthenticatedPartition` establishes the
+    // partition's log epoch, so the entry token is the epoch this request
+    // serves under. Nothing has escaped at this point; the push transaction
+    // re-evaluates the gate under the partition lock.
     const registry = await touchAuthenticatedPartition(ctx);
+    const gate = await ctx.storage.readServeGate(ctx.partition, schema.version);
+    const refusal = serveGateRefusal(gate, schema.version, ctx.checkpoints);
+    if (refusal !== undefined)
+        throw serveNotReadyError(refusal);
     const plan = await planRequest(request, ctx, schema, registry);
-    if (events === undefined)
-        return streamResponse(plan, ctx, schema);
     const report = { outcome: 'ok' };
-    return instrumentedStream(streamResponse(plan, ctx, schema, report), ctx, events, plan, report, bytes.length, startedAtMs);
+    // RFC 0007 read-verify-refuse for the streamed read path: the generator
+    // builds the whole response (its data reads) before yielding the first
+    // frame, then compares the gate token across those reads. Nothing escapes
+    // before the verification, and the buffered size is bounded by the request's
+    // pull limits and the server's inline segment cap. Every request verifies,
+    // including a mixed push+pull: a write that already applied when the token
+    // changed is durable and replayable under the same commit id / idempotency
+    // key, so refusing the request is safe (proved in the serve-gate lane).
+    const verified = async function* () {
+        const buffered = [];
+        for await (const chunk of streamResponse(plan, ctx, schema, report)) {
+            buffered.push(chunk);
+        }
+        const after = await ctx.storage.readServeGate(ctx.partition, schema.version);
+        const changed = serveGateTokenChanged(gate, after);
+        const afterRefusal = serveGateRefusal(after, schema.version, ctx.checkpoints);
+        if (afterRefusal !== undefined)
+            throw serveNotReadyError(afterRefusal);
+        if (changed !== undefined)
+            throw serveNotReadyError(changed);
+        for (const chunk of buffered)
+            yield chunk;
+    };
+    if (events === undefined)
+        return verified();
+    return instrumentedStream(verified(), ctx, events, plan, report, bytes.length, startedAtMs);
 }
 /** Counts response bytes and emits `request.handled` when the stream
  * finishes — including a thrown host failure mid-stream (fail loud). */

package/dist/operations.js

@@ -185,7 +185,7 @@ export function registerRemoteQuery(descriptor, options) {
             if (plan === undefined) {
                 throw syncError('operation.invalid_request', 'selected SQL has no generated relation plan; regenerate queries');
             }
-            await ctx.storage.ensureSchema(schema);
+            await ctx.storage.ensureSchema(schema, ctx.checkpoints);
             const prefix = 'SELECT * FROM (';
             let result;
             try {
@@ -200,7 +200,7 @@ export function registerRemoteQuery(descriptor, options) {
                     },
                     params: [...descriptor.bind(params), options.maxRows + 1],
                     tables: descriptor.tables,
-                });
+                }, ctx.checkpoints);
             }
             catch (error) {
                 if (error instanceof SyncError)
@@ -318,7 +318,7 @@ export function registerRemoteCommand(descriptor, options) {
             }
             const resolved = { ok: true, allowed };
             const schema = compileSchema(ctx.schema);
-            await ctx.storage.ensureSchema(schema);
+            await ctx.storage.ensureSchema(schema, ctx.checkpoints);
             const processed = await processPushOperationsWithTrace(ctx, schema, resolved, JSON.stringify(['remote-command', ctx.actorId, clientId]), JSON.stringify([descriptor.id, requestId]), async (tx) => commandOperations(await options.run(commandContext(ctx, tx, resolved, schema, clientId, descriptor.id, requestId), input), schema));
             return {
                 revision: 1,

package/dist/pg-executor.d.ts

@@ -39,6 +39,14 @@ export type PgRow = Record<string, unknown>;
  * `params` use Postgres positional placeholders (`$1`, `$2`, ...). `text`
  * is a single statement (no multi-statement `;`-joined batches — those are
  * driver-specific and defeat parameterization).
+ *
+ * Syncular never overlaps statements on one `PgQueryable`. A client pinned
+ * to a connection by `PgExecutor.transaction` gets every statement chained
+ * on one FIFO by `PostgresServerStorage`, so a host validator that starts
+ * independent reads concurrently still reaches the driver one statement at
+ * a time. An adapter does not need to queue calls itself, and must not
+ * accept two in flight: node-postgres warns about that today and rejects it
+ * in node-postgres 9.
  */
 export interface PgQueryable {
     query<Row = PgRow>(text: string, params?: readonly unknown[]): Promise<{
@@ -55,7 +63,9 @@ export interface PgExecutor extends PgQueryable {
     /**
      * Run `fn` inside a single Postgres transaction on one pinned connection.
      * The executor issues `BEGIN` before `fn`, `COMMIT` on resolve, and
-     * `ROLLBACK` on throw (rethrowing the original error).
+     * `ROLLBACK` on throw (rethrowing the original error). The caller
+     * serializes the statements `fn` issues on the provided client (see
+     * `PgQueryable`), so the driver never sees two of them in flight.
      */
     transaction<T>(fn: (client: PgQueryable) => Promise<T>): Promise<T>;
     /** Release any pooled resources. Optional (pglite/Bun.sql). */

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).
  *
@@ -12,7 +12,14 @@ import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorI
  *   - `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`:
@@ -24,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 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);
@@ -32,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[]>;
@@ -46,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[]>;