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

test/event-storage/event-storage-kv.test.ts

@@ -1,45 +1,70 @@
 import { describe, expect, it } from 'vitest'
 import fc from 'fast-check'
 import { EventStorageKV } from '../../src/event-storage/event-storage-kv.js'
+import type { BaseKVStorage } from '../../src/kv-storage/base-kv-storage.js'
 import { KVStorageInMemory } from '../../src/kv-storage/kv-storage-in-memory.js'
-import { ConcurrencyError } from '../../src/utils/errors.js'
 import { collect, KVStorageCounting } from '../helpers.js'
 
-function setup(kv = new KVStorageCounting()) {
-  let t = 1000
+function setup(kv: BaseKVStorage = new KVStorageCounting(), start = 1000) {
+  let t = start
   return { kv, events: new EventStorageKV(kv, { now: () => t++ }) }
 }
 
 describe('EventStorageKV', () => {
   it('appends and reads in self and child forms', async () => {
     const orders = setup().events.child('orders')
-    expect(await orders.append('o1', [{ type: 'created' }], { expectedVersion: 0 })).toEqual({ version: 1 })
-    expect(await orders.child('o1').append([{ type: 'paid' }, { type: 'shipped' }])).toEqual({ version: 3 })
+    const [created] = await orders.append('o1', [{ type: 'created' }])
+    const ids = await orders.child('o1').append([{ type: 'paid' }, { type: 'shipped' }])
     expect(await collect(orders.read('o1'))).toEqual([
-      { version: 1, at: 1000, data: { type: 'created' } },
-      { version: 2, at: 1001, data: { type: 'paid' } },
-      { version: 3, at: 1001, data: { type: 'shipped' } },
+      { id: created, at: 1000, data: { type: 'created' } },
+      { id: ids[0], at: 1001, data: { type: 'paid' } },
+      { id: ids[1], at: 1002, data: { type: 'shipped' } },
     ])
-    expect(await collect(orders.child('o1').read({ from: 3 }))).toHaveLength(1)
-    expect(await orders.version('o1')).toBe(3)
-    expect(await orders.version('none')).toBe(0)
+    expect((await collect(orders.child('o1').read({ after: ids[0] }))).map((e) => e.data)).toEqual([{ type: 'shipped' }])
+    expect((await collect(orders.read('o1', { reverse: true, limit: 2 }))).map((e) => e.id)).toEqual([ids[1], ids[0]])
+    expect((await collect(orders.read('o1', { reverse: true, after: ids[0] }))).map((e) => e.id)).toEqual([created])
   })
 
-  it('stores one key per commit', async () => {
+  it('ids are the time and a hash of the time and content', async () => {
     const { kv, events } = setup()
-    await events.child('s').append(['a'])
-    await events.child('s').append(['b', 'c'])
-    expect((await collect(kv.scan())).map(([k]) => k)).toEqual(['s/~e/000000000001', 's/~e/000000000002'])
+    const [id] = await events.child('s').append([{ b: 1, a: 2 }])
+    expect(id).toMatch(/^000000000001000_[0-9a-f]{64}$/)
+    expect(id).toBe(await EventStorageKV.id(1000, { a: 2, b: 1 }))
+    expect((await collect(kv.scan())).map(([k]) => k)).toEqual([`s/~e/${id}`])
   })
 
-  it('enforces expectedVersion and the arity rules', async () => {
+  it('one append is one write; one instance never reuses a time', async () => {
+    const kv = new KVStorageCounting()
+    const events = new EventStorageKV(kv, { now: () => 5 })
+    const ids = await events.child('s').append(['a', 'a'])
+    expect(kv.calls).toEqual({ writeMany: 1 })
+    expect(ids.map((id) => id.slice(0, 15))).toEqual(['000000000000005', '000000000000006'])
+    expect((await collect(events.child('s').read())).map((e) => e.data)).toEqual(['a', 'a'])
+  })
+
+  it('keeps concurrent appends from different writers, ordered by time', async () => {
+    const kv = new KVStorageInMemory()
+    const a = setup(kv, 1000).events.child('s')
+    const b = setup(kv, 1000).events.child('s')
+    await Promise.all([a.append(['a1', 'a2']), b.append(['b1', 'b2'])])
+    const read = await collect(a.read())
+    expect(read).toHaveLength(4)
+    expect(read.map((e) => e.at)).toEqual([1000, 1000, 1001, 1001])
+    expect(read.map((e) => e.id)).toEqual([...read.map((e) => e.id)].sort())
+    expect(await collect(b.read())).toEqual(read)
+  })
+
+  it('writing the same event again does not duplicate it', async () => {
+    const kv = new KVStorageInMemory()
+    await setup(kv).events.child('s').append(['x'])
+    await setup(kv).events.child('s').append(['x'])
+    expect(await collect(new EventStorageKV(kv).child('s').read())).toHaveLength(1)
+  })
+
+  it('checks the arity rules', async () => {
     const { events } = setup()
-    const s = events.child('s')
-    await s.append(['a'])
-    await expect(s.append(['b'], { expectedVersion: 0 })).rejects.toBeInstanceOf(ConcurrencyError)
     await expect(events.append(['x'])).rejects.toThrow(/root/)
     await expect(events.child('o').append(undefined as never, ['x'] as never)).rejects.toThrow(TypeError)
-    await expect(events.child('o').version(undefined as never)).rejects.toThrow(TypeError)
   })
 
   it('lists child streams', async () => {
@@ -51,46 +76,26 @@ describe('EventStorageKV', () => {
     expect(await collect(orders.child('o1').keys())).toEqual(['notes'])
   })
 
-  it('a warm append is one writeIfAbsent; a cold one adds one reverse scan', async () => {
-    const { kv, events } = setup()
-    await events.child('s').append(['a'])
-    kv.reset()
-    await events.child('s').append(['b'])
-    expect(kv.calls).toEqual({ writeIfAbsent: 1 })
-    const cold = setup(kv).events
-    kv.reset()
-    await cold.child('s').append(['c'])
-    expect(kv.calls).toEqual({ scan: 1, writeIfAbsent: 1 })
-  })
-
-  it('a writer with a stale cache collides; with "any" it retries', async () => {
-    const kv = new KVStorageInMemory()
-    const a = setup(new KVStorageCounting(kv)).events.child('s')
-    const b = setup(new KVStorageCounting(kv)).events.child('s')
-    await a.append(['a1'])
-    await b.append(['b1'])
-    await expect(a.append(['a2'], { expectedVersion: 1 })).rejects.toMatchObject({ actualVersion: 2 })
-    expect(await a.append(['a3'])).toEqual({ version: 3 })
-    const results = await Promise.allSettled([a.append(['x'], { expectedVersion: 3 }), b.append(['y'], { expectedVersion: 3 })])
-    expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(1)
-  })
-
   it('reads any window correctly (property)', async () => {
     await fc.assert(
       fc.asyncProperty(
         fc.array(fc.integer({ min: 1, max: 4 }), { maxLength: 20 }),
         fc.record({
-          from: fc.option(fc.integer({ min: 0, max: 60 }), { nil: undefined }),
-          to: fc.option(fc.integer({ min: 0, max: 60 }), { nil: undefined }),
+          after: fc.option(fc.nat(60), { nil: undefined }),
           limit: fc.option(fc.nat(10), { nil: undefined }),
+          reverse: fc.boolean(),
         }),
-        async (sizes, options) => {
+        async (sizes, { after, limit, reverse }) => {
           const s = setup().events.child('s')
-          let n = 0
-          for (const size of sizes) await s.append(Array.from({ length: size }, () => ++n))
-          let expected = Array.from({ length: n }, (_, i) => i + 1).filter((v) => v >= (options.from ?? 1) && v <= (options.to ?? Infinity))
-          if (options.limit !== undefined) expected = expected.slice(0, options.limit)
-          expect((await collect(s.read(options))).map((e) => e.data)).toEqual(expected)
+          const ids: string[] = []
+          for (const size of sizes) ids.push(...(await s.append(Array.from({ length: size }, () => ids.length))))
+          const all = await collect(s.read())
+          expect(all.map((e) => e.id)).toEqual(ids)
+          const ordered = reverse ? [...ids].reverse() : ids
+          const afterId = after === undefined ? undefined : ids[after]
+          let expected = afterId === undefined ? ordered : ordered.slice(ordered.indexOf(afterId) + 1)
+          if (limit !== undefined) expected = expected.slice(0, limit)
+          expect((await collect(s.read({ after: afterId, limit, reverse }))).map((e) => e.id)).toEqual(expected)
         },
       ),
       { numRuns: 200 },