@syncular/server 0.22.0 → 0.24.0

package/dist/push.js

@@ -24,7 +24,10 @@ import { emitEvent } from './events.js';
 import { prepareReactions, toNewReactions, } from './reactions.js';
 import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes.js';
 import { decodeColumnVersions, encodeColumnVersions } from './relational-rows.js';
+import { serveGateRefusal } from './storage.js';
 import { StorageConstraintError } from './storage-errors.js';
+import { transactionQuery } from './storage-query.js';
+import { serveNotReadyError } from './readiness.js';
 import { CommitValidationRejection, toValidateRow, ValidationRejection, } from './validate.js';
 /**
  * Extract the blobIds a decoded row references through its `blob_ref`
@@ -84,7 +87,7 @@ function conflictColumnsBitmap(columnCount, marked) {
  * A no-op for tables with no validator — the `undefined` short-circuit
  * keeps the feature zero-cost when off.
  */
-async function runValidator(validators, table, op, rowId, values, storedValues, opIndex, partition, actorId) {
+async function runValidator(validators, table, op, rowId, values, storedValues, opIndex, tx, partition, actorId) {
     const validator = validators?.[table.name];
     if (validator === undefined)
         return undefined;
@@ -99,7 +102,11 @@ async function runValidator(validators, table, op, rowId, values, storedValues,
             stored: storedValues !== undefined
                 ? toValidateRow(table.columns, storedValues)
                 : undefined,
-        }, { actorId, partition });
+        }, {
+            actorId,
+            partition,
+            queryAuthoritative: (query) => transactionQuery(tx, query),
+        });
     }
     catch (error) {
         if (error instanceof ValidationRejection) {
@@ -197,7 +204,7 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
         // stored = the row about to be removed). Only reached for an existing
         // row — an absent-row delete is an idempotent no-op above.
         const storedValues = decodeRow(table.columns, stored.payload);
-        const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, partition, actorId);
+        const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, tx, partition, actorId);
         if (deleteReject !== undefined)
             return deleteReject;
         await tx.deleteRow(op.table, op.rowId);
@@ -328,7 +335,7 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
         // §6.7: validate the merged row that will persist — for a crdt column
         // the validator sees the MERGED value (§5.10.3), the state the store
         // holds, not the raw pushed update.
-        const updateReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, partition, actorId);
+        const updateReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, tx, partition, actorId);
         if (updateReject !== undefined)
             return updateReject;
         const columnVersions = encodeColumnVersions(nextVersions);
@@ -410,7 +417,7 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
     // §6.7: validate the insert row (stored = undefined, so a validator can
     // distinguish create from update); crdt columns are already merged
     // against the empty document.
-    const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, partition, actorId);
+    const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, tx, partition, actorId);
     if (insertReject !== undefined)
         return insertReject;
     // §5.2: an explicit insert recreates — the tombstone goes with it.
@@ -524,6 +531,7 @@ function commitValidationReader(tx, schema) {
                 serverVersion: stored.serverVersion,
             }));
         },
