@syncular/server 0.22.0 → 0.24.0

package/README.md

@@ -168,6 +168,18 @@ the stable code/details to localized copy instead of displaying that message.
 
 Validators are per-operation. A validator must not mutate the row it receives.
 
+A validator that decides from other rows (a membership, a role, a grant) calls
+`context.queryAuthoritative` with the request `storage.queryAuthoritative`
+takes, built from a generated query descriptor. The storage binds every
+relation to the commit's partition and runs the statement on the push
+transaction's connection, so the read sees the operations staged before this
+one and needs no second pool connection. Never call
+`storage.queryAuthoritative` from a validator: on SQLite and PGlite it waits
+for the push transaction and the push never completes, and on a pool it reads
+committed state. The whole-commit reader, the reaction planner reader, and the
+remote command context expose the same method. See
+[Read a generated query inside a push transaction](https://syncular.dev/guide-remote-operations/#read-a-generated-query-inside-a-push-transaction).
+
 For a multi-row or multi-table invariant, install `commitValidator`. It runs
 once after every operation is staged in the same transaction, and can inspect
 both the decoded sibling operations and final candidate state:
@@ -215,8 +227,8 @@ const config: SyncServerConfig = {
 };
 ```
 
-The callback also receives `read.getRow()` and bounded `read.scanRows()` APIs.
-Those reads see the final candidate state, including staged sibling upserts and
+The callback also receives `read.getRow()`, bounded `read.scanRows()`, and
+`read.queryAuthoritative()` APIs. Those reads see the final candidate state, including staged sibling upserts and
 deletes. Syncular serializes the partition before any operation read so two
 aggregate validators cannot both accept mutually invalid candidates. It also
 re-checks idempotency after taking that lock and persists a rejected outcome

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

@@ -45,9 +45,9 @@ import { StorageQueryError } from './storage-errors.js';
 import { decodeRow } from '@syncular/core';
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertAppendOnlyMigration, commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { asUint8Array, collectCommitWindowPage, deserializePushResult, serializePushResult, sqliteDdlStatements, toStoredRow, } from './sqlite-dialect.js';
+import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, serializePushResult, sqliteDdlStatements, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
 function toStoredReaction(record) {
@@ -83,10 +83,44 @@ function relationalValuesEqual(left, right) {
     }
     return Object.is(left, right);
 }
+/** Run one partition-bound registered query and the cursor read as one batch. */
+async function queryAuthoritativeOn(db, partition, prepared) {
+    const results = await db.batch([
+        db.prepare(prepared.sql).bind(...prepared.params),
+        db
+            .prepare('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
+            .bind(partition),
+    ]);
+    const rowsResult = results[0];
+    const cursorResult = results[1];
+    if (typeof rowsResult !== 'object' ||
+        rowsResult === null ||
+        !('results' in rowsResult) ||
+        !Array.isArray(rowsResult.results) ||
+        typeof cursorResult !== 'object' ||
+        cursorResult === null ||
+        !('results' in cursorResult) ||
+        !Array.isArray(cursorResult.results)) {
+        throw new Error('D1 registered query returned an invalid batch result');
+    }
+    const cursor = cursorResult.results[0];
+    const maxCommitSeq = typeof cursor === 'object' &&
+        cursor !== null &&
+        'max_commit_seq' in cursor &&
+        typeof cursor.max_commit_seq === 'number'
+        ? cursor.max_commit_seq
+        : 0;
+    return {
+        rows: rowsResult.results.filter((row) => typeof row === 'object' && row !== null),
+        maxCommitSeq,
+    };
+}
 class D1Transaction {
     #db;
     #partition;
     #resolveTable;
+    /** Storage-owned relation rewrite, bound to this transaction's partition. */
+    #prepareQuery;
     #pushApplySerialized;
     #buffer = [];
     #open = true;
@@ -110,10 +144,11 @@ class D1Transaction {
      * `tbl\u0000rowId` → the pending state, consulted by `getRow` before D1.
      */
     #pending = new Map();
-    constructor(db, partition, resolveTable, pushApplySerialized) {
+    constructor(db, partition, resolveTable, prepareQuery, pushApplySerialized) {
         this.#db = db;
         this.#partition = partition;
         this.#resolveTable = resolveTable;
+        this.#prepareQuery = prepareQuery;
         this.#pushApplySerialized = pushApplySerialized;
     }
     #assertOpen() {
@@ -255,6 +290,18 @@ class D1Transaction {
             .sort((left, right) => left.rowId.localeCompare(right.rowId))
             .slice(0, query.limit);
     }
+    async queryAuthoritative(query) {
+        this.#assertOpen();
+        // D1 buffers writes until commit() and cannot overlay them on generated
+        // SQL, so a read over a written table would return committed state
+        // without this transaction's staged rows. Refuse it instead.
+        for (const key of this.#pending.keys()) {
+            if (query.tables.includes(key.slice(0, key.indexOf('\u0000')))) {
+                throw new StorageQueryError('sync.storage.query_over_staged_writes');
+            }
+        }
+        return queryAuthoritativeOn(this.#db, this.#partition, this.#prepareQuery(query));
+    }
     async lockPartitionForPush() {
         this.#assertOpen();
         if (!this.#pushApplySerialized) {
@@ -264,6 +311,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;
@@ -495,6 +557,26 @@ _a = D1Transaction;
  * binds one per app column plus the five `_sync_*` meta columns.
  */
 const D1_MAX_BIND_PARAMS = 100;
+/**
+ * The core tables `D1ServerStorage` reads or writes outside schema migration.
+ * `migrateSchema` creates them in its core phase, which runs only when the
+ * version marker advances, so a same-version open refuses a database missing
+ * one. `sync_backfill_checkpoints` and `sync_writer_fence` stay out: D1
+ * declares no checkpoints and installs no fence.
+ */
+const D1_CORE_TABLES = [
+    'sync_partitions',
+    'sync_partition_registry',
+    'sync_row_scopes',
+    'sync_commits',
+    'sync_changes',
+    'sync_change_scopes',
+    'sync_push_results',
+    'sync_reactions',
+    'sync_clients',
+    'sync_blob_refs',
+    'sync_tombstones',
+];
 export class D1ServerStorage {
     #db;
     #pushApplySerialized;
@@ -527,7 +609,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;
@@ -582,6 +669,33 @@ export class D1ServerStorage {
         const marker = await read(this.#db.prepare('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1'));
         let claim = await read(this.#db.prepare('SELECT * FROM sync_schema_migration WHERE id=1'));
         if (claim === null && marker?.schema_version === schema.version) {
+            assertStoredLayouts(schema, marker.layouts);
+            statementsExecuted++;
+            const present = await this.#db
+                .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name IN (${placeholders(D1_CORE_TABLES.length)})`)
+                .bind(...D1_CORE_TABLES)
+                .all();
+            const presentNames = new Set(present.results.map((row) => row.name));
+            for (const name of D1_CORE_TABLES) {
+                if (!presentNames.has(name)) {
+                    throw new StorageQueryError('sync.storage.physical_layout_mismatch', {
+                        table: name,
+                        reason: 'missing_table',
+                    });
+                }
+            }
+            for (const table of tables) {
+                statementsExecuted++;
+                const { results } = await this.#db
+                    .prepare(`PRAGMA table_info(${quoteIdent(table.name)})`)
+                    .all();
+                assertPhysicalColumns(table, results.map((column) => ({
+                    name: column.name,
+                    type: column.type,
+                    notNull: column.notnull === 1,
+                    primaryKeyPosition: column.pk,
+                })), 'sqlite');
+            }
             this.#tables = schema.tables;
             this.#schemaVersion = schema.version;
             return { complete: true, statementsExecuted };
