@syncular/server 0.26.4 → 0.26.6

package/src/postgres-storage.ts

@@ -40,7 +40,7 @@ import { serveNotReadyError } from './readiness';
  * would leave gaps on rollback, which the pull-window arithmetic in §4.5
  * does not tolerate). Cross-partition pushes never contend.
  */
-import type { PushOperationResult } from '@syncular/core';
+import type { PushOperationResult, ScopeMap } from '@syncular/core';
 import {
   bindAuthoritativePartition,
   type BoundAuthoritativeQuery,
@@ -59,6 +59,7 @@ import {
   assertPhysicalColumns,
   assertStoredLayouts,
   COMMIT_WINDOW_BATCH_SQL,
+  LATEST_SCOPED_CHANGE_BATCH_SQL,
   deleteRowSql,
   dropTableDdl,
   indexRowPageStatement,
@@ -76,6 +77,7 @@ import {
   schemaDdl,
   selectRowScopesSql,
   selectRowSql,
+  prefetchRowsSql,
   selectRowsForRewriteSql,
   upsertSql,
   upsertValues,
@@ -697,21 +699,31 @@ async function writeRowOn(
   partition: string,
   row: StoredRow,
 ): Promise<void> {
+  // One statement per row write: the upsert, and the scope index synced to
+  // the row's scope map (entries outside it deleted, missing ones inserted).
+  // No index entry is touched twice, so the writable CTEs cannot conflict.
+  // The scopes bind as text before the JSONB cast (see `appendCommit`).
+  const params = upsertValues(compiled, partition, row, 'postgres');
+  const n = params.length;
   await q.query(
-    upsertSql(compiled, 'postgres'),
-    upsertValues(compiled, partition, row, 'postgres'),
-  );
-  await q.query(
-    'DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$2 AND row_id=$3',
-    [partition, compiled.name, row.rowId],
+    `WITH upserted AS (${upsertSql(compiled, 'postgres')}),
+     scope AS (SELECT key, value FROM jsonb_each_text($${n + 1}::text::jsonb)),
+     removed AS (
+       DELETE FROM sync_row_scopes
+        WHERE partition=$${n + 2} AND tbl=$${n + 3} AND row_id=$${n + 4}
+          AND (var, value) NOT IN (SELECT key, value FROM scope)
+     )
+     INSERT INTO sync_row_scopes(partition, tbl, var, value, row_id)
+     SELECT $${n + 2}, $${n + 3}, key, value, $${n + 4} FROM scope
+     ON CONFLICT DO NOTHING`,
+    [
+      ...params,
+      JSON.stringify(row.scopes),
+      partition,
+      compiled.name,
+      row.rowId,
+    ],
   );
-  for (const [variable, value] of Object.entries(row.scopes)) {
-    await q.query(
-      `INSERT INTO sync_row_scopes(partition, tbl, var, value, row_id)
-       VALUES ($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING`,
-      [partition, compiled.name, variable, value, row.rowId],
-    );
-  }
 }
 
 async function getPushResultOn(
@@ -770,6 +782,13 @@ class PostgresTransaction implements StorageTransaction {
   #resolveTable: (name: string) => CompiledTable;
   #open = true;
   #pushApplySavepoint = false;
+  /**
+   * `prefetchRows` results keyed `table\u0000rowId`; `null` records a row
+   * (or tombstone) read as absent. A write in this transaction drops the
+   * key, so the next read goes to the database again.
+   */
+  readonly #prefetchedRows = new Map<string, StoredRow | null>();
+  readonly #prefetchedTombstones = new Map<string, number | null>();
   /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
   #resolve: () => void;
   #reject: (error: unknown) => void;
@@ -814,6 +833,10 @@ class PostgresTransaction implements StorageTransaction {
 
   getRow(table: string, rowId: string): Promise<StoredRow | undefined> {
     this.#assertOpen();
+    const prefetched = this.#prefetchedRows.get(`${table}\u0000${rowId}`);
+    if (prefetched !== undefined) {
+      return Promise.resolve(prefetched ?? undefined);
+    }
     return getRowOn(
       this.#client,
       this.#resolveTable(table),
@@ -822,11 +845,47 @@ class PostgresTransaction implements StorageTransaction {
     );
   }
 
+  async prefetchRows(table: string, rowIds: readonly string[]): Promise<void> {
+    this.#assertOpen();
+    const ids = [...new Set(rowIds)].filter(
+      (rowId) => !this.#prefetchedRows.has(`${table}\u0000${rowId}`),
+    );
+    if (ids.length === 0) return;
+    const { rows } = await this.#client.query<
+      Omit<RowRecord, 'row_id'> & {
+        lookup_id: string;
+        row_id: string | null;
+        tombstone_seq: unknown;
+      }
+    >(prefetchRowsSql(this.#resolveTable(table)), [
+      this.#partition,
+      JSON.stringify(ids),
+      table,
+    ]);
+    for (const record of rows) {
+      const key = `${table}\u0000${record.lookup_id}`;
+      this.#prefetchedRows.set(
+        key,
+        record.row_id === null
+          ? null
+          : toStoredRow({ ...record, row_id: record.row_id }),
+      );
+      this.#prefetchedTombstones.set(
+        key,
+        record.tombstone_seq === null || record.tombstone_seq === undefined
+          ? null
+          : asNumber(record.tombstone_seq),
+      );
+    }
+  }
+
   async getTombstoneSeq(
     table: string,
     rowId: string,
   ): Promise<number | undefined> {
     this.#assertOpen();
+    const prefetched = this.#prefetchedTombstones.get(`${table}\u0000${rowId}`);
+    if (prefetched !== undefined) return prefetched ?? undefined;
     const { rows } = await this.#client.query<{ commit_seq: unknown }>(
       'SELECT commit_seq FROM sync_tombstones WHERE partition=$1 AND tbl=$2 AND row_id=$3',
       [this.#partition, table, rowId],
@@ -837,6 +896,7 @@ class PostgresTransaction implements StorageTransaction {
 
   async clearTombstone(table: string, rowId: string): Promise<void> {
     this.#assertOpen();
+    this.#prefetchedTombstones.delete(`${table}\u0000${rowId}`);
     await this.#client.query(
       'DELETE FROM sync_tombstones WHERE partition=$1 AND tbl=$2 AND row_id=$3',
       [this.#partition, table, rowId],
@@ -976,6 +1036,7 @@ class PostgresTransaction implements StorageTransaction {
     context?: { readonly opIndex: number },
   ): Promise<void> {
     this.#assertOpen();
+    this.#prefetchedRows.delete(`${table}\u0000${row.rowId}`);
     try {
       await writeRowOn(
         this.#client,
@@ -993,18 +1054,16 @@ class PostgresTransaction implements StorageTransaction {
 
   async deleteRow(table: string, rowId: string): Promise<void> {
     this.#assertOpen();
+    this.#prefetchedRows.delete(`${table}\u0000${rowId}`);
+    // One statement: the row, its scope-index entries, and (§5.9.4: a
+    // deleted row references no blobs) its blob references.
     await this.#client.query(
-      deleteRowSql(this.#resolveTable(table), 'postgres'),
-      [this.#partition, rowId],
-    );
-    await this.#client.query(
-      'DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$2 AND row_id=$3',
-      [this.#partition, table, rowId],
-    );
-    // §5.9.4: a deleted row references no blobs.
-    await this.#client.query(
-      'DELETE FROM sync_blob_refs WHERE partition=$1 AND tbl=$2 AND row_id=$3',
-      [this.#partition, table, rowId],
+      `WITH deleted AS (${deleteRowSql(this.#resolveTable(table), 'postgres')}),
+       unscoped AS (
+         DELETE FROM sync_row_scopes WHERE partition=$1 AND tbl=$3 AND row_id=$2
+       )
+       DELETE FROM sync_blob_refs WHERE partition=$1 AND tbl=$3 AND row_id=$2`,
+      [this.#partition, rowId, table],
     );
   }
 
@@ -1030,6 +1089,8 @@ class PostgresTransaction implements StorageTransaction {
 
   async appendCommit(commit: NewCommit): Promise<number> {
     this.#assertOpen();
+    // The commit writes its delete tombstones below.
+    this.#prefetchedTombstones.clear();
     const q = this.#client;
     const p = this.#partition;
     // Allocate the next dense commitSeq under a per-partition row lock: the
@@ -1055,42 +1116,46 @@ class PostgresTransaction implements StorageTransaction {
       ],
     );
     const commitSeq = asNumber(rows[0]?.commit_seq);
-    for (let idx = 0; idx < commit.changes.length; idx++) {
-      const change = commit.changes[idx];
-      if (change === undefined) continue;
-      // Bind serialized scopes as text before parsing JSONB. Drivers that
-      // encode JSONB parameters would otherwise store this string as a scalar.
-      // One statement per change: scopes AND the §5 delete tombstone ride the
-      // same writable-CTE chain.
-      await q.query(
-        `WITH inserted AS (
-           INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
-           VALUES ($1,$2,$3,$4,$5,$6,$7,$8::text::jsonb,$9)
-           RETURNING partition, tbl, row_id, op, commit_seq, scopes
-         ),
-         scoped AS (
-           INSERT INTO sync_change_scopes(partition, tbl, var, value, commit_seq)
-           SELECT inserted.partition, inserted.tbl, scope.key, scope.value, inserted.commit_seq
-           FROM inserted CROSS JOIN LATERAL jsonb_each_text(inserted.scopes) AS scope
-           ON CONFLICT DO NOTHING
-         )
-         INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq)
-         SELECT partition, tbl, row_id, commit_seq FROM inserted WHERE op = 2
-         ON CONFLICT (partition, tbl, row_id)
-         DO UPDATE SET commit_seq = excluded.commit_seq`,
-        [
-          p,
-          commitSeq,
-          idx,
-          change.table,
-          change.rowId,
-          change.op === 'upsert' ? 1 : 2,
-          change.rowVersion ?? null,
-          JSON.stringify(change.scopes),
-          change.payload ?? null,
-        ],
+    if (commit.changes.length === 0) return commitSeq;
+    // One statement for the whole commit: its changes, their inverted scope
+    // entries, and the §5 delete tombstones ride one writable-CTE chain.
+    // Serialized scopes bind as text before parsing JSONB; drivers that
+    // encode JSONB parameters would otherwise store the string as a scalar.
+    // A commit can delete one row twice, so the tombstone insert keeps one
+    // row per key (every candidate carries the same commit_seq).
+    const params: unknown[] = [p, commitSeq];
+    const values = commit.changes.map((change, idx) => {
+      const base = params.length;
+      params.push(
+        idx,
+        change.table,
+        change.rowId,
+        change.op === 'upsert' ? 1 : 2,
+        change.rowVersion ?? null,
+        JSON.stringify(change.scopes),
+        change.payload ?? null,
       );
-    }
+      return `($1,$2::bigint,$${base + 1}::int,$${base + 2},$${base + 3},$${base + 4}::smallint,$${base + 5}::bigint,$${base + 6}::text::jsonb,$${base + 7}::bytea)`;
+    });
+    await q.query(
+      `WITH inserted AS (
+         INSERT INTO sync_changes(partition, commit_seq, idx, tbl, row_id, op, row_version, scopes, payload)
+         VALUES ${values.join(',')}
+         RETURNING partition, tbl, row_id, op, commit_seq, scopes
+       ),
+       scoped AS (
+         INSERT INTO sync_change_scopes(partition, tbl, var, value, commit_seq)
+         SELECT inserted.partition, inserted.tbl, scope.key, scope.value, inserted.commit_seq
+         FROM inserted CROSS JOIN LATERAL jsonb_each_text(inserted.scopes) AS scope
+         ON CONFLICT DO NOTHING
+       )
+       INSERT INTO sync_tombstones(partition, tbl, row_id, commit_seq)
+       SELECT DISTINCT ON (tbl, row_id) partition, tbl, row_id, commit_seq
+         FROM inserted WHERE op = 2
+       ON CONFLICT (partition, tbl, row_id)
+       DO UPDATE SET commit_seq = excluded.commit_seq`,
+      params,
+    );
     return commitSeq;
   }
 
@@ -2142,6 +2207,26 @@ FOR EACH ROW EXECUTE FUNCTION syncular_writer_fence()`);
     };
   }
 
+  async latestScopedChangeSeq(
+    partition: string,
+    query: { readonly table: string; readonly scopeFilter: ScopeMap },
+  ): Promise<number> {
+    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<{ seq: unknown }>(
+      LATEST_SCOPED_CHANGE_BATCH_SQL,
+      partition,
+      query.table,
+      { var: firstVariable, vals: values },
+    );
+    return row === undefined ? 0 : asNumber(row.seq);
+  }
+
   async readCommitWindow(
     partition: string,
     query: CommitWindowQuery,

package/src/pull.ts

@@ -9,13 +9,18 @@ import {
   type PullHeaderFrame,
   type ResponseFrame,
   type ScopeMap,
+  type SegmentRefFrame,
   type SegmentRow,
   type SubscriptionFrame,
 } from '@syncular/core';
-import type { SyncRequestContext } from './context';
+import type { SyncRequestContext, SyncServerConfig } from './context';
 import { clockOf, limitsOf } from './context';
 import type { PullSegmentSummary } from './events';
-import type { CompiledSchema, CompiledTable } from './schema';
+import {
+  type CompiledSchema,
+  type CompiledTable,
+  compileSchema,
+} from './schema';
 import { scopeDigest } from './scopes';
 import type { SegmentRecord, SegmentStore } from './segment-store';
 import { issueSegmentUrl } from './signed-url';
@@ -244,21 +249,11 @@ async function* sqliteImageSegment(
   digest: string,
   trace: PullSectionTrace | undefined,
   logEpoch: string,
+  existing: SegmentRecord | undefined,
+  probe: StoredRow[],
 ): AsyncGenerator<ResponseFrame, boolean> {
   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',
@@ -276,12 +271,7 @@ async function* sqliteImageSegment(
   }
   // 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
   // builder through `sqliteImageBuilder`; when omitted we default to the
@@ -389,7 +379,8 @@ async function* bootstrapSegments(
   startRowCursor: string | null,
   trace: PullSectionTrace | undefined,
   logEpoch: string,
-  firstPage: StoredRow[] | undefined,
+  firstPage: StoredRow[],
+  image: SegmentRecord | undefined,
 ): AsyncGenerator<
   ResponseFrame,
   { complete: boolean; rowCursor: string | null }
@@ -408,13 +399,15 @@ async function* bootstrapSegments(
       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
+      page === 0
         ? firstPage
         : await storage.scanRows(partition, {
             table: plan.table.name,
@@ -492,27 +485,45 @@ async function* bootstrapSegments(
 /**
  * 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;
+}
+
+interface PendingSection {
+  readonly commits?: Promise<StoredCommit[]>;
+  readonly firstPage?: Promise<StoredRow[]>;
+  readonly lane?: Promise<{
+    readonly pin: number | undefined;
+    readonly image: SegmentRecord | undefined;
+  }>;
 }
 
 /** Run the pre-frame storage reads of every subscription concurrently. */
 export async function prepareSections(
   ctx: SyncRequestContext,
+  schema: CompiledSchema,
   limits: PullLimits,
   plans: readonly SubscriptionPlan[],
   maxSeq: number,
   horizonSeq: number,
+  logEpoch: string,
 ): Promise<PreparedSection[]> {
-  const reads = plans.map((plan) => {
+  const reads = plans.map((plan): PendingSection => {
     const sub = plan.frame;
     if (plan.status === 'revoked') return {};
     const token = parseBootstrapToken(sub.bootstrapState, sub.table);
@@ -537,24 +548,55 @@ export async function prepareSections(
       return {};
     }
     // Bootstrapping: the same resume decision `preparedSection` makes (§4.7).
-    const startCursor =
+    const resume =
       token !== undefined && token.asOfCommitSeq >= horizonSeq
-        ? token.rowCursor
-        : null;
-    if (sqliteLaneEligible(limits, plan, startCursor)) return {};
-    return {
-      firstPage: ctx.storage.scanRows(ctx.partition, {
-        table: plan.table.name,
-        scopeFilter: plan.effective,
-        afterRowId: startCursor,
-        limit: limits.limitSnapshotRows + 1,
-      }),
-    };
+        ? 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,
+            })
+            .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
@@ -566,6 +608,8 @@ export async function prepareSections(
     commits: read.commits ?? [],
     horizonSeq: read.commits === undefined ? horizonSeq : windowHorizon,
     firstPage: read.firstPage,
+    pin: read.lane?.pin,
+    image: read.lane?.image,
   }));
 }
 
@@ -583,12 +627,17 @@ export async function* subscriptionSection(
   trace?: PullSectionTrace,
   logEpoch?: string,
 ): AsyncGenerator<ResponseFrame, SubscriptionResult> {
+  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(
@@ -660,8 +709,11 @@ export async function* preparedSection(
       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,
@@ -680,6 +732,7 @@ export async function* preparedSection(
       trace,
       logEpoch,
       prepared.firstPage,
+      prepared.image,
     );
     if (outcome.complete) {
       yield { type: 'SUB_END', nextCursor: asOf };
@@ -740,3 +793,123 @@ export async function* preparedSection(
   yield { type: 'SUB_END', nextCursor };
   return { nextCursor, active: true };
 }
+
+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 async function publishSqliteImage(
+  input: PublishSqliteImageInput,
+): Promise<PublishedSqliteImage> {
+  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: SyncRequestContext = {
+    ...config,
+    partition,
+    actorId: 'syncular.image-publisher',
+  };
+  const plan: SubscriptionPlan = {
+    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: PullLimits = {
+    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: PullSectionTrace = { segments: [] };
+  const [prepared] = await prepareSections(
+    ctx,
+    schema,
+    limits,
+    [plan],
+    maxSeq,
+    horizonSeq,
+    logEpoch,
+  );
+  if (prepared === undefined) throw new Error('prepareSections lost a plan');
+  let ref: SegmentRefFrame | undefined;
+  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',
+  };
+}