+        queryAuthoritative: (query) => transactionQuery(tx, query),
     };
 }
 async function runCommitValidator(validator, tx, schema, clientId, clientCommitId, actorId, partition, operations) {
@@ -680,7 +688,7 @@ async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit
                 const syntheticIndex = clientOpCount + originByIndex.length;
                 const storedValues = decodeRow(child.columns, childRow.payload);
                 if (reference.onDelete === 'CASCADE') {
-                    const reject = await runValidator(validators, child, 'delete', childRow.rowId, undefined, storedValues, item.originOpIndex, partition, actorId);
+                    const reject = await runValidator(validators, child, 'delete', childRow.rowId, undefined, storedValues, item.originOpIndex, tx, partition, actorId);
                     if (reject !== undefined) {
                         return { kind: 'terminate', record: reject.record };
                     }
@@ -704,7 +712,7 @@ async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit
                 else {
                     const values = [...storedValues];
                     values[reference.columnIndex] = null;
-                    const reject = await runValidator(validators, child, 'upsert', childRow.rowId, values, storedValues, item.originOpIndex, partition, actorId);
+                    const reject = await runValidator(validators, child, 'upsert', childRow.rowId, values, storedValues, item.originOpIndex, tx, partition, actorId);
                     if (reject !== undefined) {
                         return { kind: 'terminate', record: reject.record };
                     }
@@ -864,6 +872,15 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
             throw new Error('storage transaction does not support serialized push apply, atomic rejection finalization, and configured durable reactions');
         }
         await lockPartitionForPush();
+        // RFC 0007: evaluate the gate on this transaction's own connection while
+        // the partition lock is held, so the migration check and the write share
+        // one transaction and no migration can interleave in between.
+        const gate = await tx.readServeGate(schema.version);
+        const refusal = serveGateRefusal(gate, schema.version, ctx.checkpoints);
+        if (refusal !== undefined) {
+            await tx.rollback();
+            throw serveNotReadyError(refusal);
+        }
         // The optimistic lookup above may have raced another delivery. Re-check
         // only after acquiring partition serialization and before any operation
         // read, validation, merge, or staged write. The re-check runs on the
@@ -1015,6 +1032,13 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
             }
         }
         if (ctx.realtime !== undefined && changes.length > 0) {
+            // RFC 0007 fanout decision: the notification carries the durable commit
+            // entry itself (this commit's `changes`), not a projection read or a pull
+            // window, so fanning it out before the request's buffered read-verify can
+            // never serve a mixed result. Each peer's next pull is gated at the
+            // storage seam; a refused mixed push+pull is safe because the push is
+            // durable and replayable under its commit id. This is commit-entry
+            // durability, not gate inheritance.
             await ctx.realtime.notifyCommit(partition, {
                 commitSeq,
                 createdAtMs,

package/dist/readiness.d.ts

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

package/dist/readiness.js

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

package/dist/realtime.js

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

package/dist/relational-rows.d.ts

@@ -75,26 +75,38 @@ export declare function columnSqlType(column: RowColumn, dialect: RelationalDial
  * materialized), version, scopes, payload.
  */
 export declare function tableColumnNames(table: CompiledTable): string[];
+/** One physical column of a synced table, read from the database catalog. */
+export interface PhysicalColumn {
+    readonly name: string;
+    /** Declared type (SQLite) or `format_type` (PostgreSQL); compared case-insensitively. */
+    readonly type: string;
+    readonly notNull: boolean;
+    /** 1-based position in the primary key; 0 when the column is not in it. */
+    readonly primaryKeyPosition: number;
+}
 /**
- * The physical column set the row codec and the scope index read for one
- * configured table. The persisted marker's layouts describe the codec's app
+ * Refuse a same-version database whose physical table the row store cannot
+ * read or write. The persisted marker's layouts describe the codec's app
  * columns only and its version number is the schema's, not the database's, so
- * a same-version database that is missing a storage-internal meta column (a
- * version-only bump whose ALTER never ran) still has to be refused: compare
- * the physical table and fail closed without writing a migration.
+ * a same-version database whose storage-internal meta columns drifted (a
+ * version-only bump whose ALTER never ran, or a table written by another
+ * build) is only visible in the catalog. Every configured column must exist;
+ * the meta columns must also carry the type, nullability, and primary-key
+ * position `createTableDdl` declares. App-column types and nullability stay
+ * with the stored layouts: migration-added app columns are nullable by design.
+ * Fails closed without writing a migration.
  *
- * `existingColumns` must be resolved the way the unqualified row queries
- * resolve the table — on PostgreSQL, through the session `search_path`, not
+ * `columns` must be resolved the way the unqualified row queries resolve the
+ * table: on PostgreSQL, through the session `search_path`, not
  * `current_schema()`. A search path whose first schema is not where the
  * configured tables live is outside the supported contract: DDL is created in
  * that first schema, so `ensureSchema` already writes shadow tables there.
  *
- * Scope: this checks that the columns EXIST. Stored types, nullability, and
- * non-column storage internals (the tombstone bookkeeping) stay outside it,
- * because a wrong type or nullability is a codec-compatibility question the
- * persisted layouts answer for app columns.
+ * Core storage tables (`sync_tombstones`, `sync_commits`, ...) are outside
+ * this check: every open re-applies their `CREATE TABLE IF NOT EXISTS` DDL
+ * and column additions, independently of the version marker.
  */
-export declare function assertPhysicalColumns(table: CompiledTable, existingColumns: ReadonlySet<string>): void;
+export declare function assertPhysicalColumns(table: CompiledTable, columns: readonly PhysicalColumn[], dialect: RelationalDialect): void;
 /** CREATE TABLE IF NOT EXISTS for one app table. */
 export declare function createTableDdl(table: CompiledTable, dialect: RelationalDialect): string;
 /**
@@ -249,6 +261,13 @@ export type StoredLayouts = Record<string, readonly StoredColumnLayout[]>;
 /** The layouts JSON persisted alongside the schema version marker. */
 export declare function layoutsOf(schema: CompiledSchema): string;
 export declare function parseLayouts(json: string | null | undefined): StoredLayouts;
+/**
+ * Version equality is not layout equality: a marker written by another build
+ * at the same version describes rows the running codec cannot decode. Refuse
+ * when the stored layouts disagree with the configured schema, naming the
+ * first table (and column) that differs.
+ */
+export declare function assertStoredLayouts(schema: CompiledSchema, storedJson: string | null | undefined): void;
 /**
  * Tables present in the stored layout but absent from the configured head
  * schema. A schema-version bump retires their relational current-row tables;

package/dist/relational-rows.js

@@ -48,6 +48,7 @@
  *   NOT NULL per the schema.
  */
 import { decodeRow, encodeRow, } from '@syncular/core';
+import { StorageQueryError } from './storage-errors.js';
 export const SYNC_PARTITION_COLUMN = '_sync_partition';
 export const SYNC_ROW_ID_COLUMN = '_sync_row_id';
 export const SYNC_VERSION_COLUMN = '_sync_server_version';
@@ -170,52 +171,110 @@ export function tableColumnNames(table) {
     ];
 }
 /**
- * The physical column set the row codec and the scope index read for one
- * configured table. The persisted marker's layouts describe the codec's app
+ * The storage-internal columns of every synced table, in `createTableDdl`
+ * order (app columns sit between the row id and the version). The same-version
+ * physical check compares a table against exactly these declarations.
+ */
+function syncMetaColumns(dialect) {
+    const payloadType = dialect === 'postgres' ? 'BYTEA' : 'BLOB';
+    return [
+        { name: SYNC_PARTITION_COLUMN, type: 'TEXT', notNull: true },
+        { name: SYNC_ROW_ID_COLUMN, type: 'TEXT', notNull: true },
+        {
+            name: SYNC_VERSION_COLUMN,
+            type: dialect === 'postgres' ? 'BIGINT' : 'INTEGER',
+            notNull: true,
+        },
+        {
+            name: SYNC_SCOPES_COLUMN,
+            type: dialect === 'postgres' ? 'JSONB' : 'TEXT',
+            notNull: true,
+        },
+        { name: SYNC_PAYLOAD_COLUMN, type: payloadType, notNull: true },
+        { name: SYNC_COLUMN_VERSIONS_COLUMN, type: payloadType, notNull: false },
+    ];
+}
+/**
+ * Refuse a same-version database whose physical table the row store cannot
+ * read or write. The persisted marker's layouts describe the codec's app
  * columns only and its version number is the schema's, not the database's, so
- * a same-version database that is missing a storage-internal meta column (a
- * version-only bump whose ALTER never ran) still has to be refused: compare
- * the physical table and fail closed without writing a migration.
+ * a same-version database whose storage-internal meta columns drifted (a
+ * version-only bump whose ALTER never ran, or a table written by another
+ * build) is only visible in the catalog. Every configured column must exist;
+ * the meta columns must also carry the type, nullability, and primary-key
+ * position `createTableDdl` declares. App-column types and nullability stay
+ * with the stored layouts: migration-added app columns are nullable by design.
+ * Fails closed without writing a migration.
  *
- * `existingColumns` must be resolved the way the unqualified row queries
- * resolve the table — on PostgreSQL, through the session `search_path`, not
+ * `columns` must be resolved the way the unqualified row queries resolve the
+ * table: on PostgreSQL, through the session `search_path`, not
  * `current_schema()`. A search path whose first schema is not where the
  * configured tables live is outside the supported contract: DDL is created in
  * that first schema, so `ensureSchema` already writes shadow tables there.
  *
- * Scope: this checks that the columns EXIST. Stored types, nullability, and
- * non-column storage internals (the tombstone bookkeeping) stay outside it,
- * because a wrong type or nullability is a codec-compatibility question the
- * persisted layouts answer for app columns.
+ * Core storage tables (`sync_tombstones`, `sync_commits`, ...) are outside
+ * this check: every open re-applies their `CREATE TABLE IF NOT EXISTS` DDL
+ * and column additions, independently of the version marker.
  */
-export function assertPhysicalColumns(table, existingColumns) {
-    if (existingColumns.size === 0) {
-        throw new Error(`table ${JSON.stringify(table.name)} is missing from the database at the stored schema version — refusing to serve a database whose rows the running code cannot read`);
-    }
+export function assertPhysicalColumns(table, columns, dialect) {
+    const refuse = (details) => {
+        throw new StorageQueryError('sync.storage.physical_layout_mismatch', {
+            table: table.name,
+            ...details,
+        });
+    };
+    if (columns.length === 0)
+        refuse({ reason: 'missing_table' });
+    const byName = new Map(columns.map((column) => [column.name, column]));
     for (const name of tableColumnNames(table)) {
-        if (existingColumns.has(name))
+        if (!byName.has(name))
+            refuse({ column: name, reason: 'missing_column' });
+    }
+    for (const expected of syncMetaColumns(dialect)) {
+        const actual = byName.get(expected.name);
+        if (actual === undefined)
             continue;
-        throw new Error(`table ${JSON.stringify(table.name)} is missing column ${JSON.stringify(name)} at the stored schema version — refusing to serve a database whose rows the running code cannot read`);
+        if (actual.type.toUpperCase() !== expected.type) {
+            refuse({
+                column: expected.name,
+                reason: 'type',
+                expected: expected.type,
+                actual: actual.type,
+            });
+        }
+        if (actual.notNull !== expected.notNull) {
+            refuse({
+                column: expected.name,
+                reason: 'nullability',
+                expected: expected.notNull ? 'not_null' : 'nullable',
+                actual: actual.notNull ? 'not_null' : 'nullable',
+            });
+        }
+    }
+    for (const column of columns) {
+        const expected = column.name === SYNC_PARTITION_COLUMN
+            ? 1
+            : column.name === SYNC_ROW_ID_COLUMN
+                ? 2
+                : 0;
+        if (column.primaryKeyPosition !== expected) {
+            refuse({ column: column.name, reason: 'primary_key' });
+        }
     }
 }
 /** CREATE TABLE IF NOT EXISTS for one app table. */
 export function createTableDdl(table, dialect) {
-    const versionType = dialect === 'postgres' ? 'BIGINT' : 'INTEGER';
-    const scopesType = dialect === 'postgres' ? 'JSONB' : 'TEXT';
-    const payloadType = dialect === 'postgres' ? 'BYTEA' : 'BLOB';
+    const [partition, rowId, ...trailing] = syncMetaColumns(dialect).map((column) => `${quoteIdent(column.name)} ${column.type}${column.notNull ? ' NOT NULL' : ''}`);
     const defs = [
-        `${quoteIdent(SYNC_PARTITION_COLUMN)} TEXT NOT NULL`,
-        `${quoteIdent(SYNC_ROW_ID_COLUMN)} TEXT NOT NULL`,
+        partition,
+        rowId,
         ...(table.materialize
             ? table.columns.map((column) => {
                 const notNull = column.nullable ? '' : ' NOT NULL';
                 return `${quoteIdent(column.name)} ${columnSqlType(column, dialect)}${notNull}`;
             })
             : []),
-        `${quoteIdent(SYNC_VERSION_COLUMN)} ${versionType} NOT NULL`,
-        `${quoteIdent(SYNC_SCOPES_COLUMN)} ${scopesType} NOT NULL`,
-        `${quoteIdent(SYNC_PAYLOAD_COLUMN)} ${payloadType} NOT NULL`,
-        `${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} ${payloadType}`,
+        ...trailing,
         `PRIMARY KEY (${quoteIdent(SYNC_PARTITION_COLUMN)}, ${quoteIdent(SYNC_ROW_ID_COLUMN)})`,
     ];
     return `CREATE TABLE IF NOT EXISTS ${quoteIdent(table.name)} (${defs.join(', ')})`;
@@ -555,6 +614,42 @@ export function parseLayouts(json) {
         return {};
     return JSON.parse(json);
 }
+/**
+ * Version equality is not layout equality: a marker written by another build
+ * at the same version describes rows the running codec cannot decode. Refuse
+ * when the stored layouts disagree with the configured schema, naming the
+ * first table (and column) that differs.
+ */
+export function assertStoredLayouts(schema, storedJson) {
+    const storedLayouts = parseLayouts(storedJson);
+    const configuredLayouts = parseLayouts(layoutsOf(schema));
+    for (const [tableName, columns] of Object.entries(configuredLayouts)) {
+        const stored = storedLayouts[tableName];
+        const columnCount = Math.max(columns.length, stored?.length ?? 0);
+        for (let index = 0; index < columnCount; index++) {
+            const expected = columns[index];
+            const actual = stored?.[index];
+            if (expected !== undefined &&
+                actual !== undefined &&
+                actual.name === expected.name &&
+                actual.type === expected.type &&
+                actual.nullable === expected.nullable) {
+                continue;
+            }
+            throw new StorageQueryError('sync.storage.stored_layout_mismatch', {
+                table: tableName,
+                column: expected?.name ?? actual?.name ?? '',
+            });
+        }
+    }
+    for (const tableName of Object.keys(storedLayouts)) {
+        if (!(tableName in configuredLayouts)) {
+            throw new StorageQueryError('sync.storage.stored_layout_mismatch', {
+                table: tableName,
+            });
+        }
+    }
+}
 /**
  * Tables present in the stored layout but absent from the configured head
  * schema. A schema-version bump retires their relational current-row tables;

package/dist/segment-download.js

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

package/dist/sqlite-dialect.d.ts

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

package/dist/sqlite-dialect.js

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

package/dist/sqlite-storage.d.ts

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