@syncular/server 0.26.4 → 0.26.6

package/dist/pull.d.ts

@@ -3,9 +3,10 @@
  * (SPEC.md §4, §5).
  */
 import { type PullHeaderFrame, type ResponseFrame, type ScopeMap, type SubscriptionFrame } from '@syncular/core';
-import type { SyncRequestContext } from './context.js';
+import type { SyncRequestContext, SyncServerConfig } from './context.js';
 import type { PullSegmentSummary } from './events.js';
-import type { CompiledSchema, CompiledTable } from './schema.js';
+import { type CompiledSchema, type CompiledTable } from './schema.js';
+import type { SegmentRecord } from './segment-store.js';
 import type { StoredCommit, StoredRow } from './storage.js';
 /** §4.2 accept bitmask. */
 export declare const ACCEPT_INLINE_ROWS: number;
@@ -41,19 +42,26 @@ export interface PullSectionTrace {
 /**
  * The storage reads a section needs before its first frame. A pull starts
  * them for every subscription before awaiting any, so a storage that batches
- * concurrent page reads (PostgreSQL) answers all subscriptions of one table
- * with one statement, and the horizon re-check runs once per pull.
+ * concurrent page reads (PostgreSQL, D1) answers all subscriptions of one
+ * table with one statement, and the horizon re-check runs once per pull.
  */
 export interface PreparedSection {
     /** §4.5 window read for an incremental cursor; empty when none was read. */
     readonly commits: StoredCommit[];
     /** Horizon to judge the cursor against, re-read after any window read. */
     readonly horizonSeq: number;
-    /** First rows-lane snapshot page, read when the sqlite lane is excluded. */
+    /**
+     * A bootstrap's first snapshot page (`limitSnapshotRows + 1` rows from the
+     * resume cursor), which is also the §5.3 image eligibility probe.
+     */
     readonly firstPage: StoredRow[] | undefined;
+    /** §4.7 pin of a fresh bootstrap; absent ⇒ `maxCommitSeq`. */
+    readonly pin: number | undefined;
+    /** §5.3 stored image for a sqlite-lane bootstrap's reuse key, if any. */
+    readonly image: SegmentRecord | undefined;
 }
 /** Run the pre-frame storage reads of every subscription concurrently. */
-export declare function prepareSections(ctx: SyncRequestContext, limits: PullLimits, plans: readonly SubscriptionPlan[], maxSeq: number, horizonSeq: number): Promise<PreparedSection[]>;
+export declare function prepareSections(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plans: readonly SubscriptionPlan[], maxSeq: number, horizonSeq: number, logEpoch: string): Promise<PreparedSection[]>;
 /**
  * Produce the `SUB_START … SUB_END` section for one subscription (§1.6),
  * returning the cursor recorded for the retention watermark (§4.5).
@@ -61,3 +69,35 @@ export declare function prepareSections(ctx: SyncRequestContext, limits: PullLim
 export declare function subscriptionSection(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: SubscriptionPlan, maxSeq: number, horizonSeq: number, trace?: PullSectionTrace, logEpoch?: string): AsyncGenerator<ResponseFrame, SubscriptionResult>;
 /** The section of one subscription whose reads `prepareSections` ran. */
 export declare function preparedSection(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: SubscriptionPlan, maxSeq: number, prepared: PreparedSection, trace?: PullSectionTrace, logEpoch?: string): AsyncGenerator<ResponseFrame, SubscriptionResult>;
+export interface PublishSqliteImageInput {
+    /** The sync config the serving host runs, plus a `sqliteImageBuilder`. */
+    readonly config: SyncServerConfig;
+    readonly partition: string;
+    readonly table: string;
+    /**
+     * The effective scopes the subscribing clients hold for `table` (§3.2):
+     * the reuse key carries their digest, so publish once per distinct scope
+     * set that clients subscribe with.
+     */
+    readonly scopes: ScopeMap;
+}
+export interface PublishedSqliteImage {
+    readonly segmentId: string;
+    /** The §4.7 scope pin the image is stored under. */
+    readonly asOfCommitSeq: number;
+    readonly scopeDigest: string;
+    readonly rowCount: number;
+    readonly byteLength: number;
+    /** `reused` when an unexpired image for the same reuse key already existed. */
+    readonly origin: 'built' | 'reused';
+}
+/**
+ * Publish the §5.3 sqlite image that a pull for (`table`, `scopes`) looks
+ * up, from a host with a SQLite engine (a Bun process with the production
+ * storage). It runs the pull's own bootstrap path (the §4.7 scope pin, the
+ * reuse key, the build), so the stored identity is exactly the one a
+ * serving host without a builder finds. The image stays current until a
+ * change reaches the scope; its lifetime is the segment store's TTL at
+ * publication.
+ */
+export declare function publishSqliteImage(input: PublishSqliteImageInput): Promise<PublishedSqliteImage>;

package/dist/pull.js

@@ -4,6 +4,7 @@
  */
 import { decodeRow, encodeRowsSegment, } from '@syncular/core';
 import { clockOf, limitsOf } from './context.js';
+import { compileSchema, } from './schema.js';
 import { scopeDigest } from './scopes.js';
 import { issueSegmentUrl } from './signed-url.js';
 // One artifact build per owning storage pair and complete immutable identity.
@@ -153,18 +154,9 @@ function sqliteLaneEligible(limits, plan, startRowCursor) {
  * bootstrap-storm rule. Returns false when the table is not eligible
  * (the rows lane takes over).
  */
-async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace, logEpoch) {
+async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace, logEpoch, existing, probe) {
     const { storage, segments, partition } = ctx;
     const now = clockOf(ctx)();
-    const existing = await segments.find({
-        partition,
-        logEpoch,
-        table: plan.table.name,
-        schemaVersion: schema.version,
-        mediaType: 'sqlite',
-        scopeDigest: digest,
-        asOfCommitSeq: asOf,
-    }, now);
     if (existing !== undefined) {
         trace?.segments.push({
             mediaType: 'sqlite',
@@ -178,12 +170,7 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
     }
     // 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,
-    });
+    // The probe is the rows lane's first page, read by `prepareSections`.
     if (probe.length <= limits.limitSnapshotRows)
         return false;
     // §5.3: building an image needs a SQLite engine. The host injects the
@@ -273,19 +260,19 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
     yield segmentRefFrame(record, digest, await signedUrlFields(ctx, limits, record.segmentId, digest, clockOf(ctx)()));
     return true;
 }
-async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace, logEpoch, firstPage) {
+async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCursor, trace, logEpoch, firstPage, image) {
     const { storage, segments, partition } = ctx;
     const serverLimits = limitsOf(ctx);
     const digest = await scopeDigest(plan.effective);
     const now = clockOf(ctx)();
     if (sqliteLaneEligible(limits, plan, startRowCursor)) {
-        const imaged = yield* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace, logEpoch);
+        const imaged = yield* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trace, logEpoch, image, firstPage);
         if (imaged)
             return { complete: true, rowCursor: null };
     }
     let rowCursor = startRowCursor;
     for (let page = 0; page < limits.maxSnapshotPages; page++) {
-        const scanned = page === 0 && firstPage !== undefined
+        const scanned = page === 0
             ? firstPage
             : await storage.scanRows(partition, {
                 table: plan.table.name,
@@ -351,7 +338,7 @@ async function* bootstrapSegments(ctx, schema, limits, plan, asOf, startRowCurso
     return { complete: false, rowCursor };
 }
 /** Run the pre-frame storage reads of every subscription concurrently. */
-export async function prepareSections(ctx, limits, plans, maxSeq, horizonSeq) {
+export async function prepareSections(ctx, schema, limits, plans, maxSeq, horizonSeq, logEpoch) {
     const reads = plans.map((plan) => {
         const sub = plan.frame;
         if (plan.status === 'revoked')
@@ -376,23 +363,50 @@ export async function prepareSections(ctx, limits, plans, maxSeq, horizonSeq) {
             return {};
         }
         // Bootstrapping: the same resume decision `preparedSection` makes (§4.7).
-        const startCursor = token !== undefined && token.asOfCommitSeq >= horizonSeq
-            ? token.rowCursor
-            : null;
-        if (sqliteLaneEligible(limits, plan, startCursor))
-            return {};
-        return {
-            firstPage: ctx.storage.scanRows(ctx.partition, {
+        const resume = token !== undefined && token.asOfCommitSeq >= horizonSeq
+            ? token
+            : undefined;
+        const startCursor = resume?.rowCursor ?? null;
+        const firstPage = ctx.storage.scanRows(ctx.partition, {
+            table: plan.table.name,
+            scopeFilter: plan.effective,
+            afterRowId: startCursor,
+            limit: limits.limitSnapshotRows + 1,
+        });
+        if (!sqliteLaneEligible(limits, plan, startCursor))
+            return { firstPage };
+        // §4.7: a fresh sqlite-lane bootstrap pins at the newest change in its
+        // scope (never below the horizon, never above maxCommitSeq), so a stored
+        // image stays the reuse key's match until this scope changes (§5.3).
+        const pinned = resume !== undefined
+            ? Promise.resolve({ asOf: resume.asOfCommitSeq, pin: undefined })
+            : ctx.storage
+                .latestScopedChangeSeq(ctx.partition, {
                 table: plan.table.name,
                 scopeFilter: plan.effective,
-                afterRowId: startCursor,
-                limit: limits.limitSnapshotRows + 1,
-            }),
-        };
+            })
+                .then((latest) => {
+                const pin = Math.min(maxSeq, Math.max(latest, horizonSeq));
+                return { asOf: pin, pin };
+            });
+        const lane = pinned.then(async ({ asOf, pin }) => ({
+            pin,
+            image: await ctx.segments.find({
+                partition: ctx.partition,
+                logEpoch,
+                table: plan.table.name,
+                schemaVersion: schema.version,
+                mediaType: 'sqlite',
+                scopeDigest: await scopeDigest(plan.effective),
+                asOfCommitSeq: asOf,
+            }, clockOf(ctx)()),
+        }));
+        return { firstPage, lane };
     });
     const settled = await Promise.all(reads.map(async (read) => ({
         commits: read.commits === undefined ? undefined : await read.commits,
         firstPage: await read.firstPage,
+        lane: await read.lane,
     })));
     // Validate continuity before committing to an active section. A prune
     // during a paged read can otherwise make an incomplete window look empty.
@@ -403,6 +417,8 @@ export async function prepareSections(ctx, limits, plans, maxSeq, horizonSeq) {
         commits: read.commits ?? [],
         horizonSeq: read.commits === undefined ? horizonSeq : windowHorizon,
         firstPage: read.firstPage,
+        pin: read.lane?.pin,
+        image: read.lane?.image,
     }));
 }
 /**
@@ -410,7 +426,10 @@ export async function prepareSections(ctx, limits, plans, maxSeq, horizonSeq) {
  * returning the cursor recorded for the retention watermark (§4.5).
  */
 export async function* subscriptionSection(ctx, schema, limits, plan, maxSeq, horizonSeq, trace, logEpoch) {
-    const [prepared] = await prepareSections(ctx, limits, [plan], maxSeq, horizonSeq);
+    if (logEpoch === undefined || logEpoch.length === 0) {
+        throw new Error('subscriptionSection requires a non-empty log epoch');
+    }
+    const [prepared] = await prepareSections(ctx, schema, limits, [plan], maxSeq, horizonSeq, logEpoch);
     if (prepared === undefined)
         throw new Error('prepareSections lost a plan');
     return yield* preparedSection(ctx, schema, limits, plan, maxSeq, prepared, trace, logEpoch);
@@ -456,8 +475,11 @@ export async function* preparedSection(ctx, schema, limits, plan, maxSeq, prepar
         const resume = token !== undefined && token.asOfCommitSeq >= horizonSeq
             ? token
             : undefined;
-        const asOf = resume?.asOfCommitSeq ?? maxSeq;
+        const asOf = resume?.asOfCommitSeq ?? prepared.pin ?? maxSeq;
         const startCursor = resume?.rowCursor ?? null;
+        if (prepared.firstPage === undefined) {
+            throw new Error('prepareSections did not read the bootstrap page');
+        }
         yield {
             type: 'SUB_START',
             id: sub.id,
@@ -466,7 +488,7 @@ export async function* preparedSection(ctx, schema, limits, plan, maxSeq, prepar
             effectiveScopes: plan.effective,
             bootstrap: true,
         };
-        const outcome = yield* bootstrapSegments(ctx, schema, limits, plan, asOf, startCursor, trace, logEpoch, prepared.firstPage);
+        const outcome = yield* bootstrapSegments(ctx, schema, limits, plan, asOf, startCursor, trace, logEpoch, prepared.firstPage, prepared.image);
         if (outcome.complete) {
             yield { type: 'SUB_END', nextCursor: asOf };
         }
@@ -524,3 +546,76 @@ export async function* preparedSection(ctx, schema, limits, plan, maxSeq, prepar
     yield { type: 'SUB_END', nextCursor };
     return { nextCursor, active: true };
 }
+/**
+ * Publish the §5.3 sqlite image that a pull for (`table`, `scopes`) looks
+ * up, from a host with a SQLite engine (a Bun process with the production
+ * storage). It runs the pull's own bootstrap path (the §4.7 scope pin, the
+ * reuse key, the build), so the stored identity is exactly the one a
+ * serving host without a builder finds. The image stays current until a
+ * change reaches the scope; its lifetime is the segment store's TTL at
+ * publication.
+ */
+export async function publishSqliteImage(input) {
+    const { config, partition } = input;
+    if (config.sqliteImageBuilder === undefined) {
+        throw new Error('publishSqliteImage requires config.sqliteImageBuilder');
+    }
+    const schema = compileSchema(config.schema);
+    const table = schema.tables.get(input.table);
+    if (table === undefined) {
+        throw new Error('publishSqliteImage: the schema has no such table');
+    }
+    await config.storage.ensureSchema(schema, config.checkpoints);
+    const logEpoch = await config.storage.getPartitionLogEpoch(partition);
+    if (logEpoch === undefined) {
+        throw new Error('publishSqliteImage: the partition has no log epoch');
+    }
+    const ctx = {
+        ...config,
+        partition,
+        actorId: 'syncular.image-publisher',
+    };
+    const plan = {
+        frame: {
+            type: 'SUBSCRIPTION',
+            id: 'image',
+            table: input.table,
+            scopes: input.scopes,
+            cursor: -1,
+        },
+        table,
+        status: 'active',
+        effective: input.scopes,
+    };
+    // One-row pages make every table above one row image-eligible (§5.3).
+    const limits = {
+        limitCommits: 1,
+        limitSnapshotRows: 1,
+        maxSnapshotPages: 1,
+        accept: ACCEPT_SQLITE,
+    };
+    const maxSeq = await config.storage.getMaxCommitSeq(partition);
+    const horizonSeq = await config.storage.getHorizonSeq(partition);
+    const trace = { segments: [] };
+    const [prepared] = await prepareSections(ctx, schema, limits, [plan], maxSeq, horizonSeq, logEpoch);
+    if (prepared === undefined)
+        throw new Error('prepareSections lost a plan');
+    let ref;
+    for await (const frame of preparedSection(ctx, schema, limits, plan, maxSeq, prepared, trace, logEpoch)) {
+        if (frame.type === 'SEGMENT_REF' && frame.mediaType === 'sqlite') {
+            ref = frame;
+        }
+    }
+    const image = trace.segments.find((segment) => segment.mediaType === 'sqlite');
+    if (ref === undefined || image === undefined) {
+        throw new Error('publishSqliteImage: the scope holds at most one row, which pulls serve inline');
+    }
+    return {
+        segmentId: ref.segmentId,
+        asOfCommitSeq: ref.asOfCommitSeq,
+        scopeDigest: ref.scopeDigest,
+        rowCount: ref.rowCount,
+        byteLength: ref.byteLength,
+        origin: image.origin === 'reused' ? 'reused' : 'built',
+    };
+}

package/dist/push.js

@@ -420,8 +420,12 @@ async function applyOperation(tx, schema, resolved, op, opIndex, blobCtx, crdtMe
     const insertReject = await runValidator(validators, table, 'upsert', op.rowId, values, undefined, opIndex, tx, partition, actorId);
     if (insertReject !== undefined)
         return insertReject;
-    // §5.2: an explicit insert recreates — the tombstone goes with it.
-    await tx.clearTombstone(op.table, op.rowId);
+    // §5.2: an explicit insert recreates — the tombstone goes with it. An
+    // unversioned insert already proved above, under the partition lock, that
+    // no tombstone exists (this commit writes its own only in `appendCommit`).
+    if (op.baseVersion !== undefined) {
+        await tx.clearTombstone(op.table, op.rowId);
+    }
     const newRow = {
         rowId: op.rowId,
         serverVersion: 1,
@@ -915,6 +919,19 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
         const stagedWrites = [];
         let terminated;
         const operations = await buildOperations(tx);
+        if (tx.prefetchRows !== undefined) {
+            const targets = new Map();
+            for (const op of operations) {
+                if (!schema.tables.has(op.table))
+                    continue;
+                const ids = targets.get(op.table) ?? [];
+                ids.push(op.rowId);
+                targets.set(op.table, ids);
+            }
+            for (const [table, rowIds] of targets) {
+                await tx.prefetchRows(table, rowIds);
+            }
+        }
         for (let opIndex = 0; opIndex < operations.length; opIndex++) {
             const op = operations[opIndex];
             if (op === undefined)

package/dist/realtime.d.ts

@@ -18,6 +18,7 @@
  */
 import { type PresenceKind, type ScopeMap, type WakeReason } from '@syncular/core';
 import type { SyncRequestContext, SyncServerConfig } from './context.js';
+import { type SyncularErrorHandler } from './errors.js';
 import { type SyncularServerEvents } from './events.js';
 import type { ServerStorage, StoredCommit } from './storage.js';
 /**
@@ -198,6 +199,8 @@ export declare class RealtimeHub {
         readonly partition: string;
         readonly actorId: string;
     }): SyncRequestContext;
+    /** The host's error reporter (`SyncServerConfig.onError`), if any. */
+    get onError(): SyncularErrorHandler | undefined;
     requestContext(session: RealtimeSession): SyncRequestContext;
     /**
      * Register a connected socket (§8.1): load the client's last pull's

package/dist/realtime.js

@@ -18,7 +18,7 @@
  */
 import { DecodeError, decodeMessage, encodeMessage, encodePresenceError, encodePresenceFanout, MessageStreamScanner, PROTOCOL_WIRE_VERSION, parseRealtimePresencePublish, REALTIME_TAG_DELTA, REALTIME_TAG_ROUND, } from '@syncular/core';
 import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
-import { SyncError, syncError } from './errors.js';
+import { adapterSyncError, reportError, SyncError, syncError, } from './errors.js';
 import { emitEvent } from './events.js';
 import { createSyncResponseStream } from './handler.js';
 import { compileSchema } from './schema.js';
@@ -430,16 +430,15 @@ export class RealtimeSession {
             }
             catch (error) {
                 // §8.7 failures: what HTTP reports as status+JSON becomes a
-                // minimal RESP_HEADER/ERROR/END response stream on the socket.
-                if (error instanceof DecodeError || error instanceof SyncError) {
-                    const sync = error instanceof SyncError
-                        ? error
-                        : syncError(error.code, error.message);
-                    finishRound(); // END is in this one chunk
-                    await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
-                    return;
-                }
-                throw error;
+                // minimal RESP_HEADER/ERROR/END response stream on the socket. An
+                // exception outside the catalog is reported and answers
+                // `sync.internal_error`, exactly like the HTTP adapter's 500.
+                const sync = error instanceof DecodeError
+                    ? syncError(error.code, error.message)
+                    : adapterSyncError(error, this.#hub.onError, 'realtime');
+                finishRound(); // END is in this one chunk
+                await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
+                return;
             }
             // Fetch-ahead so the round stops being "in flight" the moment the
             // chunk carrying END is handed to send: the client may legally
@@ -451,20 +450,19 @@ export class RealtimeSession {
                 step = await iterator.next();
             }
             catch (error) {
-                // The buffered read-verify refusal is thrown on the generator's first
-                // `next()`, before any chunk is yielded (the generator builds the whole
-                // response, then verifies). Nothing has escaped, so it is delivered as
-                // the same §8.4 ERROR frame HTTP returns rather than a silent close. A
-                // throw after the first chunk still takes the §8.7 violation path.
-                if (error instanceof DecodeError || error instanceof SyncError) {
-                    const sync = error instanceof SyncError
-                        ? error
-                        : syncError(error.code, error.message);
-                    finishRound();
-                    await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
-                    return;
-                }
-                throw error;
+                // The generator builds the whole response (and runs the read-verify
+                // refusal) on its first `next()`, before any chunk is yielded.
+                // Nothing has escaped, so a failure there is delivered as the same
+                // §8.4 ERROR frame HTTP returns rather than a silent close; a
+                // non-catalog exception is reported and answers
+                // `sync.internal_error`. A throw after the first chunk still takes
+                // the §8.7 violation path.
+                const sync = error instanceof DecodeError
+                    ? syncError(error.code, error.message)
+                    : adapterSyncError(error, this.#hub.onError, 'realtime');
+                finishRound();
+                await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
+                return;
             }
             while (!step.done) {
                 const chunk = step.value;
@@ -474,9 +472,10 @@ export class RealtimeSession {
                 await this.#sendRoundChunk(chunk);
             }
         }
-        catch {
+        catch (error) {
             // A host failure mid-stream leaves the byte stream unfinishable —
             // fail loud, drop the connection (§8.7 / §1.4 abort rule).
+            reportError(error, this.#hub.onError, 'realtime');
             this.#violation('sync round failed mid-stream');
         }
         finally {
@@ -851,9 +850,16 @@ export class RealtimeHub {
             ...(this.#config.events !== undefined
                 ? { events: this.#config.events }
                 : {}),
+            ...(this.#config.onError !== undefined
+                ? { onError: this.#config.onError }
+                : {}),
             realtime: this,
         };
     }
+    /** The host's error reporter (`SyncServerConfig.onError`), if any. */
+    get onError() {
+        return this.#config.onError;
+    }
     requestContext(session) {
         return this.requestContextFor(session);
     }

package/dist/relational-rows.d.ts

@@ -249,6 +249,25 @@ export declare function scanRowBatchSql(table: CompiledTable): string;
  * `scanRowBatchSql`.
  */
 export declare const COMMIT_WINDOW_BATCH_SQL = "SELECT s.i AS sub, c.commit_seq AS commit_seq, m.actor_id AS actor_id, m.created_at_ms AS created_at_ms,\n       ch.tbl AS tbl, ch.row_id AS row_id, ch.op AS op, ch.row_version AS row_version, ch.scopes AS scopes, ch.payload AS payload\n     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, var text, vals text[], after bigint, through bigint, lim int)\n     CROSS JOIN LATERAL (SELECT DISTINCT commit_seq FROM sync_change_scopes\n       WHERE partition=$1 AND tbl=$3 AND var=s.var AND value=ANY(s.vals)\n         AND commit_seq>s.after AND commit_seq<=s.through\n       ORDER BY commit_seq LIMIT s.lim) c\n     LEFT JOIN sync_commits m\n       ON m.partition=$1 AND m.commit_seq=c.commit_seq\n     LEFT JOIN sync_changes ch\n       ON ch.partition=$1 AND ch.commit_seq=c.commit_seq AND ch.tbl=$3\n     ORDER BY s.i, c.commit_seq, ch.idx";
+/**
+ * PostgreSQL push read-ahead: every requested row id with its stored row
+ * (NULL columns when absent, `selectRowSql` shape) and its §5 delete
+ * tombstone. Params: [partition, rowIds as JSON array text, tbl].
+ */
+export declare function prefetchRowsSql(table: CompiledTable): string;
+/**
+ * SQLite/D1: the newest `commit_seq` in the inverted change-scope index for
+ * one variable's values, as one index-only max per value (a `(partition,
+ * tbl, var, value)` prefix), so the cost is independent of the table's
+ * history. Bind order: [partition, tbl, var, value] per value.
+ */
+export declare function latestScopedChangeSeqSql(valueCount: number): string;
+/**
+ * PostgreSQL set-based form of `latestScopedChangeSeqSql` for the
+ * subscriptions of one table in a pull. `$2` is a JSON array of
+ * `{i, var, vals}` records. Params: [partition, specs (JSON text), tbl].
+ */
+export declare const LATEST_SCOPED_CHANGE_BATCH_SQL = "SELECT s.i AS sub,\n       (SELECT max(latest.seq) FROM (\n          SELECT (SELECT max(commit_seq) FROM sync_change_scopes\n                   WHERE partition=$1 AND tbl=$3 AND var=s.var AND value=v.value) AS seq\n            FROM jsonb_array_elements_text(s.vals) AS v(value)) AS latest) AS seq\n     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, var text, vals jsonb)\n    ORDER BY s.i";
 /** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
 export declare function selectRowScopesSql(table: CompiledTable, dialect: RelationalDialect): string;
 /** DELETE one stored row. Params: [partition, rowId]. */

package/dist/relational-rows.js

@@ -593,6 +593,44 @@ export const COMMIT_WINDOW_BATCH_SQL = `SELECT s.i AS sub, c.commit_seq AS commi
      LEFT JOIN sync_changes ch
        ON ch.partition=$1 AND ch.commit_seq=c.commit_seq AND ch.tbl=$3
      ORDER BY s.i, c.commit_seq, ch.idx`;
+/**
+ * PostgreSQL push read-ahead: every requested row id with its stored row
+ * (NULL columns when absent, `selectRowSql` shape) and its §5 delete
+ * tombstone. Params: [partition, rowIds as JSON array text, tbl].
+ */
+export function prefetchRowsSql(table) {
+    return `SELECT ids.id AS lookup_id, r.${quoteIdent(SYNC_ROW_ID_COLUMN)} AS row_id, r.${quoteIdent(SYNC_VERSION_COLUMN)} AS server_version, r.${quoteIdent(SYNC_SCOPES_COLUMN)} AS scopes, r.${quoteIdent(SYNC_PAYLOAD_COLUMN)} AS payload, r.${quoteIdent(SYNC_COLUMN_VERSIONS_COLUMN)} AS column_versions, t.commit_seq AS tombstone_seq
+     FROM jsonb_array_elements_text($2::text::jsonb) AS ids(id)
+     LEFT JOIN ${quoteIdent(table.name)} r
+       ON r.${quoteIdent(SYNC_PARTITION_COLUMN)}=$1 AND r.${quoteIdent(SYNC_ROW_ID_COLUMN)}=ids.id
+     LEFT JOIN sync_tombstones t
+       ON t.partition=$1 AND t.tbl=$3 AND t.row_id=ids.id`;
+}
+/**
+ * SQLite/D1: the newest `commit_seq` in the inverted change-scope index for
+ * one variable's values, as one index-only max per value (a `(partition,
+ * tbl, var, value)` prefix), so the cost is independent of the table's
+ * history. Bind order: [partition, tbl, var, value] per value.
+ */
+export function latestScopedChangeSeqSql(valueCount) {
+    const perValue = [];
+    for (let i = 0; i < valueCount; i++) {
+        perValue.push('SELECT (SELECT max(commit_seq) FROM sync_change_scopes WHERE partition=? AND tbl=? AND var=? AND value=?) AS seq');
+    }
+    return `SELECT max(seq) AS seq FROM (${perValue.join(' UNION ALL ')})`;
+}
+/**
+ * PostgreSQL set-based form of `latestScopedChangeSeqSql` for the
+ * subscriptions of one table in a pull. `$2` is a JSON array of
+ * `{i, var, vals}` records. Params: [partition, specs (JSON text), tbl].
+ */
+export const LATEST_SCOPED_CHANGE_BATCH_SQL = `SELECT s.i AS sub,
+       (SELECT max(latest.seq) FROM (
+          SELECT (SELECT max(commit_seq) FROM sync_change_scopes
+                   WHERE partition=$1 AND tbl=$3 AND var=s.var AND value=v.value) AS seq
+            FROM jsonb_array_elements_text(s.vals) AS v(value)) AS latest) AS seq
+     FROM jsonb_to_recordset($2::text::jsonb) AS s(i int, var text, vals jsonb)
+    ORDER BY s.i`;
 /** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
 export function selectRowScopesSql(table, dialect) {
     const p = dialect === 'sqlite' ? ['?', '?'] : ['$1', '$2'];

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

@@ -42,7 +42,7 @@
  * precise, retryable `sync.segment_expired` and hit `sync.not_found` only
  * long after. Never set lifecycle below `ttlMs`.
  */
-import type { SegmentFindKey, SegmentMetadata, SegmentRecord, SegmentStore, SegmentStoreStats } from './segment-store.js';
+import type { SegmentFindKey, SegmentMetadata, SegmentRecord, SegmentStore, SegmentStoreStats, SegmentStream } from './segment-store.js';
 import type { DelegatedPresignConfig, SegmentUrlIssue } from './signed-url.js';
 export interface S3SegmentStoreConfig {
     /**
@@ -75,6 +75,8 @@ export declare class S3SegmentStore implements SegmentStore {
         record: SegmentRecord;
         bytes: Uint8Array;
     } | undefined>;
+    /** The record plus the object GET's body, never buffered (see `get`). */
+    open(segmentId: string): Promise<SegmentStream | undefined>;
     find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
     /**
      * Store-wide counters from the pointer-object accumulator (never a LIST).

package/dist/s3-segment-store.js

@@ -450,6 +450,22 @@ export class S3SegmentStore {
             bytes: new Uint8Array(await response.arrayBuffer()),
         };
     }
+    /** The record plus the object GET's body, never buffered (see `get`). */
+    async open(segmentId) {
+        if (!SEGMENT_ID_PATTERN.test(segmentId))
+            return undefined;
+        const record = await this.#readRecord(segmentId);
+        if (record === undefined)
+            return undefined;
+        const response = await this.#request('GET', this.objectKeyFor(segmentId));
+        if (response === undefined || response.body === null)
+            return undefined;
+        return {
+            record: record.record,
+            body: response.body,
+            byteLength: record.record.byteLength,
+        };
+    }
     async find(key, nowMs) {
         const response = await this.#request('GET', await this.#findKeyFor(key));
         if (response === undefined)

package/dist/segment-download.d.ts

@@ -11,4 +11,20 @@ export interface SegmentDownloadResult {
     /** Response headers per §5.5. */
     readonly headers: Record<string, string>;
 }
+/** `openSegmentDownload`: the authorized segment as a byte stream. */
+export interface SegmentStreamResult {
+    readonly record: SegmentRecord;
+    readonly body: ReadableStream<Uint8Array<ArrayBuffer>>;
+    readonly byteLength: number;
+    /** Response headers per §5.5. */
+    readonly headers: Record<string, string>;
+}
 export declare function handleSegmentDownload(ctx: SyncRequestContext, request: SegmentDownloadRequest): Promise<SegmentDownloadResult>;
+/**
+ * The §5.5 download as a stream: the same authorization as
+ * `handleSegmentDownload`, with the bytes read through `SegmentStore.open`
+ * when the store provides it, so a host with bounded memory (a Worker)
+ * relays a large sqlite image without buffering it. A store without `open`
+ * serves its `get` bytes as a one-chunk stream.
+ */
+export declare function openSegmentDownload(ctx: SyncRequestContext, request: SegmentDownloadRequest): Promise<SegmentStreamResult>;