@syncular/server 0.21.1 → 0.22.0

package/README.md

@@ -660,14 +660,28 @@ which all three providers accept.
 **Key layout.** Deterministic, so every lookup is a GET/HEAD — never a
 LIST:
 
-- `{keyPrefix}seg/sha256/{hex}` — the segment bytes, verbatim (the
-  object body is exactly the content-addressed bytes, so presigned GETs
-  serve them directly and the client's §5.1 hash check passes). The
-  record metadata rides in object user metadata
-  (`x-amz-meta-syncular-record`, base64url JSON), so `get` is one GET.
+- `{keyPrefix}seg/sha256/{hex}` — the segment bytes, verbatim and
+  immutable (the object body is exactly the content-addressed bytes, so
+  presigned GETs serve them directly and the client's §5.1 hash check
+  passes).
+- `{keyPrefix}rec/sha256/{hex}.json` — the mutable `SegmentRecord`. It
+  carries the `publications` array: one entry per (partition, log epoch,
+  table, schema version, media type, scope digest, pin, cursors) context
+  the content was published under, each with its own TTL. `get` is two
+  GETs (record + bytes). A record written by 0.21 read the metadata from
+  the bytes object's user metadata; `get` still reads that shape and
+  materializes one publication per recorded digest.
 - `{keyPrefix}find/{sha256(reuse key)}.json` — the §5.3 whole-table
   reuse pointer, written only for `rowCursor: null` segments; `find` is
-  one GET plus a HEAD to confirm the segment object still exists.
+  one GET plus a HEAD to confirm the segment object still exists, and it
+  selects the publication the key names.
+
+A host that implements `SegmentStore` itself must return `publications`
+and `scopeDigests` on every `SegmentRecord` (`scopeDigests` is the
+compatibility view over `publications`). Download and `find` select a
+publication matching the caller's partition, live log epoch, and digest;
+they never union digests across contexts. The shared contract suite is
+`test/segment-store-contract.ts`.
 
 **TTL and lifecycle.** Expiry is store-side and authoritative:
 `expiresAtMs` (`put` time + `ttlMs`, default 24 h) is recorded with the

package/dist/pg-executor.d.ts

@@ -39,6 +39,14 @@ export type PgRow = Record<string, unknown>;
  * `params` use Postgres positional placeholders (`$1`, `$2`, ...). `text`
  * is a single statement (no multi-statement `;`-joined batches — those are
  * driver-specific and defeat parameterization).
+ *
+ * Syncular never overlaps statements on one `PgQueryable`. A client pinned
+ * to a connection by `PgExecutor.transaction` gets every statement chained
+ * on one FIFO by `PostgresServerStorage`, so a host validator that starts
+ * independent reads concurrently still reaches the driver one statement at
+ * a time. An adapter does not need to queue calls itself, and must not
+ * accept two in flight: node-postgres warns about that today and rejects it
+ * in node-postgres 9.
  */
 export interface PgQueryable {
     query<Row = PgRow>(text: string, params?: readonly unknown[]): Promise<{
@@ -55,7 +63,9 @@ export interface PgExecutor extends PgQueryable {
     /**
      * Run `fn` inside a single Postgres transaction on one pinned connection.
      * The executor issues `BEGIN` before `fn`, `COMMIT` on resolve, and
-     * `ROLLBACK` on throw (rethrowing the original error).
+     * `ROLLBACK` on throw (rethrowing the original error). The caller
+     * serializes the statements `fn` issues on the provided client (see
+     * `PgQueryable`), so the driver never sees two of them in flight.
      */
     transaction<T>(fn: (client: PgQueryable) => Promise<T>): Promise<T>;
     /** Release any pooled resources. Optional (pglite/Bun.sql). */

package/dist/postgres-storage.d.ts

@@ -12,7 +12,14 @@ import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorI
  *   - `sync_row_scopes_pk (partition, tbl, var, value, row_id)` — same shape
  *     for `scanRows`, ordered by `row_id`.
  * Both are the PRIMARY KEY, so they are the clustering/covering index for
- * their table. No secondary index is needed for the hot path.
+ * their table.
+ *
+ * `sync_row_scopes_by_row (partition, tbl, row_id)` is the one secondary
+ * scope index: `writeRowOn` and `deleteRow` replace a row's scope entries
+ * with a `(partition, tbl, row_id)` predicate, and `row_id` is the LAST
+ * column of the inverted PRIMARY KEY, so without this index that predicate
+ * scans the table's whole scope range on every row written (a bulk import
+ * costs one such scan per row).
  *
  * Blob reference index (§5.9.4) — parity with the SQLite dialect's
  * `sync_blob_refs`:
@@ -24,7 +31,7 @@ import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, ClientCursorI
  *     set, §5.9.5) as an index range, never a scan. `postgres-explain
  *     .test.ts` asserts an `Index` node here too.
  */
-export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n  partition TEXT PRIMARY KEY,\n  log_epoch TEXT NOT NULL,\n  epoch_required BOOLEAN NOT NULL DEFAULT FALSE,\n  last_authenticated_at_ms BIGINT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result JSONB NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload JSONB NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,\n  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,\n  last_failure JSONB,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  wire_version INTEGER NOT NULL DEFAULT 1,\n  cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nALTER TABLE sync_clients\n  ADD COLUMN IF NOT EXISTS wire_version INTEGER NOT NULL DEFAULT 1;\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  commit_seq BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id)\n);\n";
+export declare const POSTGRES_DDL = "\nCREATE TABLE IF NOT EXISTS sync_partitions(\n  partition TEXT PRIMARY KEY,\n  max_commit_seq BIGINT NOT NULL DEFAULT 0,\n  horizon_seq BIGINT NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS sync_partition_registry(\n  partition TEXT PRIMARY KEY,\n  log_epoch TEXT NOT NULL,\n  epoch_required BOOLEAN NOT NULL DEFAULT FALSE,\n  last_authenticated_at_ms BIGINT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS sync_row_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, row_id)\n);\nCREATE INDEX IF NOT EXISTS sync_row_scopes_by_row\n  ON sync_row_scopes(partition, tbl, row_id);\nCREATE TABLE IF NOT EXISTS sync_commits(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,\n  actor_id TEXT NOT NULL, created_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, commit_seq)\n);\nCREATE INDEX IF NOT EXISTS sync_commits_by_time\n  ON sync_commits(partition, created_at_ms);\nCREATE TABLE IF NOT EXISTS sync_changes(\n  partition TEXT NOT NULL, commit_seq BIGINT NOT NULL, idx INTEGER NOT NULL,\n  tbl TEXT NOT NULL, row_id TEXT NOT NULL, op SMALLINT NOT NULL,\n  row_version BIGINT, scopes JSONB NOT NULL, payload BYTEA,\n  PRIMARY KEY(partition, commit_seq, idx)\n);\nCREATE INDEX IF NOT EXISTS sync_changes_by_table\n  ON sync_changes(partition, commit_seq, tbl, idx);\nCREATE TABLE IF NOT EXISTS sync_change_scopes(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL,\n  var TEXT NOT NULL, value TEXT NOT NULL, commit_seq BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, var, value, commit_seq)\n);\nCREATE TABLE IF NOT EXISTS sync_push_results(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL,\n  client_commit_id TEXT NOT NULL, result JSONB NOT NULL,\n  PRIMARY KEY(partition, client_id, client_commit_id)\n);\nCREATE TABLE IF NOT EXISTS sync_reactions(\n  partition TEXT NOT NULL, idempotency_key TEXT NOT NULL,\n  type TEXT NOT NULL, version INTEGER NOT NULL, payload JSONB NOT NULL,\n  source_client_id TEXT NOT NULL, source_client_commit_id TEXT NOT NULL,\n  source_commit_seq BIGINT NOT NULL, created_at_ms BIGINT NOT NULL,\n  available_at_ms BIGINT NOT NULL, status TEXT NOT NULL,\n  attempts INTEGER NOT NULL, max_attempts INTEGER NOT NULL,\n  lease_owner TEXT, lease_expires_at_ms BIGINT, completed_at_ms BIGINT,\n  last_failure JSONB,\n  PRIMARY KEY(partition, idempotency_key),\n  CHECK(status IN ('pending', 'leased', 'completed', 'dead-letter'))\n);\nCREATE INDEX IF NOT EXISTS sync_reactions_due\n  ON sync_reactions(partition, status, available_at_ms, created_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_lease\n  ON sync_reactions(partition, status, lease_expires_at_ms);\nCREATE INDEX IF NOT EXISTS sync_reactions_completed\n  ON sync_reactions(partition, status, completed_at_ms, idempotency_key);\nCREATE INDEX IF NOT EXISTS sync_reactions_dead_letter\n  ON sync_reactions(partition, status, available_at_ms, idempotency_key);\nCREATE TABLE IF NOT EXISTS sync_clients(\n  partition TEXT NOT NULL, client_id TEXT NOT NULL, actor_id TEXT NOT NULL,\n  wire_version INTEGER NOT NULL DEFAULT 1,\n  cursor BIGINT NOT NULL, subscriptions JSONB NOT NULL,\n  updated_at_ms BIGINT NOT NULL,\n  PRIMARY KEY(partition, client_id)\n);\nALTER TABLE sync_clients\n  ADD COLUMN IF NOT EXISTS wire_version INTEGER NOT NULL DEFAULT 1;\nCREATE TABLE IF NOT EXISTS sync_blob_refs(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  blob_id TEXT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id, blob_id)\n);\nCREATE INDEX IF NOT EXISTS sync_blob_refs_by_blob\n  ON sync_blob_refs(partition, blob_id);\nCREATE TABLE IF NOT EXISTS sync_tombstones(\n  partition TEXT NOT NULL, tbl TEXT NOT NULL, row_id TEXT NOT NULL,\n  commit_seq BIGINT NOT NULL,\n  PRIMARY KEY(partition, tbl, row_id)\n);\n";
 export declare class PostgresServerStorage implements ServerStorage {
     #private;
     constructor(exec: PgExecutor);

package/dist/postgres-storage.js

@@ -3,7 +3,7 @@ import { StorageQueryError } from './storage-errors.js';
 import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
-import { 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, 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';
@@ -17,7 +17,14 @@ import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js'
  *   - `sync_row_scopes_pk (partition, tbl, var, value, row_id)` — same shape
  *     for `scanRows`, ordered by `row_id`.
  * Both are the PRIMARY KEY, so they are the clustering/covering index for
- * their table. No secondary index is needed for the hot path.
+ * their table.
+ *
+ * `sync_row_scopes_by_row (partition, tbl, row_id)` is the one secondary
+ * scope index: `writeRowOn` and `deleteRow` replace a row's scope entries
+ * with a `(partition, tbl, row_id)` predicate, and `row_id` is the LAST
+ * column of the inverted PRIMARY KEY, so without this index that predicate
+ * scans the table's whole scope range on every row written (a bulk import
+ * costs one such scan per row).
  *
  * Blob reference index (§5.9.4) — parity with the SQLite dialect's
  * `sync_blob_refs`:
@@ -46,6 +53,8 @@ CREATE TABLE IF NOT EXISTS sync_row_scopes(
   var TEXT NOT NULL, value TEXT NOT NULL, row_id TEXT NOT NULL,
   PRIMARY KEY(partition, tbl, var, value, row_id)
 );
+CREATE INDEX IF NOT EXISTS sync_row_scopes_by_row
+  ON sync_row_scopes(partition, tbl, row_id);
 CREATE TABLE IF NOT EXISTS sync_commits(
   partition TEXT NOT NULL, commit_seq BIGINT NOT NULL,
   client_id TEXT NOT NULL, client_commit_id TEXT NOT NULL,
@@ -339,7 +348,20 @@ class PostgresTransaction {
     #resolve;
     #reject;
     constructor(client, partition, resolveTable, resolve, reject) {
-        this.#client = client;
+        // 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
+        // out with Promise.all must not interleave them, so every statement
+        // issued through this transaction is chained on one FIFO — the same
+        // shape as `SqliteServerStorage.queryAuthoritative`.
+        let tail = Promise.resolve();
+        this.#client = {
+            query: (text, params) => {
+                const run = tail.then(() => client.query(text, params));
+                tail = run.then(() => undefined, () => undefined);
+                return run;
+            },
+        };
         this.#partition = partition;
         this.#resolveTable = resolveTable;
         this.#resolve = resolve;
@@ -615,6 +637,60 @@ export class PostgresServerStorage {
         if (stored !== undefined && stored > schema.version) {
             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'
+                ? 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 —
+            // `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
+           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)));
+            }
+        }
         if (stored === undefined || stored < schema.version) {
             // Introspect existing app tables, apply the migration subset
             // (CREATE TABLE / ADD COLUMN / rebuild indexes), then rewrite stored

package/dist/pull.js

@@ -108,7 +108,7 @@ async function signedUrlFields(ctx, limits, segmentId, digest, now) {
         nowMs: now,
     });
 }
