@syncular/server 0.22.0 → 0.24.0

package/dist/sqlite-storage.js

@@ -1,5 +1,7 @@
 import { validateCommitPruneQuery } from './prune.js';
 import { StorageQueryError } from './storage-errors.js';
+import { serveGateRefusal } from './storage.js';
+import { serveNotReadyError } from './readiness.js';
 /**
  * SQLite server storage over the shared synchronous driver.
  *
@@ -10,12 +12,24 @@ import { StorageQueryError } from './storage-errors.js';
  */
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertPhysicalColumns, commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
-import { collectCommitWindowPage, deserializePushResult, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
+import { collectCommitWindowPage, deserializePushResult, placeholders, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
 import { isSqliteConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
+function toStoredCheckpoint(record) {
+    return {
+        partition: record.partition,
+        name: record.name,
+        schemaVersion: record.schema_version,
+        state: record.state,
+        watermark: record.watermark,
+        ownerEpoch: record.owner_epoch,
+        observedRows: record.observed_rows,
+        updatedAtMs: record.updated_at_ms,
+    };
+}
 function toStoredReaction(record) {
     return {
         idempotencyKey: record.idempotency_key,
@@ -45,12 +59,15 @@ function toStoredReaction(record) {
 class SqliteTransaction {
     #storage;
     #partition;
+    /** Schema version this transaction writes; rides every appended commit row. */
+    #writerVersion;
     #open = true;
     #pushApplySavepoint = false;
     #release;
-    constructor(storage, partition, release) {
+    constructor(storage, partition, writerVersion, release) {
         this.#storage = storage;
         this.#partition = partition;
+        this.#writerVersion = writerVersion;
         this.#release = release;
         storage.db.exec('BEGIN IMMEDIATE');
     }
@@ -89,12 +106,33 @@ class SqliteTransaction {
         this.#assertOpen();
         return this.#storage.scanRowsByIndex(this.#partition, query);
     }
+    async queryAuthoritative(query) {
+        this.#assertOpen();
+        // Same shared connection: the query runs inside this transaction's
+        // BEGIN IMMEDIATE and observes every row staged so far.
+        return this.#storage.runAuthoritativeQuery(this.#partition, query);
+    }
     async lockPartitionForPush() {
         this.#assertOpen();
         // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
         this.#storage.db.exec('SAVEPOINT syncular_push_candidate');
         this.#pushApplySavepoint = true;
     }
+    async advanceCheckpoint(name, ownerEpoch, watermark, observedRows, nowMs) {
+        this.#assertOpen();
+        const result = this.#storage.db
+            .query(`UPDATE sync_backfill_checkpoints
+            SET watermark=?, observed_rows=?, updated_at_ms=?
+          WHERE partition=? AND name=? AND owner_epoch=?`)
+            .run(watermark, observedRows, nowMs, this.#partition, name, ownerEpoch);
+        return Number(result.changes) === 1;
+    }
+    readServeGate(runningSchemaVersion) {
+        this.#assertOpen();
+        // Same shared connection: this read runs inside this transaction's
+        // BEGIN IMMEDIATE, so the gate and the write share one transaction.
+        return this.#storage.readServeGate(this.#partition, runningSchemaVersion);
+    }
     async commitRejectedPushResult(clientId, clientCommitId, result) {
         this.#assertOpen();
         if (!this.#pushApplySavepoint) {
@@ -146,7 +184,7 @@ class SqliteTransaction {
             .get(p);
         const commitSeq = (row?.max_commit_seq ?? 0) + 1;
         db.query('UPDATE sync_partitions SET max_commit_seq=? WHERE partition=?').run(commitSeq, p);
-        db.query('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms) VALUES (?,?,?,?,?,?)').run(p, commitSeq, commit.clientId, commit.clientCommitId, commit.actorId, commit.createdAtMs);
+        db.query('INSERT INTO sync_commits(partition, commit_seq, client_id, client_commit_id, actor_id, created_at_ms, writer_version) VALUES (?,?,?,?,?,?,?)').run(p, commitSeq, commit.clientId, commit.clientCommitId, commit.actorId, commit.createdAtMs, this.#writerVersion);
         commit.changes.forEach((change, idx) => {
             db.query('INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload) VALUES (?,?,?,?,?,?,?,?,?)').run(p, commitSeq, idx, change.table, change.rowId, change.op === 'upsert' ? 1 : 2, change.rowVersion ?? null, JSON.stringify(change.scopes), change.payload ?? null);
             if (change.op === 'delete') {
@@ -247,6 +285,30 @@ export class SqliteServerStorage {
         if (!clientColumns.some((column) => column.name === 'wire_version')) {
             this.db.exec('ALTER TABLE sync_clients ADD COLUMN wire_version INTEGER NOT NULL DEFAULT 1');
         }
+        const commitColumns = this.db
+            .query('PRAGMA table_info("sync_commits")')
+            .all();
+        if (!commitColumns.some((column) => column.name === 'writer_version')) {
+            // Nullable by design: an old writer omits the column and the trigger's
+            // explicit NULL test rejects it. `ADD COLUMN NOT NULL` is unavailable in
+            // SQLite, and a default would hand old writers a passing value.
+            this.db.exec('ALTER TABLE sync_commits ADD COLUMN writer_version INTEGER');
+        }
+        // The fence is database-side: an old binary's INSERT never reaches JS. An
+        // absent `sync_writer_fence` row makes the WHEN clause false, so a
+        // partition with no barrier behaves exactly as before.
+        this.db.exec(`CREATE TRIGGER IF NOT EXISTS sync_commits_writer_fence
+BEFORE INSERT ON sync_commits
+FOR EACH ROW
+WHEN EXISTS (
+  SELECT 1 FROM sync_writer_fence
+   WHERE partition = NEW.partition
+     AND (NEW.writer_version IS NULL
+          OR NEW.writer_version < required_writer_version)
+)
+BEGIN
+  SELECT RAISE(ABORT, 'sync.storage.writer_fence_rejected');
+END`);
     }
     /** Resolve a table's compiled schema; row operations require `ensureSchema`. */
     table(name) {
@@ -256,10 +318,24 @@ export class SqliteServerStorage {
         }
         return table;
     }
-    async ensureSchema(schema) {
+    async ensureSchema(schema, checkpoints) {
         // Memoized fast path: same instance, same schema version.
         if (this.#schemaVersion === schema.version)
             return;
+        // The barrier reads stored state: a checkpoint at this schema version that
+        // is not activated and that this caller did not declare means this process
+        // must not serve. An omitted or empty declaration set declares nothing and
+        // is refused here, never treated as a bypass.
+        const declarations = checkpoints ?? [];
+        const incomplete = this.db
+            .query(`SELECT partition, name FROM sync_backfill_checkpoints
+          WHERE schema_version=? AND state<>'activated'`)
+            .all(schema.version)
+            .filter((row) => !declarations.some((declaration) => declaration.partition === row.partition &&
+            declaration.name === row.name));
+        if (incomplete.length > 0) {
+            throw new StorageQueryError('sync.storage.checkpoint_incomplete');
+        }
         this.db.exec(SCHEMA_META_DDL_SQLITE);
         const marker = this.db
             .query('SELECT schema_version, layouts FROM sync_schema_meta WHERE id=1')
@@ -268,52 +344,18 @@ export class SqliteServerStorage {
             throw new Error(`stored schema version ${marker.schema_version} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
         }
         if (marker !== null && marker.schema_version === schema.version) {
-            // Version equality is not layout equality: a marker written by another
-            // build at the same version describes rows the running codec cannot
-            // decode. Compare the stored layouts instead of trusting the number.
-            const storedLayouts = parseLayouts(marker.layouts);
-            const configuredLayouts = parseLayouts(layoutsOf(schema));
-            let mismatch;
-            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;
-                    }
-                    mismatch = `table ${JSON.stringify(tableName)} column ${JSON.stringify(expected?.name ?? actual?.name ?? '')}`;
-                    break;
-                }
-                if (mismatch !== undefined)
-                    break;
-            }
-            if (mismatch === undefined) {
-                for (const tableName of Object.keys(storedLayouts)) {
-                    if (!(tableName in configuredLayouts)) {
-                        mismatch = `table ${JSON.stringify(tableName)}`;
-                        break;
-                    }
-                }
-            }
-            if (mismatch !== undefined) {
-                throw new Error(`stored schema layouts disagree with the configured schema at version ${schema.version} (${mismatch}) — refusing to serve a database whose stored rows the running code cannot decode`);
-            }
-            // The persisted layouts describe the codec's app columns only: read the
-            // physical tables so a same-version database missing a
-            // storage-internal column is refused at startup instead of failing at
-            // the first write.
+            assertStoredLayouts(schema, marker.layouts);
             for (const table of schema.tables.values()) {
                 const escapedTableName = table.name.replaceAll('"', '""');
                 const columns = this.db
                     .query(`PRAGMA table_info("${escapedTableName}")`)
                     .all();
-                assertPhysicalColumns(table, new Set(columns.map((c) => c.name)));
+                assertPhysicalColumns(table, columns.map((column) => ({
+                    name: column.name,
+                    type: column.type,
+                    notNull: column.notnull === 1,
+                    primaryKeyPosition: column.pk,
+                })), 'sqlite');
             }
         }
         if (marker === null || marker.schema_version < schema.version) {
@@ -340,36 +382,50 @@ export class SqliteServerStorage {
                     existingIndexes.set(table.name, new Set(indexes.map((index) => index.name)));
                 }
             }
-            this.db.exec('BEGIN IMMEDIATE');
-            try {
-                for (const tableName of retiredTables) {
-                    this.db
-                        .query('DELETE FROM sync_row_scopes WHERE tbl=?')
-                        .run(tableName);
+            // The migration rewrites application rows (`#rewriteRows`) with no
+            // commit log entry. Serialize it through the same writer queue as
+            // pushes and prune (`#serializeWrite`) rather than trusting the
+            // migration as privileged; `BEGIN IMMEDIATE` then owns SQLite's writer
+            // lock for the whole rewrite.
+            await this.#serializeWrite(() => {
+                this.db.exec('BEGIN IMMEDIATE');
+                try {
+                    for (const tableName of retiredTables) {
+                        this.db
+                            .query('DELETE FROM sync_row_scopes WHERE tbl=?')
+                            .run(tableName);
+                        this.db
+                            .query('DELETE FROM sync_blob_refs WHERE tbl=?')
+                            .run(tableName);
+                        this.db.exec(dropTableDdl(tableName));
+                    }
+                    for (const statement of schemaDdl(schema, existing, 'sqlite', existingIndexes)) {
+                        this.db.exec(statement);
+                    }
+                    for (const table of schema.tables.values()) {
+                        const oldLayout = layouts[table.name];
+                        const plan = rewritePlan(table, oldLayout, existing.get(table.name));
+                        if (!plan.migrate && !plan.backfill)
+                            continue;
+                        this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
+                    }
                     this.db
-                        .query('DELETE FROM sync_blob_refs WHERE tbl=?')
-                        .run(tableName);
-                    this.db.exec(dropTableDdl(tableName));
-                }
-                for (const statement of schemaDdl(schema, existing, 'sqlite', existingIndexes)) {
-                    this.db.exec(statement);
+                        .query('INSERT INTO sync_schema_meta(id, schema_version, layouts) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET schema_version=excluded.schema_version, layouts=excluded.layouts')
+                        .run(schema.version, layoutsOf(schema));
+                    // The host's declared checkpoints install in the schema-bump
+                    // transaction, so no observer sees the bumped marker without the
+                    // fence, or the fence without its declaration row.
+                    const installedAtMs = Date.now();
+                    for (const declaration of checkpoints ?? []) {
+                        this.#installCheckpoint(declaration.partition, declaration.name, declaration.schemaVersion, installedAtMs);
+                    }
+                    this.db.exec('COMMIT');
                 }
-                for (const table of schema.tables.values()) {
-                    const oldLayout = layouts[table.name];
-                    const plan = rewritePlan(table, oldLayout, existing.get(table.name));
-                    if (!plan.migrate && !plan.backfill)
-                        continue;
-                    this.#rewriteRows(table, plan.migrate ? oldLayout : undefined);
+                catch (error) {
+                    this.db.exec('ROLLBACK');
+                    throw error;
                 }
-                this.db
-                    .query('INSERT INTO sync_schema_meta(id, schema_version, layouts) VALUES (1, ?, ?) ON CONFLICT(id) DO UPDATE SET schema_version=excluded.schema_version, layouts=excluded.layouts')
-                    .run(schema.version, layoutsOf(schema));
-                this.db.exec('COMMIT');
-            }
-            catch (error) {
-                this.db.exec('ROLLBACK');
-                throw error;
-            }
+            });
         }
         this.#tables = schema.tables;
         this.#schemaVersion = schema.version;
@@ -485,7 +541,7 @@ export class SqliteServerStorage {
         });
         await previous;
         try {
-            return new SqliteTransaction(this, partition, release);
+            return new SqliteTransaction(this, partition, this.#schemaVersion ?? 0, release);
         }
         catch (error) {
             release();
@@ -513,11 +569,26 @@ export class SqliteServerStorage {
             .get(partition);
         return row?.max_commit_seq ?? 0;
     }
-    async queryAuthoritative(partition, query) {
+    /**
+     * 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, 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 rows = this.db
+            .query(prepared.sql)
+            .all(...prepared.params);
+        const cursor = this.db
+            .query('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
+            .get(partition);
+        return { rows, maxCommitSeq: cursor?.max_commit_seq ?? 0 };
+    }
+    async queryAuthoritative(partition, query, checkpoints) {
         const previous = this.#transactionTail;
         let release;
         this.#transactionTail = new Promise((resolve) => {
@@ -528,15 +599,18 @@ export class SqliteServerStorage {
         try {
             this.db.exec('BEGIN');
             open = true;
-            const rows = this.db
-                .query(prepared.sql)
-                .all(...prepared.params);
-            const cursor = this.db
-                .query('SELECT max_commit_seq FROM sync_partitions WHERE partition=?')
-                .get(partition);
+            // RFC 0007: evaluate the gate on this connection after BEGIN. SQLite is
+            // single-writer and the shared connection serializes writers, so the
+            // gate read and the query read cannot straddle a migration.
+            const runningVersion = this.#schemaVersion ?? 0;
+            const gate = await this.readServeGate(partition, runningVersion);
+            const refusal = serveGateRefusal(gate, runningVersion, checkpoints);
+            if (refusal !== undefined)
+                throw serveNotReadyError(refusal);
+            const result = this.runAuthoritativeQuery(partition, query);
             this.db.exec('COMMIT');
             open = false;
-            return { rows, maxCommitSeq: cursor?.max_commit_seq ?? 0 };
+            return result;
         }
         catch (error) {
             if (open)
@@ -616,6 +690,177 @@ export class SqliteServerStorage {
             .get(partition, createdBeforeMs);
         return row?.seq ?? 0;
     }
+    async readServeGate(partition, runningSchemaVersion) {
+        const marker = this.db
+            .query('SELECT schema_version FROM sync_schema_meta WHERE id=1')
+            .get();
+        const epoch = this.db
+            .query('SELECT log_epoch FROM sync_partition_registry WHERE partition=?')
+            .get(partition);
+        const pending = this.db
+            .query(`SELECT partition, name FROM sync_backfill_checkpoints
+          WHERE schema_version=? AND state<>'activated'`)
+            .all(runningSchemaVersion);
+        return {
+            storedSchemaVersion: marker?.schema_version ?? 0,
+            logEpoch: epoch?.log_epoch,
+            pending: pending.map((row) => ({
+                partition: row.partition,
+                name: row.name,
+            })),
+        };
+    }
+    async readCheckpoints(partition) {
+        return this.db
+            .query(`SELECT partition, name, schema_version, state, watermark,
+                owner_epoch, observed_rows, updated_at_ms
+           FROM sync_backfill_checkpoints WHERE partition=? ORDER BY name`)
+            .all(partition)
+            .map(toStoredCheckpoint);
+    }
+    /**
+     * Insert the `declared` row and raise the fence, inside the caller's open
+     * transaction. Shared by `declareCheckpoint` and the `ensureSchema`
+     * migration so the schema bump and the fence commit together. Never lowers a
+     * fence and never re-declares an existing row.
+     */
+    #installCheckpoint(partition, name, schemaVersion, nowMs) {
+        this.db
+            .query(`INSERT INTO sync_backfill_checkpoints(
+           partition, name, schema_version, state, watermark,
+           owner_epoch, observed_rows, updated_at_ms)
+         VALUES (?,?,?,'declared',0,0,0,?)
+         ON CONFLICT(partition, name) DO NOTHING`)
+            .run(partition, name, schemaVersion, nowMs);
+        this.db
+            .query(`INSERT INTO sync_writer_fence(partition, required_writer_version)
+         VALUES (?,?)
+         ON CONFLICT(partition) DO UPDATE SET
+           required_writer_version=max(
+             sync_writer_fence.required_writer_version,
+             excluded.required_writer_version)`)
+            .run(partition, schemaVersion);
+    }
+    async declareCheckpoint(partition, name, schemaVersion, nowMs) {
+        // One transaction: the checkpoint becomes visible and the fence that
+        // protects it is raised together. The fence is raised at declaration, not
+        // at activation, so old writers are rejected for the whole backfill.
+        return this.#serializeWrite(() => {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                this.#installCheckpoint(partition, name, schemaVersion, nowMs);
+                const row = this.db
+                    .query(`SELECT partition, name, schema_version, state, watermark,
+                    owner_epoch, observed_rows, updated_at_ms
+               FROM sync_backfill_checkpoints WHERE partition=? AND name=?`)
+                    .get(partition, name);
+                if (row === null)
+                    throw new StorageQueryError('sync.storage.checkpoint_not_declared');
+                this.db.exec('COMMIT');
+                return toStoredCheckpoint(row);
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+        });
+    }
+    async activateCheckpoint(partition, name, ownerEpoch, watermark, sources, nowMs) {
+        return this.#serializeWrite(() => {
+            // `BEGIN IMMEDIATE` is SQLite's partition write lock; the same writer
+            // lock a push takes. Nothing may observe activation without the fence.
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                const fence = this.db
+                    .query('SELECT required_writer_version FROM sync_writer_fence WHERE partition=?')
+                    .get(partition);
+                const checkpoint = this.db
+                    .query('SELECT schema_version FROM sync_backfill_checkpoints WHERE partition=? AND name=?')
+                    .get(partition, name);
+                if (fence === null ||
+                    checkpoint === null ||
+                    fence.required_writer_version < checkpoint.schema_version) {
+                    // The barrier is not installed. Activating would certify a state old
+                    // writers can still decay; refuse instead of silently proceeding.
+                    throw new StorageQueryError('sync.storage.checkpoint_fence_missing');
+                }
+                const coverage = this.#hasSourceChangesAbove(partition, sources, watermark);
+                if (coverage !== 'clean') {
+                    this.db.exec('ROLLBACK');
+                    return coverage === 'changed' ? 'stale' : 'unverifiable';
+                }
+                const updated = this.db
+                    .query(`UPDATE sync_backfill_checkpoints
+                SET state='activated', watermark=?, updated_at_ms=?
+              WHERE partition=? AND name=? AND owner_epoch=?
+                AND state<>'activated'`)
+                    .run(watermark, nowMs, partition, name, ownerEpoch);
+                this.db.exec('COMMIT');
+                return Number(updated.changes) === 1 ? 'activated' : 'stale';
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+        });
+    }
+    async claimCheckpoint(partition, name, schemaVersion, nowMs) {
+        return this.#serializeWrite(() => {
+            const claimed = this.db
+                .query(`UPDATE sync_backfill_checkpoints
+              SET owner_epoch=owner_epoch+1,
+                  state=CASE WHEN state='declared' THEN 'backfilling' ELSE state END,
+                  schema_version=?, updated_at_ms=?
+            WHERE partition=? AND name=? AND state<>'activated'
+        RETURNING partition, name, schema_version, state, watermark,
+                  owner_epoch, observed_rows, updated_at_ms`)
+                .get(schemaVersion, nowMs, partition, name);
+            if (claimed === null) {
+                throw new StorageQueryError('sync.storage.checkpoint_not_declared');
+            }
+            return toStoredCheckpoint(claimed);
+        });
+    }
+    async advanceCheckpoint(partition, name, ownerEpoch, watermark, observedRows, nowMs) {
+        return this.#serializeWrite(() => {
+            const result = this.db
+                .query(`UPDATE sync_backfill_checkpoints
+              SET watermark=?, observed_rows=?, updated_at_ms=?
+            WHERE partition=? AND name=? AND owner_epoch=?`)
+                .run(watermark, observedRows, nowMs, partition, name, ownerEpoch);
+            return Number(result.changes) === 1;
+        });
+    }
+    async sourceCoverageSeq(partition, tables) {
+        if (tables.length === 0)
+            return 0;
+        const row = this.db
+            .query(`SELECT max(commit_seq) AS seq FROM sync_changes
+          WHERE partition=? AND tbl IN (${placeholders(tables.length)})`)
+            .get(partition, ...tables);
+        return row?.seq ?? 0;
+    }
+    #hasSourceChangesAbove(partition, tables, seq) {
+        // Read the horizon before the window scan: a horizon past `seq` means the
+        // history that would answer the question is gone, so an empty scan proves
+        // nothing and must not be reported as `clean`.
+        const horizon = this.db
+            .query('SELECT horizon_seq FROM sync_partitions WHERE partition=?')
+            .get(partition)?.horizon_seq ?? 0;
+        if (tables.length === 0)
+            return 'clean';
+        const hit = this.db
+            .query(`SELECT 1 AS hit FROM sync_changes
+          WHERE partition=? AND tbl IN (${placeholders(tables.length)})
+            AND commit_seq>? LIMIT 1`)
+            .get(partition, ...tables, seq);
+        if (hit !== null && hit !== undefined)
+            return 'changed';
+        return horizon > seq ? 'unverifiable' : 'clean';
+    }
+    async hasSourceChangesAbove(partition, tables, seq) {
+        return this.#hasSourceChangesAbove(partition, tables, seq);
+    }
     async getRow(partition, table, rowId) {
         const record = this.db
             .query(selectRowSql(this.table(table), 'sqlite'))

package/dist/storage-errors.d.ts

@@ -9,15 +9,17 @@ export declare class StorageConstraintError extends Error {
     constructor(cause: unknown, opIndex?: number);
 }
 /** Stable, privacy-safe failures for trusted server storage queries. */
-export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor';
+export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete' | 'sync.storage.stored_layout_mismatch' | 'sync.storage.physical_layout_mismatch' | 'sync.storage.transaction_query_unsupported' | 'sync.storage.query_over_staged_writes';
 /**
  * Host-only query error. Messages never include identifiers, values, SQL,
- * paths, or row data; callers branch on `code`, never message text.
+ * paths, or row data; callers branch on `code`, never message text. The
+ * schema-readiness codes name the offending table and column in `details`.
  */
 export declare class StorageQueryError extends Error {
     readonly name = "StorageQueryError";
     readonly code: StorageQueryErrorCode;
-    constructor(code: StorageQueryErrorCode);
+    readonly details: Readonly<Record<string, string>> | undefined;
+    constructor(code: StorageQueryErrorCode, details?: Readonly<Record<string, string>>);
 }
 /** SQLite primary/extended constraint result codes (`SQLITE_CONSTRAINT*`). */
 export declare function isSqliteConstraintError(error: unknown): boolean;

package/dist/storage-errors.js

@@ -19,6 +19,14 @@ const STORAGE_QUERY_MESSAGES = {
     'sync.storage.prune_epoch_mismatch': 'partition log epoch changed; recompute retention inputs',
     'sync.storage.partition_unregistered': 'pruning requires a registered partition',
     'sync.storage.invalid_prune_cursor': 'pruning requires a non-negative safe integer cursor and a non-empty log epoch',
+    'sync.storage.checkpoint_not_declared': 'checkpoint claim requires a declared, not yet activated row',
+    'sync.storage.checkpoint_unsupported': 'this storage backend cannot declare backfill checkpoints',
+    'sync.storage.checkpoint_fence_missing': 'checkpoint activation requires the writer fence raised at declaration',
+    'sync.storage.checkpoint_incomplete': 'a declared backfill checkpoint is not activated and this caller did not declare it',
+    'sync.storage.stored_layout_mismatch': 'stored schema layouts disagree with the configured schema at the same version',
+    'sync.storage.physical_layout_mismatch': 'a synced table does not match the storage layout the running code reads and writes',
+    'sync.storage.transaction_query_unsupported': 'this storage transaction cannot run registered queries',
+    'sync.storage.query_over_staged_writes': 'registered query reads a table this transaction has buffered writes for',
     'sync.storage.scan_requires_scope': 'scope-indexed row scans require at least one scope variable',
     'sync.storage.index_not_found': 'trusted row lookup requires a declared relational index',
     'sync.storage.index_not_materialized': 'trusted row lookup requires a materialized relational table',
@@ -27,14 +35,17 @@ const STORAGE_QUERY_MESSAGES = {
 };
 /**
  * Host-only query error. Messages never include identifiers, values, SQL,
- * paths, or row data; callers branch on `code`, never message text.
+ * paths, or row data; callers branch on `code`, never message text. The
+ * schema-readiness codes name the offending table and column in `details`.
  */
 export class StorageQueryError extends Error {
     name = 'StorageQueryError';
     code;
-    constructor(code) {
+    details;
+    constructor(code, details) {
         super(STORAGE_QUERY_MESSAGES[code]);
         this.code = code;
+        this.details = details;
     }
 }
 function driverError(error) {

package/dist/storage-query.d.ts

@@ -1,5 +1,5 @@
 import type { CompiledTable, IndexSchema } from './schema.js';
-import type { IndexRowScanQuery, RowScanQuery } from './storage.js';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, IndexRowScanQuery, RowScanQuery, StorageTransaction } from './storage.js';
 /**
  * Fail loudly instead of making an unsupported unscoped scan look empty.
  * Returns the first scope variable in sorted order — the one every adapter
@@ -8,3 +8,10 @@ import type { IndexRowScanQuery, RowScanQuery } from './storage.js';
 export declare function assertScopeIndexedScan(query: RowScanQuery): string;
 /** Validate and resolve one exact trusted-host relational index lookup. */
 export declare function resolveIndexRowScan(table: CompiledTable, query: IndexRowScanQuery): IndexSchema;
+/**
+ * §6.7/§6.8 transaction-bound registered query for every host hook that runs
+ * inside a push transaction. A storage transaction without the capability
+ * fails; the call never falls back to `ServerStorage.queryAuthoritative`,
+ * which reads outside the transaction.
+ */
+export declare function transactionQuery(tx: StorageTransaction, query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;

package/dist/storage-query.js

@@ -34,3 +34,15 @@ export function resolveIndexRowScan(table, query) {
     }
     return index;
 }
+/**
+ * §6.7/§6.8 transaction-bound registered query for every host hook that runs
+ * inside a push transaction. A storage transaction without the capability
+ * fails; the call never falls back to `ServerStorage.queryAuthoritative`,
+ * which reads outside the transaction.
+ */
+export async function transactionQuery(tx, query) {
+    if (tx.queryAuthoritative === undefined) {
+        throw new StorageQueryError('sync.storage.transaction_query_unsupported');
+    }
+    return tx.queryAuthoritative(query);
+}