@zubra/sync 5.5.0 → 5.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zubra/sync",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "description": "Local-first state for Zubra components: 'use collection' keeps a component's state in IndexedDB, across reloads, offline, and in step across tabs.",
   "type": "module",
   "main": "./src/index.js",
@@ -21,14 +21,18 @@
     "./sqlite": {
       "types": "./src/sqlite.d.ts",
       "default": "./src/sqlite.js"
+    },
+    "./durable": {
+      "types": "./src/durable.d.ts",
+      "default": "./src/durable.js"
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit \"test/*.test.js\"",
-    "test:binary": "ZUBRA_SYNC_BACKEND=binary node --test --test-force-exit test/browser.test.js"
+    "test": "node --test \"test/*.test.js\"",
+    "test:binary": "ZUBRA_SYNC_BACKEND=binary node --test test/browser.test.js"
   },
   "peerDependencies": {
-    "@zubra/runtime": "^5.5.0"
+    "@zubra/runtime": "^5.6.0"
   },
   "devDependencies": {
     "@zubra/compiler": "file:../compiler",

package/src/durable-core.js

@@ -0,0 +1,38 @@
+// What a SyncObject is, without Workers' modules: a sync server on the object's storage, its
+// `authorize` asked of the object, and a snapshot of the documents for the Worker to render from.
+// durable.js wraps this in a DurableObject; tests run it on Node against a stand-in storage.
+import { createSyncServer, MOUNT } from './server.js';
+import { durableObjectLog } from './durable-log.js';
+
+export { MOUNT };
+
+/**
+ * `owner` is the object: its `authorize(…)`, if it has one, decides as `createSyncServer`'s does.
+ * `heartbeat` is shorter than on Node (2 s, not 15): a Durable Object isn't told when a page's
+ * connection is cut, only that a keep-alive couldn't be written, which on workerd is the third
+ * after the cut. So a crashed page's presence lingers about three keep-alives (6 s). A page that
+ * closes normally says it's leaving and is gone at once.
+ */
+export function syncObject(ctx, owner, { mount = MOUNT, heartbeat = 2_000, device = 'server', table = 'changes', origins = [] } = {}) {
+  const sync = createSyncServer({
+    log: durableObjectLog(ctx.storage, { table }),
+    mount,
+    heartbeat,
+    device,
+    origins,
+    authorize: (asked) => (typeof owner.authorize === 'function' ? owner.authorize(asked) : true),
+  });
+  return {
+    async fetch(request) {
+      return (await sync.fetch(request)) ?? new Response(JSON.stringify({ error: 'Not found' }), { status: 404, headers: { 'content-type': 'application/json' } });
+    },
+    documents: sync.documents,
+    write: sync.write,
+    /** `{ collection: [{ key, ...fields }] }` for the collections named, or every one: plain data, for RPC. */
+    async snapshot(collections = []) {
+      const docs = await sync.documents();
+      const names = collections.length ? collections : docs.collections();
+      return Object.fromEntries(names.map((name) => [name, docs.all(name)]));
+    },
+  };
+}

package/src/durable-log.d.ts

@@ -0,0 +1,13 @@
+import type { Log } from './server.js';
+
+/** The parts of a Durable Object's `ctx.storage` the log uses. */
+export interface DurableObjectStorageLike {
+  sql: { exec(query: string, ...bindings: unknown[]): { toArray(): any[]; one(): any } };
+  transactionSync<T>(fn: () => T): T;
+}
+
+/**
+ * A sync log in a Durable Object's SQLite: the table and cursors `sqliteLog` uses. `table` names
+ * the table (default `changes`), if the object keeps tables of its own.
+ */
+export function durableObjectLog(storage: DurableObjectStorageLike, options?: { table?: string }): Log;

package/src/durable-log.js

@@ -0,0 +1,44 @@
+// A sync log in a Cloudflare Durable Object's own SQLite (`ctx.storage.sql`): the same table and
+// the same cursors as `sqliteLog`, so a log can move between Node and a Durable Object. It runs
+// anywhere a Durable Object's storage is passed in; nothing here imports Workers' modules.
+//
+//   import { createSyncServer } from '@zubra/sync/server';
+//   import { durableObjectLog } from '@zubra/sync/durable';
+//   const sync = createSyncServer({ log: durableObjectLog(ctx.storage) });
+//
+// `table` names the table, if the object keeps tables of its own (default `changes`). Appends are
+// one transaction (`transactionSync`): a batch is written whole or not at all.
+const NAME = /^[A-Za-z_][\w]{0,62}$/;
+
+export function durableObjectLog(storage, { table = 'changes' } = {}) {
+  if (!storage?.sql || typeof storage.transactionSync !== 'function') {
+    throw new TypeError("durableObjectLog(storage): pass a Durable Object's `ctx.storage` (SQLite-backed)");
+  }
+  if (!NAME.test(table)) throw new TypeError('durableObjectLog: `table` is a plain SQL name (letters, digits, _)');
+  const { sql } = storage;
+  sql.exec(`CREATE TABLE IF NOT EXISTS ${table} (
+    seq INTEGER PRIMARY KEY AUTOINCREMENT,
+    collection TEXT NOT NULL,
+    key TEXT NOT NULL,
+    field TEXT NOT NULL,
+    value TEXT,
+    clock TEXT NOT NULL
+  )`);
+  const last = () => Number(sql.exec(`SELECT COALESCE(MAX(seq), 0) AS seq FROM ${table}`).one().seq);
+  return {
+    async append(changes) {
+      return storage.transactionSync(() => {
+        for (const { collection, key, field, value, clock } of changes) {
+          sql.exec(`INSERT INTO ${table} (collection, key, field, value, clock) VALUES (?, ?, ?, ?, ?)`, collection, key, field, JSON.stringify(value ?? null), clock);
+        }
+        return last();
+      });
+    },
+    async after(cursor, limit = 1000) {
+      const from = Number(cursor) || 0;
+      const rows = sql.exec(`SELECT seq, collection, key, field, value, clock FROM ${table} WHERE seq > ? ORDER BY seq LIMIT ?`, from, limit).toArray();
+      const changes = rows.map(({ collection, key, field, value, clock }) => ({ collection, key, field, value: JSON.parse(value), clock }));
+      return { changes, cursor: rows.length ? Number(rows[rows.length - 1].seq) : from };
+    },
+  };
+}

package/src/durable-stub.js

@@ -0,0 +1,47 @@
+// The Worker's side of a SyncObject: forward sync requests to it, read its documents, write as
+// the server. Plain JavaScript (the namespace is a binding the Worker is given), so it runs on
+// Node in tests too.
+import { MOUNT, documentsView } from './server.js';
+
+/** A snapshot (`{ collection: [{ key, ...fields }] }`) read like `sync.documents()`. */
+export function viewOf(snapshot) {
+  const split = ({ key, ...fields }) => ({ key, fields });
+  return documentsView({
+    find: (collection, key) => {
+      const doc = (snapshot[collection] ?? []).find((each) => each.key === key);
+      return doc && split(doc).fields;
+    },
+    list: (collection) => (snapshot[collection] ?? []).map(split),
+    names: () => Object.keys(snapshot),
+  });
+}
+
+/**
+ * `namespace` is the Durable Object binding (`env.SYNC`); `name` picks the object (one per app:
+ * the log's cursor is one order). The stub's own methods (`stub.placeOrder(…)`) are the object's,
+ * over RPC: put a read-then-write that mustn't interleave there, not in the Worker.
+ */
+export function syncStub(namespace, { name = 'sync', mount = MOUNT } = {}) {
+  if (!namespace || typeof namespace.idFromName !== 'function') {
+    throw new TypeError('syncStub(env.SYNC): pass the Durable Object namespace binding');
+  }
+  const stub = namespace.get(namespace.idFromName(name));
+  const base = mount.replace(/\/$/, '');
+  return {
+    stub,
+    /** The object's answer to a sync request, or null when the request isn't one. */
+    async fetch(request) {
+      return new URL(request.url).pathname.startsWith(`${base}/`) ? stub.fetch(request) : null;
+    },
+    /**
+     * The documents as they are now, for rendering: a copy, not kept current, and reading it then
+     * writing from the Worker can interleave with other requests. Name the collections you need
+     * to send less.
+     */
+    async documents(...collections) {
+      return viewOf(await stub.snapshot(collections));
+    },
+    /** Write as the server, through the object: to its log and every live page. */
+    write: (collection, key, fields) => stub.write(collection, key, fields),
+  };
+}

package/src/durable.d.ts

@@ -0,0 +1,47 @@
+import type { Change, Documents } from './server.js';
+export { durableObjectLog, type DurableObjectStorageLike } from './durable-log.js';
+
+/** `{ collection: [{ key, ...fields }] }` */
+export type Snapshot = Record<string, Array<{ key: string } & Record<string, unknown>>>;
+
+export interface SyncObjectOptions {
+  /** Default `/_zb/sync`; the Worker's `syncStub` must use the same. */
+  mount?: string;
+  /** Keep-alive interval (ms, default 2000). A page whose connection is cut is noticed about three keep-alives later. */
+  heartbeat?: number;
+  /** The server's name in its clocks (default `server`). */
+  device?: string;
+  /** The log's table (default `changes`). */
+  table?: string;
+  /** Other origins allowed to push. */
+  origins?: string[];
+}
+
+/** Extend it with your Durable Object class. Methods you add are the stub's, over RPC. */
+export class SyncObject<Env = unknown> {
+  static options?: SyncObjectOptions;
+  constructor(ctx: any, env: Env);
+  protected ctx: any;
+  protected env: Env;
+  /** Refuse a write or hide a change; as `createSyncServer`'s. Allows everything if not defined. */
+  authorize?(asked: { request: Request; collection: string; key: string; write: boolean; kind: 'change' | 'presence' | 'read' }): boolean | Promise<boolean>;
+  fetch(request: Request): Promise<Response>;
+  documents(): Promise<Documents>;
+  write(collection: string, key: string, fields: Record<string, unknown>): Promise<Change[]>;
+  snapshot(collections?: string[]): Promise<Snapshot>;
+}
+
+export function viewOf(snapshot: Snapshot): Documents;
+
+export function syncStub<Stub = any>(
+  namespace: { idFromName(name: string): unknown; get(id: unknown): Stub },
+  options?: { name?: string; mount?: string },
+): {
+  /** The object's stub: your SyncObject's own methods, over RPC. */
+  stub: Stub;
+  /** The object's answer to a sync request, or null when it isn't one. */
+  fetch(request: Request): Promise<Response | null>;
+  /** A copy of the documents (the collections named, or all), for rendering. Not kept current. */
+  documents(...collections: string[]): Promise<Documents>;
+  write(collection: string, key: string, fields: Record<string, unknown>): Promise<Change[]>;
+};

package/src/durable.js

@@ -0,0 +1,55 @@
+// @zubra/sync on Cloudflare Workers. A Durable Object holds the sync server (one per app), with
+// the log in its own SQLite; the Worker forwards sync requests to it and reads and writes through
+// it. Extend SyncObject, and put what must not interleave (check stock, then take it) in its
+// methods: the object runs one call at a time.
+//
+//   import { SyncObject, syncStub } from '@zubra/sync/durable';
+//
+//   export class Market extends SyncObject {
+//     static options = { device: 'market' };                 // createSyncServer's, and `table`
+//     authorize({ request, collection, key, kind }) { … }    // as on Node; secrets are this.env's
+//     async take(key, qty) {
+//       const left = (await this.documents()).get('stock', key)?.qty ?? 0;
+//       if (left < qty) return { error: 'Sold out' };
+//       await this.write('stock', key, { qty: left - qty });
+//       return { ok: true };
+//     }
+//   }
+//
+//   export default {
+//     async fetch(request, env) {
+//       const sync = syncStub(env.MARKET);
+//       return (await sync.fetch(request)) ?? render(request, await sync.documents('stock'));
+//     },
+//   };
+//   // wrangler.jsonc: durable_objects.bindings [{ name: 'MARKET', class_name: 'Market' }],
+//   //                 migrations [{ tag: 'v1', new_sqlite_classes: ['Market'] }]
+import { DurableObject } from 'cloudflare:workers';
+import { syncObject } from './durable-core.js';
+
+export { durableObjectLog } from './durable-log.js';
+export { syncStub, viewOf } from './durable-stub.js';
+
+export class SyncObject extends DurableObject {
+  #sync;
+  constructor(ctx, env) {
+    super(ctx, env);
+    this.#sync = syncObject(ctx, this, this.constructor.options);
+  }
+  /** Sync's requests (`/_zb/sync/*`), forwarded by the Worker's `syncStub(…).fetch`. */
+  fetch(request) {
+    return this.#sync.fetch(request);
+  }
+  /** Every document, kept current (in the object's own methods; the Worker uses the stub's). */
+  documents() {
+    return this.#sync.documents();
+  }
+  /** Write as the server: to the log and every live page. */
+  write(collection, key, fields) {
+    return this.#sync.write(collection, key, fields);
+  }
+  /** Plain data for the stub's `documents()`. */
+  snapshot(collections) {
+    return this.#sync.snapshot(collections);
+  }
+}

package/src/index.js

@@ -52,6 +52,8 @@ export const currentStore = () => theStore();
 const bound = new Map();
 const docId = (collection, key) => `${collection}\u0000${key}`;
 const channel = typeof BroadcastChannel === 'undefined' ? null : new BroadcastChannel('zubra-sync');
+// Outside a browser (Node, a test), an open channel would keep the process from exiting.
+channel?.unref?.();
 channel?.addEventListener('message', ({ data }) =>
   data.kind === 'presence' ? receivePresence(data) : deliver(data.collection, data.key, data.fields, null));
 

package/src/server.d.ts

@@ -14,18 +14,43 @@ export interface Log {
 
 export function memoryLog(): Log;
 
+export interface Documents {
+  /** A document's fields (a copy), or undefined when nothing has been written to it. */
+  get(collection: string, key: string): Record<string, unknown> | undefined;
+  /** Every document in a collection, each with its key. */
+  all(collection: string): Array<{ key: string } & Record<string, unknown>>;
+  /** The collections that have documents, in the order they were first written to. */
+  collections(): string[];
+}
+
 export function createSyncServer(options?: {
   log?: Log;
   /** Default `/_zb/sync`. */
   mount?: string;
-  /** Refuse a write, or hide a change from a reader, by returning false. */
-  authorize?: (from: { request: Request; collection: string; key: string; write: boolean }) => boolean | Promise<boolean>;
+  /**
+   * Refuse a write, or hide a change from a reader, by returning false. `kind` is what's asked:
+   * 'change' (a push), 'presence' (joining or signaling in a document's room; nothing is stored)
+   * or 'read' (a change about to be sent to this request). `write` is true for the first two.
+   */
+  authorize?: (from: { request: Request; collection: string; key: string; write: boolean; kind: 'change' | 'presence' | 'read' }) => boolean | Promise<boolean>;
   /** Other origins allowed to push. */
   origins?: string[];
   /** How often the live stream sends a keep-alive comment (ms, default 15000). */
   heartbeat?: number;
+  /** The server's name in the clocks of its own writes (default `server`). */
+  device?: string;
 }): {
   fetch(request: Request): Promise<Response | null>;
+  /**
+   * Every document as the devices merge it (last writer wins, per field), read from the log the
+   * first time and kept current after. Its reads are synchronous.
+   */
+  documents(): Promise<Documents>;
+  /**
+   * Write fields to a document as the server, with a clock later than any it has seen: to the
+   * documents view at once, then to the log and every live page. Resolves to the changes.
+   */
+  write(collection: string, key: string, fields: Record<string, unknown>): Promise<Change[]>;
   /** Node's http: answers sync requests (streaming the live ones) and resolves true, else false. */
   handle(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse): Promise<boolean>;
 };

package/src/server.js

@@ -7,14 +7,25 @@
 //   const sync = createSyncServer();
 //   const response = await sync.fetch(request);   // a Response, or null if not ours
 //
-// `authorize({ request, collection, key, write })` may refuse a change or hide one (return false).
+// `authorize({ request, collection, key, write, kind })` may refuse a change or hide one (return
+// false). `kind` says what's asked: 'read' (a change being sent to this request), 'change' (one
+// it pushed) or 'presence' (joining a document's room, or signaling in it: nothing is stored).
+// `write` is true for the last two.
+//
+// The server can take part too. `await sync.documents()` is every document as the devices see
+// it (last writer wins, per field), kept current; `sync.write(collection, key, fields)` writes as
+// the server, to the log and to every live page:
+//
+//   const docs = await sync.documents();
+//   const left = docs.get('stock', 'eggs')?.qty ?? 0;   // read and write with no await between,
+//   if (left > 0) sync.write('stock', 'eggs', { qty: left - 1 });   // and no request interleaves
 //
 // Live: `GET <mount>/live?since=<cursor>&peer=<id>` is a server-sent event stream: `changes` as
 // they're pushed, and `presence` from the other viewers (POST <mount>/presence). Subscribers are
 // this process's; several server processes need a shared log and a pub/sub between them.
 //
 // On Node, `handle(req, res)` answers sync requests (streaming the live ones) and returns true.
-const MOUNT = '/_zb/sync';
+export const MOUNT = '/_zb/sync';
 
 /** A log in memory: `append(changes)` and `after(cursor)`. */
 export function memoryLog() {
@@ -33,12 +44,130 @@ export function memoryLog() {
 
 const json = (status, value) => new Response(JSON.stringify(value), { status, headers: { 'content-type': 'application/json' } });
 
+// A clock is `<15-digit ms>-<5-digit counter>-<device>`, so clocks compare as strings.
+const CLOCK = /^(\d{15})-(\d{5})-[\w-]+$/;
+const clock = {
+  format: (time, counter, device) => `${String(time).padStart(15, '0')}-${String(counter).padStart(5, '0')}-${device}`,
+  /** `{ time, counter }`, or null when it isn't a clock. */
+  parse(text) {
+    const match = typeof text === 'string' && CLOCK.exec(text);
+    return match ? { time: Number(match[1]), counter: Number(match[2]) } : null;
+  },
+};
+
 const valid = (change) =>
   change && typeof change.collection === 'string' && typeof change.key === 'string' && typeof change.field === 'string' &&
-  typeof change.clock === 'string' && /^\d{15}-\d{5}-[\w-]+$/.test(change.clock) && change.field !== '$clocks';
+  clock.parse(change.clock) !== null && change.field !== '$clocks';
+
+/**
+ * How documents are read, wherever they're kept: `find(collection, key)` → fields or undefined,
+ * `list(collection)` → `[{ key, fields }]`, `names()` → the collections. What a reader gets is a
+ * copy, so changing it changes nothing.
+ */
+export function documentsView({ find, list, names }) {
+  return {
+    /** A document's fields (a copy), or undefined when nothing has been written to it. */
+    get(collection, key) {
+      const fields = find(collection, key);
+      return fields && structuredClone(fields);
+    },
+    /** Every document in a collection: `[{ key, ...fields }]`. */
+    all: (collection) => list(collection).map(({ key, fields }) => ({ key, ...structuredClone(fields) })),
+    /** The collections that have documents, in the order they were first written to. */
+    collections: () => names(),
+  };
+}
+
+/** The documents a log describes, merged by each field's latest clock, as every device merges them. */
+function documentsOf() {
+  const docs = new Map();
+  const id = (collection, key) => `${collection}\u0000${key}`;
+  return {
+    /** Applies a change if its clock is the field's latest; returns what undoes it, if it did. */
+    apply(change) {
+      let doc = docs.get(id(change.collection, change.key));
+      if (!doc) docs.set(id(change.collection, change.key), (doc = { collection: change.collection, key: change.key, fields: {}, clocks: {} }));
+      const known = doc.clocks[change.field];
+      if (known && known >= change.clock) return null;
+      const had = change.field in doc.fields;
+      const before = doc.fields[change.field];
+      doc.clocks[change.field] = change.clock;
+      doc.fields[change.field] = change.value;
+      return () => {
+        if (doc.clocks[change.field] !== change.clock) return; // something newer came since: it stands
+        if (had) [doc.clocks[change.field], doc.fields[change.field]] = [known, before];
+        else delete doc.clocks[change.field], delete doc.fields[change.field];
+        if (!Object.keys(doc.fields).length) docs.delete(id(change.collection, change.key));
+      };
+    },
+    view: documentsView({
+      find: (collection, key) => docs.get(id(collection, key))?.fields,
+      list: (collection) => [...docs.values()].filter((doc) => doc.collection === collection),
+      names: () => [...new Set([...docs.values()].map((doc) => doc.collection))],
+    }),
+  };
+}
 
-export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize = () => true, origins = [], heartbeat = 15_000 } = {}) {
+export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize = () => true, origins = [], heartbeat = 15_000, device = 'server' } = {}) {
+  if (!/^[\w-]{1,40}$/.test(device)) throw new Error('createSyncServer: `device` names the server in its clocks: letters, digits, - and _');
   const base = mount.replace(/\/$/, '');
+  // Appends, one after another, so the log's order is the order they were made in.
+  let appending = Promise.resolve();
+  // The server's clock: later than any clock it has seen, so its writes win over what came
+  // before them (and lose to what devices write after, as any device's would).
+  let lastTime = 0;
+  let counter = 0;
+  const tick = () => {
+    const now = Math.max(Date.now(), lastTime);
+    counter = now === lastTime ? counter + 1 : 0;
+    lastTime = now;
+    return clock.format(now, counter, device);
+  };
+  const see = (change) => {
+    const { time, counter: seen } = clock.parse(change.clock);
+    if (time > lastTime) {
+      lastTime = time;
+      counter = seen;
+    } else if (time === lastTime) {
+      counter = Math.max(counter, seen);
+    }
+  };
+  // The documents, built from the log the first time they're asked for, then kept current.
+  // While they're being built, what's recorded goes into the view being built too (applying a
+  // change twice changes nothing), so nothing that arrives during the read is missed.
+  let docs = null;
+  let built = null;
+  let building = null;
+  /** Puts changes in the documents; returns what takes them back out (for a write the log refused). */
+  const record = (changes) => {
+    const undo = [];
+    for (const change of changes) {
+      see(change);
+      const taken = (docs ?? built)?.apply(change);
+      if (taken) undo.push(taken);
+    }
+    return () => undo.reverse().forEach((take) => take());
+  };
+  async function documents() {
+    if (docs) return docs.view;
+    building ??= (async () => {
+      built = documentsOf();
+      for (let cursor = 0; ; ) {
+        const page = await log.after(cursor, 5000);
+        for (const change of page.changes) {
+          see(change);
+          built.apply(change);
+        }
+        if (!page.changes.length || String(page.cursor) === String(cursor)) break;
+        cursor = page.cursor;
+      }
+      docs = built;
+      return built.view;
+    })();
+    return building;
+  }
+  // One that fails rejects for its own caller only; the next still runs.
+  const append = (changes) => (appending = appending.catch(() => {}).then(() => log.append(changes)));
   // Live subscribers: { peer, request, send(event, data), rooms }.
   const listeners = new Set();
   const encoder = new TextEncoder();
@@ -50,7 +179,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
     for (const listener of listeners) {
       const visible = [];
       for (const change of changes) {
-        if (await authorize({ request: listener.request, collection: change.collection, key: change.key, write: false })) visible.push(change);
+        if (await authorize({ request: listener.request, collection: change.collection, key: change.key, write: false, kind: 'read' })) visible.push(change);
       }
       listener.send('changes', { changes: visible, cursor });
     }
@@ -59,7 +188,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
     const { collection, key } = roomOf(message.room);
     for (const listener of listeners) {
       if (listener.peer === message.peer) continue;
-      if (await authorize({ request: listener.request, collection, key, write: false })) listener.send('presence', message);
+      if (await authorize({ request: listener.request, collection, key, write: false, kind: 'read' })) listener.send('presence', message);
     }
   }
   const sameOrigin = (request) => {
@@ -82,10 +211,11 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       const changes = Array.isArray(body?.changes) ? body.changes : null;
       if (!changes || !changes.every(valid)) return json(400, { error: 'Expected { changes: [{ collection, key, field, value, clock }] }' });
       for (const change of changes) {
-        if (!(await authorize({ request, collection: change.collection, key: change.key, write: true }))) return json(403, { error: 'Not yours to change' });
+        if (!(await authorize({ request, collection: change.collection, key: change.key, write: true, kind: 'change' }))) return json(403, { error: 'Not yours to change' });
       }
       const appended = changes.map(({ collection, key, field, value, clock }) => ({ collection, key, field, value, clock }));
-      const cursor = await log.append(appended);
+      const cursor = await append(appended);
+      record(appended); // once it's logged: the documents never hold what the log doesn't
       await broadcastChanges(appended, cursor);
       return json(200, { ok: true });
     }
@@ -103,7 +233,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       if (!room || !okPeer || !okState || JSON.stringify(message.state).length > 4096) {
         return json(400, { error: 'Expected { room: "<collection>/<key>", peer, state: {…} | null }' });
       }
-      if (!(await authorize({ request, ...room, write: true }))) return json(403, { error: 'Not yours to join' });
+      if (!(await authorize({ request, ...room, write: true, kind: 'presence' }))) return json(403, { error: 'Not yours to join' });
       const clean = { room: message.room, peer: message.peer, state: message.state };
       for (const listener of listeners) if (listener.peer === clean.peer) {
         if (clean.state === null) listener.rooms.delete(clean.room);
@@ -128,7 +258,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       if (!room || !peerOk(message.from) || !peerOk(message.to) || !dataOk) {
         return json(400, { error: 'Expected { room, from, to, data: {…} }' });
       }
-      if (!(await authorize({ request, ...room, write: true }))) return json(403, { error: 'Not yours to join' });
+      if (!(await authorize({ request, ...room, write: true, kind: 'presence' }))) return json(403, { error: 'Not yours to join' });
       const clean = { room: message.room, from: message.from, to: message.to, data: message.data };
       for (const listener of listeners) if (listener.peer === clean.to) listener.send('signal', clean);
       return json(200, { ok: true });
@@ -170,7 +300,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
             if (!backlog.changes.length && !first) break;
             const visible = [];
             for (const change of backlog.changes) {
-              if (await authorize({ request, collection: change.collection, key: change.key, write: false })) visible.push(change);
+              if (await authorize({ request, collection: change.collection, key: change.key, write: false, kind: 'read' })) visible.push(change);
             }
             listener.send('changes', { changes: visible, cursor: backlog.cursor });
             if (!backlog.changes.length || String(backlog.cursor) === String(from)) break;
@@ -189,7 +319,7 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
       const { changes, cursor } = await log.after(url.searchParams.get('since') ?? '0');
       const visible = [];
       for (const change of changes) {
-        if (await authorize({ request, collection: change.collection, key: change.key, write: false })) visible.push(change);
+        if (await authorize({ request, collection: change.collection, key: change.key, write: false, kind: 'read' })) visible.push(change);
       }
       return json(200, { changes: visible, cursor });
     }
@@ -228,5 +358,36 @@ export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize =
     return true;
   }
 
