@syncular/server 0.23.0 → 0.24.0

package/README.md

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

package/dist/d1-storage.js

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

package/dist/operations.d.ts

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

package/dist/operations.js

@@ -5,6 +5,7 @@ import { SyncError, syncError } from './errors.js';
 import { processPushOperationsWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
 import { authorizeWrite } from './scopes.js';
+import { transactionQuery } from './storage-query.js';
 import { toValidateRow } from './validate.js';
 function scopeAllowed(allowed, variable, value) {
     const values = allowed[variable];
@@ -293,6 +294,7 @@ function commandContext(ctx, tx, resolved, schema, clientId, operationId, reques
             }
             return toValidateRow(table.columns, decodeRow(table.columns, stored.payload));
         },
+        queryAuthoritative: (query) => transactionQuery(tx, query),
     };
 }
 /** Register custom command code that plans one ordinary Syncular commit. */

package/dist/postgres-storage.js

@@ -5,7 +5,7 @@ import { serveNotReadyError } from './readiness.js';
 import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
-import { assertPhysicalColumns, commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -419,9 +419,22 @@ async function getPushResultOn(q, partition, clientId, clientCommitId) {
         throw syncError('sync.idempotency_cache_miss', 'persisted push result unreadable (§6.3)');
     }
 }
+/** Run one partition-bound registered query and the cursor read on `client`. */
+async function queryAuthoritativeOn(client, partition, prepared) {
+    const result = await client.query(postgresPlaceholders(prepared.sql), prepared.params);
+    const cursor = await client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [partition]);
+    return {
+        rows: result.rows,
+        maxCommitSeq: cursor.rows[0] === undefined
+            ? 0
+            : asNumber(cursor.rows[0].max_commit_seq),
+    };
+}
 class PostgresTransaction {
     #client;
     #partition;
+    /** Storage-owned relation rewrite, bound to this transaction's partition. */
+    #prepareQuery;
     /** Schema version this transaction writes; rides every appended commit row. */
     #writerVersion;
     #resolveTable;
@@ -430,7 +443,7 @@ class PostgresTransaction {
     /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
     #resolve;
     #reject;
-    constructor(client, partition, writerVersion, resolveTable, resolve, reject) {
+    constructor(client, partition, writerVersion, resolveTable, prepareQuery, resolve, reject) {
         // One pinned connection carries one statement at a time: node-postgres
         // warns about a concurrently issued second query today and rejects it in
         // node-postgres 9. A whole-commit validator that fans independent reads
@@ -448,6 +461,7 @@ class PostgresTransaction {
         this.#partition = partition;
         this.#writerVersion = writerVersion;
         this.#resolveTable = resolveTable;
+        this.#prepareQuery = prepareQuery;
         this.#resolve = resolve;
         this.#reject = reject;
     }
@@ -517,6 +531,12 @@ class PostgresTransaction {
         this.#assertOpen();
         return scanRowsByIndexOn(this.#client, this.#resolveTable(query.table), this.#partition, query);
     }
+    queryAuthoritative(query) {
+        this.#assertOpen();
+        // Runs on this transaction's pinned client, so the read observes every
+        // staged row and never waits for a second pool connection.
+        return queryAuthoritativeOn(this.#client, this.#partition, this.#prepareQuery(query));
+    }
     async lockPartitionForPush() {
         this.#assertOpen();
         await lockPartitionOn(this.#client, this.#partition);
@@ -775,57 +795,32 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
             throw new Error(`stored schema version ${stored} is newer than the configured schema (${schema.version}) — refusing to run an older server against a migrated database`);
         }
         if (stored !== undefined && stored === 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(typeof marker.rows[0]?.layouts === 'string'
+            assertStoredLayouts(schema, typeof marker.rows[0]?.layouts === 'string'
                 ? marker.rows[0].layouts
                 : undefined);
-            const configuredLayouts = parseLayouts(layoutsOf(schema));
-            let mismatch;
-            for (const [tableName, columns] of Object.entries(configuredLayouts)) {
-                const storedTable = storedLayouts[tableName];
-                const columnCount = Math.max(columns.length, storedTable?.length ?? 0);
-                for (let index = 0; index < columnCount; index++) {
-                    const expected = columns[index];
-                    const actual = storedTable?.[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. Resolve through `to_regclass`, which follows the
-            // session's `search_path` exactly as the unqualified row queries do —
+            // Resolve through `to_regclass`, which follows the session's
+            // `search_path` exactly as the unqualified row queries do:
             // `current_schema()` names only the first existing schema, so it would
             // reject a table that resolves later in the path.
             for (const table of schema.tables.values()) {
-                const { rows } = await this.#exec.query(`SELECT attribute.attname AS column_name
+                const { rows } = await this.#exec.query(`SELECT attribute.attname AS name,
+                  format_type(attribute.atttypid, attribute.atttypmod) AS type,
+                  attribute.attnotnull AS not_null,
+                  (SELECT key.position::int
+                     FROM pg_index pk,
+                          unnest(pk.indkey::int2[]) WITH ORDINALITY
+                            AS key(attnum, position)
+                    WHERE pk.indrelid = attribute.attrelid AND pk.indisprimary
+                      AND key.attnum = attribute.attnum) AS pk
            FROM pg_attribute attribute
            WHERE attribute.attrelid = to_regclass($1)
              AND attribute.attnum > 0 AND NOT attribute.attisdropped`, [table.name]);
-                assertPhysicalColumns(table, new Set(rows.map((r) => r.column_name)));
+                assertPhysicalColumns(table, rows.map((row) => ({
+                    name: row.name,
+                    type: row.type,
+                    notNull: row.not_null,
+                    primaryKeyPosition: row.pk ?? 0,
+                })), 'postgres');
             }
         }
         if (stored === undefined || stored < schema.version) {
@@ -990,7 +985,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         });
         const done = this.#exec
             .transaction(async (client) => {
-            const tx = new PostgresTransaction(client, partition, this.#schemaVersion ?? 0, (name) => this.table(name), resolveScope, rejectScope);
+            const tx = new PostgresTransaction(client, partition, this.#schemaVersion ?? 0, (name) => this.table(name), (query) => this.#prepareAuthoritativeQuery(partition, query), resolveScope, rejectScope);
             resolveReady(tx);
             // Hold the transaction open until commit()/rollback() settles `scope`.
             await scope;
@@ -1008,11 +1003,14 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
         const { rows } = await this.#exec.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [partition]);
         return rows[0] === undefined ? 0 : asNumber(rows[0].max_commit_seq);
     }
-    async queryAuthoritative(partition, query, checkpoints) {
+    #prepareAuthoritativeQuery(partition, query) {
         if (this.#tables === undefined) {
             throw new Error('ensureSchema(schema) must run before registered queries');
         }
-        const prepared = bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
+        return bindAuthoritativePartition(prepareAuthoritativeQuery(query.plan, query.params, query.tables, this.#tables), partition);
+    }
+    async queryAuthoritative(partition, query, checkpoints) {
+        const prepared = this.#prepareAuthoritativeQuery(partition, query);
         return this.#exec.transaction(async (client) => {
             await client.query('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
             // RFC 0007: evaluate the gate inside this pinned snapshot, so a
@@ -1024,14 +1022,7 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
             const refusal = serveGateRefusal(gate, runningVersion, checkpoints);
             if (refusal !== undefined)
                 throw serveNotReadyError(refusal);
-            const result = await client.query(postgresPlaceholders(prepared.sql), prepared.params);
-            const cursor = await client.query('SELECT max_commit_seq FROM sync_partitions WHERE partition=$1', [partition]);
-            return {
-                rows: result.rows,
-                maxCommitSeq: cursor.rows[0] === undefined
-                    ? 0
-                    : asNumber(cursor.rows[0].max_commit_seq),
-            };
+            return queryAuthoritativeOn(client, partition, prepared);
         });
     }
     async getPartitionLogEpoch(partition) {

package/dist/push.js

@@ -26,6 +26,7 @@ import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes.j
 import { decodeColumnVersions, encodeColumnVersions } from './relational-rows.js';
 import { serveGateRefusal } from './storage.js';
 import { StorageConstraintError } from './storage-errors.js';
+import { transactionQuery } from './storage-query.js';
 import { serveNotReadyError } from './readiness.js';
 import { CommitValidationRejection, toValidateRow, ValidationRejection, } from './validate.js';
 /**
@@ -86,7 +87,7 @@ function conflictColumnsBitmap(columnCount, marked) {
  * A no-op for tables with no validator — the `undefined` short-circuit
  * keeps the feature zero-cost when off.
  */
-async function runValidator(validators, table, op, rowId, values, storedValues, opIndex, partition, actorId) {
+async function runValidator(validators, table, op, rowId, values, storedValues, opIndex, tx, partition, actorId) {
     const validator = validators?.[table.name];
     if (validator === undefined)
         return undefined;
@@ -101,7 +102,11 @@ async function runValidator(validators, table, op, rowId, values, storedValues,
             stored: storedValues !== undefined
                 ? toValidateRow(table.columns, storedValues)
                 : undefined,
-        }, { actorId, partition });
+        }, {
+            actorId,
+            partition,
+            queryAuthoritative: (query) => transactionQuery(tx, query),
+        });
     }
     catch (error) {
         if (error instanceof ValidationRejection) {
@@ -199,7 +204,7 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
         // stored = the row about to be removed). Only reached for an existing
         // row — an absent-row delete is an idempotent no-op above.
         const storedValues = decodeRow(table.columns, stored.payload);
-        const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, partition, actorId);
+        const deleteReject = await runValidator(validators, table, 'delete', op.rowId, undefined, storedValues, opIndex, tx, partition, actorId);
         if (deleteReject !== undefined)
             return deleteReject;
         await tx.deleteRow(op.table, op.rowId);
@@ -330,7 +335,7 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
         // §6.7: validate the merged row that will persist — for a crdt column
         // the validator sees the MERGED value (§5.10.3), the state the store
         // holds, not the raw pushed update.
-        const updateReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, partition, actorId);
+        const updateReject = await runValidator(validators, table, 'upsert', op.rowId, values, storedValues, opIndex, tx, partition, actorId);
         if (updateReject !== undefined)
             return updateReject;
         const columnVersions = encodeColumnVersions(nextVersions);
@@ -412,7 +417,7 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
     // §6.7: validate the insert row (stored = undefined, so a validator can
     // distinguish create from update); crdt columns are already merged
     // against the empty document.
-    const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, partition, actorId);
+    const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, tx, partition, actorId);
     if (insertReject !== undefined)
         return insertReject;
     // §5.2: an explicit insert recreates — the tombstone goes with it.
@@ -526,6 +531,7 @@ function commitValidationReader(tx, schema) {
                 serverVersion: stored.serverVersion,
             }));
         },
+        queryAuthoritative: (query) => transactionQuery(tx, query),
     };
 }
 async function runCommitValidator(validator, tx, schema, clientId, clientCommitId, actorId, partition, operations) {
@@ -682,7 +688,7 @@ async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit
                 const syntheticIndex = clientOpCount + originByIndex.length;
                 const storedValues = decodeRow(child.columns, childRow.payload);
                 if (reference.onDelete === 'CASCADE') {
-                    const reject = await runValidator(validators, child, 'delete', childRow.rowId, undefined, storedValues, item.originOpIndex, partition, actorId);
+                    const reject = await runValidator(validators, child, 'delete', childRow.rowId, undefined, storedValues, item.originOpIndex, tx, partition, actorId);
                     if (reject !== undefined) {
                         return { kind: 'terminate', record: reject.record };
                     }
@@ -706,7 +712,7 @@ async function enforceReferences(tx, schema, staged, clientOpCount, cascadeLimit
                 else {
                     const values = [...storedValues];
                     values[reference.columnIndex] = null;
-                    const reject = await runValidator(validators, child, 'upsert', childRow.rowId, values, storedValues, item.originOpIndex, partition, actorId);
+                    const reject = await runValidator(validators, child, 'upsert', childRow.rowId, values, storedValues, item.originOpIndex, tx, partition, actorId);
                     if (reject !== undefined) {
                         return { kind: 'terminate', record: reject.record };
                     }

package/dist/relational-rows.d.ts

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