@syncular/server 0.23.0 → 0.25.0

package/src/relational-rows.ts

@@ -55,6 +55,7 @@ import {
 } from '@syncular/core';
 import type { CompiledSchema, CompiledTable, IndexSchema } from './schema';
 import type { StoredRow } from './storage';
+import { StorageQueryError } from './storage-errors';
 
 export type RelationalDialect = 'sqlite' | 'postgres';
 
@@ -192,38 +193,112 @@ export function tableColumnNames(table: CompiledTable): string[] {
 }
 
 /**
- * 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: RelationalDialect): readonly {
+  readonly name: string;
+  readonly type: string;
+  readonly notNull: boolean;
+}[] {
+  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 },
+  ];
+}
+
+/** One physical column of a synced table, read from the database catalog. */
+export interface PhysicalColumn {
+  readonly name: string;
+  /** Declared type (SQLite) or `format_type` (PostgreSQL); compared case-insensitively. */
+  readonly type: string;
+  readonly notNull: boolean;
+  /** 1-based position in the primary key; 0 when the column is not in it. */
+  readonly primaryKeyPosition: number;
+}
+
+/**
+ * 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: CompiledTable,
-  existingColumns: ReadonlySet<string>,
+  columns: readonly PhysicalColumn[],
+  dialect: RelationalDialect,
 ): void {
-  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`,
-    );
-  }
+  const refuse = (details: Record<string, string>): never => {
+    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)) 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 (!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;
+    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' });
+    }
   }
 }
 
@@ -232,22 +307,20 @@ export function createTableDdl(
   table: CompiledTable,
   dialect: RelationalDialect,
 ): string {
-  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(', ')})`;
@@ -660,6 +733,48 @@ export function parseLayouts(json: string | null | undefined): StoredLayouts {
   return JSON.parse(json) as StoredLayouts;
 }
 
+/**
+ * Version equality is not layout equality: a marker written by another build
+ * at the same version describes rows the running codec cannot decode. Refuse
+ * when the stored layouts disagree with the configured schema, naming the
+ * first table (and column) that differs.
+ */
+export function assertStoredLayouts(
+  schema: CompiledSchema,
+  storedJson: string | null | undefined,
+): void {
+  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/src/sqlite-storage.ts

@@ -18,6 +18,7 @@ import {
 import { syncError } from './errors';
 import {
   assertPhysicalColumns,
+  assertStoredLayouts,
   commitWindowPageSql,
   deleteRowSql,
   deleteSqliteRowScopesSql,
@@ -244,6 +245,15 @@ class SqliteTransaction implements StorageTransaction {
     return this.#storage.scanRowsByIndex(this.#partition, query);
   }
 
+  async queryAuthoritative(
+    query: AuthoritativeQueryRequest,
+  ): Promise<AuthoritativeQueryResult> {
+    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(): Promise<void> {
     this.#assertOpen();
     // BEGIN IMMEDIATE in the constructor already owns SQLite's writer lock.
@@ -594,57 +604,25 @@ END`);
       );
     }
     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: string | undefined;
-      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<{ name: string }, []>(
-            `PRAGMA table_info("${escapedTableName}")`,
-          )
+          .query<
+            { name: string; type: string; notnull: number; pk: number },
+            []
+          >(`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) {
@@ -945,11 +923,16 @@ END`);
     return row?.max_commit_seq ?? 0;
   }
 
-  async queryAuthoritative(
+  /**
+   * 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,
-    checkpoints?: readonly CheckpointDeclaration[],
-  ): Promise<AuthoritativeQueryResult> {
+  ): AuthoritativeQueryResult {
     if (this.#tables === undefined) {
       throw new Error(
         'ensureSchema(schema) must run before registered queries',
@@ -964,6 +947,24 @@ END`);
       ),
       partition,
     );
+    const rows = this.db
+      .query<Readonly<Record<string, unknown>>, AuthoritativeQueryValue[]>(
+        prepared.sql,
+      )
+      .all(...prepared.params);
+    const cursor = this.db
+      .query<{ max_commit_seq: number }, [string]>(
+        'SELECT max_commit_seq FROM sync_partitions WHERE partition=?',
+      )
+      .get(partition);
+    return { rows, maxCommitSeq: cursor?.max_commit_seq ?? 0 };
+  }
+
+  async queryAuthoritative(
+    partition: string,
+    query: AuthoritativeQueryRequest,
+    checkpoints?: readonly CheckpointDeclaration[],
+  ): Promise<AuthoritativeQueryResult> {
     const previous = this.#transactionTail;
     let release!: () => void;
     this.#transactionTail = new Promise<void>((resolve) => {
@@ -981,19 +982,10 @@ END`);
       const gate = await this.readServeGate(partition, runningVersion);
       const refusal = serveGateRefusal(gate, runningVersion, checkpoints);
       if (refusal !== undefined) throw serveNotReadyError(refusal);
-      const rows = this.db
-        .query<Readonly<Record<string, unknown>>, AuthoritativeQueryValue[]>(
-          prepared.sql,
-        )
-        .all(...prepared.params);
-      const cursor = this.db
-        .query<{ max_commit_seq: number }, [string]>(
-          '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) this.db.exec('ROLLBACK');
       throw error;

package/src/storage-errors.ts

@@ -30,7 +30,11 @@ export type StorageQueryErrorCode =
   | 'sync.storage.checkpoint_not_declared'
   | 'sync.storage.checkpoint_unsupported'
   | 'sync.storage.checkpoint_fence_missing'
-  | 'sync.storage.checkpoint_incomplete';
+  | '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';
 
 const STORAGE_QUERY_MESSAGES: Readonly<Record<StorageQueryErrorCode, string>> =
   {
@@ -56,6 +60,14 @@ const STORAGE_QUERY_MESSAGES: Readonly<Record<StorageQueryErrorCode, string>> =
       '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':
@@ -70,15 +82,21 @@ const STORAGE_QUERY_MESSAGES: Readonly<Record<StorageQueryErrorCode, string>> =
 
 /**
  * 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 {
   override readonly name = 'StorageQueryError';
   readonly code: StorageQueryErrorCode;
+  readonly details: Readonly<Record<string, string>> | undefined;
 
-  constructor(code: StorageQueryErrorCode) {
+  constructor(
+    code: StorageQueryErrorCode,
+    details?: Readonly<Record<string, string>>,
+  ) {
     super(STORAGE_QUERY_MESSAGES[code]);
     this.code = code;
+    this.details = details;
   }
 }
 

package/src/storage-query.ts

@@ -1,6 +1,12 @@
 import type { ScopeMap } from '@syncular/core';
 import type { CompiledTable, IndexSchema } from './schema';
-import type { IndexRowScanQuery, RowScanQuery } from './storage';
+import type {
+  AuthoritativeQueryRequest,
+  AuthoritativeQueryResult,
+  IndexRowScanQuery,
+  RowScanQuery,
+  StorageTransaction,
+} from './storage';
 import { StorageQueryError } from './storage-errors';
 
 /**
@@ -51,3 +57,19 @@ export function resolveIndexRowScan(
   }
   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: StorageTransaction,
+  query: AuthoritativeQueryRequest,
+): Promise<AuthoritativeQueryResult> {
+  if (tx.queryAuthoritative === undefined) {
+    throw new StorageQueryError('sync.storage.transaction_query_unsupported');
+  }
+  return tx.queryAuthoritative(query);
+}

package/src/storage.ts

@@ -473,6 +473,21 @@ 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
@@ -790,17 +805,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,

package/src/validate.ts

@@ -20,6 +20,10 @@ import {
   type RowValue,
   type ScopeMap,
 } from '@syncular/core';
+import type {
+  AuthoritativeQueryRequest,
+  AuthoritativeQueryResult,
+} from './storage';
 
 /**
  * §6.7 reserved code prefixes. A host validator code MUST NOT start with
@@ -104,6 +108,17 @@ export interface CommitValidationReader {
     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 {
@@ -126,21 +141,31 @@ export type CommitValidator = (
 /**
  * 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>;
 }
 
 /**
@@ -152,12 +177,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,