-  return { fetch, handle };
+  /**
+   * Write `fields` to a document as the server: to the documents view at once (so a check
+   * before it, with no await between, can't be interleaved), then to the log and every live
+   * page. Resolves to the changes written.
+   */
+  async function write(collection, key, fields) {
+    if (typeof collection !== 'string' || typeof key !== 'string' || !fields || typeof fields !== 'object' || Array.isArray(fields)) {
+      throw new TypeError('sync.write(collection, key, { field: value, … })');
+    }
+    if ('$clocks' in fields) throw new TypeError('sync.write: `$clocks` is not a field');
+    // A server that hasn't read its log yet (it just started, or a Durable Object was evicted)
+    // hasn't seen the clocks in it: read it first, so this write comes after all of them. Once
+    // the documents exist this doesn't wait, so a check and a write with no await between stay
+    // one step.
+    if (!docs) await documents();
+    const changes = Object.entries(fields).map(([field, value]) => ({ collection, key, field, value, clock: tick() }));
+    if (!changes.length) return [];
+    // In the documents at once, so a check before this call and the write are one step; taken
+    // back out if the log refuses it.
+    const undo = record(changes);
+    let cursor;
+    try {
+      cursor = await append(changes);
+    } catch (error) {
+      undo();
+      throw error;
+    }
+    await broadcastChanges(changes, cursor);
+    return changes;
+  }
+
+  return { fetch, handle, documents, write };
 }