@syncular/client 0.30.15 → 0.31.0

package/src/client.ts

@@ -33,6 +33,8 @@ import {
   decodeRow,
   decodeRowsSegment,
   encodeMessage,
+  encodeRow,
+  encodeSparseRow,
   encodePresencePublish,
   MessageStreamScanner,
   PROTOCOL_WIRE_VERSION,
@@ -52,6 +54,7 @@ import {
   type WakeReason,
 } from '@syncular/core';
 import { EncryptError } from '@syncular/core';
+import { EncodeError } from '@syncular/core';
 import {
   applyCommitFrame,
   applyRowsSegment,
@@ -166,8 +169,10 @@ import {
   type CommitOutcome,
   type CommitOutcomeQuery,
   type ConflictRecord,
+  isStoredOperation,
   listCommitOutcomes,
   persistCommitOutcomeResolution,
+  persistedCommitOutcome,
   pruneCommitOutcomes,
   type RejectionRecord,
   type ResolveCommitOutcomeInput,
@@ -210,6 +215,7 @@ import {
   ensureLocalSyncedSchema,
   fromSqlValue,
   coerceSqlRepresentation,
+  localColumnType,
   type JsonRowValue,
   jsonToRowValue,
   LOCAL_SCHEMA_VERSION_KEY,
@@ -234,6 +240,7 @@ import {
   type SubscriptionRecord,
   saveSubscription,
   setMeta,
+  SUBSCRIPTIONS_TABLE,
 } from './state';
 import type {
   RealtimeConnector,
@@ -336,6 +343,15 @@ export interface SyncSummary {
   readonly deferredCommits?: number;
 }
 
+/**
+ * The result of `syncUntilIdle`. The report aggregates every round that ran;
+ * `budgetExhausted` is true when the round budget ran out with the client not
+ * idle. An exhausted run is a partial success, never idle.
+ */
+export interface SyncIdleResult extends SyncSummary {
+  readonly budgetExhausted: boolean;
+}
+
 export interface SyncClientLimits {
   readonly limitCommits?: number;
   readonly limitSnapshotRows?: number;
@@ -352,6 +368,22 @@ export interface SyncClientLimits {
    * deleted to satisfy this cap. Defaults to 1,000.
    */
   readonly outcomeRetentionMaxEntries?: number;
+  /** §7.1: maximum whole commits in one push request. Default: unbounded. */
+  readonly maxPushCommitsPerRequest?: number;
+  /**
+   * §7.1: maximum operations across the push commits in one request. Default
+   * 500. A first commit that alone exceeds it is a typed
+   * `client.push_request_too_large` capacity error and stays queued.
+   */
+  readonly maxPushOperationsPerRequest?: number;
+  /**
+   * §7.1: maximum bytes of the complete encoded SSP2 request (8-byte
+   * envelope, request header, push commits, pull header, subscriptions,
+   * framing, and any §5.11 ciphertext). Default: unbounded. A request whose
+   * fixed frames alone exceed it, or whose first commit alone does not fit,
+   * raises `client.push_request_too_large` and stays queued.
+   */
+  readonly maxPushRequestBytes?: number;
 }
 
 export interface SyncClientConfig {
@@ -540,6 +572,70 @@ export interface QuerySnapshot<Row = SqlRow> {
   readonly coverage: CoverageSnapshot;
 }
 
+/** §7.5: one read-only statement in an atomic snapshot read. */
+export interface SnapshotStatement {
+  readonly sql: string;
+  readonly params?: readonly SqlValue[];
+}
+
+/**
+ * §7.5: the catch-up state of one subscription as persisted in the snapshot,
+ * never the mutable owner cache. `unknown` means the client does not currently
+ * hold the subscription (never registered, forgotten, or removed) and carries
+ * no fabricated table or cursor.
+ */
+export type SubscriptionCatchup =
+  | { readonly state: 'unknown'; readonly id: string }
+  | {
+      readonly state: 'known';
+      readonly id: string;
+      readonly table: string;
+      readonly status: 'active' | 'revoked' | 'failed';
+      readonly cursor: number;
+      readonly hasResumeToken: boolean;
+      /** True only for `active` with `cursor >= 0` and no resume token. */
+      readonly bootstrapComplete: boolean;
+      /** True only for `active` while a resume token remains or `cursor < 0`. */
+      readonly knownPendingPages: boolean;
+      readonly effectiveScopes?: unknown;
+      readonly reasonCode?: string;
+    };
+
+/**
+ * §7.5: delivery status for one client commit id. `pending` while the id still
+ * has an outbox entry (outbox precedence), otherwise the persisted-journal
+ * outcome, otherwise an explicit `unknown` (never held, or pruned by
+ * retention). The outcome omits the owner-derived `retainedRows` images.
+ */
+export type CommitDelivery =
+  | { readonly status: 'pending'; readonly clientCommitId: string }
+  | {
+      readonly status: 'known';
+      readonly clientCommitId: string;
+      readonly outcome: CommitOutcome;
+    }
+  | { readonly status: 'unknown'; readonly clientCommitId: string };
+
+/** §7.5: one atomic read request over a single SQLite read transaction. */
+export interface SnapshotReadRequest {
+  readonly statements: readonly SnapshotStatement[];
+  readonly coverage?: readonly WindowCoverage[];
+  readonly subscriptions?: readonly string[];
+  readonly commitIds?: readonly string[];
+  /** §7.5 owner: a failed owned read is reported in `queryFailures`. */
+  readonly owner?: QueryOwner;
+}
+
+/** §7.5: one atomic read result: one revision, every statement's rows, the
+ * requested coverage, catch-up states, and deliveries. */
+export interface SnapshotRead<Row = SqlRow> {
+  readonly revision: LocalRevision;
+  readonly queries: readonly (readonly Row[])[];
+  readonly coverage: CoverageSnapshot;
+  readonly subscriptions: readonly SubscriptionCatchup[];
+  readonly deliveries: readonly CommitDelivery[];
+}
+
 /**
  * True iff `unit` is windowed-in AND its bootstrap completed (§4.8 I3):
  * registered and not pending. A unit with zero server rows still becomes
@@ -564,6 +660,11 @@ const ACCEPT_SIGNED_URLS = 1 << 3;
  * Never a wire code (§10.3) — surfaced through the rejection channel.
  */
 const OUTBOX_INCOMPATIBLE_CODE = 'sync.outbox_incompatible';
+/** §7.4.4: static text for a persisted commit the current codec refuses. */
+const LEGACY_VALUE_REFUSAL_MESSAGE =
+  'the persisted commit carries values the current codec refuses';
+/** §7.4.4: bounded reason on every intrinsic value drop. */
+const INVALID_STORED_VALUES_REASON = 'invalid_stored_values';
 
 /** §6.1 per-request operation cap (matches the server's shipped default —
  * `sync.too_many_operations` above it). The push half sends whole commits in
@@ -719,6 +820,7 @@ function realtimeErrorCode(error: unknown): string | undefined {
 export type ClientSnapshotMethods = Pick<
   SyncClient,
   | 'querySnapshot'
+  | 'snapshotRead'
   | 'statusSnapshot'
   | 'diagnosticsSnapshot'
   | 'conflicts'
@@ -855,6 +957,26 @@ export class SyncClient {
       throw invalidRequest('transportEnabled must be a boolean');
     }
     this.#transportEnabled = config.transportEnabled !== false;
+    for (const [name, value] of [
+      ['maxPushCommitsPerRequest', config.limits?.maxPushCommitsPerRequest],
+      [
+        'maxPushOperationsPerRequest',
+        config.limits?.maxPushOperationsPerRequest,
+      ],
+      ['maxPushRequestBytes', config.limits?.maxPushRequestBytes],
+    ] as const) {
+      if (
+        value !== undefined &&
+        (!Number.isInteger(value) || value < 1 || value > 0xffffffff)
+      ) {
+        throw new ClientSyncError(
+          'sync.invalid_request',
+          'push limit must be an integer in 1..=4294967295',
+          false,
+          { limit: name },
+        );
+      }
+    }
     if (config.securityPreflight === true && config.encryption !== undefined) {
       throw invalidRequest(
         'securityPreflight and encryption are mutually exclusive; activateSecurity installs keys',
@@ -922,57 +1044,142 @@ export class SyncClient {
     this.#lease = await lock.acquire(
       this.#config.lockName ?? 'syncular-leader',
     );
-    // Bookkeeping must exist before we inspect the persisted schema marker.
-    // Do not materialize new app indexes/FTS projections yet: on a version
-    // bump they may reference columns that only exist after the reset.
-    ensureLocalBookkeepingSchema(this.#db);
-    if (this.#hasBlobs) ensureBlobSchema(this.#db);
-    this.#db.transaction(() => {
-      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
-    });
-    const activeFailures = activeFailureRecords(
-      listCommitOutcomes(this.#db, { activeOnly: true }),
-    );
-    this.#conflicts = activeFailures.conflicts;
-    this.#rejections = activeFailures.rejections;
-    const persisted = getMeta(this.#db, 'clientId');
-    if (
-      persisted !== undefined &&
-      this.#config.clientId !== undefined &&
-      persisted !== this.#config.clientId
-    ) {
+    // §7.4.2: the entire synchronous storage phase below (marker guard,
+    // identity and bookkeeping writes, schema reset/replay, container
+    // reconciliation, subscription pruning) runs as one deferred transaction
+    // whose first statement is the marker read. That read pins SQLite's
+    // snapshot before any write: a replica another process upgraded after the
+    // read can never be written over (its snapshot fails with
+    // BUSY/BUSY_SNAPSHOT), and one upgraded before the read refuses with
+    // `client.schema_downgrade`. The batch emits its change event only after
+    // the commit. The onUpgrading callback still reports reset intent.
+    let subscriptions!: ReturnType<typeof pruneUnknownSubscriptions>;
+    try {
+      this.#applyBatch(() => {
+        // §7.4.1/§7.4.2: this is the transaction's first read, so it pins the
+        // snapshot every write below commits under. `undefined` is an absent
+        // marker (fresh/legacy); a non-canonical value, a `_syncular_meta` that
+        // is not a table, or a duplicated marker row is unreadable state.
+        let marker: number | undefined;
+        try {
+          const meta = this.#db.query(
+            "SELECT type FROM sqlite_master WHERE name = '_syncular_meta'",
+          )[0];
+          if (meta !== undefined) {
+            if (meta.type !== 'table')
+              throw new Error('invalid metadata table');
+            const rows = this.#db.query(
+              'SELECT value FROM _syncular_meta WHERE key = ?',
+              [LOCAL_SCHEMA_VERSION_KEY],
+            );
+            // A duplicated marker cannot be resolved. Picking one row could
+            // select an older version and drive a destructive reset over a
+            // newer replica.
+            if (rows.length > 1) throw new Error('invalid schema marker');
+            const row = rows[0];
+            if (
+              row === undefined &&
+              this.#db.query(
+                "SELECT 1 FROM _syncular_meta WHERE key = 'localSchemaDescriptor' LIMIT 1",
+              ).length > 0
+            ) {
+              throw new Error('missing paired schema marker');
+            }
+            if (row !== undefined) {
+              const value = row.value;
+              const version = Number(value);
+              if (
+                typeof value !== 'string' ||
+                !Number.isInteger(version) ||
+                version < 1 ||
+                version > 2147483647 ||
+                String(version) !== value
+              ) {
+                throw new Error('invalid schema marker');
+              }
+              marker = version;
+            }
+          }
+        } catch (error) {
+          // A recognized SQLite storage failure (including BUSY/LOCKED
+          // contention on the marker read) stays classified; only an invalid
+          // or otherwise unreadable marker is `sync.local_corrupt`.
+          const failure = classifySqliteFailure(error);
+          if (failure.code !== undefined) throw failure.error;
+          throw new ClientSyncError(
+            'sync.local_corrupt',
+            'persisted local schema marker is unreadable or invalid',
+          );
+        }
+        if (marker !== undefined && marker > this.#schema.version) {
+          throw new ClientSyncError(
+            'client.schema_downgrade',
+            'persisted local schema is newer than the requested schema',
+            false,
+            {
+              persistedVersion: marker,
+              requestedVersion: this.#schema.version,
+            },
+          );
+        }
+        // New app indexes may reference columns that only exist after the
+        // reset.
+        ensureLocalBookkeepingSchema(this.#db);
+        if (this.#hasBlobs) ensureBlobSchema(this.#db);
+        pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+        const activeFailures = activeFailureRecords(
+          listCommitOutcomes(this.#db, { activeOnly: true }),
+        );
+        this.#conflicts = activeFailures.conflicts;
+        this.#rejections = activeFailures.rejections;
+        const persisted = getMeta(this.#db, 'clientId');
+        if (
+          persisted !== undefined &&
+          this.#config.clientId !== undefined &&
+          persisted !== this.#config.clientId
+        ) {
+          throw new ClientSyncError(
+            'client.identity_mismatch',
+            `database clientId ${JSON.stringify(persisted)} differs from ${JSON.stringify(this.#config.clientId)}`,
+          );
+        }
+        this.#clientId =
+          persisted ?? this.#config.clientId ?? crypto.randomUUID();
+        if (persisted === undefined) {
+          setMeta(this.#db, 'clientId', this.#clientId);
+        }
+        // §7.3.5: restore the persisted lease so leaseState survives restart.
+        const leaseJson = getMeta(this.#db, 'leaseState');
+        if (leaseJson !== undefined) {
+          this.#leaseState = JSON.parse(leaseJson) as LeaseState;
+        }
+        // §7.4.2 trigger 1: the persisted local schema version is lower than
+        // the generated version this client ships — run the wipe/re-bootstrap
+        // reset before the first sync round. A fresh install (no marker) is
+        // treated as already at the generated version.
+        this.#detectAndResetSchema(marker);
+        if (marker === this.#schema.version) {
+          this.#replayOutbox(undefined, true, false);
+        }
+        // RFC 0005 D9: a container with missing/stale metadata, or past its
+        // TTL, is discarded at boot before anything can read it; the capture
+        // above already ran against this transaction's validated marker. The
+        // orphan/stale sweep is unconditional; the TTL is aware-binary hygiene
+        // only.
+        this.#reconcilePreviousVersionAtBoot();
+        // A registration remains app intent only while its table exists in the
+        // running schema. Removed-table registrations would poison every pull.
+        subscriptions = pruneUnknownSubscriptions(
+          this.#db,
+          loadSubscriptions(this.#db),
+          this.#schema,
+        );
+      });
+    } catch (error) {
       await this.#lease.release();
       this.#lease = undefined;
-      throw new ClientSyncError(
-        'client.identity_mismatch',
-        `database clientId ${JSON.stringify(persisted)} differs from ${JSON.stringify(this.#config.clientId)}`,
-      );
+      throw classifySqliteFailure(error).error;
     }
-    this.#clientId = persisted ?? this.#config.clientId ?? crypto.randomUUID();
-    if (persisted === undefined) {
-      setMeta(this.#db, 'clientId', this.#clientId);
-    }
-    // §7.3.5: restore the persisted lease so leaseState survives restart.
-    const leaseJson = getMeta(this.#db, 'leaseState');
-    if (leaseJson !== undefined) {
-      this.#leaseState = JSON.parse(leaseJson) as LeaseState;
-    }
-    // §7.4.2 trigger 1: the persisted local schema version differs from the
-    // generated version this client ships — run the wipe/re-bootstrap reset
-    // before the first sync round. A fresh install (no marker) is treated as
-    // already at the generated version.
-    this.#detectAndResetSchema();
-    // RFC 0005 D9: a container with missing/stale metadata, or past its TTL, is
-    // discarded at boot before anything can read it. The orphan/stale sweep is
-    // unconditional; the TTL is aware-binary hygiene only.
-    this.#reconcilePreviousVersionAtBoot();
-    // A registration remains app intent only while its table exists in the
-    // running schema. Removed-table registrations would poison every pull.
-    const subscriptions = pruneUnknownSubscriptions(
-      this.#db,
-      loadSubscriptions(this.#db),
-      this.#schema,
-    );
     this.#started = true;
     // A persisted active subscription needs one catch-up round on every open:
     // realtime only covers changes after the socket connects, and an
@@ -1012,12 +1219,14 @@ export class SyncClient {
 
   /**
    * §7.4.1/§7.4.2: compare the generated schema version to the persisted
-   * marker and run the §7.4.3 reset when they differ. Idempotent by the
+   * marker and run the §7.4.3 reset when it increases. Idempotent by the
    * marker — a mid-reset crash re-runs the reset on the next boot.
+   *
+   * The startup phase's single transaction already pinned and validated the
+   * marker, so the shape chosen here commits under that snapshot.
    */
-  #detectAndResetSchema(): void {
-    const markerJson = getMeta(this.#db, LOCAL_SCHEMA_VERSION_KEY);
-    if (markerJson === undefined) {
+  #detectAndResetSchema(marker: number | undefined): void {
+    if (marker === undefined) {
       // Fresh install: the tables just created match the running code.
       this.#db.transaction(() => {
         ensureLocalSyncedSchema(this.#db, this.#schema);
@@ -1031,7 +1240,6 @@ export class SyncClient {
       });
       return;
     }
-    const marker = Number(markerJson);
     if (marker === this.#schema.version) {
       // Same-version opens remain self-healing for absent tables/indexes, and
       // RFC 0005 D1 backfills the descriptor for a database first opened by
@@ -1088,6 +1296,7 @@ export class SyncClient {
         this.#discardAcknowledgedRows();
         dropAndRecreateSyncedTables(this.#db, this.#schema);
         resetSubscriptionsForBump(this.#db);
+        this.#replayOutbox();
         setMeta(
           this.#db,
           LOCAL_SCHEMA_VERSION_KEY,
@@ -1099,11 +1308,10 @@ export class SyncClient {
       // Whole-DB reset: every synced table's rows changed (I1 eviction-shaped).
       for (const table of this.#schema.tables.values()) batch.table(table.name);
     });
-    // The stop state is over: this client now ships a servable schema. The
-    // outbox is re-applied optimistically over the (now empty) tables so
-    // pending offline writes stay visible across the bump (§7.4.5).
+    // The stop state is over: this client now ships a servable schema.
+    // The reset transaction already replayed pending intent before committing
+    // its marker and visible rows (§7.4.5).
     this.#setSchemaFloor(undefined);
-    this.#replayOutbox();
   }
 
   /**
@@ -1186,23 +1394,38 @@ export class SyncClient {
       return [];
     }
     const subscriptions = loadSubscriptions(this.#db);
-    const pending = listOutbox(this.#db);
     this.#setUpgrading(true);
     // RFC 0005 D5: the log-epoch reset is not a schema bump. It performs the
     // orphan sweep but captures no new shadow.
     this.#sweepPreviousVersionContainer();
-    this.#applyBatch((batch) => {
-      this.#db.transaction(() => {
-        this.#discardAcknowledgedRows();
-        dropAndRecreateSyncedTables(this.#db, this.#schema);
-        resetSubscriptionsForBump(this.#db);
-        setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
-        for (const commit of pending) {
-          this.#applyOperationsLocally(commit.operations, batch);
-        }
-      });
-      for (const table of this.#schema.tables.values()) batch.table(table.name);
-    });
+    const priorRejections = [...this.#rejections];
+    this.#applyBatch(
+      (batch) => {
+        this.#db.transaction(() => {
+          this.#discardAcknowledgedRows();
+          dropAndRecreateSyncedTables(this.#db, this.#schema);
+          resetSubscriptionsForBump(this.#db);
+          setMeta(this.#db, LOG_EPOCH_META_KEY, logEpoch);
+          // §7.1/§7.4.4: recover codec-invalid persisted values in this reset
+          // transaction before they replay, so the reset boundary never fails on
+          // a commit an earlier version accepted.
+          this.#dropUnencodableOutbox();
+          for (const commit of listOutbox(this.#db)) {
+            this.#applyOperationsLocally(commit.operations, batch);
+          }
+        });
+        for (const table of this.#schema.tables.values())
+          batch.table(table.name);
+      },
+      undefined,
+      (error) => {
+        // A failure after the recovery drop, including the reset's revision or
+        // COMMIT, rolls the database back: mirror that for the in-memory
+        // rejection cache so no dropped commit is published.
+        this.#rejections = priorRejections;
+        throw error;
+      },
+    );
     this.#localResetEpoch += 1;
     this.#setSyncNeeded(true);
     this.#emitSyncNeeded('startup');
@@ -1419,20 +1642,154 @@ export class SyncClient {
    * Reactive integrations use this instead of composing `query()` and
    * `windowState()` across separate worker/IPC calls.
    */
-  querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row> {
+  querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row>;
+  querySnapshot(spec: QueryReadSpec): QuerySnapshot {
+    const read = this.#readSnapshot({
+      statements: [
+        {
+          sql: spec.sql,
+          ...(spec.params !== undefined ? { params: spec.params } : {}),
+        },
+      ],
+      ...(spec.coverage !== undefined ? { coverage: spec.coverage } : {}),
+      ...(spec.owner !== undefined ? { owner: spec.owner } : {}),
+    });
+    const rows = read.queries[0];
+    if (read.queries.length !== 1 || rows === undefined) {
+      throw new ClientSyncError(
+        'client.failed',
+        'querySnapshot produced no statement result',
+      );
+    }
+    return {
+      revision: read.revision,
+      rows,
+      coverage: read.coverage,
+    };
+  }
+
+  /**
+   * §7.5: resolve several read-only statements, window coverage, subscription
+   * catch-up states, and commit deliveries from one SQLite read transaction
+   * and one revision. A host that needs those together reads them together;
+   * every statement passes the read-only guard and any failure rolls the whole
+   * read back.
+   */
+  snapshotRead<Row = SqlRow>(spec: SnapshotReadRequest): SnapshotRead<Row>;
+  snapshotRead(spec: SnapshotReadRequest): SnapshotRead {
+    return this.#readSnapshot(spec);
+  }
+
+  /** §7.5: one subscription's persisted catch-up state (never the owner cache). */
+  subscriptionCatchup(id: string): SubscriptionCatchup {
+    return this.#readSnapshot({ statements: [], subscriptions: [id] })
+      .subscriptions[0]!;
+  }
+
+  /** §7.5: one client commit's delivery status: pending, its retained outcome,
+   * or an explicit unknown (never held, or pruned by retention). */
+  commitDelivery(id: string): CommitDelivery {
+    return this.#readSnapshot({ statements: [], commitIds: [id] })
+      .deliveries[0]!;
+  }
+
+  /**
+   * §7.5: the one atomic read primitive. Every public read (`querySnapshot`,
+   * `snapshotRead`, `subscriptionCatchup`, `commitDelivery`) enters here, so
+   * the read-only guard, transaction, revision, coverage, catch-up, delivery,
+   * and owner-failure observation exist once.
+   */
+  #readSnapshot(request: SnapshotReadRequest): SnapshotRead {
     this.#requireActive();
-    const owner = spec.owner;
-    let snapshot: QuerySnapshot<Row>;
+    const owner = request.owner;
+    const catchupOf = (id: string): SubscriptionCatchup => {
+      function corrupt(): never {
+        throw new ClientSyncError(
+          'sync.local_corrupt',
+          'persisted subscription state is invalid',
+        );
+      }
+      const row = this.#db.query(
+        `SELECT tbl,status,cursor,bootstrap_state,effective_scopes,reason_code FROM ${SUBSCRIPTIONS_TABLE} WHERE id=?`,
+        [id],
+      )[0];
+      if (row === undefined) return { state: 'unknown', id };
+      const table = row.tbl;
+      const status = row.status;
+      const cursor = row.cursor;
+      if (
+        typeof table !== 'string' ||
+        (status !== 'active' && status !== 'revoked' && status !== 'failed') ||
+        typeof cursor !== 'number' ||
+        !Number.isSafeInteger(cursor)
+      ) {
+        corrupt();
+      }
+      const token = row.bootstrap_state;
+      if (token !== null && typeof token !== 'string') corrupt();
+      const rawScopes = row.effective_scopes;
+      let effectiveScopes: unknown;
+      if (rawScopes !== null) {
+        if (typeof rawScopes !== 'string') corrupt();
+        try {
+          effectiveScopes = JSON.parse(rawScopes);
+          if (effectiveScopes === null) effectiveScopes = undefined;
+          else if (
+            typeof effectiveScopes !== 'object' ||
+            Array.isArray(effectiveScopes) ||
+            !Object.values(effectiveScopes).every(
+              (values) =>
+                Array.isArray(values) &&
+                values.every((value) => typeof value === 'string'),
+            )
+          )
+            corrupt();
+        } catch {
+          corrupt();
+        }
+      }
+      const reasonCode = row.reason_code;
+      if (reasonCode !== null && typeof reasonCode !== 'string') corrupt();
+      const active = status === 'active';
+      const hasResumeToken = token !== null;
+      return {
+        state: 'known',
+        id,
+        table,
+        status,
+        cursor,
+        hasResumeToken,
+        bootstrapComplete: active && cursor >= 0 && !hasResumeToken,
+        knownPendingPages: active && (hasResumeToken || cursor < 0),
+        ...(effectiveScopes !== undefined ? { effectiveScopes } : {}),
+        ...(reasonCode !== null ? { reasonCode } : {}),
+      };
+    };
+    const deliveryOf = (id: string): CommitDelivery => {
+      const pending =
+        this.#db.query(
+          `SELECT 1 FROM ${OUTBOX_TABLE} WHERE client_commit_id=? LIMIT 1`,
+          [id],
+        ).length > 0;
+      if (pending) return { status: 'pending', clientCommitId: id };
+      const outcome = persistedCommitOutcome(this.#db, id);
+      return outcome === undefined
+        ? { status: 'unknown', clientCommitId: id }
+        : { status: 'known', clientCommitId: id, outcome };
+    };
+    let read: SnapshotRead;
     try {
-      assertReadOnlyQuery(spec.sql);
-      snapshot = this.#db.transaction(() => {
+      for (const statement of request.statements) {
+        assertReadOnlyQuery(statement.sql);
+      }
+      read = this.#db.transaction(() => {
         const revision = getLocalRevision(this.#db);
-        const rows = stripSyncColumns(
-          this.#db.query(spec.sql, spec.params),
-        ) as unknown as readonly Row[];
+        const queries = request.statements.map((statement) =>
+          stripSyncColumns(this.#db.query(statement.sql, statement.params)),
+        );
         const pending: WindowUnitRef[] = [];
         const missing: WindowUnitRef[] = [];
-        for (const requested of spec.coverage ?? []) {
+        for (const requested of request.coverage ?? []) {
           const baseKey = windowBaseKey(requested.base);
           const state = this.windowState(requested.base);
           for (const unit of new Set(requested.units)) {
@@ -1443,19 +1800,26 @@ export class SyncClient {
         }
         return {
           revision,
-          rows,
+          queries,
           coverage: {
             complete: pending.length === 0 && missing.length === 0,
             pending,
             missing,
           },
+          subscriptions: (request.subscriptions ?? []).map(catchupOf),
+          deliveries: (request.commitIds ?? []).map(deliveryOf),
         };
       });
     } catch (error) {
       const failure = classifySqliteFailure(error);
-      const sqliteCode = failure.sqliteCode;
-      const code = failure.code ?? 'client.query_failed';
       if (owner !== undefined) {
+        const code: DiagnosticQueryFailure['code'] =
+          failure.code ??
+          (error instanceof ClientSyncError &&
+          error.code === 'sync.local_corrupt'
+            ? 'sync.local_corrupt'
+            : 'client.query_failed');
+        const sqliteCode = failure.sqliteCode;
         const tables = [...new Set(owner.tables)].sort();
         const previous = this.#queryFailures.get(owner.id);
         if (
@@ -1471,7 +1835,7 @@ export class SyncClient {
               id: owner.id,
               tables,
               code,
-              sqliteCode: sqliteCode,
+              sqliteCode,
               atMs: this.#now(),
             }),
           );
@@ -1488,7 +1852,7 @@ export class SyncClient {
     if (owner !== undefined && this.#queryFailures.delete(owner.id)) {
       this.#emitDiagnostics();
     }
-    return snapshot;
+    return read;
   }
 
   // -- previous-version context (RFC 0005) ----------------------------------
@@ -1532,6 +1896,13 @@ export class SyncClient {
         refusal?.reason ?? 'no-previous-descriptor',
       );
     }
+    if (record.currentVersion !== currentVersion) {
+      this.#discardPreviousVersion();
+      return this.#previousVersionUnavailable(
+        currentVersion,
+        'no-previous-descriptor',
+      );
+    }
     if (
       nowMs - record.createdAtMs >
       previousVersionMaxAgeMs(this.#config.previousVersionContext)
@@ -2873,6 +3244,21 @@ export class SyncClient {
         });
       }
       const pkValue = requireRowId(json[table.primaryKey]);
+      // §7.1: declared-type validation runs before the commit is recorded, so a
+      // refused value leaves no outbox entry, no optimistic row, no revision
+      // and no observation event.
+      const refusal = this.#operationValuesError(table, json);
+      if (refusal !== undefined)
+        // §7.5: the same structured shape the native authoring APIs return — a
+        // static message, and the dynamic cause in `details.legacyCause`.
+        throw new ClientSyncError(
+          'sync.invalid_request',
+          'the authoring request is invalid',
+          false,
+          {
+            legacyCause: `sync.invalid_request: table ${table.name}: ${refusal}`,
+          },
+        );
       return definedObject({
         table: mutation.table,
         rowId: pkValue,
@@ -3296,9 +3682,14 @@ export class SyncClient {
    * incompatible`); its purely-optimistic rows are undone (§7.2). Returns
    * the encoded push frames index-aligned with the surviving `outbox`.
    */
-  async #encodeOutboxForPush(): Promise<{
+  async #encodeOutboxForPush(
+    header: RequestFrame,
+    pull: RequestFrame,
+    byteCap?: number,
+  ): Promise<{
     pushFrames: RequestFrame[];
     outbox: OutboxCommit[];
+    frameBytes: number[];
     deferred: number;
   }> {
     // Pin before the first encryption await: mutations can append while a
@@ -3308,26 +3699,38 @@ export class SyncClient {
     )[0]!;
     const pendingCount = bounds.count as number;
     const throughSeq = (bounds.last_seq as number | null) ?? 0;
+    const maxCommits = this.#config.limits?.maxPushCommitsPerRequest;
+    const maxOps =
+      this.#config.limits?.maxPushOperationsPerRequest ?? MAX_OPS_PER_REQUEST;
+    // A request must start with REQ_HEADER and carry PULL_HEADER; those two
+    // frames make a valid probe whose encoded size cancels out of the
+    // per-commit delta measured against the canonical encoder.
+    const baseBytes =
+      byteCap === undefined
+        ? 0
+        : encodeMessage({
+            wireVersion: PROTOCOL_WIRE_VERSION,
+            msgKind: 'request',
+            frames: [header, pull],
+          }).length;
     const pushFrames: RequestFrame[] = [];
     const outbox: OutboxCommit[] = [];
+    const frameBytes: number[] = [];
     let deferred = 0;
     let ops = 0;
+    let bytes = 0;
     let processed = 0;
     for (const commit of iterateOutbox(this.#db, throughSeq)) {
-      // §6.1 splitBatch: whole commits in commit order, stopping before the
-      // per-request operation cap. A first commit that alone exceeds the cap
-      // is sent alone — the server rejects it loudly rather than the queue
-      // wedging silently. Deferred commits stay queued for the next round.
-      if (
-        outbox.length > 0 &&
-        ops + commit.operations.length > MAX_OPS_PER_REQUEST
-      ) {
+      // §6.1/§7.1: the commit-count and operation caps are hard. A first
+      // commit that alone exceeds the operation cap is a typed capacity error
+      // and stays queued; a later one defers with the complete suffix.
+      if (maxCommits !== undefined && pushFrames.length >= maxCommits) {
         deferred = pendingCount - processed;
         break;
       }
-      processed += 1;
+      let pushFrame: RequestFrame;
       try {
-        pushFrames.push(
+        pushFrame =
           // §5.11: encrypted columns are encrypted at this encode-at-send
           // seam before the row codec serializes them. The stored local row
           // supplies an ABSENT key-id selector (§6.1 presence set first,
@@ -3349,23 +3752,99 @@ export class SyncClient {
                 ? value
                 : undefined;
             },
-          ),
-        );
-        outbox.push(commit);
-        ops += commit.operations.length;
+          );
       } catch (error) {
         if (error instanceof OutboxEncodeError) {
           this.#dropIncompatibleCommit(commit, error.message);
+          processed += 1;
           continue;
         }
         if (error instanceof EncryptError) {
           this.#dropIncompatibleCommit(commit, error.message, error.code);
+          processed += 1;
+          continue;
+        }
+        // §7.1/§7.4.4: a persisted value the current codec refuses (an earlier
+        // version accepted it) is an incompatible commit, never a wedged queue.
+        if (
+          error instanceof EncodeError ||
+          (error instanceof ClientSyncError &&
+            error.code === 'sync.invalid_request')
+        ) {
+          this.#dropIncompatibleCommit(
+            commit,
+            LEGACY_VALUE_REFUSAL_MESSAGE,
+            OUTBOX_INCOMPATIBLE_CODE,
+            true,
+            INVALID_STORED_VALUES_REASON,
+          );
+          processed += 1;
           continue;
         }
         throw error;
       }
+      // The operation cap is checked after the encode/drop so an unencodable
+      // head is dropped as a durable rejection first, matching the native
+      // prepass priority.
+      if (ops + commit.operations.length > maxOps) {
+        if (pushFrames.length === 0) {
+          throw this.#pushCapacityError(
+            'operations',
+            maxOps,
+            commit.operations.length,
+            commit.clientCommitId,
+          );
+        }
+        deferred = pendingCount - processed;
+        break;
+      }
+      const frame =
+        byteCap === undefined
+          ? 0
+          : encodeMessage({
+              wireVersion: PROTOCOL_WIRE_VERSION,
+              msgKind: 'request',
+              frames: [header, pushFrame, pull],
+            }).length - baseBytes;
+      // The head is always encoded so the caller can report the full
+      // projected request size with the final header and subscription bytes;
+      // a later commit defers once it no longer fits.
+      if (
+        byteCap !== undefined &&
+        pushFrames.length > 0 &&
+        bytes + frame > byteCap
+      ) {
+        deferred = pendingCount - processed;
+        break;
+      }
+      pushFrames.push(pushFrame);
+      outbox.push(commit);
+      frameBytes.push(frame);
+      ops += commit.operations.length;
+      bytes += frame;
+      processed += 1;
     }
-    return { pushFrames, outbox, deferred };
+    return { pushFrames, outbox, frameBytes, deferred };
+  }
+
+  /** §7.1: a configured push capacity limit cannot carry this request. */
+  #pushCapacityError(
+    kind: 'operations' | 'bytes',
+    limit: number,
+    size: number,
+    clientCommitId?: string,
+  ): ClientSyncError {
+    return new ClientSyncError(
+      'client.push_request_too_large',
+      'the push request exceeds a configured capacity limit',
+      false,
+      definedObject({
+        kind,
+        limit,
+        size,
+        ...(clientCommitId !== undefined ? { clientCommitId } : {}),
+      }),
+    );
   }
 
   /**
@@ -3378,37 +3857,56 @@ export class SyncClient {
     commit: OutboxCommit,
     message: string,
     code: string = OUTBOX_INCOMPATIBLE_CODE,
+    replay = true,
+    reason?: string,
+    classifiedFailures?: ReadonlySet<string>,
   ): void {
-    this.#applyBatch((batch) => {
-      if (this.#retainFailedCommits && code === 'client.encrypt_failed')
-        retainFailedRows(
-          this.#db,
-          commit,
-          listOutboxBeforeImages(this.#db, commit.clientCommitId),
-        );
-      this.#rollbackFailedCommit(commit, batch);
-      this.#replayOutbox();
-      const rejection: RejectionRecord = definedObject({
-        clientCommitId: commit.clientCommitId,
-        opIndex: 0,
-        code,
-        message,
-        retryable: false,
-        operation: commit.operations[0],
-      });
-      this.#rejections.push(rejection);
-      recordCommitOutcome(this.#db, {
-        clientCommitId: commit.clientCommitId,
-        status: 'rejected',
-        recordedAtMs: this.#now(),
-        results: [{ status: 'error', rejection }],
-        operations: commit.operations,
-      });
-      pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
-      batch.status();
-      batch.rejections();
-      batch.outcomes();
-    });
+    const priorRejections = [...this.#rejections];
+    this.#applyBatch(
+      (batch) => {
+        if (this.#retainFailedCommits && code === 'client.encrypt_failed')
+          retainFailedRows(
+            this.#db,
+            commit,
+            listOutboxBeforeImages(this.#db, commit.clientCommitId),
+          );
+        this.#rollbackFailedCommit(commit, batch, classifiedFailures);
+        if (replay) this.#replayOutbox();
+        // §7.2/§7.4.4: the journal holds the operation envelope only when its
+        // stored shape is representable. A dropped legacy commit whose envelope
+        // the journal cannot carry keeps its durable commitId, code and a bounded
+        // `details.reason` instead of an opaque rewritten value.
+        const representable = commit.operations.every(isStoredOperation);
+        const rejection: RejectionRecord = definedObject({
+          clientCommitId: commit.clientCommitId,
+          opIndex: 0,
+          code,
+          message,
+          retryable: false,
+          ...(representable ? { operation: commit.operations[0] } : {}),
+          ...(reason === undefined ? {} : { details: { reason } }),
+        });
+        this.#rejections.push(rejection);
+        recordCommitOutcome(this.#db, {
+          clientCommitId: commit.clientCommitId,
+          status: 'rejected',
+          recordedAtMs: this.#now(),
+          results: [{ status: 'error', rejection }],
+          ...(representable ? { operations: commit.operations } : {}),
+        });
+        pruneCommitOutcomes(this.#db, this.#outcomeRetentionMaxEntries);
+        batch.status();
+        batch.rejections();
+        batch.outcomes();
+      },
+      undefined,
+      (error) => {
+        // The drop's own outcome write or publication failed: mirror the
+        // rollback so no rejection the journal did not keep stays in memory.
+        this.#rejections = priorRejections;
+        throw error;
+      },
+    );
   }
 
   // -- sync -------------------------------------------------------------------
@@ -3540,6 +4038,34 @@ export class SyncClient {
     try {
       await this.#drainPendingEvictions();
       const logEpoch = getMeta(this.#db, LOG_EPOCH_META_KEY);
+      // §7.4.4: encode the outbox with the CURRENT codec; a commit that
+      // cannot express itself under the new schema (a dropped column/table)
+      // is removed from the push and surfaced as a rejection, never wedging
+      // the queue. `pushFrames` and `outbox` stay index-aligned for result
+      // mapping.
+      const limits = this.#config.limits;
+      const byteCap = limits?.maxPushRequestBytes;
+      const header: RequestFrame = definedObject({
+        type: 'REQ_HEADER',
+        clientId: this.#clientId,
+        schemaVersion: this.#schema.version,
+        logEpoch: logEpoch,
+      });
+      const pull: RequestFrame = {
+        type: 'PULL_HEADER',
+        limitCommits: limits?.limitCommits ?? 0,
+        limitSnapshotRows: limits?.limitSnapshotRows ?? 0,
+        maxSnapshotPages: limits?.maxSnapshotPages ?? 0,
+        accept: this.#acceptMask(),
+      };
+      const {
+        pushFrames,
+        outbox,
+        frameBytes,
+        deferred: encodedDeferred,
+      } = logEpoch === undefined
+        ? { pushFrames: [], outbox: [], frameBytes: [], deferred: 0 }
+        : await this.#encodeOutboxForPush(header, pull, byteCap);
       // §5.9.7 B4: upload pending blobs BEFORE pushing rows that reference
       // them, so the server-side existence check (§6.6) passes.
       if (
@@ -3549,37 +4075,16 @@ export class SyncClient {
       ) {
         await this.#flushBlobUploads();
       }
-      // §7.4.4: encode the outbox with the CURRENT codec; a commit that
-      // cannot express itself under the new schema (a dropped column/table)
-      // is removed from the push and surfaced as a rejection, never wedging
-      // the queue. `pushFrames` and `outbox` stay index-aligned for result
-      // mapping.
-      const { pushFrames, outbox, deferred } =
-        logEpoch === undefined
-          ? { pushFrames: [], outbox: [], deferred: 0 }
-          : await this.#encodeOutboxForPush();
-      // Captured together with the subscription state below: the response
-      // apply persists SUB_END cursors only while this epoch is current.
+      // Captured after encoding: a subscribe/unsubscribe during the
+      // encryption await must not make the final request exceed the byte
+      // budget, and the reset epoch must be the one the response apply checks.
       const resetEpoch = this.#localResetEpoch;
       const subs = loadSubscriptions(this.#db).filter(
         (sub) => sub.status === 'active',
       );
-      const limits = this.#config.limits;
-      const frames: RequestFrame[] = [
-        definedObject({
-          type: 'REQ_HEADER',
-          clientId: this.#clientId,
-          schemaVersion: this.#schema.version,
-          logEpoch: logEpoch,
-        }),
-        ...pushFrames,
-        {
-          type: 'PULL_HEADER',
-          limitCommits: limits?.limitCommits ?? 0,
-          limitSnapshotRows: limits?.limitSnapshotRows ?? 0,
-          maxSnapshotPages: limits?.maxSnapshotPages ?? 0,
-          accept: this.#acceptMask(),
-        },
+      const fixedFrames: RequestFrame[] = [
+        header,
+        pull,
         ...subs.map(
           (sub): RequestFrame =>
             definedObject({
@@ -3593,6 +4098,42 @@ export class SyncClient {
             }),
         ),
       ];
+      let admitted = pushFrames.length;
+      let deferred = encodedDeferred;
+      if (byteCap !== undefined) {
+        // The fixed frames encode as envelope + fixed frames + END; each
+        // admitted push frame adds its own (5 + payload). Trimming the tail
+        // re-fits the request to the final subscription state.
+        const fixedBytes = encodeMessage({
+          wireVersion: PROTOCOL_WIRE_VERSION,
+          msgKind: 'request',
+          frames: fixedFrames,
+        }).length;
+        if (fixedBytes > byteCap)
+          throw this.#pushCapacityError('bytes', byteCap, fixedBytes);
+        let admittedBytes = 0;
+        for (const size of frameBytes) admittedBytes += size;
+        while (admitted > 0 && fixedBytes + admittedBytes > byteCap) {
+          admitted -= 1;
+          admittedBytes -= frameBytes[admitted]!;
+          deferred += 1;
+        }
+        if (admitted === 0 && pushFrames.length > 0) {
+          throw this.#pushCapacityError(
+            'bytes',
+            byteCap,
+            fixedBytes + frameBytes[0]!,
+            outbox[0]!.clientCommitId,
+          );
+        }
+        pushFrames.length = admitted;
+        outbox.length = admitted;
+      }
+      const frames: RequestFrame[] = [
+        fixedFrames[0]!,
+        ...pushFrames,
+        ...fixedFrames.slice(1),
+      ];
       const requestBytes = encodeMessage({
         wireVersion: PROTOCOL_WIRE_VERSION,
         msgKind: 'request',
@@ -3673,16 +4214,73 @@ export class SyncClient {
    * Pull repeatedly until quiescent: no commits delivered, no bootstrap
    * pages pending, no resets to recover (§4.5 "pull again" SHOULD).
    */
-  async syncUntilIdle(maxRounds?: number): Promise<SyncSummary> {
+  async syncUntilIdle(maxRounds?: number): Promise<SyncIdleResult> {
+    // §7.7: an explicit budget is a strict positive round count. Zero,
+    // fractional, and out-of-range values are caller errors.
+    if (
+      maxRounds !== undefined &&
+      (!Number.isInteger(maxRounds) || maxRounds < 1 || maxRounds > 0xffffffff)
+    )
+      throw invalidRequest('maxRounds must be a positive integer');
     const budget = maxRounds ?? 20;
-    let last: SyncSummary | undefined;
+    const aggregate = {
+      pushed: 0,
+      applied: [] as string[],
+      rejected: [] as string[],
+      retryable: [] as string[],
+      conflicts: [] as ConflictRecord[],
+      commitsApplied: 0,
+      segmentRowsApplied: 0,
+      bootstrapping: [] as string[],
+      resets: [] as string[],
+      revoked: [] as string[],
+      failed: [] as string[],
+      deferredCommits: 0,
+      schemaFloor: undefined as SchemaFloor | undefined,
+    };
+    const result = (budgetExhausted: boolean): SyncIdleResult => ({
+      pushed: aggregate.pushed,
+      applied: aggregate.applied,
+      rejected: aggregate.rejected,
+      retryable: aggregate.retryable,
+      conflicts: aggregate.conflicts,
+      commitsApplied: aggregate.commitsApplied,
+      segmentRowsApplied: aggregate.segmentRowsApplied,
+      bootstrapping: aggregate.bootstrapping,
+      resets: aggregate.resets,
+      revoked: aggregate.revoked,
+      failed: aggregate.failed,
+      ...(aggregate.deferredCommits > 0
+        ? { deferredCommits: aggregate.deferredCommits }
+        : {}),
+      ...(aggregate.schemaFloor !== undefined
+        ? { schemaFloor: aggregate.schemaFloor }
+        : {}),
+      budgetExhausted,
+    });
     for (let round = 0; round < budget; round++) {
       const before = JSON.stringify(
         loadSubscriptions(this.#db).map((sub) => [sub.id, sub.bootstrapState]),
       );
-      last = await this.sync();
+      const last = await this.sync();
+      // Historical counters accumulate; current readiness (`bootstrapping`,
+      // `deferredCommits`, `schemaFloor`) describes the latest round.
+      aggregate.pushed += last.pushed;
+      aggregate.applied.push(...last.applied);
+      aggregate.rejected.push(...last.rejected);
+      aggregate.retryable.push(...last.retryable);
+      aggregate.conflicts.push(...last.conflicts);
+      aggregate.commitsApplied += last.commitsApplied;
+      aggregate.segmentRowsApplied += last.segmentRowsApplied;
+      aggregate.bootstrapping = [...last.bootstrapping];
+      aggregate.resets.push(...last.resets);
+      aggregate.revoked.push(...last.revoked);
+      aggregate.failed.push(...last.failed);
+      aggregate.deferredCommits = last.deferredCommits ?? 0;
+      aggregate.schemaFloor = last.schemaFloor;
+      // A disabled transport or a schema floor ends the loop, not the budget.
       if (!this.#transportEnabled || last.schemaFloor !== undefined)
-        return last;
+        return result(false);
       if (
         maxRounds === undefined &&
         last.segmentRowsApplied > 0 &&
@@ -3704,10 +4302,10 @@ export class SyncClient {
         (last.deferredCommits ?? 0) === 0 &&
         !this.#needsPull
       ) {
-        return last;
+        return result(false);
       }
     }
-    throw invalidRequest('sync did not reach idle within the round budget');
+    return result(true);
   }
 
   /**
@@ -3734,7 +4332,7 @@ export class SyncClient {
         tagged.set(request, 1);
         try {
           socket.sendBytes(tagged);
-        } catch (error) {
+        } catch {
           this.#pendingRound = undefined;
           // The socket could not carry the round: record the same loss the
           // Rust core records when its realtime round call fails (§8.8).
@@ -3742,8 +4340,9 @@ export class SyncClient {
           reject(
             new ClientSyncError(
               'sync.transport_failed',
-              `socket round send failed: ${error instanceof Error ? error.message : String(error)}`,
+              'socket round send failed',
               true,
+              { causeKind: 'unknown' },
             ),
           );
         }
@@ -3765,8 +4364,9 @@ export class SyncClient {
         }
         throw new ClientSyncError(
           'sync.transport_failed',
-          `transport round failed: ${error instanceof Error ? error.message : String(error)}`,
+          'transport round failed',
           true,
+          { causeKind: 'unknown' },
         );
       });
   }
@@ -3930,13 +4530,9 @@ export class SyncClient {
       let done: ReturnType<MessageStreamScanner['push']>;
       try {
         done = round.scanner.push(body);
-      } catch (error) {
+      } catch {
         this.#pendingRound = undefined;
-        round.reject(
-          invalidRequest(
-            `malformed round response stream (§8.7): ${error instanceof Error ? error.message : String(error)}`,
-          ),
-        );
+        round.reject(invalidRequest('malformed round response stream (§8.7)'));
         return;
       }
       if (done === undefined) return;
@@ -4561,14 +5157,23 @@ export class SyncClient {
           listOutboxBeforeImages(this.#db, commit.clientCommitId),
         );
       this.#rollbackFailedCommit(commit, batch);
+      // §7.2: rebasing a rejection reaches rows the same-row replay inside
+      // `#rollbackFailedCommit` cannot: peers of a secondary UNIQUE index
+      // (table-wide scope) and later commits over legacy before-images.
+      // ACK-only groups reconcile nothing and stay zero-work.
       this.#replayOutbox(
-        commit.operations.map((operation) =>
-          JSON.stringify(
-            hasUniqueIndex(this.#table(operation.table))
-              ? [operation.table]
-              : [operation.table, operation.rowId],
-          ),
-        ),
+        commit.operations.flatMap((operation) => {
+          const table = this.#schema.tables.get(operation.table);
+          return table === undefined
+            ? []
+            : [
+                JSON.stringify(
+                  hasUniqueIndex(table)
+                    ? [operation.table]
+                    : [operation.table, operation.rowId],
+                ),
+              ];
+        }),
       );
     });
     batch.status();
@@ -5136,7 +5741,11 @@ export class SyncClient {
     }
   }
 
-  #rollbackFailedCommit(commit: OutboxCommit, batch: ChangeAccumulator): void {
+  #rollbackFailedCommit(
+    commit: OutboxCommit,
+    batch: ChangeAccumulator,
+    classifiedFailures?: ReadonlySet<string>,
+  ): void {
     const images = listOutboxBeforeImages(this.#db, commit.clientCommitId);
     const imageByIndex = new Map(images.map((image) => [image.opIndex, image]));
     const complete = commit.operations.every((_, index) =>
@@ -5175,6 +5784,10 @@ export class SyncClient {
         later.clientCommitId,
         this.#captureBeforeImages(later.operations, affectedKeys),
       );
+      // §7.4.4: a later commit the recovery already classified refused never
+      // replays. Its before-image is still rebased above, so dropping it later
+      // restores the same base this rollback just restored.
+      if (classifiedFailures?.has(later.clientCommitId)) continue;
       this.#applyOperationsLocally(affectedOperations, batch);
     }
   }
@@ -5185,7 +5798,17 @@ export class SyncClient {
     replay = false,
   ): void {
     for (const op of operations) {
-      const table = this.#table(op.table);
+      // §7.4.4: the overlay replay is schema-agnostic (§0), so an operation
+      // whose table the current schema removed has no local mirror to replay
+      // into and is skipped here. A removed-table upsert stays durable for the
+      // send-time `sync.outbox_incompatible` classification; a value-free
+      // delete carries no values to classify and keeps ordinary server
+      // validation. Every other call runs against the live schema and keeps the
+      // loud `sync.unknown_table`.
+      const table = replay
+        ? this.#schema.tables.get(op.table)
+        : this.#table(op.table);
+      if (table === undefined) continue;
       let precise =
         batch === undefined
           ? false
@@ -5214,8 +5837,32 @@ export class SyncClient {
         if (value !== undefined) return jsonToRowValue(value);
         return local === undefined
           ? null
-          : fromSqlValue(column, local[column.name] ?? null);
+          : replay
+            ? (coerceSqlRepresentation(
+                column,
+                local[column.name] ?? null,
+              ) as RowValue)
+            : fromSqlValue(column, local[column.name] ?? null);
       });
+      if (replay) {
+        try {
+          encodeRow(
+            table.columns.map((column, index) => ({
+              ...column,
+              type:
+                column.encrypted && values[index] instanceof Uint8Array
+                  ? 'bytes'
+                  : localColumnType(column),
+            })),
+            values,
+          );
+        } catch {
+          throw new ClientSyncError(
+            'sync.local_corrupt',
+            'persisted optimistic row value is invalid',
+          );
+        }
+      }
       // Record the row's scope keys from its scope columns (I2 refinement).
       if (batch !== undefined) {
         for (const [variable, column] of table.scopeColumnByVariable) {
@@ -5283,9 +5930,102 @@ export class SyncClient {
     return scope;
   }
 
-  #replayOutbox(scope?: OverlayScope, restoreBases = true): void {
+  /**
+   * §7.1: the operation's values must encode under the current schema. Returns
+   * the refusal message, or `undefined` when they encode. Structural failures
+   * (a programming error, never caller data) propagate unchanged.
+   */
+  #operationValuesError(
+    table: CompiledClientTable,
+    values: Readonly<Record<string, JsonRowValue>>,
+  ): string | undefined {
+    const declared = table.columns.map((column) => ({
+      ...column,
+      type: localColumnType(column),
+    }));
+    const sparse: Array<RowValue | undefined> = [];
+    for (const column of table.columns) {
+      const raw = values[column.name];
+      if (raw === undefined) {
+        sparse.push(undefined);
+        continue;
+      }
+      // §7.1: the schema-agnostic outbox form serializes through JSON, which
+      // turns NaN and ±Infinity into null. The authoring boundary refuses them
+      // instead of recording a different value; the wire `f64` encoding itself
+      // stays IEEE-754 binary64 (§2.4).
+      if (
+        localColumnType(column) === 'float' &&
+        typeof raw === 'number' &&
+        !Number.isFinite(raw)
+      )
+        return `column ${column.name} (float) requires a finite number value`;
+      try {
+        sparse.push(jsonToRowValue(raw));
+      } catch (error) {
+        if (error instanceof ClientSyncError)
+          return `column ${column.name}: ${error.message}`;
+        throw error;
+      }
+    }
+    try {
+      encodeSparseRow(declared, table.primaryKeyIndex, sparse);
+      return undefined;
+    } catch (error) {
+      if (error instanceof EncodeError || error instanceof ClientSyncError)
+        return error.message;
+      throw error;
+    }
+  }
+
+  /**
+   * §7.4.4: a pending commit whose own values the current codec refuses (an
+   * envelope or a type an earlier version accepted) leaves the outbox as
+   * `sync.outbox_incompatible` instead of failing every replay and sync. The
+   * commit goes through the rejection channel; encryption and storage failures
+   * never reach this path.
+   */
+  #dropUnencodableOutbox(): void {
+    const failures: OutboxCommit[] = [];
+    for (const commit of listOutbox(this.#db)) {
+      const refused = commit.operations.some((op) => {
+        if (op.op !== 'upsert' || op.values === undefined) return false;
+        const table = this.#schema.tables.get(op.table);
+        if (table === undefined) return false;
+        return this.#operationValuesError(table, op.values) !== undefined;
+      });
+      if (refused) failures.push(commit);
+    }
+    // §7.4.4: every refused commit is classified before the FIFO drop pass, so
+    // a rollback never replays a refused successor it has not removed yet.
+    const classifiedFailures = new Set(
+      failures.map((commit) => commit.clientCommitId),
+    );
+    for (const commit of failures)
+      this.#dropIncompatibleCommit(
+        commit,
+        LEGACY_VALUE_REFUSAL_MESSAGE,
+        OUTBOX_INCOMPATIBLE_CODE,
+        false,
+        INVALID_STORED_VALUES_REASON,
+        classifiedFailures,
+      );
+  }
+
+  #replayOutbox(
+    scope?: OverlayScope,
+    restoreBases = true,
+    observe = true,
+  ): void {
     if (scope?.length === 0) return;
-    this.#applyBatch((batch) => {
+    const replay = (batch?: ChangeAccumulator) => {
+      // §7.4.4: classify value-unencodable pending commits inside the
+      // reconciliation transaction, so a commit persisted by an earlier version
+      // is dropped atomically with the replay it would otherwise fail. A
+      // scoped (partial) reconciliation leaves the classification to these full
+      // boundaries and to the send-time drop, so a partial rebuild never drops
+      // a commit whose other tables are outside the scope.
+      if (scope === undefined) this.#dropUnencodableOutbox();
       if (restoreBases) restoreFailedBases(this.#db, this.#schema, scope);
       const acknowledged = failedOverlayCommits(
         this.#db,
@@ -5308,7 +6048,18 @@ export class SyncClient {
           batch,
           true,
         );
-    });
+    };
+    const priorRejections = [...this.#rejections];
+    try {
+      if (observe) this.#applyBatch(replay);
+      else this.#db.transaction(() => replay());
+    } catch (error) {
+      // SQLite rolled the reconciliation back: mirror that rollback for the
+      // in-memory rejection cache, so a later failure in the same transaction
+      // publishes no drop the durable journal did not keep.
+      this.#rejections = priorRejections;
+      throw error;
+    }
   }
 
   #deleteUnreferencedBlobs(): void {