@syncular/server 0.1.3 → 0.2.1

package/dist/pull.js

@@ -1,1222 +1,422 @@
-import { bytesToReadableStream, captureSyncException, concatByteChunks, countSyncMetric, createSnapshotManifest, distributionSyncMetric, encodeBinarySnapshotTable, gzipBytes, randomId, SYNC_SCOPED_SNAPSHOT_ARTIFACT_KIND_SQLITE_V1, SYNC_SNAPSHOT_CHUNK_COMPRESSION, SYNC_SNAPSHOT_CHUNK_ENCODING, sha256Hex, snapshotScopeDigestFromCacheKey, startSyncSpan, } from '@syncular/core';
-import { createWireSubscriptionIntegrity, SYNCULAR_COMMIT_GENESIS_ROOT, } from './commit-integrity.js';
-import { getServerBootstrapOrderFor, } from './handlers/collection.js';
-import { EXTERNAL_CLIENT_ID } from './notify.js';
-import { sortServerPullPlugins, } from './plugins/types.js';
-import { createScopedSnapshotArtifactScopeCacheKey, readBestScopedSnapshotArtifactRefForPageCapacity, } from './snapshot-artifacts.js';
-import { createSnapshotChunkScopeCacheKey, insertSnapshotChunk, readSnapshotChunkRefByPageKey, } from './snapshot-chunks.js';
-import { createMemoryScopeCache, } from './subscriptions/cache.js';
-import { resolveEffectiveScopesForSubscriptions } from './subscriptions/resolve.js';
-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;
-function toResponseChunkRef(ref) {
-    return {
-        id: ref.id,
-        byteLength: ref.byteLength,
-        sha256: ref.sha256,
-        encoding: ref.encoding,
-        compression: ref.compression,
-    };
-}
-async function createChunkedSnapshotManifest(args) {
-    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),
-    });
-}
-function normalizeFeatureSet(features) {
-    return Array.from(new Set(features ?? [])).sort();
-}
-function resolveSnapshotArtifactSelection(request, clientSchemaVersion) {
-    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;
+/**
+ * Pull: incremental commit delivery, cursors, bootstrap segments
+ * (SPEC.md §4, §5).
+ */
+import { decodeRow, encodeRowsSegment, } from '@syncular/core';
+import { clockOf, limitsOf } from './context.js';
+import { scopeDigest } from './scopes.js';
+import { issueSegmentUrl } from './signed-url.js';
+/**
+ * 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;
+async function resolveImageBuilder(ctx) {
+    if (ctx.sqliteImageBuilder !== undefined)
+        return ctx.sqliteImageBuilder;
+    if (cachedDefaultBuilder === undefined) {
+        const hasBun = globalThis.Bun !== undefined;
+        cachedDefaultBuilder = hasBun
+            ? (await import('./sqlite-image.js')).buildSqliteImage
+            : null;
     }
-    return {
-        artifactKind: SYNC_SCOPED_SNAPSHOT_ARTIFACT_KIND_SQLITE_V1,
-        compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-        schemaVersion: String(clientSchemaVersion),
-        featureSet: normalizeFeatureSet(request.featureSet),
-    };
-}
-function resolveSnapshotBinaryColumns(handler, schemaVersion) {
-    const versioned = handler.snapshotBinaryColumnsForVersion?.(schemaVersion);
-    return versioned === undefined
-        ? handler.snapshotBinaryColumns
-        : (versioned ?? undefined);
-}
-function resolveSnapshotBinaryEncoder(handler, schemaVersion) {
-    const versioned = handler.snapshotBinaryEncoderForVersion?.(schemaVersion);
-    return versioned === undefined
-        ? handler.snapshotBinaryEncoder
-        : (versioned ?? undefined);
-}
-function createPullBootstrapTimings() {
-    return {
-        snapshotQueryMs: 0,
-        binaryEncodeMs: 0,
-        chunkCacheLookupMs: 0,
-        artifactCacheLookupMs: 0,
-        chunkGzipMs: 0,
-        chunkHashMs: 0,
-        chunkPersistMs: 0,
-    };
-}
-function resolveBinarySnapshotBundleRowLimit(args) {
-    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, gzipLevel) {
-    return gzipBytes(concatByteChunks(chunks), {
-        level: gzipLevel,
-    });
+    return cachedDefaultBuilder ?? undefined;
 }
-async function encodeCompressedSnapshotChunk(chunks, gzipLevel) {
-    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 };
+/** §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;
+function clamp(value, min, max, dflt) {
+    if (value === 0)
+        return dflt;
+    return Math.min(max, Math.max(min, value));
 }
-async function encodeCompressedSnapshotChunkToStream(chunks, gzipLevel) {
-    const encoded = await encodeCompressedSnapshotChunk(chunks, gzipLevel);
+/** §4.2 defaults and silent clamps (the v1 values). */
+export function clampPullLimits(header) {
     return {
-        stream: bytesToReadableStream(encoded.body),
-        byteLength: encoded.body.length,
-        sha256: encoded.sha256,
-        gzipMs: encoded.gzipMs,
-        hashMs: encoded.hashMs,
+        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 encodeBinarySnapshotRows(table, rows, columns) {
-    const recordRows = rows.map((row) => toSnapshotRecordRow(table, row));
-    return encodeBinarySnapshotTable({
-        table,
-        columns: columns ?? inferBinarySnapshotColumns(recordRows),
-        rows: recordRows,
-    });
-}
-function toSnapshotRecordRow(table, row) {
-    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;
-}
-function inferBinarySnapshotColumns(rows) {
-    const columns = [];
-    const columnsByName = new Map();
-    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));
+function parseBootstrapToken(raw, table) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        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,
+            tableIndex: parsed.tableIndex,
+            rowCursor: parsed.rowCursor ?? null,
+        };
     }
