@syncular/server 0.26.5 → 0.26.6

package/dist/content-encoding.d.ts

@@ -25,3 +25,20 @@ export interface EncodedSegmentBody {
  * tiny, or the runtime has no codec.
  */
 export declare function encodeSegmentBody(bytes: Uint8Array, acceptEncoding: string | undefined): EncodedSegmentBody;
+/**
+ * Segments above this size are relayed as a stream instead of being
+ * buffered and compressed in memory: a sqlite image can exceed the memory of
+ * a Workers isolate (128 MB).
+ */
+export declare const SEGMENT_STREAM_THRESHOLD_BYTES: number;
+export interface EncodedSegmentStream {
+    readonly body: ReadableStream<Uint8Array<ArrayBuffer>>;
+    /** Absent ⇒ identity (no `Content-Encoding` header). */
+    readonly contentEncoding?: 'gzip';
+}
+/**
+ * Compress a streamed segment body per §5.8 with the runtime's
+ * `CompressionStream`: gzip when the client accepts it, identity otherwise
+ * (zstd has no standard streaming codec).
+ */
+export declare function encodeSegmentStream(body: ReadableStream<Uint8Array<ArrayBuffer>>, acceptEncoding: string | undefined): EncodedSegmentStream;

package/dist/content-encoding.js

@@ -67,3 +67,25 @@ export function encodeSegmentBody(bytes, acceptEncoding) {
     }
     return { bytes };
 }
+/**
+ * Segments above this size are relayed as a stream instead of being
+ * buffered and compressed in memory: a sqlite image can exceed the memory of
+ * a Workers isolate (128 MB).
+ */
+export const SEGMENT_STREAM_THRESHOLD_BYTES = 16 * 1024 * 1024;
+/**
+ * Compress a streamed segment body per §5.8 with the runtime's
+ * `CompressionStream`: gzip when the client accepts it, identity otherwise
+ * (zstd has no standard streaming codec).
+ */
+export function encodeSegmentStream(body, acceptEncoding) {
+    if (acceptEncoding === undefined ||
+        !accepts(acceptEncoding, 'gzip') ||
+        typeof CompressionStream !== 'function') {
+        return { body };
+    }
+    return {
+        body: body.pipeThrough(new CompressionStream('gzip')),
+        contentEncoding: 'gzip',
+    };
+}

package/dist/context.d.ts

@@ -7,6 +7,7 @@
 import type { ScopeMap } from '@syncular/core';
 import type { BlobStore } from './blob-store.js';
 import type { CrdtMergerRegistry } from './crdt-merger.js';
+import type { SyncularErrorHandler } from './errors.js';
 import type { SyncularServerEvents } from './events.js';
 import type { LeaseStore } from './lease-store.js';
 import type { AnyReactionPlanner } from './reactions.js';
