Plain operations: last write wins, hash-keyed events, simpler composite

- KV: one write primitive, write(changes) with { key, value? }; writeIfAbsent removed.
  The server executes exactly what clients send and never reads values, so they can be
  encrypted end to end. Adds setFields/getFields on the base class.
- HTTP: no server history or event ids; SSE relays every change (own writes included) and
  the client emits resync when a dropped stream reconnects.
- Composite: writes apply locally, then go to the source (undone locally if refused);
  pushed changes are applied and announced only where they differ from local values;
  offline writes go to a queue store (any KV storage); sync() = replay, diff, replay.
  Removes KVReplicaSet, KVOutbox, KeyCounter, SerialQueue and RetryTimer.
- Events: id = <time>_<sha256(time + canonical data)>, so concurrent appends never
  collide and retries can't duplicate; no versions or ConcurrencyError.
- Event-sourced documents: read, resolve, append, apply; catchUp folds in foreign events;
  getAt takes an event id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Qxbkp4tA7G5SCWjzWuxmE

src/document-storage/event-sourced-document-storage.ts

@@ -2,16 +2,9 @@ import type { BaseEventStorage, StoredEvent } from '../event-storage/base-event-
 import type { Doc } from '../utils/document-path.js'
 import type { DocumentQuery, FindResult } from '../utils/document-query.js'
 import { DocumentUpdate, type DocChange } from '../utils/document-update.js'
-import { ConcurrencyError } from '../utils/errors.js'
-import { SerialQueue } from '../utils/serial-queue.js'
 import type { AnySpec, ChildOf, KeyOf, Spec, ValueAt } from '../utils/schema.js'
 import { BaseDocumentStorage } from './base-document-storage.js'
 
