@syncular/server 0.26.5 → 0.27.0

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/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

@@ -255,6 +255,19 @@ export declare const COMMIT_WINDOW_BATCH_SQL = "SELECT s.i AS sub, c.commit_seq
  * 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

@@ -606,6 +606,31 @@ export function prefetchRowsSql(table) {
      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>;

package/dist/segment-download.js

@@ -3,7 +3,7 @@ import { SyncError, syncError } from './errors.js';
 import { emitEvent } from './events.js';
 import { compileSchema } from './schema.js';
 import { computeEffective, scopeDigest } from './scopes.js';
-import { publicationRecord } from './segment-store.js';
+import { bytesStream, publicationRecord, } from './segment-store.js';
 function parseScopesHeader(header) {
     let parsed;
     try {
@@ -25,14 +25,28 @@ function parseScopesHeader(header) {
     }
     return scopes;
 }
-export async function handleSegmentDownload(ctx, request) {
+export function handleSegmentDownload(ctx, request) {
+    return withDownloadEvent(ctx, request, () => downloadSegment(ctx, request), (result) => result.bytes.length);
+}
+/**
+ * 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 function openSegmentDownload(ctx, request) {
+    return withDownloadEvent(ctx, request, () => openSegment(ctx, request), (result) => result.byteLength);
+}
+/** Emit `segment.downloaded` around a download when an events sink exists. */
+async function withDownloadEvent(ctx, request, run, bytesOf) {
     const events = ctx.events;
     if (events === undefined)
-        return downloadSegment(ctx, request);
+        return run();
     const clock = clockOf(ctx);
     const startedAtMs = clock();
     try {
-        const result = await downloadSegment(ctx, request);
+        const result = await run();
         emitEvent(events, {
             type: 'segment.downloaded',
             atMs: clock(),
@@ -41,7 +55,7 @@ export async function handleSegmentDownload(ctx, request) {
             segmentId: request.segmentId,
             outcome: 'ok',
             mediaType: result.record.mediaType,
-            bytes: result.bytes.length,
+            bytes: bytesOf(result),
             durationMs: clock() - startedAtMs,
         });
         return result;
@@ -66,11 +80,57 @@ async function downloadSegment(ctx, request) {
     if (entry === undefined) {
         throw syncError('sync.not_found', 'unknown segment (§5.5)');
     }
+    const record = await authorizePublication(ctx, request, registry.logEpoch, entry.record);
+    return { record, bytes: entry.bytes, headers: segmentHeaders(record) };
+}
+async function openSegment(ctx, request) {
+    const registry = await touchAuthenticatedPartition(ctx);
+    const opened = ctx.segments.open !== undefined
+        ? await ctx.segments.open(request.segmentId)
+        : await ctx.segments.get(request.segmentId).then((entry) => entry === undefined
+            ? undefined
+            : {
+                record: entry.record,
+                body: bytesStream(entry.bytes),
+                byteLength: entry.bytes.length,
+            });
+    if (opened === undefined) {
+        throw syncError('sync.not_found', 'unknown segment (§5.5)');
+    }
+    let record;
+    try {
+        record = await authorizePublication(ctx, request, registry.logEpoch, opened.record);
+    }
+    catch (error) {
+        await opened.body.cancel();
+        throw error;
+    }
+    return {
+        record,
+        body: opened.body,
+        byteLength: opened.byteLength,
+        headers: segmentHeaders(record),
+    };
+}
+function segmentHeaders(record) {
+    return {
+        'Content-Type': 'application/octet-stream',
+        ETag: `"${record.segmentId}"`,
+        'Cache-Control': 'private, max-age=0',
+        // Accept-Encoding: the body may be served compressed (§5.8).
+        Vary: 'Authorization, X-Syncular-Scopes, Accept-Encoding',
+    };
+}
+/**
+ * Select and authorize the caller's publication of a stored segment
+ * (§5.5), projected onto that publication.
+ */
+async function authorizePublication(ctx, request, logEpoch, stored) {
     // Select the caller's own publication context. A publication under a
     // different partition or a stale log epoch is not this caller's grant, and
     // the entry's existence must not leak across that boundary (§5.5).
-    const inContext = entry.record.publications.filter((publication) => publication.partition === ctx.partition &&
-        publication.logEpoch === registry.logEpoch);
+    const inContext = stored.publications.filter((publication) => publication.partition === ctx.partition &&
+        publication.logEpoch === logEpoch);
     if (inContext.length === 0) {
         throw syncError('sync.not_found', 'unknown segment (§5.5)');
     }
@@ -144,18 +204,8 @@ async function downloadSegment(ctx, request) {
     if (checkpoints.some((checkpoint) => checkpoint.schemaVersion > publication.schemaVersion)) {
         throw syncError('sync.segment_expired', 'segment predates the partition backfill checkpoint — re-pull (§5.1)');
     }
-    return {
-        // The returned record is projected onto the selected publication, so its
-        // `scopeDigests`/`publications` compatibility view cannot union a grant
-        // from another partition (§5.1).
-        record: publicationRecord(entry.record, publication),
-        bytes: entry.bytes,
-        headers: {
-            'Content-Type': 'application/octet-stream',
-            ETag: `"${entry.record.segmentId}"`,
-            'Cache-Control': 'private, max-age=0',
-            // Accept-Encoding: the body may be served compressed (§5.8).
-            Vary: 'Authorization, X-Syncular-Scopes, Accept-Encoding',
-        },
-    };
+    // The returned record is projected onto the selected publication, so its
+    // `scopeDigests`/`publications` compatibility view cannot union a grant
+    // from another partition (§5.1).
+    return publicationRecord(stored, publication);
 }

package/dist/segment-store.d.ts

@@ -130,6 +130,14 @@ export interface SegmentStoreStats {
      */
     readonly approximate?: boolean;
 }
+/** `SegmentStore.open`: a stored segment with its bytes as a stream. */
+export interface SegmentStream {
+    readonly record: SegmentRecord;
+    readonly body: ReadableStream<Uint8Array<ArrayBuffer>>;
+    readonly byteLength: number;
+}
+/** One buffered segment as a single-chunk `SegmentStream` body. */
+export declare function bytesStream(bytes: Uint8Array): ReadableStream<Uint8Array<ArrayBuffer>>;
 export interface SegmentStore {
     put(metadata: SegmentMetadata, bytes: Uint8Array, nowMs: number): Promise<SegmentRecord>;
     /** Returns expired records too — expiry is the caller's check (§5.5). */
@@ -151,6 +159,13 @@ export interface SegmentStore {
      * against the descriptor.
      */
     find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
+    /**
+     * Optional streaming read: the record plus the bytes as a stream, so the
+     * download route relays a segment larger than the host's memory (a
+     * sqlite image through a Worker). Returns expired records like `get`.
+     * Stores without it are served through `get`.
+     */
+    open?(segmentId: string): Promise<SegmentStream | undefined>;
     /** Admin/console counters: ADDITIVE, optional. */
     stats?(): Promise<SegmentStoreStats>;
 }
@@ -165,6 +180,7 @@ export declare class MemorySegmentStore implements SegmentStore {
         record: SegmentRecord;
         bytes: Uint8Array;
     } | undefined>;
+    open(segmentId: string): Promise<SegmentStream | undefined>;
     find(key: SegmentFindKey, nowMs: number): Promise<SegmentRecord | undefined>;
     stats(): Promise<SegmentStoreStats>;
 }