@syncular/server 0.30.16 → 0.31.0

package/README.md

@@ -28,8 +28,8 @@ telemetry. See the [domain event guide](https://syncular.dev/guide-domain-events
 
 The server core is **runtime-neutral TypeScript** — `handleSyncRequest` and
 the realtime session speak only Web `Request`/`Response`/`fetch`/Web-Crypto,
-no Bun- or Node-only builtin (enforced by a static import-graph scan,
-`test/runtime-neutrality.test.ts`). Adapters wire that core to a runtime.
+no Bun- or Node-only builtin (enforced by static and dynamic import scans
+and an unminified browser bundle in `test/runtime-neutrality.test.ts`). Adapters wire that core to a runtime.
 The supported set, and what deliberately does **not** get an adapter:
 
 | Runtime | Adapter | Transport | Storage | Status |
@@ -83,11 +83,12 @@ import {
   ensureSyncServerReady,
   type SyncServerConfig,
 } from '@syncular/server';
-import { SqliteServerStorage } from '@syncular/server/sqlite';
+import { buildSqliteImage, SqliteServerStorage } from '@syncular/server/sqlite';
 
 const config: SyncServerConfig = {
   schema,
   storage: new SqliteServerStorage('./sync.db'),
+  sqliteImageBuilder: buildSqliteImage,
   segments,
   resolveScopes,
 };
@@ -102,6 +103,14 @@ storage, leases, and SQLite-image generation without an external SQLite
 package. The runtime-specific database wrappers are `BunSqliteDatabase` and
 `NodeSqliteDatabase` when a host needs direct access to the native handle.
 
+Hosts opt into building SQLite bootstrap images by supplying
+`sqliteImageBuilder: buildSqliteImage` in the server config (and the realtime
+hub config when it serves sync rounds). The neutral `@syncular/server` entry
+never detects the runtime or loads a SQLite builder. Import the builder from
+`@syncular/server/sqlite` on Bun or Node. Without a builder, the server serves
+matching stored images and negotiates inline or external rows, including
+signed URLs when configured, according to the client's accepted formats.
+
 The helper accepts the generated `ServerSchema`, compiles it, and calls the
 storage backend's low-level `ensureSchema(CompiledSchema)`. A failure is a
 `SyncServerReadinessError` with stable code `sync.schema_not_ready`, a `phase`
@@ -121,6 +130,22 @@ partition. The rotation clears stale client cursors and requires version 2
 clients to reset their server-derived rows while preserving the outbox. Follow
 the complete [backup and restore runbook](https://syncular.dev/server-backup-restore/).
 
+## Adapter error hooks
+
+A `SyncError` answers with its catalog code and status. By default, any other exception an
+adapter catches answers `sync.internal_error` and is handed to
+`SyncServerConfig.onError` exactly once; a throwing observer does not change
+the response. The same config accepts an optional synchronous `mapError` hook:
+after `onError` observes the original, `mapError` may return a catalog
+`SyncError` (with structured `details`, for example `retryAfterMs`) that the
+adapter answers instead. Return `undefined` to keep `sync.internal_error`. A
+throw, a non-`SyncError` return, a code that is not an own catalog entry, or
+`details` that is not a JSON document is contained as `sync.internal_error`.
+The hook covers the sync, operations, segments, blobs, admin, and realtime
+surfaces; `createSyncularAdminRoutes` takes its own `mapError`. It does not
+change a remote operation's `operation.*` envelope, and a mapped `retryAfterMs`
+is delivery metadata. Client retry scheduling remains unchanged.
+
 ## Write validators and recovery metadata
 
 `validators` is the server-authoritative seam for row business rules that
@@ -243,10 +268,55 @@ Do not set that assertion on a stateless Worker. Custom storages must implement
 the pre-operation partition lock, locked idempotency re-check, atomic rejection
 finalization, and—when `commitValidator` is used—candidate scans.
 
+`D1ServerStorage` updates the client record in place instead of deleting and
+reinserting it, and a row update whose scope map is unchanged leaves the
+scope-index entries alone. Both liveness timestamps keep their cadence: the
+partition's `last_authenticated_at_ms` and the client's `updated_at_ms`
+retain their existing refresh cadence. A logical same-value commit still
+applies in full: it advances `server_version`, records the change, and stores
+the submitted payload. See the measured local baseline in the
+[Cloudflare Workers guide](https://syncular.dev/server-workers/#routine-write-cost).
+
 Whole-commit validation checks a client-proposed commit; it does not grant
 authority. Privileged operations such as connecting facilities still belong in
 explicit server-authoritative commands.
 
+## Push idempotency and retry contract
+
+The idempotency key for a push commit is the triple
+**(`partition`, `clientId`, `clientCommitId`)**. The server persists the full
+commit result in the same transaction as the writes, and a replay of the same
+key returns that result byte-equivalent: an applied commit replays as `cached`,
+a rejected commit replays as `rejected` (§2.3, §6.3).
+
+The key contains the commit ID and nothing about the operations. Host
+authentication, request-envelope validation, and the §1.5 clientId-actor
+binding run before the lookup.
+`clientId` is a client-supplied namespace inside the authenticated partition,
+not proof of an authenticated device. When a retained result exists for the
+key, the server skips `buildOperations`, the commit and write validators, and
+the apply transaction: a retry that reuses the key with different operations
+returns the persisted result, and those operations are never built, validated,
+or applied. `packages/server/test/push.test.ts` pins this.
+
+A client MUST NOT reuse a `clientCommitId` for changed intent, including after
+the persisted result has been pruned. One ID identifies one logical commit
+permanently, and a later edit is a later commit with a new ID.
+
+Do not key idempotency on the request payload bytes. A §5.11 client re-encrypts
+an encrypted column at every send with a fresh nonce, and a schema upgrade
+re-encodes pending commits, so the wire payload of an unchanged commit differs
+between a lost-ACK retry and the original send. A payload fingerprint rejects
+those retries. The `encryption/lost-ack-retry-dedupes-changed-ciphertext`
+conformance scenario exercises the changed-ciphertext retry against both cores.
+
+Per-device namespacing and content binding are not implemented. Each needs an
+input the ID does not carry: an authenticated device identity from the host, or
+a client-side format that binds the commit content. Neither is specified here,
+and the ID check does not authenticate the client. Within one partition the ID
+contract is a correctness property: it stops a replayed ID from applying
+different operations.
+
 ## Seed idempotency and safe revisioning
 
 `seedMutations` uses the real push path and a stable `clientId`/`commitId`.

package/dist/context.d.ts

@@ -7,7 +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 { SyncularErrorHandler, SyncularErrorMapper } from './errors.js';
 import type { SyncularServerEvents } from './events.js';
 import type { LeaseStore } from './lease-store.js';
 import type { AnyReactionPlanner } from './reactions.js';
@@ -157,11 +157,10 @@ export interface SyncServerConfig {
      */
     readonly blobUploadUrls?: BlobUploadPresignConfig;
     /**
-     * §5.3 sqlite-image builder, injected so the pull path never
-     * statically imports `bun:sqlite`. Absent ⇒ the sqlite-image lane is off
-     * (bit-2 clients are served the rows lane) — the Workers/edge posture. A
-     * Bun or Node host wires `buildSqliteImage` from
-     * `@syncular/server/sqlite`.
+     * §5.3 sqlite-image builder. The host explicitly imports and supplies
+     * `buildSqliteImage` from `@syncular/server/sqlite` on Bun or Node.
+     * Absent ⇒ serve matching stored images or negotiate the rows lane.
+     * The neutral core never imports a runtime-specific builder.
      */
     readonly sqliteImageBuilder?: SqliteImageBuilder;
     readonly realtime?: RealtimeNotifier;
@@ -178,6 +177,17 @@ export interface SyncServerConfig {
      * handler never changes the response.
      */
     readonly onError?: SyncularErrorHandler;
+    /**
+     * Optional synchronous adapter error mapper (§10.2). After `onError`
+     * observes an adapter exception, `mapError` may return a catalog
+     * `SyncError` (including structured `details`, e.g. `retryAfterMs`) that
+     * the adapter answers instead of `sync.internal_error`; `undefined` keeps
+     * the default. A throw, a non-`SyncError` return, or malformed `details`
+     * JSON is contained as `sync.internal_error`. Unlike `onError`, this hook
+     * may affect the response. It does not change the remote-operation
+     * `operation.*` envelope.
+     */
+    readonly mapError?: SyncularErrorMapper;
 }
 /** Per-request context: the config plus host-authenticated identity. */
 export interface SyncRequestContext extends SyncServerConfig {

package/dist/d1-storage.js

@@ -410,13 +410,16 @@ class D1Transaction {
             row,
         });
         const p = this.#partition;
-        this.#buffer_(deleteSqliteRowScopesSql(compiled), [
-            p,
-            table,
-            row.rowId,
-            p,
-            row.rowId,
-        ]);
+        // Scope index maintenance: delete only the old keys the new scope map no
+        // longer carries, then insert the new keys. Keys present in both are left
+        // alone, so the `INSERT OR IGNORE` below finds them and writes nothing.
+        // This DELETE precedes the row upsert in the same atomic batch, and its
+        // subquery reads the row's pre-upsert scope map.
+        const scopesJson = JSON.stringify(row.scopes);
+        this.#buffer_(`${deleteSqliteRowScopesSql(compiled)}
+        AND (var, value) NOT IN (
+          SELECT key, value FROM json_each(?)
+        )`, [p, table, row.rowId, p, row.rowId, scopesJson]);
         this.#buffer_(upsertSql(compiled, 'sqlite'), upsertValues(compiled, p, row, 'sqlite'));
         for (const [variable, value] of Object.entries(row.scopes)) {
             this.#buffer_('INSERT OR IGNORE INTO sync_row_scopes(partition, tbl, var, value, row_id) VALUES (?,?,?,?,?)', [p, table, variable, value, row.rowId]);
@@ -1563,8 +1566,17 @@ export class D1ServerStorage {
         };
     }
     async putClientRecord(partition, record) {
+        // Update the existing record in place, so the table keeps one row per
+        // (partition, client_id). Every non-key field is written from the new
+        // record; a delete-and-insert would drop and recreate the row instead.
         await this.#db
-            .prepare('INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)')
+            .prepare(`INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)
+         ON CONFLICT(partition, client_id) DO UPDATE SET
+           actor_id=excluded.actor_id,
+           wire_version=excluded.wire_version,
+           cursor=excluded.cursor,
+           subscriptions=excluded.subscriptions,
+           updated_at_ms=excluded.updated_at_ms`)
             .bind(partition, record.clientId, record.actorId, record.wireVersion, record.cursor, JSON.stringify(record.subscriptions), record.updatedAtMs)
             .run();
     }

package/dist/errors.d.ts

@@ -44,12 +44,25 @@ export type SyncularErrorRoute = 'sync' | 'operations' | 'segments' | 'blobs' |
 export type SyncularErrorHandler = (error: unknown, context: {
     readonly route: SyncularErrorRoute;
 }) => void;
+/**
+ * Optional synchronous error mapper. After `onError` has observed the
+ * original, `mapError` may translate an adapter exception to a catalog
+ * `SyncError` (with `details` metadata such as `retryAfterMs`) that the
+ * adapter answers instead of `sync.internal_error`. Return `undefined` to
+ * keep the default. A throw, a non-`SyncError` return, or `details` that is
+ * not a JSON document is contained as `sync.internal_error`.
+ */
+export type SyncularErrorMapper = (error: unknown, context: {
+    readonly route: SyncularErrorRoute;
+}) => SyncError | undefined;
 /**
  * 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.
+ * passes through unchanged. Anything else goes to `onError` and answers
+ * `sync.internal_error` (§10.2) unless the optional `mapError` hook returns a
+ * catalog `SyncError` to answer instead. The default `sync.internal_error`
+ * message never carries the exception text; a mapped error's message is the
+ * host's choice.
  */
-export declare function adapterSyncError(error: unknown, onError: SyncularErrorHandler | undefined, route: SyncularErrorRoute): SyncError;
+export declare function adapterSyncError(error: unknown, onError: SyncularErrorHandler | undefined, route: SyncularErrorRoute, mapError?: SyncularErrorMapper): 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

@@ -272,10 +272,10 @@ export class SyncError extends Error {
     httpStatus;
     details;
     constructor(code, message, details) {
-        const entry = ERROR_CATALOG[code];
-        if (entry === undefined) {
+        if (!Object.hasOwn(ERROR_CATALOG, code)) {
             throw new Error(`unknown error code ${code} (not in the §10.2 catalog)`);
         }
+        const entry = ERROR_CATALOG[code];
         super(message ?? code);
         this.code = code;
         this.category = entry.category;
@@ -304,14 +304,39 @@ 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.
+ * passes through unchanged. Anything else goes to `onError` and answers
+ * `sync.internal_error` (§10.2) unless the optional `mapError` hook returns a
+ * catalog `SyncError` to answer instead. The default `sync.internal_error`
+ * message never carries the exception text; a mapped error's message is the
+ * host's choice.
  */
-export function adapterSyncError(error, onError, route) {
+export function adapterSyncError(error, onError, route, mapError) {
     if (error instanceof SyncError)
         return error;
     reportError(error, onError, route);
+    try {
+        const mapped = mapError?.(error, { route });
+        if (mapped instanceof SyncError) {
+            const { code, message, details } = mapped;
+            let detailsValid = details === undefined;
+            if (!detailsValid && typeof details === 'string') {
+                JSON.parse(details);
+                detailsValid = true;
+            }
+            if (typeof code === 'string' &&
+                typeof message === 'string' &&
+                Object.hasOwn(ERROR_CATALOG, code) &&
+                detailsValid) {
+                // Reconstruct from the validated fields: the catalog owns
+                // retryability and status, so a mutated `SyncError` cannot smuggle a
+                // different entry onto the wire.
+                return new SyncError(code, message, details);
+            }
+        }
+    }
+    catch {
+        // A throwing mapper or getter, or malformed details, keeps the default.
+    }
     return new SyncError('sync.internal_error', 'internal server error');
 }
 /** Hand `error` to the host's `onError`; a throwing handler is contained. */

package/dist/pull.js

@@ -10,24 +10,6 @@ import { issueSegmentUrl } from './signed-url.js';
 import { projectRowPayload, projectRowValues } from './schema-window.js';
 // One artifact build per owning storage pair and complete immutable identity.
 const imageBuilds = new WeakMap();
-/**
- * Resolve the §5.3 image builder: the host-injected one if present, else the
- * in-tree `buildSqliteImage` on a Bun runtime (dynamic import so `bun:sqlite`
- * is never a static dep of the neutral core), else `undefined` (rows lane).
- * Memoized so the dynamic import happens at most once per process.
- */
-let cachedDefaultBuilder;
-async function resolveImageBuilder(ctx) {
-    if (ctx.sqliteImageBuilder !== undefined)
-        return ctx.sqliteImageBuilder;
-    if (cachedDefaultBuilder === undefined) {
-        const hasBun = globalThis.Bun !== undefined;
-        cachedDefaultBuilder = hasBun
-            ? (await import('./sqlite-bun.js')).buildSqliteImage
-            : null;
-    }
-    return cachedDefaultBuilder ?? undefined;
-}
 /** §4.2 accept bitmask. */
 export const ACCEPT_INLINE_ROWS = 1 << 0;
 export const ACCEPT_EXTERNAL_ROWS = 1 << 1;
@@ -176,14 +158,9 @@ async function* sqliteImageSegment(ctx, schema, limits, plan, asOf, digest, trac
     // 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
-    // in-tree `buildSqliteImage` ONLY on a Bun runtime, reached by a *dynamic*
-    // import so `bun:sqlite` is never a static dependency of the pull path
-    // (runtime neutrality is enforced by test/runtime-neutrality.test.ts). On
-    // Workers/edge (no `Bun`) this yields the rows lane for a bit-2 client — a
-    // support floor, not a fallback (§5.3: sqlite is an *accept*, not a demand).
-    const buildImage = await resolveImageBuilder(ctx);
+    // §5.3: hosts opt into image construction with a runtime-specific builder.
+    // Without one, matching stored images remain usable and cold pulls use rows.
+    const buildImage = ctx.sqliteImageBuilder;
     if (buildImage === undefined)
         return false;
     let stores = imageBuilds.get(storage);

package/dist/realtime.d.ts

@@ -18,7 +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 SyncularErrorHandler, type SyncularErrorMapper } from './errors.js';
 import { type SyncularServerEvents } from './events.js';
 import { type CompiledTable } from './schema.js';
 import type { ServerStorage, StoredCommit } from './storage.js';
@@ -204,6 +204,8 @@ export declare class RealtimeHub {
     }): SyncRequestContext;
     /** The host's error reporter (`SyncServerConfig.onError`), if any. */
     get onError(): SyncularErrorHandler | undefined;
+    /** The host's adapter error mapper (`SyncServerConfig.mapError`), if any. */
+    get mapError(): SyncularErrorMapper | undefined;
     requestContext(session: RealtimeSession): SyncRequestContext;
     /**
      * Register a connected socket (§8.1): load the client's last pull's

package/dist/realtime.js

@@ -436,7 +436,7 @@ export class RealtimeSession {
                 // `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');
+                    : adapterSyncError(error, (error, context) => this.#hub.onError?.(error, context), 'realtime', (error, context) => this.#hub.mapError?.(error, context));
                 finishRound(); // END is in this one chunk
                 await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
                 return;
@@ -460,7 +460,7 @@ export class RealtimeSession {
                 // the §8.7 violation path.
                 const sync = error instanceof DecodeError
                     ? syncError(error.code, error.message)
-                    : adapterSyncError(error, this.#hub.onError, 'realtime');
+                    : adapterSyncError(error, (error, context) => this.#hub.onError?.(error, context), 'realtime', (error, context) => this.#hub.mapError?.(error, context));
                 finishRound();
                 await this.#sendRoundChunk(errorResponseBytes(sync, this.wireVersion, this.logEpoch));
                 return;
@@ -476,7 +476,7 @@ export class RealtimeSession {
         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');
+            reportError(error, (error, context) => this.#hub.onError?.(error, context), 'realtime');
             this.#violation('sync round failed mid-stream');
         }
         finally {
@@ -876,6 +876,10 @@ export class RealtimeHub {
     get onError() {
         return this.#config.onError;
     }
+    /** The host's adapter error mapper (`SyncServerConfig.mapError`), if any. */
+    get mapError() {
+        return this.#config.mapError;
+    }
     requestContext(session) {
         return this.requestContextFor(session);
     }

package/dist/sqlite-image.d.ts

@@ -18,7 +18,7 @@ export interface SqliteImageInput {
  * a real SQLite engine, which is not available on every runtime. The core
  * takes the builder as an optional capability rather than importing a driver
  * on the pull path. A Bun or Node host passes `buildSqliteImage`; a Workers
- * host omits it and serves the rows lane.
+ * host omits it and serves matching stored images or the rows lane.
  */
 export type SqliteImageBuilder = (input: SqliteImageInput) => Promise<Uint8Array>;
 /** Populate a §5.3 image database for a whole-table snapshot. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.30.16",
+  "version": "0.31.0",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
   },
   "dependencies": {
-    "@syncular/core": "0.30.16"
+    "@syncular/core": "0.31.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/context.ts

@@ -7,7 +7,7 @@
 import type { ScopeMap } from '@syncular/core';
 import type { BlobStore } from './blob-store';
 import type { CrdtMergerRegistry } from './crdt-merger';
-import type { SyncularErrorHandler } from './errors';
+import type { SyncularErrorHandler, SyncularErrorMapper } from './errors';
 import type { SyncularServerEvents } from './events';
 import type { LeaseStore } from './lease-store';
 import type { AnyReactionPlanner } from './reactions';
@@ -182,11 +182,10 @@ export interface SyncServerConfig {
    */
   readonly blobUploadUrls?: BlobUploadPresignConfig;
   /**
-   * §5.3 sqlite-image builder, injected so the pull path never
-   * statically imports `bun:sqlite`. Absent ⇒ the sqlite-image lane is off
-   * (bit-2 clients are served the rows lane) — the Workers/edge posture. A
-   * Bun or Node host wires `buildSqliteImage` from
-   * `@syncular/server/sqlite`.
+   * §5.3 sqlite-image builder. The host explicitly imports and supplies
+   * `buildSqliteImage` from `@syncular/server/sqlite` on Bun or Node.
+   * Absent ⇒ serve matching stored images or negotiate the rows lane.
+   * The neutral core never imports a runtime-specific builder.
    */
   readonly sqliteImageBuilder?: SqliteImageBuilder;
   readonly realtime?: RealtimeNotifier;
@@ -203,6 +202,17 @@ export interface SyncServerConfig {
    * handler never changes the response.
    */
   readonly onError?: SyncularErrorHandler;
+  /**
+   * Optional synchronous adapter error mapper (§10.2). After `onError`
+   * observes an adapter exception, `mapError` may return a catalog
+   * `SyncError` (including structured `details`, e.g. `retryAfterMs`) that
+   * the adapter answers instead of `sync.internal_error`; `undefined` keeps
+   * the default. A throw, a non-`SyncError` return, or malformed `details`
+   * JSON is contained as `sync.internal_error`. Unlike `onError`, this hook
+   * may affect the response. It does not change the remote-operation
+   * `operation.*` envelope.
+   */
+  readonly mapError?: SyncularErrorMapper;
 }
 
 /** Per-request context: the config plus host-authenticated identity. */

package/src/d1-storage.ts

@@ -660,13 +660,19 @@ class D1Transaction implements StorageTransaction {
       row,
     });
     const p = this.#partition;
-    this.#buffer_(deleteSqliteRowScopesSql(compiled), [
-      p,
-      table,
-      row.rowId,
-      p,
-      row.rowId,
-    ]);
+    // Scope index maintenance: delete only the old keys the new scope map no
+    // longer carries, then insert the new keys. Keys present in both are left
+    // alone, so the `INSERT OR IGNORE` below finds them and writes nothing.
+    // This DELETE precedes the row upsert in the same atomic batch, and its
+    // subquery reads the row's pre-upsert scope map.
+    const scopesJson = JSON.stringify(row.scopes);
+    this.#buffer_(
+      `${deleteSqliteRowScopesSql(compiled)}
+        AND (var, value) NOT IN (
+          SELECT key, value FROM json_each(?)
+        )`,
+      [p, table, row.rowId, p, row.rowId, scopesJson],
+    );
     this.#buffer_(
       upsertSql(compiled, 'sqlite'),
       upsertValues(compiled, p, row, 'sqlite'),
@@ -2310,9 +2316,18 @@ export class D1ServerStorage implements ServerStorage {
     partition: string,
     record: ClientRecord,
   ): Promise<void> {
+    // Update the existing record in place, so the table keeps one row per
+    // (partition, client_id). Every non-key field is written from the new
+    // record; a delete-and-insert would drop and recreate the row instead.
     await this.#db
       .prepare(
-        'INSERT OR REPLACE INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)',
+        `INSERT INTO sync_clients(partition, client_id, actor_id, wire_version, cursor, subscriptions, updated_at_ms) VALUES (?,?,?,?,?,?,?)
+         ON CONFLICT(partition, client_id) DO UPDATE SET
+           actor_id=excluded.actor_id,
+           wire_version=excluded.wire_version,
+           cursor=excluded.cursor,
+           subscriptions=excluded.subscriptions,
+           updated_at_ms=excluded.updated_at_ms`,
       )
       .bind(
         partition,

package/src/errors.ts

@@ -282,10 +282,10 @@ export class SyncError extends Error {
   readonly details?: string;
 
   constructor(code: string, message?: string, details?: string) {
-    const entry = ERROR_CATALOG[code];
-    if (entry === undefined) {
+    if (!Object.hasOwn(ERROR_CATALOG, code)) {
       throw new Error(`unknown error code ${code} (not in the §10.2 catalog)`);
     }
+    const entry = ERROR_CATALOG[code]!;
     super(message ?? code);
     this.code = code;
     this.category = entry.category;
@@ -344,19 +344,59 @@ export type SyncularErrorHandler = (
   context: { readonly route: SyncularErrorRoute },
 ) => void;
 
+/**
+ * Optional synchronous error mapper. After `onError` has observed the
+ * original, `mapError` may translate an adapter exception to a catalog
+ * `SyncError` (with `details` metadata such as `retryAfterMs`) that the
+ * adapter answers instead of `sync.internal_error`. Return `undefined` to
+ * keep the default. A throw, a non-`SyncError` return, or `details` that is
+ * not a JSON document is contained as `sync.internal_error`.
+ */
+export type SyncularErrorMapper = (
+  error: unknown,
+  context: { readonly route: SyncularErrorRoute },
+) => SyncError | undefined;
+
 /**
  * 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.
+ * passes through unchanged. Anything else goes to `onError` and answers
+ * `sync.internal_error` (§10.2) unless the optional `mapError` hook returns a
+ * catalog `SyncError` to answer instead. The default `sync.internal_error`
+ * message never carries the exception text; a mapped error's message is the
+ * host's choice.
  */
 export function adapterSyncError(
   error: unknown,
   onError: SyncularErrorHandler | undefined,
   route: SyncularErrorRoute,
+  mapError?: SyncularErrorMapper,
 ): SyncError {
   if (error instanceof SyncError) return error;
   reportError(error, onError, route);
+  try {
+    const mapped = mapError?.(error, { route });
+    if (mapped instanceof SyncError) {
+      const { code, message, details } = mapped;
+      let detailsValid = details === undefined;
+      if (!detailsValid && typeof details === 'string') {
+        JSON.parse(details);
+        detailsValid = true;
+      }
+      if (
+        typeof code === 'string' &&
+        typeof message === 'string' &&
+        Object.hasOwn(ERROR_CATALOG, code) &&
+        detailsValid
+      ) {
+        // Reconstruct from the validated fields: the catalog owns
+        // retryability and status, so a mutated `SyncError` cannot smuggle a
+        // different entry onto the wire.
+        return new SyncError(code, message, details);
+      }
+    }
+  } catch {
+    // A throwing mapper or getter, or malformed details, keeps the default.
+  }
   return new SyncError('sync.internal_error', 'internal server error');
 }
 

package/src/pull.ts

@@ -23,7 +23,6 @@ import {
 import { scopeDigest } from './scopes';
 import type { SegmentRecord, SegmentStore } from './segment-store';
 import { issueSegmentUrl } from './signed-url';
-import type { SqliteImageBuilder } from './sqlite-image';
 import type { ServerStorage, StoredCommit, StoredRow } from './storage';
 import { projectRowPayload, projectRowValues } from './schema-window';
 
@@ -33,26 +32,6 @@ const imageBuilds = new WeakMap<
   WeakMap<SegmentStore, Map<string, Promise<SegmentRecord>>>
 >();
 
-/**
- * Resolve the §5.3 image builder: the host-injected one if present, else the
- * in-tree `buildSqliteImage` on a Bun runtime (dynamic import so `bun:sqlite`
- * is never a static dep of the neutral core), else `undefined` (rows lane).
- * Memoized so the dynamic import happens at most once per process.
- */
-let cachedDefaultBuilder: SqliteImageBuilder | null | undefined;
-async function resolveImageBuilder(
-  ctx: SyncRequestContext,
-): Promise<SqliteImageBuilder | undefined> {
-  if (ctx.sqliteImageBuilder !== undefined) return ctx.sqliteImageBuilder;
-  if (cachedDefaultBuilder === undefined) {
-    const hasBun = (globalThis as { Bun?: unknown }).Bun !== undefined;
-    cachedDefaultBuilder = hasBun
-      ? (await import('./sqlite-bun')).buildSqliteImage
-      : null;
-  }
-  return cachedDefaultBuilder ?? undefined;
-}
-
 /** §4.2 accept bitmask. */
 export const ACCEPT_INLINE_ROWS = 1 << 0;
 export const ACCEPT_EXTERNAL_ROWS = 1 << 1;
@@ -280,14 +259,9 @@ async function* sqliteImageSegment(
   // rows page — smaller tables stay on the (typically inline) rows lane.
   // 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
-  // in-tree `buildSqliteImage` ONLY on a Bun runtime, reached by a *dynamic*
-  // import so `bun:sqlite` is never a static dependency of the pull path
-  // (runtime neutrality is enforced by test/runtime-neutrality.test.ts). On
-  // Workers/edge (no `Bun`) this yields the rows lane for a bit-2 client — a
-  // support floor, not a fallback (§5.3: sqlite is an *accept*, not a demand).
-  const buildImage = await resolveImageBuilder(ctx);
+  // §5.3: hosts opt into image construction with a runtime-specific builder.
+  // Without one, matching stored images remain usable and cold pulls use rows.
+  const buildImage = ctx.sqliteImageBuilder;
   if (buildImage === undefined) return false;
   let stores = imageBuilds.get(storage);
   if (stores === undefined) {

package/src/realtime.ts

@@ -44,6 +44,7 @@ import {
   reportError,
   SyncError,
   type SyncularErrorHandler,
+  type SyncularErrorMapper,
   syncError,
 } from './errors';
 import { emitEvent, type SyncularServerEvents } from './events';
@@ -599,7 +600,12 @@ export class RealtimeSession {
         const sync =
           error instanceof DecodeError
             ? syncError(error.code, error.message)
-            : adapterSyncError(error, this.#hub.onError, 'realtime');
+            : adapterSyncError(
+                error,
+                (error, context) => this.#hub.onError?.(error, context),
+                'realtime',
+                (error, context) => this.#hub.mapError?.(error, context),
+              );
         finishRound(); // END is in this one chunk
         await this.#sendRoundChunk(
           errorResponseBytes(sync, this.wireVersion, this.logEpoch),
@@ -625,7 +631,12 @@ export class RealtimeSession {
         const sync =
           error instanceof DecodeError
             ? syncError(error.code, error.message)
-            : adapterSyncError(error, this.#hub.onError, 'realtime');
+            : adapterSyncError(
+                error,
+                (error, context) => this.#hub.onError?.(error, context),
+                'realtime',
+                (error, context) => this.#hub.mapError?.(error, context),
+              );
         finishRound();
         await this.#sendRoundChunk(
           errorResponseBytes(sync, this.wireVersion, this.logEpoch),
@@ -641,7 +652,11 @@ export class RealtimeSession {
     } 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');
+      reportError(
+        error,
+        (error, context) => this.#hub.onError?.(error, context),
+        'realtime',
+      );
       this.#violation('sync round failed mid-stream');
     } finally {
       finishRound();
@@ -1108,6 +1123,11 @@ export class RealtimeHub {
     return this.#config.onError;
   }
 
+  /** The host's adapter error mapper (`SyncServerConfig.mapError`), if any. */
+  get mapError(): SyncularErrorMapper | undefined {
+    return this.#config.mapError;
+  }
+
   requestContext(session: RealtimeSession): SyncRequestContext {
     return this.requestContextFor(session);
   }

package/src/sqlite-image.ts

@@ -69,7 +69,7 @@ export interface SqliteImageInput {
  * a real SQLite engine, which is not available on every runtime. The core
  * takes the builder as an optional capability rather than importing a driver
  * on the pull path. A Bun or Node host passes `buildSqliteImage`; a Workers
- * host omits it and serves the rows lane.
+ * host omits it and serves matching stored images or the rows lane.
  */
 export type SqliteImageBuilder = (
   input: SqliteImageInput,