@spooky-sync/core 0.0.1-canary.330 → 0.0.1-canary.332

package/dist/types.d.ts

@@ -733,6 +733,9 @@ declare class RemoteDatabaseService extends AbstractDatabaseService {
    * from-scratch connect reproduce that state.
    */
   setAuthToken(token: string | null): void;
+  /** The token the session is signed in with (or the configured one), for
+   *  calls that leave the socket: `r2` bucket files go to the SSP over HTTP. */
+  getAuthToken(): string | null;
   /** Resolved reconnect tunables; the supervisor reads its own knobs here. */
   getReconnectConfig(): Required<ReconnectConfig>;
   /** Current transport state as reported by the SDK. */
@@ -1591,14 +1594,20 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    */
   streamDebounceTime?: number;
   /**
-   * Debounce time in milliseconds for syncing collaborative (CRDT) field
-   * edits to the server. Local state is kept on every change (so reload and
-   * offline work), but a field's own new ops go out as one edit-log row per
-   * pause of this length (at most 2 s apart while typing continues).
-   * Lower = snappier propagation and more rows; higher = fewer rows and more
-   * lag for other collaborators. Defaults to 300ms.
+   * How long in milliseconds the first edit to a collaborative (CRDT) field
+   * after a quiet spell waits before it goes out, so a burst of keystrokes
+   * travels as one edit-log row. Local state is kept on every change (so
+   * reload and offline work). Defaults to 50ms.
    */
   crdtDebounceMs?: number;
+  /**
+   * The shortest gap in milliseconds between two edit-log rows of one CRDT
+   * field: while someone keeps typing, their edits go out on this cadence
+   * instead of waiting for a pause. Lower = other collaborators see the text
+   * sooner and more rows are written; higher = fewer rows and more lag.
+   * Defaults to 200ms.
+   */
+  crdtSendIntervalMs?: number;
   /**
    * Enable collaborative CRDT fields. When `true`, the `loro-crdt` engine is
    * preloaded at client startup (fetched as a separate chunk on page load) so
@@ -1632,15 +1641,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * back for it.
    *
    * The client holds exactly one live subscription, on its `_00_list_ref`
-   * table, and today it is a doorbell: the notification is reduced to the
-   * query hash and the row is then pulled with `SELECT * FROM $ids`. The edge
+   * table. Without this, the notification names the row and the client then
+   * pulls it with `SELECT * FROM $ids`. The edge
    * is a real graph edge, so `FETCH out` makes SurrealDB resolve the row into
    * the notification and the body fetch disappears.
    *
    * The push stays advisory: the body is landed exactly the way a fetched body
    * is (store write, circuit ingest, version recorded), so a notification the
-   * server drops costs nothing but the old round trip. Membership is still
-   * read back; only the body fetch is saved.
+   * server drops costs nothing but the old round trip. A row joining a live
+   * view is committed to membership from the notification either way (no
+   * re-read); with this on, the body fetch is saved as well.
    *
    * Default `false`. The cost is wire bytes: one edit bumps the edge in every
    * view holding the row, and under `FETCH` each of those notifications
@@ -1707,6 +1717,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
     componentX?: number;
     componentY?: number;
   };
+  /**
+   * Buckets declared `BACKEND "r2"` keep their files with the SSP (R2 on
+   * Cloudflare, a directory under `spky dev`) instead of in SurrealDB, which
+   * on Surreal Cloud can only hold memory buckets. `endpoint` is the SSP's
+   * URL: `spky dev` and `spky deploy` hand it to Vite as
+   * `VITE_SPKY_FILES_ENDPOINT`.
+   */
+  files?: {
+    endpoint?: string;
+  };
   /**
    * Deadline (ms) for a single outgoing mutation push. Tighter than
    * {@link Sp00kyConfig.database.queryTimeoutMs} because the up-queue drains
@@ -1860,6 +1880,17 @@ interface InlineRow {
   version: number;
   record: Record<string, unknown>;
 }
+/**
+ * A row that joined a query's view, or moved to a newer version, as one LIVE
+ * notification on `_00_list_ref` reports it: the edge's `out` and `version`.
+ * The client commits it to the query's membership straight away instead of
+ * re-reading the edges (see `sync/live.saga.ts`).
+ */
+interface EdgeDelta {
+  hash: QueryHash;
+  id: string;
+  version: number;
+}
 type RecordVersionArray = Array<[string, number]>;
 /**
  * Represents the difference between two record version sets.
@@ -2162,4 +2193,4 @@ interface DebounceOptions {
   flushOnHide?: boolean;
 }
 //#endregion
-export { WebPushSubscribeOptions as $, RunOptions as A, Logger$1 as At, SyncHealthStatus as B, SESSION_POLL_MS as Bt, QueryTimeToLive as C, SignOutHook as Ct, RecordVersionArray as D, createAuthEventSystem as Dt, ReconnectConfig as E, AuthEventTypes as Et, StorageHealth as F, IMPERSONATION_ACCESS as Ft, WebPushConfig as G, sameImpersonation as Gt, UpdateOptions as H, decodeTokenClaims as Ht, StorageHealthStatus as I, ImpersonationInfo as It, WebPushErrorCode as J, WebPushDevice as K, StoreType as L, ImpersonationTimerHost as Lt, Sp00kyConfig as M, SealedQuery as Mt, Sp00kyQueryResult as N, EventDefinition as Nt, RecordVersionDiff as O, RemoteDatabaseService as Ot, Sp00kyQueryResultPromise as P, EventSystem as Pt, WebPushModule as Q, SyncHealth as R, ImpersonationTimers as Rt, QueryStatusCallback as S, SignOutContext as St, QueryUpdateCallback as T, AuthEventTypeMap as Tt, PUSH_ENDPOINT_KEY as U, impersonationFromToken as Ut, TimingPhase as V, TokenClaims as Vt, PushDeviceKind as W, renewDelayMs as Wt, WebPushMessage as X, WebPushInfo as Y, WebPushMessageInput as Z, QueryConfig as _, isPushPayload as _t, Level$1 as a, WebPushUpdateOptions as at, QueryState as b, ImpersonationCandidate as bt, MutationCallback as c, BridgeTokenMessage as ct, PersistenceClient as d, PushNotificationAction as dt, WebPushSupport as et, PhaseStat as f, PushOp as ft, QueryAuthorityCallback as g, WebPushClientMessage as gt, PreloadRefresh as h, PushUrgency as ht, InlineRow as i, WebPushUnsupportedReason as it, ServerViewMeta as j, LocalStore as jt, RegistrationTimings as k, LogTap as kt, MutationEvent as l, PUSH_PAYLOAD_VERSION as lt, PreloadOptions as m, PushPayloadKind as mt, DebounceOptions as n, WebPushSyncStatus as nt, MATERIALIZATION_SAMPLE_WINDOW as o, detectWebPushSupport as ot, PinoTransmit as p, PushPayload as pt, WebPushError as q, EventSubscriptionOptions as r, WebPushUnsubscribeOptions as rt, MembershipOutcome as s, BridgeSignOutMessage as st, ConnectionState as t, WebPushSyncOptions as tt, MutationEventType as u, PushNotification as ut, QueryConfigRecord as v, ActiveImpersonation as vt, QueryTimings as w, AuthEventSystem as wt, QueryStatus as x, SIGN_OUT_HOOK_TIMEOUT_MS as xt, QueryHash as y, AuthService as yt, SyncHealthConfig as z, ORIGIN_TOKEN_KEY as zt };
+export { WebPushModule as $, RegistrationTimings as A, LogTap as At, SyncHealthConfig as B, ORIGIN_TOKEN_KEY as Bt, QueryStatusCallback as C, SignOutContext as Ct, ReconnectConfig as D, AuthEventTypes as Dt, QueryUpdateCallback as E, AuthEventTypeMap as Et, Sp00kyQueryResultPromise as F, EventSystem as Ft, PushDeviceKind as G, renewDelayMs as Gt, TimingPhase as H, TokenClaims as Ht, StorageHealth as I, IMPERSONATION_ACCESS as It, WebPushError as J, WebPushConfig as K, sameImpersonation as Kt, StorageHealthStatus as L, ImpersonationInfo as Lt, ServerViewMeta as M, LocalStore as Mt, Sp00kyConfig as N, SealedQuery as Nt, RecordVersionArray as O, createAuthEventSystem as Ot, Sp00kyQueryResult as P, EventDefinition as Pt, WebPushMessageInput as Q, StoreType as R, ImpersonationTimerHost as Rt, QueryStatus as S, SIGN_OUT_HOOK_TIMEOUT_MS as St, QueryTimings as T, AuthEventSystem as Tt, UpdateOptions as U, decodeTokenClaims as Ut, SyncHealthStatus as V, SESSION_POLL_MS as Vt, PUSH_ENDPOINT_KEY as W, impersonationFromToken as Wt, WebPushInfo as X, WebPushErrorCode as Y, WebPushMessage as Z, QueryAuthorityCallback as _, WebPushClientMessage as _t, InlineRow as a, WebPushUnsupportedReason as at, QueryHash as b, AuthService as bt, MembershipOutcome as c, BridgeSignOutMessage as ct, MutationEventType as d, PushNotification as dt, WebPushSubscribeOptions as et, PersistenceClient as f, PushNotificationAction as ft, PreloadRefresh as g, PushUrgency as gt, PreloadOptions as h, PushPayloadKind as ht, EventSubscriptionOptions as i, WebPushUnsubscribeOptions as it, RunOptions as j, Logger$1 as jt, RecordVersionDiff as k, RemoteDatabaseService as kt, MutationCallback as l, BridgeTokenMessage as lt, PinoTransmit as m, PushPayload as mt, DebounceOptions as n, WebPushSyncOptions as nt, Level$1 as o, WebPushUpdateOptions as ot, PhaseStat as p, PushOp as pt, WebPushDevice as q, EdgeDelta as r, WebPushSyncStatus as rt, MATERIALIZATION_SAMPLE_WINDOW as s, detectWebPushSupport as st, ConnectionState as t, WebPushSupport as tt, MutationEvent as u, PUSH_PAYLOAD_VERSION as ut, QueryConfig as v, isPushPayload as vt, QueryTimeToLive as w, SignOutHook as wt, QueryState as x, ImpersonationCandidate as xt, QueryConfigRecord as y, ActiveImpersonation as yt, SyncHealth as z, ImpersonationTimers as zt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.330",
+  "version": "0.0.1-canary.332",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -75,8 +75,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.330",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.330",
+    "@spooky-sync/query-builder": "0.0.1-canary.332",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.332",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.1.0",
     "@surrealdb/wasm-native": "^3.3.4",

package/src/client/bucket-handle.test.ts

@@ -115,3 +115,81 @@ describe('BucketHandle', () => {
     expect(calls.some(([s]) => s === 'RETURN f"files:/pre/".list();')).toBe(true);
   });
 });
+
+describe('r2 buckets (files with the SSP)', () => {
+  function fakeSsp(files: Record<string, string> = {}) {
+    const requests: Array<{ method: string; url: string; auth: string | null; body: unknown }> = [];
+    const fetchMock = vi.fn(async (url: string, init: RequestInit) => {
+      const headers = (init.headers ?? {}) as Record<string, string>;
+      requests.push({ method: init.method ?? 'GET', url, auth: headers.Authorization ?? null, body: init.body });
+      const key = decodeURIComponent(new URL(url).pathname.replace(/^\/bucket\/[^/]+\//, ''));
+      const json = (status: number, value: unknown) => new Response(JSON.stringify(value), { status });
+      if (headers.Authorization !== 'Bearer tok') return json(401, { error: 'invalid or expired token' });
+      switch (init.method) {
+        case 'PUT':
+          files[key] = typeof init.body === 'string' ? init.body : 'bytes';
+          return json(200, { ok: true });
+        case 'GET':
+          return key in files ? new Response(files[key], { status: 200 }) : json(404, { error: 'no such file' });
+        case 'DELETE':
+          delete files[key];
+          return json(200, { ok: true });
+        default: {
+          const op = JSON.parse(String(init.body));
+          if (op.op === 'exists') return json(200, key in files);
+          if (op.op === 'head') return json(200, key in files ? { key: `/${key}`, size: files[key].length } : null);
+          if (!(key in files)) return json(404, { error: 'no such file' });
+          files[op.target] = files[key];
+          if (op.op === 'rename') delete files[key];
+          return json(200, { ok: true });
+        }
+      }
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    return { requests, files };
+  }
+
+  const remote = (token: string | null = 'tok') => ({ getAuthToken: () => token, query: vi.fn() }) as any;
+  const r2 = (r = remote()) =>
+    new BucketHandle('pics', r, null, { backend: 'r2', files: { endpoint: 'https://app.db.example/' }, blurhash: false });
+
+  it('reads and writes over HTTP with the session token, never the database socket', async () => {
+    const { requests, files } = fakeSsp();
+    const db = remote();
+    const h = r2(db);
+    await h.put('u1/a b.png', 'PNG');
+    expect(files['u1/a b.png']).toBe('PNG');
+    expect(requests[0]).toMatchObject({ method: 'PUT', url: 'https://app.db.example/bucket/pics/u1/a%20b.png', auth: 'Bearer tok' });
+    expect(await ((await h.get('u1/a b.png')) as Blob).text()).toBe('PNG');
+    expect(await h.get('missing.png')).toBeNull();
+    expect(await h.exists('u1/a b.png')).toBe(true);
+    expect(await h.head('u1/a b.png')).toEqual({ key: '/u1/a b.png', size: 3 });
+    await h.copy('u1/a b.png', 'u1/c.png');
+    await h.rename('u1/c.png', 'u1/d.png');
+    expect(Object.keys(files).sort()).toEqual(['u1/a b.png', 'u1/d.png']);
+    await expect(h.copy('nope.png', 'x.png')).rejects.toThrow(/no file/);
+    await h.delete('u1/a b.png');
+    expect(await h.exists('u1/a b.png')).toBe(false);
+    await expect(h.list()).rejects.toThrow(/listing/);
+    expect(db.query).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+
+  it('surfaces refusals and a missing endpoint as errors', async () => {
+    fakeSsp({ 'a.png': 'x' });
+    await expect(r2(remote(null)).get('a.png')).rejects.toThrow(/401.*invalid or expired token/);
+    const noEndpoint = new BucketHandle('pics', remote(), null, { backend: 'r2', files: {} });
+    await expect(noEndpoint.get('a.png')).rejects.toThrow(/files\.endpoint/);
+    vi.unstubAllGlobals();
+  });
+
+  it('a bucket without backend r2 keeps using the database', async () => {
+    const db = { getAuthToken: () => 'tok', query: vi.fn(async () => ['content']) } as any;
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+    const h = new BucketHandle('pics', db, null, { files: { endpoint: 'https://app.db.example' } });
+    expect(await h.get('a.png')).toBe('content');
+    expect(fetchMock).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+});

package/src/client/bucket-handle.ts

@@ -34,6 +34,143 @@ export interface BucketPutResult {
 interface BucketHandleSettings {
   blurhash?: BlurhashSetting;
   logger?: { warn: (obj: unknown, msg?: string) => void };
+  /** The bucket's backend as generated (`'r2'`: files live with the SSP). */
+  backend?: string;
+  /** {@link Sp00kyConfig.files}: where `r2` bucket files are read and written. */
+  files?: { endpoint?: string };
+}
+
+/** A handle's settings from the client config and the bucket's generated schema. */
+export function bucketSettings(
+  config: { blurhash?: BlurhashSetting; files?: { endpoint?: string }; schema: { buckets?: readonly { name: string; backend?: string }[] } },
+  name: string,
+  logger: { warn: (obj: unknown, msg?: string) => void }
+): BucketHandleSettings {
+  const backend = config.schema.buckets?.find((b) => b.name === name)?.backend;
+  return { blurhash: config.blurhash, logger, backend, files: config.files };
+}
+
+/** Where a bucket's bytes go: SurrealDB itself, or the SSP for `r2` buckets. */
+interface BucketIo {
+  put(path: string, content: string | Uint8Array | Blob): Promise<void>;
+  /** The file, or null when it does not exist. */
+  get(path: string): Promise<unknown>;
+  delete(path: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  head(path: string): Promise<Record<string, unknown>>;
+  copy(sourcePath: string, targetPath: string): Promise<void>;
+  rename(sourcePath: string, targetPath: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+}
+
+/** `f"bucket:/path"` statements over the database connection. */
+function surrealIo(bucket: string, remote: RemoteDatabaseService): BucketIo {
+  const file = (path: string) => `f"${bucket}:/${path}"`;
+  return {
+    async put(path, content) {
+      await remote.query(`RETURN ${file(path)}.put($content);`, { content });
+    },
+    async get(path) {
+      const [result] = await remote.query<[unknown]>(`RETURN ${file(path)}.get();`);
+      return result;
+    },
+    async delete(path) {
+      await remote.query(`RETURN ${file(path)}.delete();`);
+    },
+    async exists(path) {
+      const [result] = await remote.query<[boolean]>(`RETURN ${file(path)}.exists();`);
+      return result;
+    },
+    async head(path) {
+      const [result] = await remote.query<[Record<string, unknown>]>(`RETURN ${file(path)}.head();`);
+      return result;
+    },
+    async copy(sourcePath, targetPath) {
+      await remote.query(`RETURN ${file(sourcePath)}.copy($target);`, { target: targetPath });
+    },
+    async rename(sourcePath, targetPath) {
+      await remote.query(`RETURN ${file(sourcePath)}.rename($target);`, { target: targetPath });
+    },
+    async list(prefix) {
+      const [result] = await remote.query<[string[]]>(`RETURN ${file(prefix)}.list();`);
+      return result;
+    },
+  };
+}
+
+/**
+ * `BACKEND "r2"` buckets: the SSP keeps the files (R2 on Cloudflare, a
+ * directory under `spky dev`) and serves them at `/bucket/<name>/<key>`,
+ * after asking SurrealDB, as the signed-in user, whether the bucket's
+ * PERMISSIONS clause allows it. The request carries the session's token.
+ */
+function sspIo(bucket: string, remote: RemoteDatabaseService, endpoint: string | undefined): BucketIo {
+  const base = () => {
+    if (!endpoint) {
+      throw new Error(
+        `Bucket '${bucket}' is stored with the SSP (BACKEND "r2"): set \`files.endpoint\` in the client config to the SSP's URL.`
+      );
+    }
+    return endpoint.replace(/\/+$/, '');
+  };
+  const url = (path: string) =>
+    `${base()}/bucket/${encodeURIComponent(bucket)}/${path
+      .split('/')
+      .filter(Boolean)
+      .map(encodeURIComponent)
+      .join('/')}`;
+  const send = async (method: string, path: string, body?: BodyInit, contentType?: string): Promise<Response> => {
+    const headers: Record<string, string> = {};
+    const token = remote.getAuthToken();
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (contentType) headers['Content-Type'] = contentType;
+    const response = await fetch(url(path), { method, headers, body, credentials: 'omit' });
+    if (!response.ok && response.status !== 404) {
+      let message = response.statusText;
+      try {
+        message = ((await response.json()) as { error?: string }).error ?? message;
+      } catch {
+        // Not JSON: keep the status text.
+      }
+      throw new Error(`Bucket '${bucket}' ${method} ${path} failed (${response.status}): ${message}`);
+    }
+    return response;
+  };
+  const op = async <T>(path: string, body: Record<string, unknown>): Promise<T | null> => {
+    const response = await send('POST', path, JSON.stringify(body), 'application/json');
+    if (response.status === 404) return null;
+    return (await response.json()) as T;
+  };
+  const missing = (path: string) => new Error(`Bucket '${bucket}': no file at ${path}`);
+  return {
+    async put(path, content) {
+      const type = content instanceof Blob ? content.type : undefined;
+      await send('PUT', path, content as BodyInit, type || 'application/octet-stream');
+    },
+    async get(path) {
+      const response = await send('GET', path);
+      return response.status === 404 ? null : await response.blob();
+    },
+    async delete(path) {
+      await send('DELETE', path);
+    },
+    async exists(path) {
+      return (await op<boolean>(path, { op: 'exists' })) ?? false;
+    },
+    async head(path) {
+      return (await op<Record<string, unknown>>(path, { op: 'head' })) as Record<string, unknown>;
+    },
+    async copy(sourcePath, targetPath) {
+      if ((await op(sourcePath, { op: 'copy', target: targetPath })) === null) throw missing(sourcePath);
+    },
+    async rename(sourcePath, targetPath) {
+      if ((await op(sourcePath, { op: 'rename', target: targetPath })) === null) throw missing(sourcePath);
+    },
+    async list() {
+      // SurrealDB refuses `list` to record users; the SSP does too.
+      throw new Error(`Bucket '${bucket}': listing is not available (BACKEND "r2")`);
+    },
+  };
 }
 
 /**
@@ -45,13 +182,20 @@ interface BucketHandleSettings {
 const missingBlurhash = new Set<string>();
 
 export class BucketHandle {
+  private io: BucketIo;
+
   constructor(
     private bucketName: string,
-    private remote: RemoteDatabaseService,
+    remote: RemoteDatabaseService,
     /** Absent on the raw handle the cache itself reads through. */
     private blobs?: BlobCache | null,
     private settings?: BucketHandleSettings
-  ) {}
+  ) {
+    this.io =
+      settings?.backend === 'r2'
+        ? sspIo(bucketName, remote, settings.files?.endpoint)
+        : surrealIo(bucketName, remote);
+  }
 
   /** Effective blurhash setting: per-call option > client config > default ON. */
   private resolveBlurhash(option?: BlurhashSetting): BlurhashEncodeOptions | null {
@@ -73,7 +217,7 @@ export class BucketHandle {
         ? encodeImageToBlurhash(content, encodeOptions)
         : Promise.resolve(null);
 
-    await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
+    await this.io.put(path, content);
     // A path can be overwritten, so anything cached under it is now wrong.
     await this.blobs?.invalidate({ bucket: this.bucketName, path });
 
@@ -84,9 +228,7 @@ export class BucketHandle {
       hash = await hashPromise;
       if (hash) {
         const sidecar = blurhashSidecarPath(path);
-        await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".put($content);`, {
-          content: hash,
-        });
+        await this.io.put(sidecar, hash);
         await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
         missingBlurhash.delete(`${this.bucketName}:${path}`);
       }
@@ -128,10 +270,7 @@ export class BucketHandle {
   }
 
   async get(path: string): Promise<unknown> {
-    const [result] = await this.remote.query<[unknown]>(
-      `RETURN f"${this.bucketName}:/${path}".get();`
-    );
-    return result;
+    return this.io.get(path);
   }
 
   /**
@@ -174,14 +313,14 @@ export class BucketHandle {
   }
 
   async delete(path: string): Promise<void> {
-    await this.remote.query(`RETURN f"${this.bucketName}:/${path}".delete();`);
+    await this.io.delete(path);
     await this.blobs?.invalidate({ bucket: this.bucketName, path });
     // Symmetry with put: an image's blurhash sidecar dies with it. Best-effort,
     // the sidecar may simply not exist.
     if (isImagePath(path)) {
       const sidecar = blurhashSidecarPath(path);
       try {
-        await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".delete();`);
+        await this.io.delete(sidecar);
         await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
       } catch {
         // Nothing to clean up.
@@ -191,37 +330,23 @@ export class BucketHandle {
   }
 
   async exists(path: string): Promise<boolean> {
-    const [result] = await this.remote.query<[boolean]>(
-      `RETURN f"${this.bucketName}:/${path}".exists();`
-    );
-    return result;
+    return this.io.exists(path);
   }
 
   async head(path: string): Promise<Record<string, unknown>> {
-    const [result] = await this.remote.query<[Record<string, unknown>]>(
-      `RETURN f"${this.bucketName}:/${path}".head();`
-    );
-    return result;
+    return this.io.head(path);
   }
 
   async copy(sourcePath: string, targetPath: string): Promise<void> {
-    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".copy($target);`, {
-      target: targetPath,
-    });
+    await this.io.copy(sourcePath, targetPath);
   }
 
   async rename(sourcePath: string, targetPath: string): Promise<void> {
-    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".rename($target);`, {
-      target: targetPath,
-    });
+    await this.io.rename(sourcePath, targetPath);
   }
 
   async list(prefix?: string): Promise<string[]> {
-    const p = prefix ?? '';
-    const [result] = await this.remote.query<[string[]]>(
-      `RETURN f"${this.bucketName}:/${p}".list();`
-    );
-    return result;
+    return this.io.list(prefix ?? '');
   }
 }
 

package/src/client/router.ts

@@ -77,7 +77,7 @@ export function route(env: SagaEnv, event: RuntimeEvent): RouteTarget {
     case 'LiveStart':
       return { saga: liveStart(env), lane: serial('live') };
     case 'LiveChange':
-      return { saga: liveChange(env, event.hashes, event.rows), lane: serial('live-change') };
+      return { saga: liveChange(env, event.hashes, event.rows, event.deltas), lane: serial('live-change') };
     case 'TabRole':
       return { saga: setRole(env, event.role), lane: serial('tabs') };
     case 'TabMessage':

package/src/client/services.ts

@@ -30,9 +30,9 @@ import type { ServiceCalls } from '../kernel/effects';
 import { encodeRecordId, mintOwnerSecret } from '../utils/index';
 import { sha256Hex } from '../utils/sha256';
 import { leaveViewsBeacon, listRefLive } from '../query/sql';
-import { hashOfEdge, rowOfEdge } from '../utils/edges';
+import { deltaOfEdge, hashOfEdge, rowOfEdge } from '../utils/edges';
 import { mintMutationId } from '../mutation/mutation-id';
-import { BucketHandle, bucketContentToBlob } from './bucket-handle';
+import { BucketHandle, bucketContentToBlob, bucketSettings } from './bucket-handle';
 
 const LAST_BUCKET_KEY = 'sp00ky:last_bucket';
 
@@ -157,7 +157,7 @@ export function createServices<S extends SchemaStructure>(config: Sp00kyConfig<S
   const local = createLocalEngine(config.localEngine, config.database, logger, { shared: tabsSupport.supported });
   const remote = new RemoteDatabaseService(config.database, logger);
   const connectionSupervisor = new ConnectionSupervisor(remote, logger);
-  const rawBucket = (name: string) => new BucketHandle(name, remote, null, { blurhash: config.blurhash, logger });
+  const rawBucket = (name: string) => new BucketHandle(name, remote, null, bucketSettings(config, name, logger));
   const blobs = createBlobCache({
     local,
     namespace: ANON_USER_ID,
@@ -176,7 +176,7 @@ export function createServices<S extends SchemaStructure>(config: Sp00kyConfig<S
   streamProcessor.configureCircuitPersistence(config.persistCircuit ?? config.localEngine === 'sqlite', config.circuitCheckpointMs);
   streamProcessor.configureProjection(config.circuitProjection ?? true);
   const migrator = new LocalMigrator(local, logger);
-  const crdt = new CrdtManager(config.schema, local, remote, logger, config.crdtDebounceMs ?? 300);
+  const crdt = new CrdtManager(config.schema, local, remote, logger, config.crdtDebounceMs ?? 50, config.crdtSendIntervalMs ?? 200);
   const auth = new AuthService(config.schema, remote, persistence, logger);
   const tabId = typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `tab_${Math.random().toString(36).slice(2)}`;
   return {
@@ -395,7 +395,8 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
           // that was actually deleted the join yields nothing anyway. Landing
           // a body there would only ever write back what is going away.
           const row = message.action === 'DELETE' ? null : rowOfEdge(message.value);
-          onChange([hash], row ? [row] : undefined);
+          const delta = deltaOfEdge(message.action, message.value);
+          onChange([hash], row ? [row] : undefined, delta ? [delta] : undefined);
         });
         return String(uuid);
       },

package/src/client/sp00ky-client.ts

@@ -54,7 +54,7 @@ import { preload } from '../boot/preload.saga';
 import { DEGRADE_AFTER_FAILURES, OUTBOX_BATCH_SIZE, PUSH_TIMEOUT_MS } from '../kernel/constants';
 import { Runtime } from './runtime';
 import { createAdapters, createServices, createTabsCoordinator, type ServiceHost, type Services } from './services';
-import { BucketHandle } from './bucket-handle';
+import { BucketHandle, bucketSettings } from './bucket-handle';
 import { ImpersonationBanner } from '../modules/auth/impersonation-banner';
 import type { LeaderSyncHub, SyncForwarder } from '../services/tabs/coordinator';
 
@@ -615,7 +615,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
   }
 
   bucket<B extends BucketNames<S>>(name: B): BucketHandle {
-    return new BucketHandle(name, this.services.remote, this.services.blobs, { blurhash: this.config.blurhash, logger: this.services.logger });
+    return new BucketHandle(name, this.services.remote, this.services.blobs, bucketSettings(this.config, name, this.services.logger));
   }
 
   getBlobCacheStats() {

package/src/kernel/events.ts

@@ -1,4 +1,4 @@
-import type { ConnectionState, InlineRow, QueryHash, QueryStatus, SyncHealth } from '../types';
+import type { ConnectionState, EdgeDelta, InlineRow, QueryHash, QueryStatus, SyncHealth } from '../types';
 import type { StreamUpdate } from '../services/stream-processor/index';
 
 /**
@@ -36,7 +36,7 @@ export type RuntimeEvent =
   | { type: 'ConnectionChanged'; state: ConnectionState }
   | { type: 'StreamUpdate'; update: StreamUpdate }
   | { type: 'LiveStart' }
-  | { type: 'LiveChange'; hashes: QueryHash[]; rows?: InlineRow[] }
+  | { type: 'LiveChange'; hashes: QueryHash[]; rows?: InlineRow[]; deltas?: EdgeDelta[] }
   | { type: 'TabRole'; role: 'solo' | 'leader' | 'follower' }
   | { type: 'TabMessage'; message: unknown };
 

package/src/kernel/interpreter.ts

@@ -2,7 +2,7 @@ import { Duration } from 'surrealdb';
 import type { LocalStore } from '../services/database/cache-engine';
 import type { IngestRecord, StreamUpdate } from '../services/stream-processor/index';
 import type { ClientState } from '../state/client-state';
-import type { InlineRow } from '../types';
+import type { EdgeDelta, InlineRow } from '../types';
 import { withTimeout } from '../utils/index';
 import type { Effect, IdScope, RegisterResult, ServiceCalls, Settled, StatementResult } from './effects';
 import type { OutEvent, RuntimeEvent } from './events';
@@ -17,7 +17,7 @@ export interface Adapters {
      * changed query hashes, plus the changed rows themselves when the
      * subscription was opened with the body joined on (`liveInlineBodies`).
      */
-    live(table: string, onChange: (hashes: string[], rows?: InlineRow[]) => void): Promise<string>;
+    live(table: string, onChange: (hashes: string[], rows?: InlineRow[], deltas?: EdgeDelta[]) => void): Promise<string>;
     kill(uuid: string): Promise<void>;
   };
   ssp: {
@@ -81,7 +81,7 @@ export function createInterpreter(adapters: Adapters, host: InterpreterHost): In
           : pending;
       }
       case 'remote.live':
-        return adapters.remote.live(effect.table, (hashes, rows) => host.dispatch({ type: 'LiveChange', hashes, rows }));
+        return adapters.remote.live(effect.table, (hashes, rows, deltas) => host.dispatch({ type: 'LiveChange', hashes, rows, deltas }));
       case 'remote.kill':
         return adapters.remote.kill(effect.uuid);
       case 'ssp.register': {