@syncular/server 0.23.0 → 0.24.0

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/sqlite-storage.d.ts

@@ -16,6 +16,13 @@ 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>;
+    /**
+     * 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>;

package/dist/sqlite-storage.js

@@ -12,7 +12,7 @@ import { serveNotReadyError } from './readiness.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, placeholders, SQLITE_DDL, serializePushResult, toStoredRow, } from './sqlite-dialect.js';
 import { SqliteAdapterRequiredError, } from './sqlite-driver.js';
@@ -106,6 +106,12 @@ 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.
@@ -338,52 +344,18 @@ END`);
             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) {
@@ -597,11 +569,26 @@ END`);
             .get(partition);
         return row?.max_commit_seq ?? 0;
     }
-    async queryAuthoritative(partition, query, checkpoints) {
+    /**
+     * 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) => {
@@ -620,15 +607,10 @@ END`);
             const refusal = serveGateRefusal(gate, runningVersion, checkpoints);
             if (refusal !== undefined)
                 throw serveNotReadyError(refusal);
-            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);
+            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)

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' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete';
+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

@@ -23,6 +23,10 @@ const STORAGE_QUERY_MESSAGES = {
     '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',
@@ -31,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);
+}

package/dist/storage.d.ts

@@ -381,6 +381,19 @@ export interface StorageTransaction {
      * read-your-own-writes semantics. It is not reachable from SSP2 requests.
      */
     scanRowsByIndex?(query: IndexRowScanQuery): Promise<StoredRow[]>;
