@syncular/server 0.1.3 → 0.2.0

package/src/pull.ts

@@ -1,1865 +1,565 @@
+/**
+ * Pull: incremental commit delivery, cursors, bootstrap segments
+ * (SPEC.md §4, §5).
+ */
 import {
-  type BinarySnapshotColumn,
-  type BinarySnapshotColumnType,
-  type BinarySnapshotRowsEncoder,
-  bytesToReadableStream,
-  captureSyncException,
-  concatByteChunks,
-  countSyncMetric,
-  createSnapshotManifest,
-  distributionSyncMetric,
-  encodeBinarySnapshotTable,
-  gzipBytes,
-  randomId,
-  type ScopeValues,
-  SYNC_SCOPED_SNAPSHOT_ARTIFACT_KIND_SQLITE_V1,
-  SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-  SYNC_SNAPSHOT_CHUNK_ENCODING,
-  type SyncBootstrapState,
-  type SyncChange,
-  type SyncCommit,
-  type SyncCrdtStateVectorHint,
-  type SyncPullRequest,
-  type SyncPullResponse,
-  type SyncPullSubscriptionResponse,
-  type SyncScopedSnapshotArtifactKind,
-  type SyncSnapshot,
-  type SyncSnapshotArtifactCompression,
-  type SyncSnapshotArtifactsRequest,
-  type SyncSnapshotChunkRef,
-  sha256Hex,
-  snapshotScopeDigestFromCacheKey,
-  startSyncSpan,
+  type CommitChange,
+  decodeRow,
+  encodeRowsSegment,
+  type PullHeaderFrame,
+  type ResponseFrame,
+  type ScopeMap,
+  type SegmentRow,
+  type SubscriptionFrame,
 } from '@syncular/core';
-import type { Kysely } from 'kysely';
-import {
-  createWireSubscriptionIntegrity,
-  SYNCULAR_COMMIT_GENESIS_ROOT,
-} from './commit-integrity';
-import type {
-  DbExecutor,
-  IncrementalPullRow,
-  ServerSyncDialect,
-} from './dialect/types';
-import {
-  getServerBootstrapOrderFor,
-  type ServerHandlerCollection,
-} from './handlers/collection';
-import type { ServerTableHandler, SyncServerAuth } from './handlers/types';
-import { EXTERNAL_CLIENT_ID } from './notify';
-import {
-  type SyncServerPullPlugin,
-  sortServerPullPlugins,
-} from './plugins/types';
-import type { SyncCoreDb } from './schema';
-import {
-  createScopedSnapshotArtifactScopeCacheKey,
-  readBestScopedSnapshotArtifactRefForPageCapacity,
-} from './snapshot-artifacts';
-import {
-  createSnapshotChunkScopeCacheKey,
-  insertSnapshotChunk,
-  readSnapshotChunkRefByPageKey,
-  type SnapshotChunkRefWithContinuation,
-} from './snapshot-chunks';
-import type { SnapshotChunkStorage } from './snapshot-chunks/types';
-import {
-  createMemoryScopeCache,
-  type ScopeCacheBackend,
-} from './subscriptions/cache';
-import { resolveEffectiveScopesForSubscriptions } from './subscriptions/resolve';
-
-const defaultScopeCache = createMemoryScopeCache();
-const DEFAULT_MAX_BINARY_SNAPSHOT_BUNDLE_ROWS = 50_000;
-const DEFAULT_SNAPSHOT_CHUNK_GZIP_LEVEL = 1;
-const MAX_PULL_TRANSACTION_RETRIES = 2;
-const PULL_TRANSACTION_RETRY_DELAY_MS = 15;
-
-interface PullBootstrapTimings {
-  snapshotQueryMs: number;
-  binaryEncodeMs: number;
-  chunkCacheLookupMs: number;
-  artifactCacheLookupMs: number;
-  chunkGzipMs: number;
-  chunkHashMs: number;
-  chunkPersistMs: number;
-}
-
-interface SnapshotChunkEncodeResult {
-  body: Uint8Array;
-  sha256: string;
-  gzipMs: number;
-  hashMs: number;
-}
-
-function toResponseChunkRef(ref: SyncSnapshotChunkRef): SyncSnapshotChunkRef {
-  return {
-    id: ref.id,
-    byteLength: ref.byteLength,
-    sha256: ref.sha256,
-    encoding: ref.encoding,
-    compression: ref.compression,
-  };
-}
-
-async function createChunkedSnapshotManifest(args: {
-  table: string;
-  asOfCommitSeq: number;
-  scopeKey: string;
-  rowCursor: string | null;
-  rowLimit: number;
-  nextRowCursor: string | null;
-  isFirstPage: boolean;
-  isLastPage: boolean;
-  chunks: readonly SyncSnapshotChunkRef[];
-}): Promise<SyncSnapshot['manifest']> {
-  return createSnapshotManifest({
-    version: 1,
-    table: args.table,
-    asOfCommitSeq: args.asOfCommitSeq,
-    scopeDigest: snapshotScopeDigestFromCacheKey(args.scopeKey),
-    rowCursor: args.rowCursor,
-    rowLimit: args.rowLimit,
-    nextRowCursor: args.nextRowCursor,
-    isFirstPage: args.isFirstPage,
-    isLastPage: args.isLastPage,
-    chunks: args.chunks.map(toResponseChunkRef),
-  });
-}
+import type { SyncRequestContext } from './context';
+import { clockOf, limitsOf } from './context';
+import type { PullSegmentSummary } from './events';
+import type { CompiledSchema, CompiledTable } from './schema';
+import { scopeDigest } from './scopes';
+import type { SegmentRecord } from './segment-store';
+import { issueSegmentUrl } from './signed-url';
+import type { SqliteImageBuilder } from './sqlite-image';
+import type { StoredCommit, StoredRow } from './storage';
 