@@ -167,6 +168,14 @@ export interface SyncServerConfig {
      * event objects are built. A throwing sink never affects processing.
      */
     readonly events?: SyncularServerEvents;
+    /**
+     * Host error reporting (§10.2 `sync.internal_error`). Receives the original
+     * exception whenever a request, socket round, segment or blob download,
+     * or remote operation fails with something other than a `SyncError`; the
+     * client sees only the catalog code. Like the events sink, a throwing
+     * handler never changes the response.
+     */
+    readonly onError?: SyncularErrorHandler;
 }
 /** Per-request context: the config plus host-authenticated identity. */
 export interface SyncRequestContext extends SyncServerConfig {

package/dist/d1-storage.d.ts

@@ -1,4 +1,46 @@
 import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
+/**
+ * Cloudflare D1 server storage for Workers deployments.
+ *
+ * D1 *is* SQLite exposed over an async, statement-at-a-time API
+ * (`prepare(sql).bind(...).all()` / `.first()` / `.run()`, plus `batch([…])`
+ * for atomic multi-statement writes). So this storage shares the schema and
+ * value codecs with `SqliteServerStorage` via `sqlite-dialect.ts` — same
+ * DDL, same `?` placeholders, same JSON-scope / base64-push-result
+ * serialization — and differs only in the execution shape (async, no
+ * interactive transaction).
+ *
+ * ## Transaction model (the one real divergence)
+ *
+ * D1 has **no interactive transaction**: you cannot `BEGIN`, run
+ * conditional reads and writes on a pinned connection, then `COMMIT`. The
+ * only atomic primitive is `db.batch([stmt, …])` — a set of statements
+ * applied in one implicit transaction, all-or-nothing.
+ *
+ * The push handler (§6) reads first (conflict detection via `getRow`) and
+ * only then writes (`upsertRow`/`deleteRow`/`appendCommit`/
+ * `putPushResult`). `D1Transaction` exploits exactly that ordering:
+ *
+ *   - reads (`getRow`) execute immediately against D1 (autocommit);
+ *   - writes are **buffered** as prepared statements;
+ *   - `commit()` flushes the whole buffer as one `db.batch(...)` — the same
+ *     atomicity §6.4 requires (a rejected op rolls back by simply never
+ *     flushing);
+ *   - `rollback()` drops the buffer unsent.
+ *
+ * `appendCommit` allocates the dense per-partition `commitSeq` (§2.1) by
+ * reading `max_commit_seq` live and buffering the `+1` write. Under a single
+ * Worker request this is exact. Two concurrent pushes to one partition need an
+ * external serialization point (normally a per-partition Durable Object); a
+ * realtime notifier alone does not serialize HTTP writes. Every deployment
+ * that accepts D1 pushes MUST front same-partition sync rounds with a
+ * coordinating primitive (a DO or a Queue). The adapter fails closed unless
+ * that coordinator explicitly sets `pushApplySerialized`, because D1 cannot
+ * provide the required pre-operation lock.
+ * This mirrors PostgreSQL's per-partition row lock, achieved by placement
+ * rather than a lock D1 does not expose.
+ */
+import { type ScopeMap } from '@syncular/core';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCommit, StoredCheckpoint, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
 export interface D1PreparedStatement {
@@ -73,6 +115,10 @@ export declare class D1ServerStorage implements ServerStorage {
     getReaction(partition: string, idempotencyKey: string): Promise<StoredReaction | undefined>;
     listReactions(partition: string, query: ReactionListQuery): Promise<StoredReaction[]>;
     pruneReactions(partition: string, query: ReactionPruneQuery): Promise<PrunedReactionCounts>;
+    latestScopedChangeSeq(partition: string, query: {
+        readonly table: string;
+        readonly scopeFilter: ScopeMap;
+    }): Promise<number>;
     readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
     scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;

package/dist/d1-storage.js

@@ -45,7 +45,7 @@ import { StorageQueryError } from './storage-errors.js';
 import { decodeRow } from '@syncular/core';
 import { bindAuthoritativePartition, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
-import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertAppendOnlyMigration, assertPhysicalColumns, assertStoredLayouts, commitWindowPageSql, latestScopedChangeSeqSql, deleteRowSql, deleteSqliteRowScopesSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, quoteIdent, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_SQLITE, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, selectRowsForRewriteSql, tableColumnNames, toSqlValue, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { asUint8Array, collectCommitWindowPage, deserializePushResult, placeholders, serializePushResult, sqliteDdlStatements, toStoredRow, } from './sqlite-dialect.js';
 import { isD1ConstraintError, StorageConstraintError } from './storage-errors.js';
@@ -1439,6 +1439,17 @@ export class D1ServerStorage {
             deadLetter: results.filter((row) => row.status === 'dead-letter').length,
         };
     }
+    async latestScopedChangeSeq(partition, query) {
+        const firstVariable = Object.keys(query.scopeFilter).sort()[0];
+        const values = firstVariable === undefined
+            ? []
+            : (query.scopeFilter[firstVariable] ?? []);
+        if (firstVariable === undefined || values.length === 0)
+            return 0;
+        // Concurrent reads of a pull share one `db.batch` round trip.
+        const [row] = await this.#batchedAll(latestScopedChangeSeqSql(values.length), values.flatMap((value) => [partition, query.table, firstVariable, value]));
+        return row?.seq ?? 0;
+    }
     async readCommitWindow(partition, query) {
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];

package/dist/errors.d.ts

@@ -34,3 +34,22 @@ export declare function errorBody(error: SyncError): {
     message: string;
     details?: unknown;
 };
+/** The adapter surface that caught an exception reported through `onError`. */
+export type SyncularErrorRoute = 'sync' | 'operations' | 'segments' | 'blobs' | 'admin' | 'realtime';
+/**
+ * Host error reporting: receives every exception that is not a `SyncError`
+ * before the adapter answers `sync.internal_error` (or the remote-operation
+ * `operation.*` failure code), with the surface that caught it.
+ */
+export type SyncularErrorHandler = (error: unknown, context: {
+    readonly route: SyncularErrorRoute;
+}) => void;
+/**
+ * The protocol error for an exception an adapter caught. A `SyncError`
+ * passes through unchanged. Anything else goes to `onError` and becomes
+ * `sync.internal_error` (§10.2), whose message never carries the exception
+ * text.
+ */
+export declare function adapterSyncError(error: unknown, onError: SyncularErrorHandler | undefined, route: SyncularErrorRoute): SyncError;
+/** Hand `error` to the host's `onError`; a throwing handler is contained. */
+export declare function reportError(error: unknown, onError: SyncularErrorHandler | undefined, route: SyncularErrorRoute): void;

package/dist/errors.js

@@ -163,6 +163,14 @@ export const ERROR_CATALOG = {
     // checkpoint is incomplete or the database is newer than the running build.
     // Formerly host-only; promoted to the §10.2 catalogue so an in-flight
     // request can be refused with a distinguishable identity.
+    // An exception outside this catalog (host code, storage, network) reached
+    // an adapter; the original goes to `onError`, never onto the wire.
+    'sync.internal_error': {
+        category: 'internal',
+        retryable: true,
+        recommendedAction: 'retryLater',
+        httpStatus: 500,
+    },
     'sync.schema_not_ready': {
         category: 'internal',
         retryable: true,
@@ -288,3 +296,24 @@ export function errorBody(error) {
             : {}),
     };
 }
+/**
+ * The protocol error for an exception an adapter caught. A `SyncError`
+ * passes through unchanged. Anything else goes to `onError` and becomes
+ * `sync.internal_error` (§10.2), whose message never carries the exception
+ * text.
+ */
+export function adapterSyncError(error, onError, route) {
+    if (error instanceof SyncError)
+        return error;
+    reportError(error, onError, route);
+    return new SyncError('sync.internal_error', 'internal server error');
+}
+/** Hand `error` to the host's `onError`; a throwing handler is contained. */
+export function reportError(error, onError, route) {
+    try {
+        onError?.(error, { route });
+    }
+    catch {
+        // The report is best effort; the response stays the catalog error.
+    }
+}

package/dist/handler.js

@@ -353,7 +353,7 @@ async function* streamResponse(plan, ctx, schema, report) {
             const limits = clampPullLimits(plan.pull);
             const maxSeq = await ctx.storage.getMaxCommitSeq(ctx.partition);
             const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
-            const prepared = await prepareSections(ctx, limits, plan.subscriptions, maxSeq, horizonSeq);
+            const prepared = await prepareSections(ctx, schema, limits, plan.subscriptions, maxSeq, horizonSeq, plan.logEpoch);
             for (const [index, subscription] of plan.subscriptions.entries()) {
                 const trace = summaries !== undefined ? { segments: [] } : undefined;
                 const reads = prepared[index];

package/dist/index.d.ts

@@ -44,7 +44,7 @@ export * from './segment-store.js';
 export * from './signed-url.js';
 export * from './sqlite-dialect.js';
 export * from './sqlite-driver.js';
-export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, type SqliteImageBuilder, type SqliteImageInput, } from './sqlite-image.js';
+export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, type SqliteImageBuilder, type SqliteImageInput, writeSqliteImage, } from './sqlite-image.js';
 export * from './sqlite-blob-store.js';
 export * from './sqlite-lease-store.js';
 export * from './sqlite-segment-store.js';

package/dist/index.js

@@ -48,7 +48,7 @@ export * from './segment-store.js';
 export * from './signed-url.js';
 export * from './sqlite-dialect.js';
 export * from './sqlite-driver.js';
-export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, } from './sqlite-image.js';
+export { IMAGE_METADATA_TABLE, IMAGE_VERSION_COLUMN, writeSqliteImage, } from './sqlite-image.js';
 export * from './sqlite-blob-store.js';
 export * from './sqlite-lease-store.js';
 export * from './sqlite-segment-store.js';

package/dist/operations-realtime.js

@@ -1,6 +1,6 @@
 import { decodeRemoteOperationRealtimeMessage, encodeRemoteOperationRealtimeMessage, } from '@syncular/core';
 import { REMOTE_COMMAND_CLIENT_ID_PREFIX } from './context.js';
-import { SyncError, syncError } from './errors.js';
+import { reportError, SyncError, syncError } from './errors.js';
 class WatchSession {
     #ctx;
     #registry;
@@ -122,6 +122,9 @@ class WatchSession {
                     if (this.#isClosed || this.#watches.get(state.watchId) !== state) {
                         return;
                     }
+                    if (!(error instanceof SyncError)) {
+                        reportError(error, this.#ctx.onError, 'operations');
+                    }
                     this.#sendError(state.watchId, error instanceof SyncError
                         ? error
                         : syncError('operation.query_failed'));

package/dist/operations.js

@@ -1,7 +1,7 @@
 import { validateAuthoritativeRelationPlan, } from './authoritative-query.js';
 import { decodeRow, decodeRemoteOperationRequest, encodeRemoteOperationResponse, encodeSparseRow, } from '@syncular/core';
 import { REMOTE_COMMAND_CLIENT_ID_PREFIX, RESOLVER_OUTAGE, touchAuthenticatedPartition, } from './context.js';
-import { SyncError, syncError } from './errors.js';
+import { reportError, SyncError, syncError } from './errors.js';
 import { processPushOperationsWithTrace } from './push.js';
 import { compileSchema } from './schema.js';
 import { authorizeWrite } from './scopes.js';
@@ -206,6 +206,7 @@ export function registerRemoteQuery(descriptor, options) {
             catch (error) {
                 if (error instanceof SyncError)
                     throw error;
+                reportError(error, ctx.onError, 'operations');
                 throw syncError('operation.query_failed', 'registered query execution failed');
             }
             if (result.rows.length > options.maxRows) {
@@ -218,6 +219,7 @@ export function registerRemoteQuery(descriptor, options) {
             catch (error) {
                 if (error instanceof SyncError)
                     throw error;
+                reportError(error, ctx.onError, 'operations');
                 throw syncError('operation.query_failed', 'registered query result decoding failed');
             }
             return {
@@ -409,6 +411,9 @@ export async function handleRemoteOperation(bytes, ctx, registry) {
         return encodeRemoteOperationResponse(await operation.run(ctx, request.clientId, request.requestId, request.params));
     }
     catch (error) {
+        if (!(error instanceof SyncError)) {
+            reportError(error, ctx.onError, 'operations');
+        }
         return encodeRemoteOperationError(error, 'operation.execution_failed');
     }
 }

package/dist/postgres-storage.d.ts

@@ -1,4 +1,42 @@
 import type { CommitPruneQuery, CommitPruneResult } from './storage.js';
+/**
+ * Postgres server storage: the production database path.
+ *
+ * Semantics mirror `SqliteServerStorage` exactly (both run the shared
+ * storage contract in `test/storage-contract.ts`); the difference is that
+ * scope fanout MUST survive contact with Postgres — no scan-before-LIMIT,
+ * ever (performance-by-construction):
+ *
+ *   - both the commit log and the current-row table carry a (table, var,
+ *     value) inverted scope index;
+ *   - `readCommitWindow`/`scanRows` select candidates through that index
+ *     (`sync_change_scopes` / `sync_row_scopes`), ordered + LIMITed at the
+ *     index, then verify the full multi-variable match against the stored
+ *     scope map — never a log or table scan;
+ *   - the candidate indexes are *covering* for their selection: the ordered
+ *     column (`commit_seq` / `row_id`) sits in the index key after
+ *     (tbl, var, value), so the planner does an index range scan and returns
+ *     already-ordered candidates without a heap sort. `test/postgres-explain
+ *     .test.ts` asserts an `Index` node (never `Seq Scan`) so the regression
+ *     cannot silently return.
+ *
+ * Storage is written against the `PgExecutor` seam (zero runtime deps); the
+ * production driver (Bun.sql / node-postgres) and the test driver (pglite)
+ * are wired by the host. See `pg-executor.ts` and the server README.
+ *
+ * ## commitSeq allocation under concurrency
+ *
+ * Per-partition `commitSeq` is a dense, gap-free counter (§2.1), allocated
+ * inside the push transaction by `UPDATE sync_partitions SET
+ * max_commit_seq = max_commit_seq + 1 … RETURNING`. The `UPDATE` takes a
+ * row-level write lock on the partition row for the duration of the
+ * transaction, so two concurrent pushes to the same partition serialize on
+ * that row: the second blocks until the first commits, then reads the
+ * advanced counter. This keeps the sequence dense (a Postgres `SEQUENCE`
+ * would leave gaps on rollback, which the pull-window arithmetic in §4.5
+ * does not tolerate). Cross-partition pushes never contend.
+ */
+import type { ScopeMap } from '@syncular/core';
 import { type PgExecutor } from './pg-executor.js';
 import type { CompiledSchema, CompiledTable } from './schema.js';
 import type { AuthoritativeQueryRequest, AuthoritativeQueryResult, CheckpointDeclaration, ClientCursorInfo, ClientRecord, CommitMetadata, CommitMetadataQuery, CommitWindowQuery, IndexRowScanQuery, PartitionRegistryEntry, PrunedReactionCounts, ReactionClaimQuery, ReactionFailureUpdate, ReactionListQuery, ReactionPruneQuery, RowScanQuery, ScopeActivityQuery, ScopeCommitActivity, ServerStorage, ServeGate, StorageTransaction, StoredCheckpoint, StoredCommit, StoredPushResult, StoredReaction, StoredRow } from './storage.js';
@@ -77,6 +115,10 @@ export declare class PostgresServerStorage implements ServerStorage {
     getReaction(partition: string, idempotencyKey: string): Promise<StoredReaction | undefined>;
     listReactions(partition: string, query: ReactionListQuery): Promise<StoredReaction[]>;
     pruneReactions(partition: string, query: ReactionPruneQuery): Promise<PrunedReactionCounts>;
+    latestScopedChangeSeq(partition: string, query: {
+        readonly table: string;
+        readonly scopeFilter: ScopeMap;
+    }): Promise<number>;
     readCommitWindow(partition: string, query: CommitWindowQuery): Promise<StoredCommit[]>;
     scanRows(partition: string, query: RowScanQuery): Promise<StoredRow[]>;
     scanRowsByIndex(partition: string, query: IndexRowScanQuery): Promise<StoredRow[]>;

package/dist/postgres-storage.js

@@ -5,7 +5,7 @@ import { serveNotReadyError } from './readiness.js';
 import { bindAuthoritativePartition, postgresPlaceholders, prepareAuthoritativeQuery, } from './authoritative-query.js';
 import { syncError } from './errors.js';
 import { asBytes, asNumber, } from './pg-executor.js';
-import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowBatchSql, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, prefetchRowsSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
+import { assertPhysicalColumns, assertStoredLayouts, COMMIT_WINDOW_BATCH_SQL, LATEST_SCOPED_CHANGE_BATCH_SQL, deleteRowSql, dropTableDdl, indexRowPageStatement, layoutsOf, migratePayload, parseLayouts, retiredTableNames, rewritePlan, rewriteRowSql, rewriteValues, SCHEMA_META_DDL_POSTGRES, scanRowBatchSql, scanRowPageSql, schemaDdl, selectRowScopesSql, selectRowSql, prefetchRowsSql, selectRowsForRewriteSql, upsertSql, upsertValues, } from './relational-rows.js';
 import { matchesEffective } from './scopes.js';
 import { isPostgresConstraintError, StorageConstraintError, } from './storage-errors.js';
 import { assertScopeIndexedScan, resolveIndexRowScan } from './storage-query.js';
@@ -1402,6 +1402,17 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
             deadLetter: rows.filter((row) => row.status === 'dead-letter').length,
         };
     }
+    async latestScopedChangeSeq(partition, query) {
+        const firstVariable = Object.keys(query.scopeFilter).sort()[0];
+        const values = firstVariable === undefined
+            ? []
+            : (query.scopeFilter[firstVariable] ?? []);
+        if (firstVariable === undefined || values.length === 0)
+            return 0;
+        // Concurrent reads of one table in a pull share one statement.
+        const [row] = await this.#batchedPage(LATEST_SCOPED_CHANGE_BATCH_SQL, partition, query.table, { var: firstVariable, vals: values });
+        return row === undefined ? 0 : asNumber(row.seq);
+    }
     async readCommitWindow(partition, query) {
         const variables = Object.keys(query.scopeFilter).sort();
         const firstVariable = variables[0];

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