-function segmentRefFrame(record, extra) {
+function segmentRefFrame(record, scopeDigest, extra) {
     return {
         type: 'SEGMENT_REF',
         segmentId: record.segmentId,
@@ -117,7 +117,11 @@ function segmentRefFrame(record, extra) {
         byteLength: record.byteLength,
         rowCount: record.rowCount,
         asOfCommitSeq: record.asOfCommitSeq,
-        scopeDigest: record.scopeDigest,
+        // The frame reports the digest THIS subscription is authorized under. A
+        // stored entry can carry several digests when identical content was
+        // published under different scopes (§5.1), and the record's primary
+        // digest is not necessarily the caller's (§5.5).
+        scopeDigest,
         ...(record.rowCursor !== null ? { rowCursor: record.rowCursor } : {}),
         ...(record.nextRowCursor !== null
             ? { nextRowCursor: record.nextRowCursor }
@@ -156,7 +160,7 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
             bytes: existing.byteLength,
             rows: existing.rowCount,
         });
-        yield segmentRefFrame(existing, await signedUrlFields(ctx, limits, existing.segmentId, digest, now));
+        yield segmentRefFrame(existing, digest, await signedUrlFields(ctx, limits, existing.segmentId, digest, now));
         return true;
     }
     // Eligibility probe (§5.3): image only when the snapshot exceeds one
@@ -253,7 +257,7 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
         bytes: record.byteLength,
         rows: record.rowCount,
     });