-    return columns.map((column) => ({
-        name: column.name,
-        type: column.type ?? 'json',
-        ...(column.nullable || column.presentCount < rows.length
-            ? { nullable: true }
+    catch {
+        return undefined;
+    }
+}
+function commitFrame(table, commit) {
+    const changes = 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) {
-    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';
+function chunkRows(rows, size) {
+    if (rows.length === 0)
+        return [];
+    const blocks = [];
+    for (let i = 0; i < rows.length; i += size) {
+        blocks.push(rows.slice(i, i + size));
     }
-    return 'json';
+    return blocks;
 }
-function mergeBinarySnapshotColumnTypes(current, next) {
-    if (!current || current === next)
-        return next;
-    if ((current === 'integer' && next === 'float') ||
-        (current === 'float' && next === 'integer')) {
-        return 'float';
-    }
-    return 'json';
+/** §5.4 signed-URL fields for a descriptor, when the client asked (bit 3). */
+async function signedUrlFields(ctx, limits, segmentId, digest, now) {
+    if ((limits.accept & ACCEPT_SIGNED_URLS) === 0 || !ctx.signedUrls)
+        return {};
+    return issueSegmentUrl(ctx.signedUrls, {
+        segmentId,
+        partition: ctx.partition,
+        scopeDigest: digest,
+        nowMs: now,
+    });
 }
-async function runWithConcurrency(items, concurrency, worker) {
-    if (items.length === 0)
-        return;
-    const workerCount = Math.max(1, Math.min(concurrency, items.length));
-    let nextIndex = 0;
-    async function runWorker() {
-        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()));
+function segmentRefFrame(record, extra) {
+    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 }
+            : {}),
+    };
 }
 /**
- * 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, defaultValue, min, max) {
-    if (value === undefined || value === null)
-        return defaultValue;
-    if (Number.isNaN(value))
-        return defaultValue;
-    return Math.max(min, Math.min(max, value));
-}
-function sanitizeGzipLevel(value) {
-    if (value === undefined || value === null || !Number.isFinite(value)) {
-        return DEFAULT_SNAPSHOT_CHUNK_GZIP_LEVEL;
+async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace) {
+    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);
+    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;
     }
-    return Math.max(0, Math.min(9, Math.trunc(value)));
-}
-function isSerializablePullError(error) {
-    const withCode = error;
-    return (withCode.code === '40001' ||
-        error.message.toLowerCase().includes('could not serialize access'));
-}
-async function delay(ms) {
-    await new Promise((resolve) => {
-        setTimeout(resolve, ms);
+    // 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,
     });
-}
-/**
- * Merge all scope values into a flat ScopeValues for cursor tracking.
- */
-function mergeScopes(subscriptions) {
-    const result = {};
-    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 = {};
-    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;
+    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 = [...probe];
+    let afterRowId = probe[probe.length - 1]?.rowId ?? null;
+    for (;;) {
+        const scanned = 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;
     }
-    return merged;
+    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;
 }
-function assertPullChangeIdentityUnchanged(source, before, after) {
-    if (before.table !== after.table) {
-        throw new Error(`${source} cannot change change.table (${before.table} -> ${after.table})`);
+async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace) {
+    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 };
     }
-    if (before.row_id !== after.row_id) {
-        throw new Error(`${source} cannot change change.row_id (${before.row_id} -> ${after.row_id})`);
-    }
-    if (before.op !== after.op) {
-        throw new Error(`${source} cannot change change.op (${before.op} -> ${after.op})`);
-    }
-}
-function projectPullChangeForClientSchema(args) {
-    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(args) {
-    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) => ({
+            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 };
         }
-        for (let i = 0; i < changes.length; i += 1) {
-            assertPullChangeIdentityUnchanged(`Server pull plugin "${plugin.name}"`, changes[i], nextChanges[i]);
+        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);
+            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) {
-    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;
+/**
+ * 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, schema, limits, plan, maxSeq, horizonSeq, trace) {
+    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 };
+    }
+    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 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 {
-            activeSubscriptionCount += 1;
-        }
-        if (sub.bootstrap) {
-            bootstrapSubscriptionCount += 1;
+            const nextToken = {
+                asOfCommitSeq: asOf,
+                tables: [sub.table],
+                tableIndex: 0,
+                rowCursor: outcome.rowCursor,
+            };
+            yield {
+                type: 'SUB_END',
+                nextCursor: asOf,
+                bootstrapState: JSON.stringify(nextToken),
+            };
         }
-        const commits = sub.commits ?? [];
-        commitCount += commits.length;
-        for (const commit of commits) {
-            changeCount += commit.changes?.length ?? 0;
-        }
-        snapshotPageCount += sub.snapshots?.length ?? 0;
+        return { nextCursor: asOf, active: true };
     }
-    return {
-        subscriptionCount: subscriptions.length,
-        activeSubscriptionCount,
-        revokedSubscriptionCount,
-        bootstrapSubscriptionCount,
-        commitCount,
-        changeCount,
-        snapshotPageCount,
+    // 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,
     };
-}
-function recordPullMetrics(args) {
-    const { status, dedupeRows, durationMs, stats } = args;
-    const attributes = {
-        status,
-        dedupe_rows: dedupeRows,
-    };
-    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(trx, args) {
-    const tableNames = Array.from(new Set(args.tables.filter((table) => typeof table === 'string')));
-    const latestByTable = new Map();
-    if (tableNames.length === 0) {
-        return latestByTable;
-    }
-    const executor = trx;
-    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(args) {
-    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 = [];
-                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 = [];
-                        const activeSubscriptions = [];
-                        const nextCursors = [];
-                        // 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();
-                        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();
-                        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 = {
-                                    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
-                                    : 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 = [];
-                                let nextState = 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;
-                                const createSnapshotBundle = (table, tableIndex, rowCursor, ttlMs, binaryColumns, binaryEncoder) => {
-                                    return {
-                                        table,
-                                        tableIndex,
-                                        startCursor: rowCursor,
-                                        nextRowCursor: null,
-                                        isFirstPage: rowCursor == null,
-                                        isLastPage: false,
-                                        pageCount: 0,
-                                        cacheRowLimit: null,
-                                        ttlMs,
-                                        binaryColumns,
-                                        binaryEncoder,
-                                        binaryRows: [],
-                                    };
-                                };
-                                const snapshotBootstrapStateAfter = (args) => {
-                                    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) => {
-                                    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) => {
-                                    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 = cached;
-                                    if (!chunkRef) {
-                                        const expiresAt = new Date(Date.now() + Math.max(1000, bundle.ttlMs)).toISOString();
-                                        if (args.chunkStorage) {
-                                            const snapshot = {
-                                                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 = null;
-                                for (let pageIndex = 0; pageIndex < maxSnapshotPages; pageIndex++) {
-                                    if (!nextState)
-                                        break;
-                                    const nextTableName = 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 = 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 = 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 = [];
-                            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,
-                                    },
-                                }),
-                            }));
-                            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();
-                                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 = [];
-                                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 = [];
-                            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,
-                                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 = 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');
+    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;
         }
-        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;
-        }
-    });
+        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 };
 }
-//# sourceMappingURL=pull.js.map