Simplify: one abstract base class per layer

- BaseKVStorage / BaseEventStorage / BaseDocumentStorage define the API once;
  implementations provide only raw primitives (client and server share an API)
- Drop KV indexes, query planner, unique indexes; document stores take index fields
- Escape every char <= '/' so child keys stay contiguous; skip-scan is now simple
- Event-sourced documents = event storage + any document store for projections
- New folder layout (kv-storage, event-storage, document-storage, utils); tests only in test/

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

@@ -0,0 +1,125 @@
+import type { BaseEventStorage, StoredEvent } from '../event-storage/base-event-storage.js'
+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 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> {
+  child<K extends KeyOf<S>>(key: K): EventSourcedDocumentStorage<ChildOf<S, K>>
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export class EventSourcedDocumentStorage<S extends Spec = AnySpec> extends BaseDocumentStorage<S> {
+  private readonly maxRetries: number
+  /** Tail of the pending writes per document, so writes in one process don't conflict with each other. */
+  private readonly locks = new Map<string, Promise<unknown>>()
+
+  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))
+  }
+
+  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)! }
+  }
+
+  mutate(path: readonly string[], change: (current: Doc | undefined) => DocChange | null): Promise<Doc | undefined> {
+    const id = JSON.stringify(path)
+    const result = (this.locks.get(id) ?? Promise.resolve()).then(() => this.write(path, change))
+    const tail = result.catch(() => {})
+    this.locks.set(id, tail)
+    void tail.then(() => this.locks.get(id) === tail && this.locks.delete(id))
+    return result
+  }
+
+  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). */
+  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])
+    let state: Doc | undefined
+    for await (const event of this.events.readFrom(path, { to: args[args.length - 1] as number })) {
+      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> {
+    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
+    return state
+  }
+}