-    yield segmentRefFrame(record, await signedUrlFields(ctx, limits, record.segmentId, digest, clockOf(ctx)()));
+    yield segmentRefFrame(record, digest, await signedUrlFields(ctx, limits, record.segmentId, digest, clockOf(ctx)()));
     return true;
 }
 async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace, logEpoch) {
@@ -331,7 +335,7 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
                 bytes: record.byteLength,
                 rows: record.rowCount,
             });
-            yield segmentRefFrame(record, await signedUrlFields(ctx, limits, record.segmentId, digest, now));
+            yield segmentRefFrame(record, digest, await signedUrlFields(ctx, limits, record.segmentId, digest, now));
         }
         if (!hasMore)
             return { complete: true, rowCursor: null };

package/dist/realtime.d.ts

@@ -3,7 +3,10 @@
  *
  * A `RealtimeSession` wraps a connected socket's send/receive callbacks:
  * the host feeds inbound text frames to `handleMessage`, binary frames to
- * `handleBinary`, and wires `session.close()` to socket close. Initial
+ * `handleBinary`, and wires `session.close()` to socket close. `handleMessage`
+ * queues the ack's cursor write without awaiting it, so `drain()` is the
+ * awaitable boundary a host uses before closing its storage or ending a
+ * hibernatable event (§8.2). Initial
  * subscription registration comes from the client's most recent pull
  * (§8.1, loaded from the client record); a sync round completed on the
  * connection replaces it at round end (§8.7). Deltas are complete SSP2