+    /**
+     * Optional transaction-bound registered query (§6.7, §6.8): the relation
+     * rewrite of `ServerStorage.queryAuthoritative`, bound to this
+     * transaction's partition and executed on this transaction's connection.
+     * A hook inside the push transaction therefore reads the transaction's
+     * snapshot and never waits for a second connection. The push layer has
+     * already evaluated the serve gate on this transaction, so the call takes
+     * no checkpoint declarations. SQLite and PostgreSQL return the staged
+     * writes of this transaction. D1 buffers writes until commit and fails
+     * with `sync.storage.query_over_staged_writes` when the query reads a
+     * table this transaction has written.
+     */
+    queryAuthoritative?(query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
     /**
      * Serialize every push apply for this partition before any operation read,
      * validation, merge, or write. The push layer re-checks idempotency only
@@ -575,17 +588,18 @@ export interface ServerStorage {
      * every generated app-table relation with a partition-filtered relation and
      * return rows plus maxCommitSeq from one consistent database snapshot.
      *
-     * The storage serializes this call behind an open transaction on a
-     * single-connection executor (SQLite, PGlite). A validator runs inside the
-     * push transaction, so on that executor a validator that calls
-     * `queryAuthoritative` waits on the transaction it is already inside and
-     * the push never completes. A pool-backed executor (`pg`, `Bun.sql`) hands
-     * the call a second connection instead: the validator does not deadlock,
-     * but it reads committed state without the candidate write. On either
-     * executor read candidate state through the whole-commit `CommitValidator`
-     * reader (§6.8). A call made from any other context waits for the open
-     * transaction to finish on a single-connection executor, and runs
-     * concurrently on a pool-backed one.
+     * Do not call this method from a hook that runs inside the push
+     * transaction (a row validator, the whole-commit validator, or a reaction
+     * planner). On a single-connection executor (SQLite, PGlite) the storage
+     * serializes this call behind the open transaction, so the hook waits on
+     * the transaction it is inside and the push never completes. A pool-backed
+     * executor (`pg`, `Bun.sql`) runs the call on a second connection: it reads
+     * committed state without the transaction's staged writes, and it waits
+     * forever when the push transactions hold every pool connection. Those
+     * hooks call the transaction-bound `queryAuthoritative` on
+     * `ValidateContext` or on the candidate-state reader instead (§6.7, §6.8).
+     * A call from any other context waits for the open transaction on a
+     * single-connection executor and runs concurrently on a pool-backed one.
      */
     queryAuthoritative?(partition: string, query: AuthoritativeQueryRequest, checkpoints?: readonly CheckpointDeclaration[]): Promise<AuthoritativeQueryResult>;
     /**

package/dist/validate.d.ts

@@ -14,6 +14,7 @@
  * object — zero cost, the events-seam discipline.
  */
 import { type RejectionDetails, type RowColumn, type RowValue, type ScopeMap } from '@syncular/core';
+import type { AuthoritativeQueryRequest, AuthoritativeQueryResult } from './storage.js';
 /**
  * §6.7 reserved code prefixes. A host validator code MUST NOT start with
  * any of these: they namespace the protocol's own error families (§10.2)
@@ -81,6 +82,15 @@ export interface CommitValidationScanInput {
 export interface CommitValidationReader {
     getRow(table: string, rowId: string): Promise<CommitValidationRow | undefined>;
     scanRows(input: CommitValidationScanInput): Promise<CommitValidationRow[]>;
+    /**
+     * Run a generated registered query on the commit transaction (§6.8). The
+     * request has the shape `ServerStorage.queryAuthoritative` takes; the
+     * storage binds every relation to the commit's partition. SQLite and
+     * PostgreSQL return the final candidate state; D1 fails with
+     * `sync.storage.query_over_staged_writes` when the query reads a table the
+     * commit has written.
+     */
+    queryAuthoritative(query: AuthoritativeQueryRequest): Promise<AuthoritativeQueryResult>;
 }
 export interface ValidateCommitInput {
     readonly clientId: string;
@@ -98,21 +108,29 @@ export type CommitValidator = (input: ValidateCommitInput) => void | Promise<voi
 /**
  * Ambient context a validator may consult (§6.7).
  *
- * A validator runs inside the push transaction. On a single-connection
- * executor (SQLite, PGlite) the storage serializes authoritative queries
- * behind that transaction, so a validator that calls `queryAuthoritative`
- * waits for the transaction it is already inside and the push never
- * completes. On a pool-backed executor (`pg`, `Bun.sql`) the query takes a
- * second connection and returns committed state without the candidate write.
- * Either way a rule that must read rows belongs in the whole-commit
- * `CommitValidator`, whose reader runs get and scan operations on the same
- * transaction (§6.8).
+ * A validator runs inside the push transaction. It MUST NOT call
+ * `ServerStorage.queryAuthoritative`: on a single-connection executor
+ * (SQLite, PGlite) that call waits for the transaction the validator is
+ * inside and the push never completes, and on a pool-backed executor (`pg`,
+ * `Bun.sql`) it reads committed state without the staged writes, or waits
+ * forever once push transactions hold every pool connection. An authority
+ * read calls `queryAuthoritative` on this context instead.
  */
 export interface ValidateContext {
     /** Host-authenticated actor (§1.1) performing the write. */
     readonly actorId: string;
     /** The partition (§1.1) the commit targets. */
     readonly partition: string;
+    /**
+     * Run a generated registered query on the push transaction (§6.7). The
+     * request has the shape `ServerStorage.queryAuthoritative` takes; the
+     * storage binds every relation to the commit's partition. SQLite and
+     * PostgreSQL return the transaction's snapshot, including the operations
+     * staged before this one; D1 fails with
+     * `sync.storage.query_over_staged_writes` when the query reads a table the
+     * commit has written.
+     */
+    readonly queryAuthoritative: (query: AuthoritativeQueryRequest) => Promise<AuthoritativeQueryResult>;
 }
 /**
  * A per-table validation hook (§6.7). Called once per push operation on
@@ -123,12 +141,12 @@ export interface ValidateContext {
  * `sync.constraint_violation` code (a validator SHOULD throw
  * `ValidationRejection` to control the code). MUST NOT mutate the row.
  *
- * The hook runs inside the push transaction and cannot read candidate rows
- * from an authoritative query: on a single-connection executor
- * `queryAuthoritative` serializes behind that transaction and the push never
- * completes, and on a pool-backed executor it reads committed state without
- * the candidate write. Read rows with the whole-commit `CommitValidator`
- * reader instead (§6.8).
+ * The hook runs inside the push transaction. An authority read uses
+ * `ctx.queryAuthoritative`, which executes on that transaction; calling
+ * `ServerStorage.queryAuthoritative` from here deadlocks on a
+ * single-connection executor and reads committed state on a pool-backed one.
+ * A rule over sibling operations belongs in the whole-commit
+ * `CommitValidator` (§6.8).
  */
 export type Validator = (op: ValidateOperation, ctx: ValidateContext) => void | Promise<void>;
 /** Table name → validator (§6.7). Absent tables are unvalidated. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.23.0"
+    "@syncular/core": "0.24.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"