-export interface EventSourcedDocumentStorageOptions {
-  /** Retries after a write conflict, each preceded by a catch-up. Default 5. */
-  maxRetries?: number
-}
-
 // Types only: children of an event-sourced store are event-sourced stores too (child() creates
 // them with Object.create, so they share this class's prototype).
 export interface EventSourcedDocumentStorage<S extends Spec = AnySpec> {
@@ -19,103 +12,66 @@ export interface EventSourcedDocumentStorage<S extends Spec = AnySpec> {
 }
 
 /**
- * Documents as event streams: each document's changes are appended to its own stream, and the
- * current state is kept in a projection store (any `BaseDocumentStorage`), which serves all
- * reads and queries.
+ * Documents as event streams: each change to a document is appended to its own stream, and the
+ * current state is kept in a projection store (any `BaseDocumentStorage`), which serves all reads
+ * and queries.
  *
- * Projections carry a `_version` field (stripped from results) used as `expectedVersion` on the
- * next append. If a write crashes between appending and updating the projection, the next
- * write's append conflicts, the projection is rebuilt from the stream, and the write retries.
- * `_version` is therefore reserved in documents.
+ * A document's state is its events folded in order. Changes are stored as resolved values
+ * (`$inc` becomes `set: { n: 6 }`), so two devices editing the same field concurrently end with
+ * the later event's value; edits to different fields both survive.
+ *
+ * The projection is updated by this store's own writes. Events written elsewhere (another device,
+ * arriving through sync) are folded in by `catchUp(key)`, which rebuilds the document from its
+ * whole stream; call it when such events arrive.
  */
 export class EventSourcedDocumentStorage<S extends Spec = AnySpec> extends BaseDocumentStorage<S> {
-  private readonly maxRetries: number
-  /** Writes to one document run one at a time, so writes in one process don't conflict with each other. */
-  private readonly writes = new SerialQueue()
-
   constructor(
     private readonly events: BaseEventStorage,
     private readonly projections: BaseDocumentStorage,
-    options: EventSourcedDocumentStorageOptions = {},
   ) {
     super()
-    this.maxRetries = options.maxRetries ?? 5
   }
 
-  async readMany(paths: (readonly string[])[]): Promise<(Doc | undefined)[]> {
-    return (await this.projections.readMany(paths)).map((doc) => EventSourcedDocumentStorage.strip(doc))
+  readMany(paths: (readonly string[])[]): Promise<(Doc | undefined)[]> {
+    return this.projections.readMany(paths)
   }
 
-  async *query(parent: readonly string[], query: DocumentQuery): AsyncGenerator<FindResult> {
-    for await (const { key, data } of this.projections.query(parent, query)) yield { key, data: EventSourcedDocumentStorage.strip(data)! }
+  query(parent: readonly string[], query: DocumentQuery): AsyncIterable<FindResult> {
+    return this.projections.query(parent, query)
   }
 
-  mutate(path: readonly string[], change: (current: Doc | undefined) => DocChange | null): Promise<Doc | undefined> {
-    return this.writes.run(() => this.write(path, change), JSON.stringify(path))
+  async mutate(path: readonly string[], change: (current: Doc | undefined) => DocChange | null): Promise<Doc | undefined> {
+    const [current] = await this.projections.readMany([path])
+    const resolved = change(current)
+    if (!resolved) return current
+    await this.events.appendTo(path, [resolved])
+    // Apply the change itself (not the state computed above), so concurrent writes in this
+    // process each land on the latest projection.
+    return this.projections.mutate(path, () => resolved)
   }
 
-  private async write(path: readonly string[], change: (current: Doc | undefined) => DocChange | null): Promise<Doc | undefined> {
-    for (let attempt = 0; ; attempt++) {
-      const [stored] = await this.projections.readMany([path])
-      const version = (stored?._version as number | undefined) ?? (await this.events.versionOf(path))
-      if (!stored && version > 0) {
-        // No projection but the stream has history (deleted, or a crashed first write): rebuild.
-        if ((await this.rebuild(path)) !== undefined) continue
-      }
-      const current = EventSourcedDocumentStorage.strip(stored)
-      const resolved = change(current)
-      if (!resolved) return current
-      const next = DocumentUpdate.apply(current, resolved)
-      try {
-        await this.events.appendTo(path, [resolved], version)
-      } catch (error) {
-        if (!(error instanceof ConcurrencyError) || attempt >= this.maxRetries) throw error
-        await this.rebuild(path)
-        continue
-      }
-      await this.project(path, next, version + 1)
-      return next
-    }
-  }
-
-  /** Events of this document (or a child). */
+  /** Events of this document (or a child), oldest first. */
   history(key?: KeyOf<S>): AsyncIterable<StoredEvent<DocChange>> {
     return this.events.readFrom(this.pathOf(arguments.length > 0, key), {}) as AsyncIterable<StoredEvent<DocChange>>
   }
 
-  /** State as of `version`: `getAt(version)` for this document, `getAt(key, version)` for a child. */
-  async getAt<K extends KeyOf<S>>(...args: [version: number] | [key: K, version: number]): Promise<ValueAt<S, K> | undefined> {
-    const path = this.pathOf(args.length > 1, args[0])
+  /** State right after event `eventId`: `getAt(eventId)` for this document, `getAt(key, eventId)` for a child. */
+  async getAt<K extends KeyOf<S>>(...args: [eventId: string] | [key: K, eventId: string]): Promise<ValueAt<S, K> | undefined> {
+    const until = args[args.length - 1] as string
     let state: Doc | undefined
-    for await (const event of this.events.readFrom(path, { to: args[args.length - 1] as number })) {
+    for await (const event of this.events.readFrom(this.pathOf(args.length > 1, args[0]), {})) {
+      if (event.id > until) break
       state = DocumentUpdate.apply(state, event.data as DocChange)
     }
     return state as ValueAt<S, K> | undefined
   }
 
-  /** Rebuilds the projection of this document (or a child) from its stream. Returns the state. */
-  catchUp(key?: KeyOf<S>): Promise<Doc | undefined> {
-    return this.rebuild(this.pathOf(arguments.length > 0, key))
-  }
-
-  private async rebuild(path: readonly string[]): Promise<Doc | undefined> {
+  /** Rebuilds the projection of this document (or a child) from all its events. Returns the state. */
+  async catchUp(key?: KeyOf<S>): Promise<Doc | undefined> {
+    const path = this.pathOf(arguments.length > 0, key)
     let state: Doc | undefined
-    let version = 0
-    for await (const event of this.events.readFrom(path, {})) {
-      state = DocumentUpdate.apply(state, event.data as DocChange)
-      version = event.version
-    }
-    await this.project(path, state, version)
-    return state
-  }
-
-  private async project(path: readonly string[], state: Doc | undefined, version: number): Promise<void> {
-    await this.projections.mutate(path, () => (state ? { op: 'set', doc: { ...state, _version: version } } : { op: 'delete' }))
-  }
-
-  private static strip(doc: Doc | undefined): Doc | undefined {
-    if (!doc) return undefined
-    const { _version, ...state } = doc
+    for await (const event of this.events.readFrom(path, {})) state = DocumentUpdate.apply(state, event.data as DocChange)
+    await this.projections.mutate(path, () => (state ? { op: 'set', doc: state } : { op: 'delete' }))
     return state
   }
 }