@@ -112,6 +115,13 @@ export declare class RealtimeSession {
     /** Feed an inbound text frame (client → server control message, §8.2
      * ack, §8.6.2 presence). */
     handleMessage(text: string): void;
+    /**
+     * Resolve once every queued control-plane write has settled (§8.2). A host
+     * awaits this before it closes its storage or ends a hibernatable event, so
+     * an ack's cursor write is not abandoned mid-flight. A persistence failure
+     * surfaces here instead of vanishing.
+     */
+    drain(): Promise<void>;
     /** Deliver a fanout event to this session (called by the hub for peers,
      * §8.6.3 receive authorization checked by the caller). */
     receivePresence(scopeKey: string, kind: PresenceKind, actorId: string, clientId: string, doc: PresenceDoc | null): void;
@@ -135,6 +145,21 @@ export declare class RealtimeSession {
      * coordinated hosts await it to retain their partition FIFO through commit.
      */
     handleBinary(bytes: Uint8Array): Promise<void> | undefined;
+    /**
+     * Reload this connection's registrations and reconcile presence (§8.7).
+     * The round-end refresh and the host-initiated `RealtimeHub.refreshScopes`
+     * both route through here under one per-session generation, so a load that
+     * resolves late can never overwrite a newer result: a slow resolver may
+     * return scopes a later refresh already revoked, and the later refresh
+     * keeps the connection's current grants.
+     *
+     * `failClosed` selects the failure semantics. The round-end refresh keeps
+     * the previous registrations so a failed round changes nothing. The host
+     * refresh empties them so a revoked or unreadable grant stops receiving
+     * deltas immediately; it also survives a newer round-end refresh that
+     * failed, because that round applied nothing.
+     */
+    refreshRegistrations(failClosed: boolean): Promise<void>;
     sendHeartbeat(): void;
     sendWake(reason: WakeReason): void;
     /** Called by the hub for every applied commit notification. */
@@ -182,6 +207,20 @@ export declare class RealtimeHub {
     disconnect(session: RealtimeSession): void;
     /** RealtimeNotifier: fan an applied commit out to matching sessions. */
     notifyCommit(partition: string, commit: StoredCommit): Promise<void>;
+    /**
+     * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
+     * after it changes an actor's membership or connection state, so the
+     * partition's connected sessions stop using grants the host already revoked
+     * without waiting for the client to happen to run a round.
+     *
+     * This differs deliberately from the round-end refresh
+     * (`RealtimeSession.refreshRegistrations`), which keeps the previous
+     * registrations when the client record or resolver cannot be read so a
+     * failed round changes nothing. Here an unresolvable session is emptied:
+     * a revoked or unreadable grant must stop receiving deltas rather than live
+     * on until the next round. Presence is reconciled exactly as at round end.
+     */
+    refreshScopes(partition: string, actorId?: string): Promise<void>;
     /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
     wake(partition: string, reason: WakeReason): void;
 }

package/dist/realtime.js

@@ -3,7 +3,10 @@
  *
  * A `RealtimeSession` wraps a connected socket's send/receive callbacks:
  * the host feeds inbound text frames to `handleMessage`, binary frames to
- * `handleBinary`, and wires `session.close()` to socket close. Initial
+ * `handleBinary`, and wires `session.close()` to socket close. `handleMessage`
+ * queues the ack's cursor write without awaiting it, so `drain()` is the
+ * awaitable boundary a host uses before closing its storage or ending a
+ * hibernatable event (§8.2). Initial
  * subscription registration comes from the client's most recent pull
  * (§8.1, loaded from the client record); a sync round completed on the
  * connection replaces it at round end (§8.7). Deltas are complete SSP2
@@ -147,6 +150,14 @@ export class RealtimeSession {
     /** §8.6.4 rate cap: per-scope-key last-fanout time + a pending latest
      * document coalesced while over the cap. */
     #presenceRate = new Map();
+    /** Queued control-plane writes (ack cursor persistence, §8.2). */
+    #controlTail = Promise.resolve();
+    /** First control-plane failure not yet surfaced by `drain()`. */
+    #controlFailure = undefined;
+    /** Issue counter for registration refreshes (§8.7). */
+    #registrationGeneration = 0;
+    /** Generation of the most recent refresh whose result was applied. */
+    #registrationApplied = 0;
     constructor(hub, options, registrations, cursor, latestSeq, clock, maxDeltaBytes, storage, logEpoch, wireVersion, events) {
         this.sessionId = crypto.randomUUID();
         this.partition = options.partition;
@@ -198,7 +209,21 @@ export class RealtimeSession {
         if (this.cursor >= this.lastKnownSeq)
             this.wakePending = false;
         // §8.2: acks update the client cursor record without an HTTP pull.
-        void this.#persistCursor();
+        this.#persistCursor();
+    }
+    /**
+     * Resolve once every queued control-plane write has settled (§8.2). A host
+     * awaits this before it closes its storage or ends a hibernatable event, so
+     * an ack's cursor write is not abandoned mid-flight. A persistence failure
+     * surfaces here instead of vanishing.
+     */
+    drain() {
+        return this.#controlTail.then(() => {
+            const failure = this.#controlFailure;
+            this.#controlFailure = undefined;
+            if (failure !== undefined)
+                throw failure;
+        });
     }
     /** §8.6.2 inbound presence publish/leave from the client. */
     #handlePresence(text) {
@@ -439,7 +464,7 @@ export class RealtimeSession {
             finishRound();
             // §8.7 registration at round end: reload the persisted list — it
             // only advances on success, so failed rounds change nothing.
-            await this.#refreshRegistrations();
+            await this.refreshRegistrations(false);
         }
     }
     async #sendRoundChunk(chunk) {
@@ -448,19 +473,41 @@ export class RealtimeSession {
         tagged.set(chunk, 1);
         await this.#send(tagged);
     }
-    async #refreshRegistrations() {
-        // §8.6.3: a registration change re-derives the presence grant — capture
-        // the keys before, reconcile after (leaves on lost keys, snapshots on
-        // gained keys).
-        const previousKeys = this.#currentScopeKeys();
+    /**
+     * Reload this connection's registrations and reconcile presence (§8.7).
+     * The round-end refresh and the host-initiated `RealtimeHub.refreshScopes`
+     * both route through here under one per-session generation, so a load that
+     * resolves late can never overwrite a newer result: a slow resolver may
+     * return scopes a later refresh already revoked, and the later refresh
+     * keeps the connection's current grants.
+     *
+     * `failClosed` selects the failure semantics. The round-end refresh keeps
+     * the previous registrations so a failed round changes nothing. The host
+     * refresh empties them so a revoked or unreadable grant stops receiving
+     * deltas immediately; it also survives a newer round-end refresh that
+     * failed, because that round applied nothing.
+     */
+    async refreshRegistrations(failClosed) {
+        const generation = ++this.#registrationGeneration;
+        let registrations;
         try {
-            this.registrations = await this.#hub.loadRegistrations(this.partition, this.actorId, this.clientId);
+            registrations = await this.#hub.loadRegistrations(this.partition, this.actorId, this.clientId);
         }
         catch {
-            // Fail closed: an unreadable record or resolver failure leaves the
-            // previous registrations in place; the next round repairs it.
-            return;
+            if (!failClosed)
+                return;
+            // Fail closed (host refresh): drop every grant on the connection.
+            registrations = [];
         }
+        // A newer refresh already applied its result; this late one is stale.
+        if (generation < this.#registrationApplied)
+            return;
+        this.#registrationApplied = generation;
+        // §8.6.3: a registration change re-derives the presence grant — capture
+        // the keys before, reconcile after (leaves on lost keys, snapshots on
+        // gained keys).
+        const previousKeys = this.#currentScopeKeys();
+        this.registrations = registrations;
         this.reconcilePresence(previousKeys);
     }
     /** §8.7 protocol violation: drop the connection, fail loud. The
@@ -470,13 +517,19 @@ export class RealtimeSession {
         this.#closeSocket?.();
         this.#hub.disconnect(this);
     }
-    async #persistCursor() {
-        try {
+    #persistCursor() {
+        // §8.2: start the write now and keep it on the control tail so `drain()`
+        // can await it. Two acks may write concurrently: storage folds them with
+        // `MAX(cursor, ?)`, so neither order loses the later cursor.
+        const write = (async () => {
             await this.#storage.advanceClientCursor(this.partition, this.clientId, this.actorId, this.logEpoch, this.cursor, this.#clock());
-        }
-        catch {
-            // Cursor persistence is best-effort; the next pull repairs it.
-        }
+        })();
+        write.catch((error) => {
+            // Best-effort for the connection (the next pull repairs the cursor);
+            // `drain()` carries the first failure to the host.
+            this.#controlFailure ??= error;
+        });
+        this.#controlTail = Promise.allSettled([this.#controlTail, write]).then(() => undefined);
     }
     /** Fire-and-forget send for control text and deltas; a host send
      * failure surfaces on the socket, not here. */
@@ -872,6 +925,31 @@ export class RealtimeHub {
             session.deliverCommit(commit);
         }
     }
+    /**
+     * Host-initiated, fail-closed registration refresh (§8.7). A host calls this
+     * after it changes an actor's membership or connection state, so the
+     * partition's connected sessions stop using grants the host already revoked
+     * without waiting for the client to happen to run a round.
+     *
+     * This differs deliberately from the round-end refresh
+     * (`RealtimeSession.refreshRegistrations`), which keeps the previous
+     * registrations when the client record or resolver cannot be read so a
+     * failed round changes nothing. Here an unresolvable session is emptied:
+     * a revoked or unreadable grant must stop receiving deltas rather than live
+     * on until the next round. Presence is reconciled exactly as at round end.
+     */
+    async refreshScopes(partition, actorId) {
+        for (const session of [...this.#sessions]) {
+            if (session.partition !== partition)
+                continue;
+            if (actorId !== undefined && session.actorId !== actorId)
+                continue;
+            // Fail closed (see the doc above): an unreadable client record drops
+            // every grant on the connection. The session's generation guard keeps
+            // this revocation from being overwritten by a slower round-end reload.
+            await session.refreshRegistrations(true);
+        }
+    }
     /** Broadcast a wake-up (host-initiated resync, schema rollover, §8.3). */
     wake(partition, reason) {
         for (const session of this.#sessions) {

package/dist/relational-rows.d.ts

@@ -75,6 +75,26 @@ export declare function columnSqlType(column: RowColumn, dialect: RelationalDial
  * materialized), version, scopes, payload.
  */
 export declare 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
+ * 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.
+ *
+ * `existingColumns` 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.
+ */
+export declare function assertPhysicalColumns(table: CompiledTable, existingColumns: ReadonlySet<string>): void;
 /** CREATE TABLE IF NOT EXISTS for one app table. */
 export declare function createTableDdl(table: CompiledTable, dialect: RelationalDialect): string;
 /**

package/dist/relational-rows.js

@@ -169,6 +169,35 @@ export function tableColumnNames(table) {
         SYNC_COLUMN_VERSIONS_COLUMN,
     ];
 }
+/**
+ * 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
+ * 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.
+ *
+ * `existingColumns` 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.
+ */
+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`);
+    }
+    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`);
+    }
+}
 /** CREATE TABLE IF NOT EXISTS for one app table. */
 export function createTableDdl(table, dialect) {
     const versionType = dialect === 'postgres' ? 'BIGINT' : 'INTEGER';

package/dist/s3-segment-store.d.ts

@@ -6,12 +6,19 @@
  * Key layout (deterministic — every lookup is a GET/HEAD, never a LIST):
  *
  *   {keyPrefix}seg/sha256/{hex}
- *     The segment bytes, verbatim (the object body MUST be exactly the
- *     content-addressed bytes so presigned GETs serve them directly and
- *     the client's §5.1 hash check passes). The full `SegmentRecord`
- *     (minus bytes) rides along as object user metadata
- *     `x-amz-meta-syncular-record` = base64url(JSON), so `get` is a
- *     single GET.
+ *     The segment bytes, verbatim and immutable (the object body MUST be
+ *     exactly the content-addressed bytes so presigned GETs serve them
+ *     directly and the client's §5.1 hash check passes).
+ *
+ *   {keyPrefix}rec/sha256/{hex}.json
+ *     The `SegmentRecord` (§5.1). It is the one MUTABLE object of the two:
+ *     the scope-digest set is a union that every publication extends, so
+ *     the merge is a read-modify-write. Keeping the record in the body (not
+ *     in the bytes object's user metadata) is what makes that write
+ *     conditional — a body ETag changes when the union changes, while the
+ *     bytes ETag is a content hash and is identical for identical bytes. A
+ *     `412` re-reads and merges again, so no concurrent publication can drop
+ *     another one's digest. `get` therefore reads two objects.
  *
  *   {keyPrefix}find/{sha256Hex(canonical reuse key)}.json
  *     Whole-table reuse pointer (§5.3): written only when
@@ -21,9 +28,14 @@
  *     confirm the segment object itself still exists — lifecycle GC may
  *     remove objects independently of pointers).
  *
+ * Records written before the split kept the record in the bytes object's
+ * user metadata `x-amz-meta-syncular-record`; `get` still reads that shape
+ * and the next `put` materializes the record object from it, so an upgrade
+ * loses no cache entry.
+ *
  * TTL mapping: expiry is **store-side and authoritative** — `expiresAtMs`
- * (put-time + `ttlMs`, default 24 h) is recorded in the object metadata
- * and the pointer; `get` returns expired records so §5.5 can answer
+ * (put-time + `ttlMs`, default 24 h) is recorded in the record and the
+ * pointer; `get` returns expired records so §5.5 can answer
  * `sync.segment_expired`, and `find` filters them out itself. S3 lifecycle
  * expiration is garbage collection only: configure it comfortably ABOVE
  * `ttlMs` (e.g. 2 days for the 24 h default) so clients normally see the