-interface SnapshotArtifactSelection {
-  artifactKind: SyncScopedSnapshotArtifactKind;
-  compression: SyncSnapshotArtifactCompression;
-  schemaVersion: string;
-  featureSet: readonly string[];
-}
-
-function normalizeFeatureSet(
-  features: readonly string[] | undefined
-): string[] {
-  return Array.from(new Set(features ?? [])).sort();
-}
-
-function resolveSnapshotArtifactSelection(
-  request: SyncSnapshotArtifactsRequest | undefined,
-  clientSchemaVersion: number
-): SnapshotArtifactSelection | null {
-  if (!request) return null;
-  if (
-    !request.artifactKinds.includes(
-      SYNC_SCOPED_SNAPSHOT_ARTIFACT_KIND_SQLITE_V1
-    )
-  ) {
-    return null;
-  }
-  if (!request.compressions?.includes(SYNC_SNAPSHOT_CHUNK_COMPRESSION)) {
-    return null;
+/**
+ * Resolve the §5.3 image builder: the host-injected one if present, else the
+ * in-tree `buildSqliteImage` on a Bun runtime (dynamic import so `bun:sqlite`
+ * is never a static dep of the neutral core), else `undefined` (rows lane).
+ * Memoized so the dynamic import happens at most once per process.
+ */
+let cachedDefaultBuilder: SqliteImageBuilder | null | undefined;
+async function resolveImageBuilder(
+  ctx: SyncRequestContext,
+): Promise<SqliteImageBuilder | undefined> {
+  if (ctx.sqliteImageBuilder !== undefined) return ctx.sqliteImageBuilder;
+  if (cachedDefaultBuilder === undefined) {
+    const hasBun = (globalThis as { Bun?: unknown }).Bun !== undefined;
+    cachedDefaultBuilder = hasBun
+      ? (await import('./sqlite-image')).buildSqliteImage
+      : null;
   }
-  return {
-    artifactKind: SYNC_SCOPED_SNAPSHOT_ARTIFACT_KIND_SQLITE_V1,
-    compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-    schemaVersion: String(clientSchemaVersion),
-    featureSet: normalizeFeatureSet(request.featureSet),
-  };
+  return cachedDefaultBuilder ?? undefined;
 }
 
-function resolveSnapshotBinaryColumns<
-  DB extends SyncCoreDb,
-  Auth extends SyncServerAuth,
->(
-  handler: ServerTableHandler<DB, Auth>,
-  schemaVersion: number
-): readonly BinarySnapshotColumn[] | undefined {
-  const versioned = handler.snapshotBinaryColumnsForVersion?.(schemaVersion);
-  return versioned === undefined
-    ? handler.snapshotBinaryColumns
-    : (versioned ?? undefined);
+/** §4.2 accept bitmask. */
+export const ACCEPT_INLINE_ROWS = 1 << 0;
+export const ACCEPT_EXTERNAL_ROWS = 1 << 1;
+export const ACCEPT_SQLITE = 1 << 2;
+export const ACCEPT_SIGNED_URLS = 1 << 3;
+
+export interface PullLimits {
+  readonly limitCommits: number;
+  readonly limitSnapshotRows: number;
+  readonly maxSnapshotPages: number;
+  readonly accept: number;
 }
 
-function resolveSnapshotBinaryEncoder<
-  DB extends SyncCoreDb,
-  Auth extends SyncServerAuth,
->(
-  handler: ServerTableHandler<DB, Auth>,
-  schemaVersion: number
-): BinarySnapshotRowsEncoder | undefined {
-  const versioned = handler.snapshotBinaryEncoderForVersion?.(schemaVersion);
-  return versioned === undefined
-    ? handler.snapshotBinaryEncoder
-    : (versioned ?? undefined);
+function clamp(value: number, min: number, max: number, dflt: number): number {
+  if (value === 0) return dflt;
+  return Math.min(max, Math.max(min, value));
 }
 
-function createPullBootstrapTimings(): PullBootstrapTimings {
+/** §4.2 defaults and silent clamps (the v1 values). */
+export function clampPullLimits(header: PullHeaderFrame): PullLimits {
   return {
-    snapshotQueryMs: 0,
-    binaryEncodeMs: 0,
-    chunkCacheLookupMs: 0,
-    artifactCacheLookupMs: 0,
-    chunkGzipMs: 0,
-    chunkHashMs: 0,
-    chunkPersistMs: 0,
+    limitCommits: clamp(header.limitCommits, 1, 1000, 1000),
+    limitSnapshotRows: clamp(header.limitSnapshotRows, 1, 50000, 1000),
+    maxSnapshotPages: clamp(header.maxSnapshotPages, 1, 50, 4),
+    accept: header.accept,
   };
 }
 
-function resolveBinarySnapshotBundleRowLimit(args: {
-  limitSnapshotRows: number;
-  pagesRemaining: number;
-}): number {
-  const pageSize = Math.max(1, args.limitSnapshotRows);
-  const pagesRemaining = Math.max(1, args.pagesRemaining);
-  const maxBundlePages = Math.max(
-    1,
-    Math.ceil(DEFAULT_MAX_BINARY_SNAPSHOT_BUNDLE_ROWS / pageSize)
-  );
-  return pageSize * Math.min(pagesRemaining, maxBundlePages);
-}
-
-async function gzipByteChunks(
-  chunks: readonly Uint8Array[],
-  gzipLevel: number
-): Promise<Uint8Array> {
-  return gzipBytes(concatByteChunks(chunks), {
-    level: gzipLevel,
-  });
+export interface SubscriptionPlan {
+  readonly frame: SubscriptionFrame;
+  readonly table: CompiledTable;
+  readonly status: 'active' | 'revoked';
+  readonly effective: ScopeMap;
 }
 
-async function encodeCompressedSnapshotChunk(
-  chunks: readonly Uint8Array[],
-  gzipLevel: number
-): Promise<SnapshotChunkEncodeResult> {
-  const gzipStartedAt = Date.now();
-  const body = await gzipByteChunks(chunks, gzipLevel);
-  const gzipMs = Math.max(0, Date.now() - gzipStartedAt);
-  const hashStartedAt = Date.now();
-  const sha256 = await sha256Hex(body);
-  const hashMs = Math.max(0, Date.now() - hashStartedAt);
-  return { body, sha256, gzipMs, hashMs };
+export interface SubscriptionResult {
+  readonly nextCursor: number;
+  readonly active: boolean;
 }
 
-async function encodeCompressedSnapshotChunkToStream(
-  chunks: readonly Uint8Array[],
-  gzipLevel: number
-): Promise<{
-  stream: ReadableStream<Uint8Array>;
-  byteLength: number;
-  sha256: string;
-  gzipMs: number;
-  hashMs: number;
-}> {
-  const encoded = await encodeCompressedSnapshotChunk(chunks, gzipLevel);
-  return {
-    stream: bytesToReadableStream(encoded.body),
-    byteLength: encoded.body.length,
-    sha256: encoded.sha256,
-    gzipMs: encoded.gzipMs,
-    hashMs: encoded.hashMs,
-  };
-}
-
-interface SnapshotColumnInference {
-  name: string;
-  type: BinarySnapshotColumnType | null;
-  nullable: boolean;
-  presentCount: number;
+/**
+ * Mutable per-section collector for the `pull.served` event. Only created
+ * when an events sink is configured — with `trace` undefined the pull path
+ * does zero extra work (`trace?.…` short-circuits argument evaluation).
+ */
+export interface PullSectionTrace {
+  readonly segments: PullSegmentSummary[];
 }
 
-function encodeBinarySnapshotRows(
-  table: string,
-  rows: readonly unknown[],
-  columns?: readonly BinarySnapshotColumn[]
-): Uint8Array {
-  const recordRows = rows.map((row) => toSnapshotRecordRow(table, row));
-  return encodeBinarySnapshotTable({
-    table,
-    columns: columns ?? inferBinarySnapshotColumns(recordRows),
-    rows: recordRows,
-  });
+interface BootstrapToken {
+  asOfCommitSeq: number;
+  tables: string[];
+  tableIndex: number;
+  rowCursor: string | null;
 }
 
-function toSnapshotRecordRow(
+function parseBootstrapToken(
+  raw: string | undefined,
   table: string,
-  row: unknown
-): Record<string, unknown> {
-  if (
-    row == null ||
-    typeof row !== 'object' ||
-    Array.isArray(row) ||
-    row instanceof Uint8Array ||
-    row instanceof ArrayBuffer
-  ) {
-    throw new Error(
-      `Cannot encode binary snapshot for table ${table}: snapshot rows must be objects`
-    );
-  }
-  return row as Record<string, unknown>;
-}
-
-function inferBinarySnapshotColumns(
-  rows: readonly Record<string, unknown>[]
-): BinarySnapshotColumn[] {
-  const columns: SnapshotColumnInference[] = [];
-  const columnsByName = new Map<string, SnapshotColumnInference>();
-
-  for (const row of rows) {
-    for (const name in row) {
-      if (!Object.hasOwn(row, name)) continue;
-      const value = row[name];
-      let column = columnsByName.get(name);
-      if (!column) {
-        column = { name, type: null, nullable: false, presentCount: 0 };
-        columnsByName.set(name, column);
-        columns.push(column);
-      }
-      column.presentCount += 1;
-      if (value == null) {
-        column.nullable = true;
-        continue;
-      }
-      column.type = mergeBinarySnapshotColumnTypes(
-        column.type,
-        inferBinarySnapshotColumnType(value)
-      );
+): BootstrapToken | undefined {
+  if (raw === undefined) return undefined;
+  try {
+    const parsed = JSON.parse(raw) as Partial<BootstrapToken>;
+    if (
+      typeof parsed.asOfCommitSeq !== 'number' ||
+      !Array.isArray(parsed.tables) ||
+      typeof parsed.tableIndex !== 'number' ||
+      (parsed.rowCursor !== null && typeof parsed.rowCursor !== 'string') ||
+      parsed.tables[0] !== table
+    ) {
+      return undefined;
     }
+    return {
+      asOfCommitSeq: parsed.asOfCommitSeq,
+      tables: parsed.tables as string[],
+      tableIndex: parsed.tableIndex,
+      rowCursor: parsed.rowCursor ?? null,
+    };
+  } catch {
+    return undefined;
   }
+}
 
-  return columns.map((column) => ({
-    name: column.name,
-    type: column.type ?? 'json',
-    ...(column.nullable || column.presentCount < rows.length
-      ? { nullable: true }
+function commitFrame(table: string, commit: StoredCommit): ResponseFrame {
+  const changes: CommitChange[] = commit.changes.map((change) => ({
+    tableIndex: 0,
+    rowId: change.rowId,
+    op: change.op,
+    ...(change.rowVersion !== undefined
+      ? { rowVersion: change.rowVersion }
       : {}),
+    scopes: change.scopes,
+    ...(change.payload !== undefined ? { row: change.payload } : {}),
   }));
+  return {
+    type: 'COMMIT',
+    commitSeq: commit.commitSeq,
+    createdAtMs: commit.createdAtMs,
+    actorId: commit.actorId,
+    tables: [table],
+    changes,
+  };
 }
 
-function inferBinarySnapshotColumnType(
-  value: unknown
-): BinarySnapshotColumnType {
-  if (typeof value === 'string') return 'string';
-  if (typeof value === 'boolean') return 'boolean';
-  if (typeof value === 'bigint') return 'integer';
-  if (typeof value === 'number') {
-    return Number.isSafeInteger(value) ? 'integer' : 'float';
-  }
-  if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
-    return 'bytes';
-  }
-  return 'json';
-}
-
-function mergeBinarySnapshotColumnTypes(
-  current: BinarySnapshotColumnType | null,
-  next: BinarySnapshotColumnType
-): BinarySnapshotColumnType {
-  if (!current || current === next) return next;
-  if (
-    (current === 'integer' && next === 'float') ||
-    (current === 'float' && next === 'integer')
-  ) {
-    return 'float';
+function chunkRows(rows: SegmentRow[], size: number): SegmentRow[][] {
+  if (rows.length === 0) return [];
+  const blocks: SegmentRow[][] = [];
+  for (let i = 0; i < rows.length; i += size) {
+    blocks.push(rows.slice(i, i + size));
   }
-  return 'json';
-}
-
-export interface PullResult {
-  response: SyncPullResponse;
-  /**
-   * Effective scopes for all active subscriptions (for cursor tracking).
-   * Maps subscription ID to effective scopes.
-   */
-  effectiveScopes: ScopeValues;
-  /** Minimum nextCursor across active subscriptions (for pruning cursor tracking). */
-  clientCursor: number;
-  /** Internal bootstrap timing breakdown used for benchmark-gated diagnostics. */
-  bootstrapTimings?: PullBootstrapTimings;
+  return blocks;
+}
+
+/** §5.4 signed-URL fields for a descriptor, when the client asked (bit 3). */
+async function signedUrlFields(
+  ctx: SyncRequestContext,
+  limits: PullLimits,
+  segmentId: string,
+  digest: string,
+  now: number,
+): Promise<{ url?: string; urlExpiresAtMs?: number }> {
+  if ((limits.accept & ACCEPT_SIGNED_URLS) === 0 || !ctx.signedUrls) return {};
+  return issueSegmentUrl(ctx.signedUrls, {
+    segmentId,
+    partition: ctx.partition,
+    scopeDigest: digest,
+    nowMs: now,
+  });
 }
 
-interface PendingExternalChunkWrite {
-  snapshot: SyncSnapshot;
-  cacheLookup: {
-    partitionId: string;
-    scopeKey: string;
-    scope: string;
-    asOfCommitSeq: number;
-    rowCursor: string | null;
-    rowLimit: number;
-    nextRowCursor: string | null;
-    isLastPage: boolean;
+function segmentRefFrame(
+  record: SegmentRecord,
+  extra: { url?: string; urlExpiresAtMs?: number },
+): ResponseFrame {
+  return {
+    type: 'SEGMENT_REF',
+    segmentId: record.segmentId,
+    mediaType: record.mediaType,
+    table: record.table,
+    byteLength: record.byteLength,
+    rowCount: record.rowCount,
+    asOfCommitSeq: record.asOfCommitSeq,
+    scopeDigest: record.scopeDigest,
+    ...(record.rowCursor !== null ? { rowCursor: record.rowCursor } : {}),
+    ...(record.nextRowCursor !== null
+      ? { nextRowCursor: record.nextRowCursor }
+      : {}),
+    ...(extra.url !== undefined ? { url: extra.url } : {}),
+    ...(extra.urlExpiresAtMs !== undefined
+      ? { urlExpiresAtMs: extra.urlExpiresAtMs }
+      : {}),
   };
-  payloadParts: Uint8Array[];
-  expiresAt: string;
-}
-
-async function runWithConcurrency<T>(
-  items: readonly T[],
-  concurrency: number,
-  worker: (item: T) => Promise<void>
-): Promise<void> {
-  if (items.length === 0) return;
-
-  const workerCount = Math.max(1, Math.min(concurrency, items.length));
-  let nextIndex = 0;
-
-  async function runWorker(): Promise<void> {
-    while (nextIndex < items.length) {
-      const index = nextIndex;
-      nextIndex += 1;
-      const item = items[index];
-      if (item === undefined) continue;
-      await worker(item);
-    }
-  }
-
-  await Promise.all(Array.from({ length: workerCount }, () => runWorker()));
 }
 
 /**
- * Sanitize a numeric limit parameter with bounds checking.
- * Handles NaN, negative values, and undefined.
+ * §5.3 sqlite-image lane: only at the start of a table, only when the
+ * client advertised bit 2, and only when the snapshot exceeds one rows
+ * page. Reuses an unexpired stored image for the same (partition, table,
+ * schemaVersion, scope digest, pin) instead of rebuilding — the
+ * bootstrap-storm rule. Returns false when the table is not eligible
+ * (the rows lane takes over).
  */
-function sanitizeLimit(
-  value: number | undefined,
-  defaultValue: number,
-  min: number,
-  max: number
-): number {
-  if (value === undefined || value === null) return defaultValue;
-  if (Number.isNaN(value)) return defaultValue;
-  return Math.max(min, Math.min(max, value));
-}
-
-function sanitizeGzipLevel(value: number | undefined): number {
-  if (value === undefined || value === null || !Number.isFinite(value)) {
-    return DEFAULT_SNAPSHOT_CHUNK_GZIP_LEVEL;
-  }
-  return Math.max(0, Math.min(9, Math.trunc(value)));
-}
-
-function isSerializablePullError(error: Error): boolean {
-  const withCode = error as Error & { code?: string };
-  return (
-    withCode.code === '40001' ||
-    error.message.toLowerCase().includes('could not serialize access')
+async function* sqliteImageSegment(
+  ctx: SyncRequestContext,
+  schema: CompiledSchema,
+  limits: PullLimits,
+  plan: SubscriptionPlan,
+  asOf: number,
+  digest: string,
+  trace: PullSectionTrace | undefined,
+): AsyncGenerator<ResponseFrame, boolean> {
+  const { storage, segments, partition } = ctx;
+  const now = clockOf(ctx)();
+  const existing = await segments.find(
+    {
+      partition,
+      table: plan.table.name,
+      schemaVersion: schema.version,
+      mediaType: 'sqlite',
+      scopeDigest: digest,
+      asOfCommitSeq: asOf,
+    },
+    now,
   );
-}
-
-async function delay(ms: number): Promise<void> {
-  await new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
-/**
- * Merge all scope values into a flat ScopeValues for cursor tracking.
- */
-function mergeScopes(subscriptions: { scopes: ScopeValues }[]): ScopeValues {
-  const result: Record<string, Set<string>> = {};
-
-  for (const sub of subscriptions) {
-    for (const [key, value] of Object.entries(sub.scopes)) {
-      if (!result[key]) result[key] = new Set();
-      const arr = Array.isArray(value) ? value : [value];
-      for (const v of arr) result[key].add(v);
-    }
-  }
-
-  const merged: ScopeValues = {};
-  for (const [key, set] of Object.entries(result)) {
-    const arr = Array.from(set);
-    if (arr.length === 0) continue;
-    merged[key] = arr.length === 1 ? arr[0]! : arr;
-  }
-  return merged;
-}
-
-interface PullResponseStats {
-  subscriptionCount: number;
-  activeSubscriptionCount: number;
-  revokedSubscriptionCount: number;
-  bootstrapSubscriptionCount: number;
-  commitCount: number;
-  changeCount: number;
-  snapshotPageCount: number;
-}
-
-function assertPullChangeIdentityUnchanged(
-  source: string,
-  before: SyncChange,
-  after: SyncChange
-): void {
-  if (before.table !== after.table) {
-    throw new Error(
-      `${source} cannot change change.table (${before.table} -> ${after.table})`
+  if (existing !== undefined) {
+    trace?.segments.push({
+      mediaType: 'sqlite',
+      delivery: 'ref',
+      origin: 'reused',
+      bytes: existing.byteLength,
+      rows: existing.rowCount,
+    });
+    yield segmentRefFrame(
+      existing,
+      await signedUrlFields(ctx, limits, existing.segmentId, digest, now),
     );
+    return true;
   }
-  if (before.row_id !== after.row_id) {
-    throw new Error(
-      `${source} cannot change change.row_id (${before.row_id} -> ${after.row_id})`
-    );
+  // Eligibility probe (§5.3): image only when the snapshot exceeds one
+  // rows page — smaller tables stay on the (typically inline) rows lane.
+  const probe = await storage.scanRows(partition, {
+    table: plan.table.name,
+    scopeFilter: plan.effective,
+    afterRowId: null,
+    limit: limits.limitSnapshotRows + 1,
+  });
+  if (probe.length <= limits.limitSnapshotRows) return false;
+  // §5.3: building an image needs a SQLite engine. The host injects the
+  // builder through `sqliteImageBuilder`; when omitted we default to the
+  // in-tree `buildSqliteImage` ONLY on a Bun runtime, reached by a *dynamic*
+  // import so `bun:sqlite` is never a static dependency of the pull path
+  // (TODO §4.2 neutrality — enforced by test/runtime-neutrality.test.ts). On
+  // Workers/edge (no `Bun`) this yields the rows lane for a bit-2 client — a
+  // support floor, not a fallback (§5.3: sqlite is an *accept*, not a demand).
+  const buildImage = await resolveImageBuilder(ctx);
+  if (buildImage === undefined) return false;
+  // The probe rows are the snapshot's first page — keep them and scan on
+  // from the probe's cursor instead of re-reading the whole prefix (the
+  // scan is keyset-ordered by rowId, so the concatenation is exactly the
+  // rows a single full scan would return).
+  const rows: StoredRow[] = [...probe];
+  let afterRowId: string | null = probe[probe.length - 1]?.rowId ?? null;
+  for (;;) {
+    const scanned: StoredRow[] = await storage.scanRows(partition, {
+      table: plan.table.name,
+      scopeFilter: plan.effective,
+      afterRowId,
+      limit: 50_000,
+    });
+    rows.push(...scanned);
+    const last = scanned[scanned.length - 1];
+    if (scanned.length < 50_000 || last === undefined) break;
+    afterRowId = last.rowId;
   }
-  if (before.op !== after.op) {
-    throw new Error(
-      `${source} cannot change change.op (${before.op} -> ${after.op})`
+  const bytes = buildImage({
+    table: plan.table,
+    schemaVersion: schema.version,
+    asOfCommitSeq: asOf,
+    scopeDigest: digest,
+    rows,
+  });
+  const record = await segments.put(
+    {
+      partition,
+      table: plan.table.name,
+      schemaVersion: schema.version,
+      mediaType: 'sqlite',
+      scopeDigest: digest,
+      asOfCommitSeq: asOf,
+      rowCount: rows.length,
+      rowCursor: null,
+      nextRowCursor: null,
+    },
+    bytes,
+    now,
+  );
+  trace?.segments.push({
+    mediaType: 'sqlite',
+    delivery: 'ref',
+    origin: 'built',
+    bytes: record.byteLength,
+    rows: record.rowCount,
+  });
+  yield segmentRefFrame(
+    record,
+    await signedUrlFields(ctx, limits, record.segmentId, digest, now),
+  );
+  return true;
+}
+
+async function* bootstrapSegments(
+  ctx: SyncRequestContext,
+  schema: CompiledSchema,
+  limits: PullLimits,
+  plan: SubscriptionPlan,
+  asOf: number,
+  startRowCursor: string | null,
+  trace: PullSectionTrace | undefined,
+): AsyncGenerator<
+  ResponseFrame,
+  { complete: boolean; rowCursor: string | null }
+> {
+  const { storage, segments, partition } = ctx;
+  const serverLimits = limitsOf(ctx);
+  const digest = await scopeDigest(plan.effective);
+  const now = clockOf(ctx)();
+  // §5.3: the sqlite-image lane — whole-table, chosen only at the start
+  // of a table (a mid-table resume stays on the rows lane, never
+  // switching lanes), and only when the client advertised bit 2.
+  // §5.11: a table with any encrypted column is image-INELIGIBLE — an image
+  // copies ciphertext wholesale with no per-row decrypt pass, so it MUST be
+  // served on the rows lane (which decrypts per row on the client).
+  if (
+    (limits.accept & ACCEPT_SQLITE) !== 0 &&
+    startRowCursor === null &&
+    plan.table.encryptedColumnIndices.length === 0
+  ) {
+    const imaged = yield* sqliteImageSegment(
+      ctx,
+      schema,
+      limits,
+      plan,
+      asOf,
+      digest,
+      trace,
     );
+    if (imaged) return { complete: true, rowCursor: null };
   }
-}
-
-function projectPullChangeForClientSchema<
-  DB extends SyncCoreDb,
-  Auth extends SyncServerAuth,
->(args: {
-  handler: ServerTableHandler<DB, Auth>;
-  change: SyncChange;
-  schemaVersion: number;
-}): SyncChange {
-  const projected = args.handler.projectChangeForVersion
-    ? args.handler.projectChangeForVersion(args.change, args.schemaVersion)
-    : args.change;
-  assertPullChangeIdentityUnchanged(
-    'Server table handler projectChangeForVersion',
-    args.change,
-    projected
-  );
-  return projected;
-}
-
-async function transformPullChanges<
-  DB extends SyncCoreDb,
-  Auth extends SyncServerAuth,
->(args: {
-  plugins: readonly SyncServerPullPlugin<DB, Auth>[];
-  ctx: { db: DbExecutor<DB>; actorId: string; auth: Auth };
-  tableHandler: ServerTableHandler<DB, Auth>;
-  subscription: {
-    id: string;
-    table: string;
-    scopes: ScopeValues;
-    params: Record<string, unknown> | undefined;
-    cursor: number;
-    crdtStateVectors: readonly SyncCrdtStateVectorHint[];
-  };
-  changes: readonly SyncChange[];
-}): Promise<SyncChange[]> {
-  let changes = [...args.changes];
-  for (const plugin of args.plugins) {
-    if (!plugin.transformPullChanges) continue;
-    const nextChanges = await plugin.transformPullChanges({
-      ctx: args.ctx,
-      tableHandler: args.tableHandler,
-      subscription: args.subscription,
-      changes,
+  let rowCursor = startRowCursor;
+  for (let page = 0; page < limits.maxSnapshotPages; page++) {
+    const scanned = await storage.scanRows(partition, {
+      table: plan.table.name,
+      scopeFilter: plan.effective,
+      afterRowId: rowCursor,
+      limit: limits.limitSnapshotRows + 1,
+    });
+    const pageRows = scanned.slice(0, limits.limitSnapshotRows);
+    const hasMore = scanned.length > limits.limitSnapshotRows;
+    // §5.2: every row record carries the row's current server_version.
+    const decoded = pageRows.map((row: StoredRow) => ({
+      serverVersion: row.serverVersion,
+      values: decodeRow(plan.table.columns, row.payload),
+    }));
+    const bytes = encodeRowsSegment({
+      table: plan.table.name,
+      schemaVersion: schema.version,
+      columns: plan.table.columns,
+      blocks: chunkRows(decoded, 1000),
     });
-    if (nextChanges.length !== changes.length) {
-      throw new Error(
-        `Server pull plugin "${plugin.name}" cannot change pull change count (${changes.length} -> ${nextChanges.length})`
+    const lastRow = pageRows[pageRows.length - 1];
+    const nextRowCursor =
+      hasMore && lastRow !== undefined ? lastRow.rowId : null;
+
+    const canInline = (limits.accept & ACCEPT_INLINE_ROWS) !== 0;
+    const canExternal = (limits.accept & ACCEPT_EXTERNAL_ROWS) !== 0;
+    const inline =
+      canInline &&
+      (bytes.length <= serverLimits.inlineSegmentMaxBytes || !canExternal);
+    if (inline) {
+      trace?.segments.push({
+        mediaType: 'rows',
+        delivery: 'inline',
+        origin: 'built',
+        bytes: bytes.length,
+        rows: pageRows.length,
+      });
+      yield { type: 'SEGMENT_INLINE', payload: bytes };
+    } else {
+      const record = await segments.put(
+        {
+          partition,
+          table: plan.table.name,
+          schemaVersion: schema.version,
+          mediaType: 'rows',
+          scopeDigest: digest,
+          asOfCommitSeq: asOf,
+          rowCount: pageRows.length,
+          rowCursor,
+          nextRowCursor,
+        },
+        bytes,
+        now,
       );
-    }
-    for (let i = 0; i < changes.length; i += 1) {
-      assertPullChangeIdentityUnchanged(
-        `Server pull plugin "${plugin.name}"`,
-        changes[i]!,
-        nextChanges[i]!
+      trace?.segments.push({
+        mediaType: 'rows',
+        delivery: 'ref',
+        origin: 'built',
+        bytes: record.byteLength,
+        rows: record.rowCount,
+      });
+      yield segmentRefFrame(
+        record,
+        await signedUrlFields(ctx, limits, record.segmentId, digest, now),
       );
     }
-    changes = [...nextChanges];
+    if (!hasMore) return { complete: true, rowCursor: null };
+    rowCursor = nextRowCursor;
   }
-  return changes;
+  return { complete: false, rowCursor };
 }
 
-function summarizePullResponse(response: SyncPullResponse): PullResponseStats {
-  const subscriptions = response.subscriptions ?? [];
-  let activeSubscriptionCount = 0;
-  let revokedSubscriptionCount = 0;
-  let bootstrapSubscriptionCount = 0;
-  let commitCount = 0;
-  let changeCount = 0;
-  let snapshotPageCount = 0;
-
-  for (const sub of subscriptions) {
-    if (sub.status === 'revoked') {
-      revokedSubscriptionCount += 1;
-    } else {
-      activeSubscriptionCount += 1;
-    }
+/**
+ * Produce the `SUB_START … SUB_END` section for one subscription (§1.6),
+ * returning the cursor recorded for the retention watermark (§4.5).
+ */
+export async function* subscriptionSection(
+  ctx: SyncRequestContext,
+  schema: CompiledSchema,
+  limits: PullLimits,
+  plan: SubscriptionPlan,
+  maxSeq: number,
+  horizonSeq: number,
+  trace?: PullSectionTrace,
+): AsyncGenerator<ResponseFrame, SubscriptionResult> {
+  const sub = plan.frame;
+
+  if (plan.status === 'revoked') {
+    yield {
+      type: 'SUB_START',
+      id: sub.id,
+      status: 'revoked',
+      reasonCode: 'sync.scope_revoked',
+      effectiveScopes: {},
+      bootstrap: false,
+    };
+    yield { type: 'SUB_END', nextCursor: sub.cursor };
+    return { nextCursor: sub.cursor, active: false };
+  }
 
-    if (sub.bootstrap) {
-      bootstrapSubscriptionCount += 1;
-    }
+  const token = parseBootstrapToken(sub.bootstrapState, sub.table);
+
+  // §4.6: a cursor behind the horizon (and not resuming a bootstrap)
+  // cannot compute deltas — answer `reset` and echo the cursor.
+  if (token === undefined && sub.cursor >= 0 && sub.cursor < horizonSeq) {
+    yield {
+      type: 'SUB_START',
+      id: sub.id,
+      status: 'reset',
+      reasonCode: 'sync.cursor_expired',
+      effectiveScopes: {},
+      bootstrap: false,
+    };
+    yield { type: 'SUB_END', nextCursor: sub.cursor };
+    return { nextCursor: sub.cursor, active: false };
+  }
 
-    const commits = sub.commits ?? [];
-    commitCount += commits.length;
-    for (const commit of commits) {
-      changeCount += commit.changes?.length ?? 0;
+  const bootstrapping =
+    token !== undefined || sub.cursor < 0 || sub.cursor > maxSeq;
+
+  if (bootstrapping) {
+    // §4.7: resume at the pinned point unless the pin fell behind the
+    // horizon (or the token is unusable) — then restart from a fresh pin.
+    const resume =
+      token !== undefined && token.asOfCommitSeq >= horizonSeq
+        ? token
+        : undefined;
+    const asOf = resume?.asOfCommitSeq ?? maxSeq;
+    const startCursor = resume?.rowCursor ?? null;
+    yield {
+      type: 'SUB_START',
+      id: sub.id,
+      status: 'active',
+      reasonCode: '',
+      effectiveScopes: plan.effective,
+      bootstrap: true,
+    };
+    const outcome = yield* bootstrapSegments(
+      ctx,
+      schema,
+      limits,
+      plan,
+      asOf,
+      startCursor,
+      trace,
+    );
+    if (outcome.complete) {
+      yield { type: 'SUB_END', nextCursor: asOf };
+    } else {
+      const nextToken: BootstrapToken = {
+        asOfCommitSeq: asOf,
+        tables: [sub.table],
+        tableIndex: 0,
+        rowCursor: outcome.rowCursor,
+      };
+      yield {
+        type: 'SUB_END',
+        nextCursor: asOf,
+        bootstrapState: JSON.stringify(nextToken),
+      };
     }
-
-    snapshotPageCount += sub.snapshots?.length ?? 0;
+    return { nextCursor: asOf, active: true };
   }
 
-  return {
-    subscriptionCount: subscriptions.length,
-    activeSubscriptionCount,
-    revokedSubscriptionCount,
-    bootstrapSubscriptionCount,
-    commitCount,
-    changeCount,
-    snapshotPageCount,
-  };
-}
-
-function recordPullMetrics(args: {
-  status: string;
-  dedupeRows: boolean;
-  durationMs: number;
-  stats: PullResponseStats;
-}): void {
-  const { status, dedupeRows, durationMs, stats } = args;
-  const attributes = {
-    status,
-    dedupe_rows: dedupeRows,
+  // Incremental (§4.5): window cursor < commitSeq <= maxSeq, oldest first,
+  // cut off at limitCommits total changes, never splitting a commit.
+  yield {
+    type: 'SUB_START',
+    id: sub.id,
+    status: 'active',
+    reasonCode: '',
+    effectiveScopes: plan.effective,
+    bootstrap: false,
   };
-
-  countSyncMetric('sync.server.pull.requests', 1, { attributes });
-  distributionSyncMetric('sync.server.pull.duration_ms', durationMs, {
-    unit: 'millisecond',
-    attributes,
-  });
-  distributionSyncMetric(
-    'sync.server.pull.subscriptions',
-    stats.subscriptionCount,
-    { attributes }
-  );
-  distributionSyncMetric(
-    'sync.server.pull.active_subscriptions',
-    stats.activeSubscriptionCount,
-    { attributes }
-  );
-  distributionSyncMetric(
-    'sync.server.pull.revoked_subscriptions',
-    stats.revokedSubscriptionCount,
-    { attributes }
-  );
-  distributionSyncMetric(
-    'sync.server.pull.bootstrap_subscriptions',
-    stats.bootstrapSubscriptionCount,
-    { attributes }
-  );
-  distributionSyncMetric('sync.server.pull.commits', stats.commitCount, {
-    attributes,
+  const commits = await ctx.storage.readCommitWindow(ctx.partition, {
+    table: sub.table,
+    scopeFilter: plan.effective,
+    afterSeq: sub.cursor,
+    throughSeq: maxSeq,
+    limitChanges: limits.limitCommits + 1,
   });
-  distributionSyncMetric('sync.server.pull.changes', stats.changeCount, {
-    attributes,
-  });
-  distributionSyncMetric(
-    'sync.server.pull.snapshot_pages',
-    stats.snapshotPageCount,
-    { attributes }
-  );
-}
-
-async function readLatestExternalCommitByTable<DB extends SyncCoreDb>(
-  trx: DbExecutor<DB>,
-  args: { partitionId: string; afterCursor: number; tables: string[] }
-): Promise<Map<string, number>> {
-  const tableNames = Array.from(
-    new Set(args.tables.filter((table) => typeof table === 'string'))
-  );
-  const latestByTable = new Map<string, number>();
-  if (tableNames.length === 0) {
-    return latestByTable;
-  }
-
-  type SyncExecutor = Pick<Kysely<SyncCoreDb>, 'selectFrom'>;
-  const executor = trx as SyncExecutor;
-  const rows = await executor
-    .selectFrom('sync_table_commits as tc')
-    .innerJoin('sync_commits as cm', (join) =>
-      join
-        .onRef('cm.commit_seq', '=', 'tc.commit_seq')
-        .onRef('cm.partition_id', '=', 'tc.partition_id')
-    )
-    .select(['tc.table as table'])
-    .select((eb) => eb.fn.max('tc.commit_seq').as('latest_commit_seq'))
-    .where('tc.partition_id', '=', args.partitionId)
-    .where('cm.client_id', '=', EXTERNAL_CLIENT_ID)
-    .where('cm.change_count', '=', 0)
-    .where('tc.commit_seq', '>', args.afterCursor)
-    .where('tc.table', 'in', tableNames)
-    .groupBy('tc.table')
-    .execute();
-
-  for (const row of rows) {
-    const commitSeq = Number(row.latest_commit_seq ?? -1);
-    if (!Number.isFinite(commitSeq) || commitSeq < 0) continue;
-    latestByTable.set(row.table, commitSeq);
-  }
-
-  return latestByTable;
-}
-
-export async function pull<
-  DB extends SyncCoreDb,
-  Auth extends SyncServerAuth,
->(args: {
-  db: Kysely<DB>;
-  dialect: ServerSyncDialect;
-  handlers: ServerHandlerCollection<DB, Auth>;
-  auth: Auth;
-  request: SyncPullRequest;
-  /**
-   * Optional snapshot chunk storage adapter.
-   * When provided, stores chunk bodies in external storage (S3, etc.)
-   * instead of inline in the database.
-   */
-  chunkStorage?: SnapshotChunkStorage;
-  /**
-   * Optional shared scope cache backend.
-   * Request-local memoization is always applied, even with custom backends.
-   * Defaults to process-local memory cache.
-   */
-  scopeCache?: ScopeCacheBackend;
-  /**
-   * Gzip compression level for generated snapshot chunks. The protocol remains
-   * gzip-only; this tunes CPU/size tradeoffs for deployments that know their
-   * network constraints.
-   *
-   * Default: 1, range: 0-9.
-   */
-  snapshotChunkGzipLevel?: number;
-  /**
-   * Schema/cache semantic version included in generated snapshot chunk cache
-   * keys. Changing this value invalidates cached bootstrap chunks without
-   * requiring table data to change.
-   */
-  snapshotChunkCacheSchemaVersion?: number | string | null;
-  /**
-   * Optional server plugins for protocol-level pull transforms.
-   */
-  plugins?: readonly SyncServerPullPlugin<DB, Auth>[];
-}): Promise<PullResult> {
-  const { request, dialect } = args;
-  const db = args.db;
-  const pullPlugins = sortServerPullPlugins(args.plugins);
-  const partitionId = args.auth.partitionId ?? 'default';
-  const snapshotChunkGzipLevel = sanitizeGzipLevel(args.snapshotChunkGzipLevel);
-  const clientSchemaVersion = request.schemaVersion;
-  if (!Number.isInteger(clientSchemaVersion) || clientSchemaVersion < 1) {
-    throw new Error('Pull request schemaVersion must be a positive integer');
-  }
-  const snapshotChunkCacheSchemaVersion =
-    args.snapshotChunkCacheSchemaVersion === null ||
-    args.snapshotChunkCacheSchemaVersion === undefined
-      ? clientSchemaVersion
-      : `${clientSchemaVersion}:${args.snapshotChunkCacheSchemaVersion}`;
-  const requestedSubscriptionCount = Array.isArray(request.subscriptions)
-    ? request.subscriptions.length
-    : 0;
-  const startedAtMs = Date.now();
-
-  return startSyncSpan(
-    {
-      name: 'sync.server.pull',
-      op: 'sync.pull',
-      attributes: {
-        requested_subscription_count: requestedSubscriptionCount,
-        dedupe_rows: request.dedupeRows === true,
-      },
-    },
-    async (span) => {
-      try {
-        // Validate and sanitize request limits
-        const limitCommits = sanitizeLimit(request.limitCommits, 1000, 1, 1000);
-        const limitSnapshotRows = sanitizeLimit(
-          request.limitSnapshotRows,
-          1000,
-          1,
-          50000
-        );
-        const maxSnapshotPages = sanitizeLimit(
-          request.maxSnapshotPages,
-          4,
-          1,
-          50
-        );
-        const dedupeRows = request.dedupeRows === true;
-        const snapshotChunkEncoding = SYNC_SNAPSHOT_CHUNK_ENCODING;
-        const snapshotArtifactSelection = resolveSnapshotArtifactSelection(
-          request.snapshotArtifacts,
-          clientSchemaVersion
-        );
-        const snapshotArtifactSchemaVersion =
-          snapshotArtifactSelection?.schemaVersion ?? null;
-        // Resolve effective scopes for each subscription
-        const resolved = await resolveEffectiveScopesForSubscriptions({
-          db,
-          auth: args.auth,
-          subscriptions: request.subscriptions ?? [],
-          handlers: args.handlers,
-          scopeCache: args.scopeCache ?? defaultScopeCache,
-        });
-
-        for (
-          let attemptIndex = 0;
-          attemptIndex < MAX_PULL_TRANSACTION_RETRIES;
-          attemptIndex += 1
-        ) {
-          const pendingExternalChunkWrites: PendingExternalChunkWrite[] = [];
-          const bootstrapTimings = createPullBootstrapTimings();
-
-          try {
-            const result = await dialect.executeInTransaction(
-              db,
-              async (trx) => {
-                await dialect.setRepeatableRead(trx);
-
-                const maxCommitSeq = await dialect.readMaxCommitSeq(trx, {
-                  partitionId,
-                });
-                const minCommitSeq = await dialect.readMinCommitSeq(trx, {
-                  partitionId,
-                });
-
-                const subResponses: SyncPullSubscriptionResponse[] = [];
-                const activeSubscriptions: { scopes: ScopeValues }[] = [];
-                const nextCursors: number[] = [];
-
-                // Detect external data changes (synthetic commits from notifyExternalDataChange)
-                // Compute minimum cursor across all active subscriptions to scope the query.
-                let minSubCursor = Number.MAX_SAFE_INTEGER;
-                const activeTables = new Set<string>();
-                for (const sub of resolved) {
-                  if (
-                    sub.status === 'revoked' ||
-                    Object.keys(sub.scopes).length === 0
-                  )
-                    continue;
-                  activeTables.add(sub.table);
-                  const cursor = Math.max(-1, sub.cursor ?? -1);
-                  if (cursor >= 0 && cursor < minSubCursor) {
-                    minSubCursor = cursor;
-                  }
-                }
-
-                const maxExternalCommitByTable =
-                  minSubCursor < Number.MAX_SAFE_INTEGER && minSubCursor >= 0
-                    ? await readLatestExternalCommitByTable(trx, {
-                        partitionId,
-                        afterCursor: minSubCursor,
-                        tables: Array.from(activeTables),
-                      })
-                    : new Map<string, number>();
-
-                for (const sub of resolved) {
-                  const cursor = Math.max(-1, sub.cursor ?? -1);
-                  // Validate table handler exists (throws if not registered)
-                  if (!args.handlers.byTable.has(sub.table)) {
-                    throw new Error(`Unknown table: ${sub.table}`);
-                  }
-
-                  if (
-                    sub.status === 'revoked' ||
-                    Object.keys(sub.scopes).length === 0
-                  ) {
-                    subResponses.push({
-                      id: sub.id,
-                      status: 'revoked',
-                      scopes: {},
-                      bootstrap: false,
-                      nextCursor: cursor,
-                      commits: [],
-                    });
-                    continue;
-                  }
-
-                  const effectiveScopes = sub.scopes;
-                  activeSubscriptions.push({ scopes: effectiveScopes });
-                  const latestExternalCommitForTable =
-                    maxExternalCommitByTable.get(sub.table);
-
-                  const needsBootstrap =
-                    sub.bootstrapState != null ||
-                    cursor < 0 ||
-                    cursor > maxCommitSeq ||
-                    (minCommitSeq > 0 && cursor < minCommitSeq - 1) ||
-                    (latestExternalCommitForTable !== undefined &&
-                      latestExternalCommitForTable > cursor);
-
-                  if (needsBootstrap) {
-                    const tables = getServerBootstrapOrderFor(
-                      args.handlers,
-                      sub.table
-                    ).map((handler) => handler.table);
-                    const initState: SyncBootstrapState = {
-                      asOfCommitSeq: maxCommitSeq,
-                      tables,
-                      tableIndex: 0,
-                      rowCursor: null,
-                    };
-
-                    const requestedState = sub.bootstrapState ?? null;
-                    const state =
-                      requestedState &&
-                      typeof requestedState.asOfCommitSeq === 'number' &&
-                      Array.isArray(requestedState.tables) &&
-                      typeof requestedState.tableIndex === 'number'
-                        ? (requestedState as SyncBootstrapState)
-                        : initState;
-
-                    // If the bootstrap state's asOfCommitSeq is no longer catch-up-able, restart bootstrap.
-                    const effectiveState =
-                      state.asOfCommitSeq < minCommitSeq - 1
-                        ? initState
-                        : state;
-
-                    const tableName =
-                      effectiveState.tables[effectiveState.tableIndex];
-
-                    // No tables (or ran past the end): treat bootstrap as complete.
-                    if (!tableName) {
-                      subResponses.push({
-                        id: sub.id,
-                        status: 'active',
-                        scopes: effectiveScopes,
-                        bootstrap: true,
-                        bootstrapState: null,
-                        nextCursor: effectiveState.asOfCommitSeq,
-                        commits: [],
-                        snapshots: [],
-                      });
-                      nextCursors.push(effectiveState.asOfCommitSeq);
-                      continue;
-                    }
-
-                    const snapshots: SyncSnapshot[] = [];
-                    let nextState: SyncBootstrapState | null = effectiveState;
-                    const cacheKey = await createSnapshotChunkScopeCacheKey({
-                      partitionId,
-                      scopes: effectiveScopes,
-                      schemaVersion: snapshotChunkCacheSchemaVersion,
-                      encoding: snapshotChunkEncoding,
-                      compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-                      gzipLevel: snapshotChunkGzipLevel,
-                    });
-                    const artifactScopeKey =
-                      snapshotArtifactSelection && snapshotArtifactSchemaVersion
-                        ? await createScopedSnapshotArtifactScopeCacheKey({
-                            partitionId,
-                            subscriptionId: sub.id,
-                            scopes: effectiveScopes,
-                            schemaVersion: snapshotArtifactSchemaVersion,
-                            artifactKind:
-                              snapshotArtifactSelection.artifactKind,
-                            compression: snapshotArtifactSelection.compression,
-                            features: snapshotArtifactSelection.featureSet,
-                          })
-                        : null;
-
-                    interface SnapshotBundle {
-                      table: string;
-                      tableIndex: number;
-                      startCursor: string | null;
-                      nextRowCursor: string | null;
-                      isFirstPage: boolean;
-                      isLastPage: boolean;
-                      pageCount: number;
-                      cacheRowLimit: number | null;
-                      ttlMs: number;
-                      binaryColumns?: readonly BinarySnapshotColumn[];
-                      binaryEncoder?: BinarySnapshotRowsEncoder;
-                      binaryRows: unknown[];
-                    }
-
-                    const createSnapshotBundle = (
-                      table: string,
-                      tableIndex: number,
-                      rowCursor: string | null,
-                      ttlMs: number,
-                      binaryColumns?: readonly BinarySnapshotColumn[],
-                      binaryEncoder?: BinarySnapshotRowsEncoder
-                    ): SnapshotBundle => {
-                      return {
-                        table,
-                        tableIndex,
-                        startCursor: rowCursor,
-                        nextRowCursor: null,
-                        isFirstPage: rowCursor == null,
-                        isLastPage: false,
-                        pageCount: 0,
-                        cacheRowLimit: null,
-                        ttlMs,
-                        binaryColumns,
-                        binaryEncoder,
-                        binaryRows: [],
-                      };
-                    };
-
-                    const snapshotBootstrapStateAfter = (args: {
-                      tableIndex: number;
-                      nextRowCursor: string | null;
-                      isLastPage: boolean;
-                    }): SyncBootstrapState | null => {
-                      if (!args.isLastPage) {
-                        return {
-                          ...effectiveState,
-                          tableIndex: args.tableIndex,
-                          rowCursor: args.nextRowCursor,
-                        };
-                      }
-                      if (args.tableIndex + 1 < effectiveState.tables.length) {
-                        return {
-                          ...effectiveState,
-                          tableIndex: args.tableIndex + 1,
-                          rowCursor: null,
-                        };
-                      }
-                      return null;
-                    };
-
-                    const encodeSnapshotBundlePayload = (
-                      bundle: SnapshotBundle
-                    ): Uint8Array[] => {
-                      const encodeStartedAt = Date.now();
-                      const payload = bundle.binaryEncoder
-                        ? bundle.binaryEncoder(bundle.binaryRows)
-                        : encodeBinarySnapshotRows(
-                            bundle.table,
-                            bundle.binaryRows,
-                            bundle.binaryColumns
-                          );
-                      bootstrapTimings.binaryEncodeMs += Math.max(
-                        0,
-                        Date.now() - encodeStartedAt
-                      );
-                      return [payload];
-                    };
-
-                    const flushSnapshotBundle = async (
-                      bundle: SnapshotBundle
-                    ): Promise<void> => {
-                      const nowIso = new Date().toISOString();
-                      const bundleRowLimit = Math.max(
-                        1,
-                        bundle.cacheRowLimit ??
-                          limitSnapshotRows * bundle.pageCount
-                      );
-
-                      const cacheLookupStartedAt = Date.now();
-                      const cached = await readSnapshotChunkRefByPageKey(trx, {
-                        partitionId,
-                        scopeKey: cacheKey,
-                        scope: bundle.table,
-                        asOfCommitSeq: effectiveState.asOfCommitSeq,
-                        rowCursor: bundle.startCursor,
-                        rowLimit: bundleRowLimit,
-                        encoding: snapshotChunkEncoding,
-                        compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-                        nowIso,
-                      });
-                      bootstrapTimings.chunkCacheLookupMs += Math.max(
-                        0,
-                        Date.now() - cacheLookupStartedAt
-                      );
-
-                      let chunkRef: SyncSnapshotChunkRef | null = cached;
-                      if (!chunkRef) {
-                        const expiresAt = new Date(
-                          Date.now() + Math.max(1000, bundle.ttlMs)
-                        ).toISOString();
-
-                        if (args.chunkStorage) {
-                          const snapshot: SyncSnapshot = {
-                            table: bundle.table,
-                            rows: [],
-                            chunks: [],
-                            isFirstPage: bundle.isFirstPage,
-                            isLastPage: bundle.isLastPage,
-                            bootstrapStateAfter: snapshotBootstrapStateAfter({
-                              tableIndex: bundle.tableIndex,
-                              nextRowCursor: bundle.nextRowCursor,
-                              isLastPage: bundle.isLastPage,
-                            }),
-                          };
-                          snapshots.push(snapshot);
-                          pendingExternalChunkWrites.push({
-                            snapshot,
-                            cacheLookup: {
-                              partitionId,
-                              scopeKey: cacheKey,
-                              scope: bundle.table,
-                              asOfCommitSeq: effectiveState.asOfCommitSeq,
-                              rowCursor: bundle.startCursor,
-                              rowLimit: bundleRowLimit,
-                              nextRowCursor: bundle.nextRowCursor,
-                              isLastPage: bundle.isLastPage,
-                            },
-                            payloadParts: encodeSnapshotBundlePayload(bundle),
-                            expiresAt,
-                          });
-                          return;
-                        }
-                        const encodedChunk =
-                          await encodeCompressedSnapshotChunk(
-                            encodeSnapshotBundlePayload(bundle),
-                            snapshotChunkGzipLevel
-                          );
-                        bootstrapTimings.chunkGzipMs += encodedChunk.gzipMs;
-                        bootstrapTimings.chunkHashMs += encodedChunk.hashMs;
-                        const chunkId = randomId();
-                        const chunkPersistStartedAt = Date.now();
-                        chunkRef = await insertSnapshotChunk(trx, {
-                          chunkId,
-                          partitionId,
-                          scopeKey: cacheKey,
-                          scope: bundle.table,
-                          asOfCommitSeq: effectiveState.asOfCommitSeq,
-                          rowCursor: bundle.startCursor,
-                          rowLimit: bundleRowLimit,
-                          nextRowCursor: bundle.nextRowCursor,
-                          isLastPage: bundle.isLastPage,
-                          encoding: snapshotChunkEncoding,
-                          compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-                          sha256: encodedChunk.sha256,
-                          body: encodedChunk.body,
-                          expiresAt,
-                        });
-                        bootstrapTimings.chunkPersistMs += Math.max(
-                          0,
-                          Date.now() - chunkPersistStartedAt
-                        );
-                      }
-
-                      const chunk = toResponseChunkRef(chunkRef);
-                      snapshots.push({
-                        table: bundle.table,
-                        rows: [],
-                        chunks: [chunk],
-                        manifest: await createChunkedSnapshotManifest({
-                          table: bundle.table,
-                          asOfCommitSeq: effectiveState.asOfCommitSeq,
-                          scopeKey: cacheKey,
-                          rowCursor: bundle.startCursor,
-                          rowLimit: bundleRowLimit,
-                          nextRowCursor: bundle.nextRowCursor,
-                          isFirstPage: bundle.isFirstPage,
-                          isLastPage: bundle.isLastPage,
-                          chunks: [chunk],
-                        }),
-                        isFirstPage: bundle.isFirstPage,
-                        isLastPage: bundle.isLastPage,
-                        bootstrapStateAfter: snapshotBootstrapStateAfter({
-                          tableIndex: bundle.tableIndex,
-                          nextRowCursor: bundle.nextRowCursor,
-                          isLastPage: bundle.isLastPage,
-                        }),
-                      });
-                    };
-
-                    let activeBundle: SnapshotBundle | null = null;
-
-                    for (
-                      let pageIndex = 0;
-                      pageIndex < maxSnapshotPages;
-                      pageIndex++
-                    ) {
-                      if (!nextState) break;
-
-                      const nextTableName: string | undefined =
-                        nextState.tables[nextState.tableIndex];
-                      if (!nextTableName) {
-                        if (activeBundle) {
-                          activeBundle.isLastPage = true;
-                          await flushSnapshotBundle(activeBundle);
-                          activeBundle = null;
-                        }
-                        nextState = null;
-                        break;
-                      }
-
-                      const tableHandler =
-                        args.handlers.byTable.get(nextTableName);
-                      if (!tableHandler) {
-                        throw new Error(`Unknown table: ${nextTableName}`);
-                      }
-                      if (
-                        !activeBundle ||
-                        activeBundle.table !== nextTableName
-                      ) {
-                        if (activeBundle) {
-                          await flushSnapshotBundle(activeBundle);
-                        }
-                        activeBundle = createSnapshotBundle(
-                          nextTableName,
-                          nextState.tableIndex,
-                          nextState.rowCursor,
-                          tableHandler.snapshotChunkTtlMs ??
-                            24 * 60 * 60 * 1000,
-                          resolveSnapshotBinaryColumns(
-                            tableHandler,
-                            clientSchemaVersion
-                          ),
-                          resolveSnapshotBinaryEncoder(
-                            tableHandler,
-                            clientSchemaVersion
-                          )
-                        );
-                      }
-
-                      if (artifactScopeKey && activeBundle.pageCount === 0) {
-                        const pagesRemaining = Math.max(
-                          1,
-                          maxSnapshotPages - pageIndex
-                        );
-                        const artifactRowLimit =
-                          resolveBinarySnapshotBundleRowLimit({
-                            limitSnapshotRows,
-                            pagesRemaining,
-                          });
-                        const artifactLookupStartedAt = Date.now();
-                        const artifact =
-                          await readBestScopedSnapshotArtifactRefForPageCapacity(
-                            trx,
-                            {
-                              partitionId,
-                              scopeKey: artifactScopeKey,
-                              subscriptionId: sub.id,
-                              table: nextTableName,
-                              asOfCommitSeq: effectiveState.asOfCommitSeq,
-                              rowCursor: nextState.rowCursor,
-                              maxRowLimit: artifactRowLimit,
-                              artifactKind:
-                                snapshotArtifactSelection!.artifactKind,
-                              schemaVersion: snapshotArtifactSchemaVersion!,
-                              compression:
-                                snapshotArtifactSelection!.compression,
-                            }
-                          );
-                        bootstrapTimings.artifactCacheLookupMs += Math.max(
-                          0,
-                          Date.now() - artifactLookupStartedAt
-                        );
-
-                        if (
-                          artifact &&
-                          (artifact.isLastPage ||
-                            artifact.nextRowCursor !== null)
-                        ) {
-                          snapshots.push({
-                            table: nextTableName,
-                            rows: [],
-                            artifacts: [artifact],
-                            isFirstPage: artifact.isFirstPage,
-                            isLastPage: artifact.isLastPage,
-                            bootstrapStateAfter: snapshotBootstrapStateAfter({
-                              tableIndex: nextState.tableIndex,
-                              nextRowCursor: artifact.nextRowCursor,
-                              isLastPage: artifact.isLastPage,
-                            }),
-                          });
-                          activeBundle = null;
-                          const selectedArtifactRowLimit =
-                            artifact.manifest.rowLimit;
-                          pageIndex +=
-                            Math.max(
-                              1,
-                              Math.ceil(
-                                selectedArtifactRowLimit / limitSnapshotRows
-                              )
-                            ) - 1;
-
-                          nextState = snapshotBootstrapStateAfter({
-                            tableIndex: nextState.tableIndex,
-                            nextRowCursor: artifact.nextRowCursor,
-                            isLastPage: artifact.isLastPage,
-                          });
-                          continue;
-                        }
-                      }
-
-                      if (activeBundle.pageCount === 0) {
-                        const pagesRemaining = Math.max(
-                          1,
-                          maxSnapshotPages - pageIndex
-                        );
-                        const cachedRowLimit =
-                          resolveBinarySnapshotBundleRowLimit({
-                            limitSnapshotRows,
-                            pagesRemaining,
-                          });
-                        activeBundle.cacheRowLimit = cachedRowLimit;
-                        const cacheLookupStartedAt = Date.now();
-                        const cached: SnapshotChunkRefWithContinuation | null =
-                          await readSnapshotChunkRefByPageKey(trx, {
-                            partitionId,
-                            scopeKey: cacheKey,
-                            scope: nextTableName,
-                            asOfCommitSeq: effectiveState.asOfCommitSeq,
-                            rowCursor: nextState.rowCursor,
-                            rowLimit: cachedRowLimit,
-                            encoding: snapshotChunkEncoding,
-                            compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-                          });
-                        bootstrapTimings.chunkCacheLookupMs += Math.max(
-                          0,
-                          Date.now() - cacheLookupStartedAt
-                        );
-
-                        if (
-                          cached &&
-                          (cached.isLastPage || cached.nextRowCursor !== null)
-                        ) {
-                          const chunk = toResponseChunkRef(cached);
-                          snapshots.push({
-                            table: nextTableName,
-                            rows: [],
-                            chunks: [chunk],
-                            manifest: await createChunkedSnapshotManifest({
-                              table: nextTableName,
-                              asOfCommitSeq: effectiveState.asOfCommitSeq,
-                              scopeKey: cacheKey,
-                              rowCursor: nextState.rowCursor,
-                              rowLimit: cachedRowLimit,
-                              nextRowCursor: cached.nextRowCursor,
-                              isFirstPage: nextState.rowCursor == null,
-                              isLastPage: cached.isLastPage,
-                              chunks: [chunk],
-                            }),
-                            isFirstPage: nextState.rowCursor == null,
-                            isLastPage: cached.isLastPage,
-                            bootstrapStateAfter: snapshotBootstrapStateAfter({
-                              tableIndex: nextState.tableIndex,
-                              nextRowCursor: cached.nextRowCursor,
-                              isLastPage: cached.isLastPage,
-                            }),
-                          });
-                          activeBundle = null;
-                          pageIndex +=
-                            Math.max(
-                              1,
-                              Math.ceil(cachedRowLimit / limitSnapshotRows)
-                            ) - 1;
-
-                          nextState = snapshotBootstrapStateAfter({
-                            tableIndex: nextState.tableIndex,
-                            nextRowCursor: cached.nextRowCursor,
-                            isLastPage: cached.isLastPage,
-                          });
-                          continue;
-                        }
-                      }
-
-                      const snapshotQueryStartedAt = Date.now();
-                      const page: {
-                        rows: unknown[];
-                        nextCursor: string | null;
-                      } = await tableHandler.snapshot(
-                        {
-                          db: trx,
-                          actorId: args.auth.actorId,
-                          auth: args.auth,
-                          scopeValues: effectiveScopes,
-                          cursor: nextState.rowCursor,
-                          limit: limitSnapshotRows,
-                          schemaVersion: clientSchemaVersion,
-                        },
-                        sub.params
-                      );
-                      bootstrapTimings.snapshotQueryMs += Math.max(
-                        0,
-                        Date.now() - snapshotQueryStartedAt
-                      );
-
-                      const pageRows = page.rows ?? [];
-                      activeBundle.nextRowCursor = page.nextCursor;
-                      activeBundle.binaryRows.push(...pageRows);
-                      activeBundle.pageCount += 1;
-
-                      if (page.nextCursor != null) {
-                        const shouldFlushBinaryBundle =
-                          activeBundle.binaryRows.length >=
-                          DEFAULT_MAX_BINARY_SNAPSHOT_BUNDLE_ROWS;
-                        if (shouldFlushBinaryBundle) {
-                          await flushSnapshotBundle(activeBundle);
-                          activeBundle = null;
-                        }
-                        nextState = {
-                          ...nextState,
-                          rowCursor: page.nextCursor,
-                        };
-                        continue;
-                      }
-
-                      activeBundle.isLastPage = true;
-                      await flushSnapshotBundle(activeBundle);
-                      activeBundle = null;
-
-                      if (nextState.tableIndex + 1 < nextState.tables.length) {
-                        nextState = {
-                          ...nextState,
-                          tableIndex: nextState.tableIndex + 1,
-                          rowCursor: null,
-                        };
-                        continue;
-                      }
-
-                      nextState = null;
-                      break;
-                    }
-
-                    if (activeBundle) {
-                      await flushSnapshotBundle(activeBundle);
-                    }
-
-                    subResponses.push({
-                      id: sub.id,
-                      status: 'active',
-                      scopes: effectiveScopes,
-                      bootstrap: true,
-                      bootstrapState: nextState,
-                      nextCursor: effectiveState.asOfCommitSeq,
-                      commits: [],
-                      snapshots,
-                    });
-                    nextCursors.push(effectiveState.asOfCommitSeq);
-                    continue;
-                  }
-
-                  // Incremental pull for this subscription. The dialect row query
-                  // carries the scanned commit-window max when matching rows exist,
-                  // so we only need a separate commit-window scan when the row query
-                  // returns no matches at all.
-                  const incrementalRows: IncrementalPullRow[] = [];
-                  let maxScannedCommitSeq = cursor;
-
-                  for await (const row of dialect.iterateIncrementalPullRows(
-                    trx,
-                    {
-                      partitionId,
-                      table: sub.table,
-                      scopes: effectiveScopes,
-                      cursor,
-                      limitCommits,
-                    }
-                  )) {
-                    incrementalRows.push(row);
-                    maxScannedCommitSeq = Math.max(
-                      maxScannedCommitSeq,
-                      row.scanned_max_commit_seq ?? row.commit_seq
-                    );
-                  }
-
-                  if (incrementalRows.length === 0) {
-                    const scannedCommitSeqs =
-                      await dialect.readCommitSeqsForPull(trx, {
-                        partitionId,
-                        cursor,
-                        limitCommits,
-                        tables: [sub.table],
-                      });
-                    maxScannedCommitSeq =
-                      scannedCommitSeqs.length > 0
-                        ? scannedCommitSeqs[scannedCommitSeqs.length - 1]!
-                        : cursor;
-
-                    if (scannedCommitSeqs.length === 0) {
-                      subResponses.push({
-                        id: sub.id,
-                        status: 'active',
-                        scopes: effectiveScopes,
-                        bootstrap: false,
-                        nextCursor: cursor,
-                        commits: [],
-                      });
-                      nextCursors.push(cursor);
-                      continue;
-                    }
-                  }
-
-                  const tableHandler = args.handlers.byTable.get(sub.table);
-                  if (!tableHandler) {
-                    throw new Error(`Unknown table: ${sub.table}`);
-                  }
-
-                  const incrementalItems = incrementalRows.map((r) => ({
-                    commitSeq: r.commit_seq,
-                    createdAt: r.created_at,
-                    actorId: r.actor_id,
-                    change: projectPullChangeForClientSchema({
-                      handler: tableHandler,
-                      schemaVersion: clientSchemaVersion,
-                      change: {
-                        table: r.table,
-                        row_id: r.row_id,
-                        op: r.op,
-                        row_json: r.row_json,
-                        row_version: r.row_version,
-                        scopes: r.scopes,
-                      } satisfies SyncChange,
-                    }),
-                  }));
-
-                  if (pullPlugins.length > 0 && incrementalItems.length > 0) {
-                    const transformedChanges = await transformPullChanges({
-                      plugins: pullPlugins,
-                      ctx: {
-                        db: trx,
-                        actorId: args.auth.actorId,
-                        auth: args.auth,
-                      },
-                      tableHandler,
-                      subscription: {
-                        id: sub.id,
-                        table: sub.table,
-                        scopes: effectiveScopes,
-                        params: sub.params,
-                        cursor,
-                        crdtStateVectors: sub.crdtStateVectors,
-                      },
-                      changes: incrementalItems.map((item) => item.change),
-                    });
-                    for (let i = 0; i < incrementalItems.length; i += 1) {
-                      incrementalItems[i]!.change = transformedChanges[i]!;
-                    }
-                  }
-
-                  let nextCursor = cursor;
-
-                  if (dedupeRows) {
-                    const latestByRowKey = new Map<
-                      string,
-                      {
-                        commitSeq: number;
-                        createdAt: string;
-                        actorId: string;
-                        change: SyncChange;
-                      }
-                    >();
-
-                    for (const item of incrementalItems) {
-                      nextCursor = Math.max(nextCursor, item.commitSeq);
-                      const rowKey = `${item.change.table}\u0000${item.change.row_id}`;
-
-                      // Move row keys to insertion tail so Map iteration yields
-                      // "latest change wins" order without a full array sort.
-                      if (latestByRowKey.has(rowKey)) {
-                        latestByRowKey.delete(rowKey);
-                      }
-                      latestByRowKey.set(rowKey, {
-                        commitSeq: item.commitSeq,
-                        createdAt: item.createdAt,
-                        actorId: item.actorId,
-                        change: item.change,
-                      });
-                    }
-
-                    nextCursor = Math.max(nextCursor, maxScannedCommitSeq);
-
-                    if (latestByRowKey.size === 0) {
-                      subResponses.push({
-                        id: sub.id,
-                        status: 'active',
-                        scopes: effectiveScopes,
-                        bootstrap: false,
-                        nextCursor,
-                        commits: [],
-                      });
-                      nextCursors.push(nextCursor);
-                      continue;
-                    }
-
-                    const commits: SyncCommit[] = [];
-                    for (const item of latestByRowKey.values()) {
-                      const lastCommit = commits[commits.length - 1];
-                      if (
-                        !lastCommit ||
-                        lastCommit.commitSeq !== item.commitSeq
-                      ) {
-                        commits.push({
-                          commitSeq: item.commitSeq,
-                          createdAt: item.createdAt,
-                          actorId: item.actorId,
-                          changes: [item.change],
-                        });
-                        continue;
-                      }
-                      lastCommit.changes.push(item.change);
-                    }
-                    const integrity = await createWireSubscriptionIntegrity({
-                      partitionId,
-                      subscriptionId: sub.id,
-                      previousRoot:
-                        typeof sub.verifiedRoot === 'string'
-                          ? sub.verifiedRoot
-                          : SYNCULAR_COMMIT_GENESIS_ROOT,
-                      commits,
-                    });
-
-                    subResponses.push({
-                      id: sub.id,
-                      status: 'active',
-                      scopes: effectiveScopes,
-                      bootstrap: false,
-                      nextCursor,
-                      ...(integrity ? { integrity } : {}),
-                      commits,
-                    });
-                    nextCursors.push(nextCursor);
-                    continue;
-                  }
-
-                  const commits: SyncCommit[] = [];
-
-                  for (const item of incrementalItems) {
-                    nextCursor = Math.max(nextCursor, item.commitSeq);
-                    const seq = item.commitSeq;
-                    let commit = commits[commits.length - 1];
-                    if (!commit || commit.commitSeq !== seq) {
-                      commit = {
-                        commitSeq: seq,
-                        createdAt: item.createdAt,
-                        actorId: item.actorId,
-                        changes: [],
-                      };
-                      commits.push(commit);
-                    }
-
-                    commit.changes.push(item.change);
-                  }
-
-                  const integrity = await createWireSubscriptionIntegrity({
-                    partitionId,
-                    subscriptionId: sub.id,
-                    previousRoot:
-                      typeof sub.verifiedRoot === 'string'
-                        ? sub.verifiedRoot
-                        : SYNCULAR_COMMIT_GENESIS_ROOT,
-                    commits,
-                  });
-
-                  nextCursor = Math.max(nextCursor, maxScannedCommitSeq);
-
-                  if (commits.length === 0) {
-                    subResponses.push({
-                      id: sub.id,
-                      status: 'active',
-                      scopes: effectiveScopes,
-                      bootstrap: false,
-                      nextCursor,
-                      commits: [],
-                    });
-                    nextCursors.push(nextCursor);
-                    continue;
-                  }
-
-                  subResponses.push({
-                    id: sub.id,
-                    status: 'active',
-                    scopes: effectiveScopes,
-                    bootstrap: false,
-                    nextCursor,
-                    ...(integrity ? { integrity } : {}),
-                    commits,
-                  });
-                  nextCursors.push(nextCursor);
-                }
-
-                const effectiveScopes = mergeScopes(activeSubscriptions);
-                const clientCursor =
-                  nextCursors.length > 0
-                    ? Math.min(...nextCursors)
-                    : maxCommitSeq;
-
-                return {
-                  response: {
-                    ok: true as const,
-                    subscriptions: subResponses,
-                  },
-                  effectiveScopes,
-                  clientCursor,
-                };
-              }
-            );
-
-            const chunkStorage = args.chunkStorage;
-            if (chunkStorage && pendingExternalChunkWrites.length > 0) {
-              await runWithConcurrency(
-                pendingExternalChunkWrites,
-                4,
-                async (pending) => {
-                  const cacheLookupStartedAt = Date.now();
-                  let chunkRef: SyncSnapshotChunkRef | null =
-                    await readSnapshotChunkRefByPageKey(db, {
-                      partitionId: pending.cacheLookup.partitionId,
-                      scopeKey: pending.cacheLookup.scopeKey,
-                      scope: pending.cacheLookup.scope,
-                      asOfCommitSeq: pending.cacheLookup.asOfCommitSeq,
-                      rowCursor: pending.cacheLookup.rowCursor,
-                      rowLimit: pending.cacheLookup.rowLimit,
-                      encoding: snapshotChunkEncoding,
-                      compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-                    });
-                  bootstrapTimings.chunkCacheLookupMs += Math.max(
-                    0,
-                    Date.now() - cacheLookupStartedAt
-                  );
-
-                  if (!chunkRef) {
-                    if (chunkStorage.storeChunkStream) {
-                      const {
-                        stream: bodyStream,
-                        byteLength,
-                        sha256,
-                        gzipMs,
-                        hashMs,
-                      } = await encodeCompressedSnapshotChunkToStream(
-                        pending.payloadParts,
-                        snapshotChunkGzipLevel
-                      );
-                      bootstrapTimings.chunkGzipMs += gzipMs;
-                      bootstrapTimings.chunkHashMs += hashMs;
-                      const chunkPersistStartedAt = Date.now();
-                      chunkRef = await chunkStorage.storeChunkStream({
-                        partitionId: pending.cacheLookup.partitionId,
-                        scopeKey: pending.cacheLookup.scopeKey,
-                        scope: pending.cacheLookup.scope,
-                        asOfCommitSeq: pending.cacheLookup.asOfCommitSeq,
-                        rowCursor: pending.cacheLookup.rowCursor,
-                        rowLimit: pending.cacheLookup.rowLimit,
-                        nextRowCursor: pending.cacheLookup.nextRowCursor,
-                        isLastPage: pending.cacheLookup.isLastPage,
-                        encoding: snapshotChunkEncoding,
-                        compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-                        sha256,
-                        byteLength,
-                        bodyStream,
-                        expiresAt: pending.expiresAt,
-                      });
-                      bootstrapTimings.chunkPersistMs += Math.max(
-                        0,
-                        Date.now() - chunkPersistStartedAt
-                      );
-                    } else {
-                      const encodedChunk = await encodeCompressedSnapshotChunk(
-                        pending.payloadParts,
-                        snapshotChunkGzipLevel
-                      );
-                      bootstrapTimings.chunkGzipMs += encodedChunk.gzipMs;
-                      bootstrapTimings.chunkHashMs += encodedChunk.hashMs;
-                      const chunkPersistStartedAt = Date.now();
-                      chunkRef = await chunkStorage.storeChunk({
-                        partitionId: pending.cacheLookup.partitionId,
-                        scopeKey: pending.cacheLookup.scopeKey,
-                        scope: pending.cacheLookup.scope,
-                        asOfCommitSeq: pending.cacheLookup.asOfCommitSeq,
-                        rowCursor: pending.cacheLookup.rowCursor,
-                        rowLimit: pending.cacheLookup.rowLimit,
-                        nextRowCursor: pending.cacheLookup.nextRowCursor,
-                        isLastPage: pending.cacheLookup.isLastPage,
-                        encoding: snapshotChunkEncoding,
-                        compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-                        sha256: encodedChunk.sha256,
-                        body: encodedChunk.body,
-                        expiresAt: pending.expiresAt,
-                      });
-                      bootstrapTimings.chunkPersistMs += Math.max(
-                        0,
-                        Date.now() - chunkPersistStartedAt
-                      );
-                    }
-                  }
-
-                  const chunk = toResponseChunkRef(chunkRef);
-                  pending.snapshot.chunks = [chunk];
-                  pending.snapshot.manifest =
-                    await createChunkedSnapshotManifest({
-                      table: pending.snapshot.table,
-                      asOfCommitSeq: pending.cacheLookup.asOfCommitSeq,
-                      scopeKey: pending.cacheLookup.scopeKey,
-                      rowCursor: pending.cacheLookup.rowCursor,
-                      rowLimit: pending.cacheLookup.rowLimit,
-                      nextRowCursor: pending.cacheLookup.nextRowCursor,
-                      isFirstPage: pending.snapshot.isFirstPage,
-                      isLastPage: pending.cacheLookup.isLastPage,
-                      chunks: [chunk],
-                    });
-                }
-              );
-            }
-
-            const durationMs = Math.max(0, Date.now() - startedAtMs);
-            const stats = summarizePullResponse(result.response);
-
-            span.setAttribute('status', 'ok');
-            span.setAttribute('duration_ms', durationMs);
-            span.setAttribute('subscription_count', stats.subscriptionCount);
-            span.setAttribute('commit_count', stats.commitCount);
-            span.setAttribute('change_count', stats.changeCount);
-            span.setAttribute('snapshot_page_count', stats.snapshotPageCount);
-            span.setAttributes({
-              bootstrap_snapshot_query_ms: bootstrapTimings.snapshotQueryMs,
-              bootstrap_snapshot_binary_encode_ms:
-                bootstrapTimings.binaryEncodeMs,
-              bootstrap_chunk_cache_lookup_ms:
-                bootstrapTimings.chunkCacheLookupMs,
-              bootstrap_artifact_cache_lookup_ms:
-                bootstrapTimings.artifactCacheLookupMs,
-              bootstrap_chunk_gzip_ms: bootstrapTimings.chunkGzipMs,
-              bootstrap_chunk_hash_ms: bootstrapTimings.chunkHashMs,
-              bootstrap_chunk_persist_ms: bootstrapTimings.chunkPersistMs,
-            });
-            span.setStatus('ok');
-
-            recordPullMetrics({
-              status: 'ok',
-              dedupeRows,
-              durationMs,
-              stats,
-            });
-
-            return {
-              ...result,
-              bootstrapTimings,
-            };
-          } catch (error) {
-            if (
-              error instanceof Error &&
-              attemptIndex < MAX_PULL_TRANSACTION_RETRIES - 1 &&
-              isSerializablePullError(error)
-            ) {
-              await delay(PULL_TRANSACTION_RETRY_DELAY_MS * (attemptIndex + 1));
-              continue;
-            }
-            throw error;
-          }
-        }
-
-        throw new Error('Pull transaction retry loop exhausted unexpectedly');
-      } catch (error) {
-        const durationMs = Math.max(0, Date.now() - startedAtMs);
-
-        span.setAttribute('status', 'error');
-        span.setAttribute('duration_ms', durationMs);
-        span.setStatus('error');
-
-        recordPullMetrics({
-          status: 'error',
-          dedupeRows: request.dedupeRows === true,
-          durationMs,
-          stats: {
-            subscriptionCount: 0,
-            activeSubscriptionCount: 0,
-            revokedSubscriptionCount: 0,
-            bootstrapSubscriptionCount: 0,
-            commitCount: 0,
-            changeCount: 0,
-            snapshotPageCount: 0,
-          },
-        });
-
-        captureSyncException(error, {
-          event: 'sync.server.pull',
-          requestedSubscriptionCount,
-          dedupeRows: request.dedupeRows === true,
-        });
-        throw error;
-      }
+  let delivered = 0;
+  let deliveredCommits = 0;
+  let lastDeliveredSeq = sub.cursor;
+  for (const commit of commits) {
+    if (
+      delivered > 0 &&
+      delivered + commit.changes.length > limits.limitCommits
+    ) {
+      break;
     }
-  );
+    yield commitFrame(sub.table, commit);
+    delivered += commit.changes.length;
+    deliveredCommits += 1;
+    lastDeliveredSeq = commit.commitSeq;
+    if (delivered >= limits.limitCommits) break;
+  }
+  const totalReturned = commits.reduce((n, c) => n + c.changes.length, 0);
+  // The window is proven exhausted only when the storage lookahead came
+  // back under budget (it scanned to `throughSeq`) and every returned
+  // commit was delivered.
+  const exhausted =
+    totalReturned <= limits.limitCommits && deliveredCommits === commits.length;
+  // §4.5: the cursor advances even when no matching changes exist; when
+  // the change limit truncated the window it stops at the last fully
+  // delivered commit.
+  const nextCursor = exhausted
+    ? Math.max(sub.cursor, maxSeq)
+    : Math.max(sub.cursor, lastDeliveredSeq);
+  yield { type: 'SUB_END', nextCursor };
+  return { nextCursor, active: true };
 }