@@ -963,7 +1077,7 @@ export class D1ServerStorage {
             if (table === undefined)
                 throw new StorageQueryError('sync.storage.schema_changed');
             return table;
-        }, this.#pushApplySerialized);
+        }, (query) => this.#prepareAuthoritativeQuery(partition, query), this.#pushApplySerialized);
     }
     async getMaxCommitSeq(partition) {
         const row = await this.#db
@@ -972,41 +1086,18 @@ 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();
+        return queryAuthoritativeOn(db, partition, this.#prepareAuthoritativeQuery(partition, query));
+    }
+    #prepareAuthoritativeQuery(partition, query) {
         if (this.#tables === undefined) {
             throw new Error('ensureSchema(schema) must run before registered queries');
         }
-        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
-        const results = await db.batch([
-            db.prepare(prepared.sql).bind(...prepared.params),
-            db
-                .prepare('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
-                .bind(partition),
-        ]);
-        const rowsResult = results[0];
-        const cursorResult = results[1];
-        if (typeof rowsResult !== 'object' ||
-            rowsResult === null ||
-            !('results' in rowsResult) ||
-            !Array.isArray(rowsResult.results) ||
-            typeof cursorResult !== 'object' ||
-            cursorResult === null ||
-            !('results' in cursorResult) ||
-            !Array.isArray(cursorResult.results)) {
-            throw new Error('D1 registered query returned an invalid batch result');
-        }
-        const cursor = cursorResult.results[0];
-        const maxCommitSeq = typeof cursor === 'object' &&
-            cursor !== null &&
-            'max_commit_seq' in cursor &&
-            typeof cursor.max_commit_seq === 'number'
-            ? cursor.max_commit_seq
-            : 0;
-        return {
-            rows: rowsResult.results.filter((row) => typeof row === 'object' && row !== null),
-            maxCommitSeq,
-        };
+        return bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
     }
     async getPartitionLogEpoch(partition) {
         const row = await this.#db
@@ -1086,6 +1177,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.d.ts

@@ -1,7 +1,7 @@
 import { type AuthoritativeRelationPlan } from './authoritative-query.js';
 import { type RemoteOperationResponse, type RowValue } from '@syncular/core';
 import type { SyncRequestContext } from './context.js';
-import type { AuthoritativeQueryValue } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, AuthoritativeQueryValue } from './storage.js';
 import { type ValidateRow } from './validate.js';
 export interface RemoteQueryDependency {
     readonly table: string;
@@ -63,6 +63,12 @@ export interface RemoteCommandContext {
     readonly operationId: string;
     readonly requestId: string;
     getRow(table: string, rowId: string): Promise<ValidateRow | undefined>;
+    /**
+     * Run a generated registered query on the command's push transaction
+     * (§6.7). The storage binds every relation to the partition; unlike
+     * `getRow`, the rows are not filtered by the actor's scopes.
+     */
+    queryAuthoritative(query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
 }
 export interface RemoteCommandOptions<Input> {
     readonly authorize: (context: RemoteOperationAuthContext, input: Input) => boolean | Promise<boolean>;

package/dist/operations.js

@@ -5,6 +5,7 @@ import { SyncError, syncError } from './errors.js';
 import { processPushOperationsWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
 import { authorizeWrite } from './scopes.js';
+import { transactionQuery } from './storage-query.js';
 import { toValidateRow } from './validate.js';
 function scopeAllowed(allowed, variable, value) {
     const values = allowed[variable];
@@ -185,7 +186,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 +201,7 @@ export function registerRemoteQuery(descriptor, options) {
                     },
                     params: [...descriptor.bind(params), options.maxRows + 1],
                     tables: descriptor.tables,
-                });
+                }, ctx.checkpoints);
             }
             catch (error) {
                 if (error instanceof SyncError)
@@ -293,6 +294,7 @@ function commandContext(ctx, tx, resolved, schema, clientId, operationId, reques
             }
             return toValidateRow(table.columns, decodeRow(table.columns, stored.payload));
         },
+        queryAuthoritative: (query) => transactionQuery(tx, query),
     };
 }
 /** Register custom command code that plans one ordinary Syncular commit. */
@@ -318,7 +320,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,