@livestore/common 0.4.0 → 0.5.0-dev.0

package/src/sync/errors.ts

@@ -2,14 +2,15 @@ import { Schema } from '@livestore/utils/effect'
 
 import { EventSequenceNumber } from '../schema/mod.ts'
 
-export class IsOfflineError extends Schema.TaggedError<IsOfflineError>(
-  '~@livestore/common/IsOfflineError',
-)('IsOfflineError', {
-  cause: Schema.Defect,
-}) {}
+export class IsOfflineError extends Schema.TaggedError<IsOfflineError>('~@livestore/common/IsOfflineError')(
+  'IsOfflineError',
+  {
+    cause: Schema.Defect(),
+  },
+) {}
 
 /** Unique ID generated by the backend when its created. Used to check whether the backend identity has changed. */
-export const BackendId = Schema.String.annotations({ title: '@livestore/sync-cf:BackendId' })
+export const BackendId = Schema.String.annotate({ title: '@livestore/sync-cf:BackendId' })
 
 export class BackendIdMismatchError extends Schema.TaggedError<BackendIdMismatchError>(
   '~@livestore/common/BackendIdMismatchError',
@@ -18,9 +19,10 @@ export class BackendIdMismatchError extends Schema.TaggedError<BackendIdMismatch
   received: BackendId,
 }) {}
 
-export class ServerAheadError extends Schema.TaggedError<ServerAheadError>(
-  '~@livestore/common/ServerAheadError',
-)('ServerAheadError', {
-  minimumExpectedNum: EventSequenceNumber.Global.Schema,
-  providedNum: EventSequenceNumber.Global.Schema,
-}) {}
+export class ServerAheadError extends Schema.TaggedError<ServerAheadError>('~@livestore/common/ServerAheadError')(
+  'ServerAheadError',
+  {
+    minimumExpectedNum: EventSequenceNumber.Global.Schema,
+    providedNum: EventSequenceNumber.Global.Schema,
+  },
+) {}

package/src/sync/mock-sync-backend.test.ts

@@ -0,0 +1,78 @@
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { Effect, Fiber, Option, Stream } from '@livestore/utils/effect'
+
+import { EventSequenceNumber, type LiveStoreEvent } from '../schema/mod.ts'
+import { makeMockSyncBackend } from './mock-sync-backend.ts'
+
+Vitest.describe('makeMockSyncBackend', () => {
+  Vitest.live('broadcasts live events to every backend connection', () =>
+    Effect.gen(function* () {
+      const mockBackend = yield* makeMockSyncBackend({ startConnected: true })
+      const backendA = yield* mockBackend.makeSyncBackend
+      const backendB = yield* mockBackend.makeSyncBackend
+      const nextBatch = (backend: typeof backendA) =>
+        backend.pull(Option.none(), { live: true }).pipe(
+          Stream.filter((item) => item.batch.length > 0),
+          Stream.runFirstUnsafe,
+        )
+
+      const pullA = yield* nextBatch(backendA).pipe(Effect.forkScoped)
+      const pullB = yield* nextBatch(backendB).pipe(Effect.forkScoped)
+      const event = makeEvent(1)
+
+      yield* mockBackend.advance(event)
+
+      Vitest.expect((yield* Fiber.join(pullA)).batch.map((item) => item.eventEncoded)).toEqual([event])
+      Vitest.expect((yield* Fiber.join(pullB)).batch.map((item) => item.eventEncoded)).toEqual([event])
+    }),
+  )
+
+  Vitest.live('seeds a new backend connection with existing live events', () =>
+    Effect.gen(function* () {
+      const mockBackend = yield* makeMockSyncBackend({ startConnected: true })
+      const event = makeEvent(1)
+      yield* mockBackend.advance(event)
+
+      const backend = yield* mockBackend.makeSyncBackend
+      const item = yield* backend.pull(Option.none(), { live: true }).pipe(
+        Stream.filter((item) => item.batch.length > 0),
+        Stream.runFirstUnsafe,
+      )
+
+      Vitest.expect(item.batch.map((entry) => entry.eventEncoded)).toEqual([event])
+    }),
+  )
+
+  Vitest.live('filters seeded live events against the requested cursor', () =>
+    Effect.gen(function* () {
+      const mockBackend = yield* makeMockSyncBackend({ startConnected: true })
+      const existing = makeEvent(1)
+      const next = makeEvent(2)
+      yield* mockBackend.advance(existing)
+
+      const backend = yield* mockBackend.makeSyncBackend
+      const cursor = Option.some({
+        eventSequenceNumber: existing.seqNum,
+        metadata: Option.none(),
+      })
+      const pull = yield* backend.pull(cursor, { live: true }).pipe(
+        Stream.filter((item) => item.batch.length > 0),
+        Stream.runFirstUnsafe,
+        Effect.forkScoped,
+      )
+
+      yield* mockBackend.advance(next)
+
+      Vitest.expect((yield* Fiber.join(pull)).batch.map((entry) => entry.eventEncoded)).toEqual([next])
+    }),
+  )
+})
+
+const makeEvent = (seqNum: number): LiveStoreEvent.Global.Encoded => ({
+  name: 'v1.TestEvent',
+  args: { id: `event-${seqNum}` },
+  seqNum: EventSequenceNumber.Global.make(seqNum),
+  parentSeqNum: EventSequenceNumber.Global.make(seqNum - 1),
+  clientId: 'client-a',
+  sessionId: 'session-a',
+})

package/src/sync/mock-sync-backend.ts

@@ -1,9 +1,18 @@
-import type { Schema, Scope } from '@livestore/utils/effect'
-import { Effect, Mailbox, Option, Queue, Ref, Stream, SubscriptionRef } from '@livestore/utils/effect'
+import {
+  type Schema,
+  type Scope,
+  Effect,
+  Option,
+  Queue,
+  Ref,
+  Semaphore,
+  Stream,
+  SubscriptionRef,
+} from '@livestore/utils/effect'
 
 import { UnknownError } from '../errors.ts'
 import { EventSequenceNumber, type LiveStoreEvent } from '../schema/mod.ts'
-import { type BackendIdMismatchError, type ServerAheadError } from './errors.ts'
+import type { BackendIdMismatchError, ServerAheadError } from './errors.ts'
 import * as SyncBackend from './sync-backend.ts'
 import { validatePushPayload } from './validate-push-payload.ts'
 
@@ -40,7 +49,7 @@ export const makeMockSyncBackend = (
 ): Effect.Effect<MockSyncBackend, UnknownError, Scope.Scope> =>
   Effect.gen(function* () {
     const span = yield* Effect.currentSpan.pipe(Effect.orDie)
-    const semaphore = yield* Effect.makeSemaphore(1)
+    const semaphore = yield* Semaphore.make(1)
 
     // State refs
     const syncHeadRef = yield* Ref.make(EventSequenceNumber.Client.ROOT.global)
@@ -48,12 +57,22 @@ export const makeMockSyncBackend = (
     const syncIsConnectedRef = yield* SubscriptionRef.make(options?.startConnected ?? false)
 
     // Queues for streaming
-    const syncPullQueue = yield* Queue.unbounded<LiveStoreEvent.Global.Encoded>()
-    const pushedEventsQueue = yield* Mailbox.make<LiveStoreEvent.Global.Encoded>()
+    const syncPullQueues = new Set<Queue.Queue<LiveStoreEvent.Global.Encoded>>()
+    const pushedEventsQueue = yield* Queue.unbounded<LiveStoreEvent.Global.Encoded>()
+
+    yield* Effect.addFinalizer(() =>
+      Effect.gen(function* () {
+        for (const queue of syncPullQueues) yield* Queue.shutdown(queue)
+        syncPullQueues.clear()
+      }),
+    )
 
     // Failure simulation state
     const failPushRef = yield* Ref.make<
-      FailureState<UnknownError | ServerAheadError | BackendIdMismatchError, [ReadonlyArray<LiveStoreEvent.Global.Encoded>]>
+      FailureState<
+        UnknownError | ServerAheadError | BackendIdMismatchError,
+        [ReadonlyArray<LiveStoreEvent.Global.Encoded>]
+      >
     >({ remaining: 0, error: undefined })
     const failPullRef = yield* Ref.make<FailureState<UnknownError | BackendIdMismatchError, []>>({
       remaining: 0,
@@ -85,27 +104,12 @@ export const makeMockSyncBackend = (
 
     const pullNonLive = (cursor: Option.Option<{ eventSequenceNumber: EventSequenceNumber.Global.Type }>) =>
       Effect.gen(function* () {
-        const lastSeen = Option.match(cursor, {
-          onNone: () => EventSequenceNumber.Client.ROOT.global,
-          onSome: (_) => _.eventSequenceNumber,
-        })
+        const lastSeen = cursorPosition(cursor)
         const allEvents = yield* Ref.get(allEventsRef)
-        const slice = allEvents.filter((e) => e.seqNum > lastSeen)
-
-        // Split into chunks with remaining count for pageInfo
-        const chunks: Array<{ events: LiveStoreEvent.Global.Encoded[]; remaining: number }> = []
-        for (let i = 0; i < slice.length; i += nonLiveChunkSize) {
-          const end = Math.min(i + nonLiveChunkSize, slice.length)
-          chunks.push({
-            events: slice.slice(i, end),
-            remaining: Math.max(slice.length - end, 0),
-          })
-        }
-        // Always return at least one empty chunk
-        if (chunks.length === 0) {
-          chunks.push({ events: [], remaining: 0 })
-        }
-        return chunks
+        return chunkEvents(
+          allEvents.filter((event) => event.seqNum > lastSeen),
+          nonLiveChunkSize,
+        )
       }).pipe(
         Effect.map((chunks) =>
           Stream.fromIterable(chunks).pipe(
@@ -119,18 +123,38 @@ export const makeMockSyncBackend = (
         Stream.flatten(),
       )
 
-    const pullLive = Stream.concat(
-      Stream.make(SyncBackend.pullResItemEmpty()),
-      Stream.fromQueue(syncPullQueue).pipe(
-        Stream.chunks,
-        Stream.map((chunk) => ({
-          batch: [...chunk].map((eventEncoded) => ({ eventEncoded, metadata: Option.none() })),
-          pageInfo: SyncBackend.pageInfoNoMore,
-        })),
-      ),
-    )
-
     const makeSyncBackend = Effect.gen(function* () {
+      // Every backend connection needs its own live cursor. A shared queue would
+      // load-balance events across Clients instead of broadcasting the log.
+      const syncPullQueue = yield* Effect.acquireRelease(
+        Queue.unbounded<LiveStoreEvent.Global.Encoded>(),
+        Queue.shutdown,
+      )
+      yield* semaphore.withPermits(1)(
+        Effect.gen(function* () {
+          const existingEvents = yield* Ref.get(allEventsRef)
+          syncPullQueues.add(syncPullQueue)
+          yield* Queue.offerAll(syncPullQueue, existingEvents)
+        }),
+      )
+      yield* Effect.addFinalizer(() => Effect.sync(() => syncPullQueues.delete(syncPullQueue)))
+
+      const pullLive = (cursor: Option.Option<{ eventSequenceNumber: EventSequenceNumber.Global.Type }>) => {
+        const lastSeen = cursorPosition(cursor)
+        return Stream.concat(
+          Stream.make(SyncBackend.pullResItemEmpty()),
+          Stream.fromQueue(syncPullQueue).pipe(
+            Stream.chunks,
+            Stream.map((chunk) => ({
+              batch: [...chunk]
+                .filter((eventEncoded) => eventEncoded.seqNum > lastSeen)
+                .map((eventEncoded) => ({ eventEncoded, metadata: Option.none() })),
+              pageInfo: SyncBackend.pageInfoNoMore,
+            })),
+          ),
+        )
+      }
+
       // TODO consider making offline state actively error pull/push.
       // Currently, offline only reflects in `isConnected`, while operations still succeed,
       // mirroring how some real providers behave during transient disconnects.
@@ -145,7 +169,7 @@ export const makeMockSyncBackend = (
               new UnknownError({ cause: new Error('MockSyncBackend: simulated pull failure') }),
             ),
           ).pipe(
-            Stream.flatMap(() => (pullOptions?.live === true ? pullLive : pullNonLive(cursor))),
+            Stream.flatMap(() => (pullOptions?.live === true ? pullLive(cursor) : pullNonLive(cursor))),
             Stream.withSpan('MockSyncBackend:pull', { parent: span }),
           ),
         push: (batch) =>
@@ -161,8 +185,11 @@ export const makeMockSyncBackend = (
 
             yield* Effect.sleep(10).pipe(Effect.withSpan('MockSyncBackend:push:sleep')) // Simulate network latency
 
-            yield* pushedEventsQueue.offerAll(batch)
-            yield* syncPullQueue.offerAll(batch)
+            yield* Queue.offerAll(pushedEventsQueue, batch)
+            yield* Effect.forEach(syncPullQueues, (queue) => Queue.offerAll(queue, batch), {
+              concurrency: 'unbounded',
+              discard: true,
+            })
             yield* Ref.update(allEventsRef, (events) => events.concat(batch))
             yield* Ref.set(syncHeadRef, batch.at(-1)!.seqNum)
           }).pipe(
@@ -187,7 +214,10 @@ export const makeMockSyncBackend = (
       Effect.gen(function* () {
         yield* Ref.set(syncHeadRef, batch.at(-1)!.seqNum)
         yield* Ref.update(allEventsRef, (events) => events.concat(batch))
-        yield* syncPullQueue.offerAll(batch)
+        yield* Effect.forEach(syncPullQueues, (queue) => Queue.offerAll(queue, batch), {
+          concurrency: 'unbounded',
+          discard: true,
+        })
       }).pipe(
         Effect.withSpan('MockSyncBackend:advance', {
           parent: span,
@@ -203,13 +233,11 @@ export const makeMockSyncBackend = (
       ) => Effect.Effect<never, UnknownError | ServerAheadError | BackendIdMismatchError>,
     ) => Ref.set(failPushRef, { remaining: count, error })
 
-    const failNextPulls = (
-      count: number,
-      error?: () => Effect.Effect<never, UnknownError | BackendIdMismatchError>,
-    ) => Ref.set(failPullRef, { remaining: count, error })
+    const failNextPulls = (count: number, error?: () => Effect.Effect<never, UnknownError | BackendIdMismatchError>) =>
+      Ref.set(failPullRef, { remaining: count, error })
 
     return {
-      pushedEvents: Mailbox.toStream(pushedEventsQueue),
+      pushedEvents: Stream.fromQueue(pushedEventsQueue),
       connect: SubscriptionRef.set(syncIsConnectedRef, true),
       disconnect: SubscriptionRef.set(syncIsConnectedRef, false),
       makeSyncBackend,
@@ -224,3 +252,21 @@ interface FailureState<E, Args extends unknown[]> {
   remaining: number
   error: ((...args: Args) => Effect.Effect<never, E>) | undefined
 }
+
+const cursorPosition = (
+  cursor: Option.Option<{ eventSequenceNumber: EventSequenceNumber.Global.Type }>,
+): EventSequenceNumber.Global.Type =>
+  Option.match(cursor, {
+    onNone: () => EventSequenceNumber.Client.ROOT.global,
+    onSome: (_) => _.eventSequenceNumber,
+  })
+
+const chunkEvents = (events: ReadonlyArray<LiveStoreEvent.Global.Encoded>, chunkSize: number) => {
+  const chunks: Array<{ events: ReadonlyArray<LiveStoreEvent.Global.Encoded>; remaining: number }> = []
+  for (let index = 0; index < events.length; index += chunkSize) {
+    const end = Math.min(index + chunkSize, events.length)
+    chunks.push({ events: events.slice(index, end), remaining: Math.max(events.length - end, 0) })
+  }
+  if (chunks.length === 0) chunks.push({ events: [], remaining: 0 })
+  return chunks
+}

package/src/sync/next/history-dag-common.ts

@@ -1,5 +1,5 @@
 import { shouldNeverHappen } from '@livestore/utils'
-import { Graph } from '@livestore/utils/effect'
+import { Graph, Option } from '@livestore/utils/effect'
 
 import type { EventDefFactsGroup } from '../../schema/EventDef/mod.ts'
 import * as EventSequenceNumber from '../../schema/EventSequenceNumber/mod.ts'
@@ -60,6 +60,8 @@ export class HistoryDag {
   private readonly options: HistoryDagOptions
   private readonly idToIndex: Map<string, Graph.NodeIndex>
   private readonly indexToId: Map<Graph.NodeIndex, string>
+  private readonly incomingEdges: Map<Graph.NodeIndex, Set<Graph.EdgeIndex>>
+  private readonly outgoingEdges: Map<Graph.NodeIndex, Set<Graph.EdgeIndex>>
   private readonly graph: Graph.MutableDirectedGraph<HistoryDagNode, HistoryDagEdgeAttributes>
 
   private constructor({
@@ -77,6 +79,8 @@ export class HistoryDag {
     this.options = { ...defaultOptions, ...options }
     this.idToIndex = idToIndex !== undefined ? new Map(idToIndex) : new Map()
     this.indexToId = indexToId !== undefined ? new Map(indexToId) : new Map()
+    this.incomingEdges = new Map()
+    this.outgoingEdges = new Map()
   }
 
   static create(options?: Partial<HistoryDagOptions>): HistoryDag {
@@ -88,11 +92,11 @@ export class HistoryDag {
     const clone = HistoryDag.create(this.options)
 
     for (const [id, index] of this.idToIndex) {
-      const node = this.graph.nodes.get(index) ?? shouldNeverHappen(`HistoryDag.copy missing node for ${id}`)
+      const node = this.nodeAt(index, `HistoryDag.copy missing node for ${id}`)
       clone.addNode(id, cloneHistoryDagNode(node))
     }
 
-    for (const edge of this.graph.edges.values()) {
+    for (const [, edge] of Graph.edges(this.graph)) {
       const sourceId = this.indexToId.get(edge.source) ?? shouldNeverHappen('HistoryDag.copy missing source id')
       const targetId = this.indexToId.get(edge.target) ?? shouldNeverHappen('HistoryDag.copy missing target id')
       clone.addEdge(sourceId, targetId, { ...edge.data })
@@ -117,6 +121,8 @@ export class HistoryDag {
     const nodeIndex = Graph.addNode(this.graph, attributes)
     this.idToIndex.set(id, nodeIndex)
     this.indexToId.set(nodeIndex, id)
+    this.incomingEdges.set(nodeIndex, new Set())
+    this.outgoingEdges.set(nodeIndex, new Set())
   }
 
   hasNode(id: string): boolean {
@@ -129,8 +135,7 @@ export class HistoryDag {
       return shouldNeverHappen(`HistoryDag node ${id} not found`)
     }
 
-    const node = this.graph.nodes.get(index)
-    return node ?? shouldNeverHappen(`HistoryDag node data missing for ${id}`)
+    return this.nodeAt(index, `HistoryDag node data missing for ${id}`)
   }
 
   nodes(): IterableIterator<string> {
@@ -140,7 +145,7 @@ export class HistoryDag {
   nodeEntries(): IterableIterator<{ key: string; attributes: HistoryDagNode }> {
     return function* (this: HistoryDag) {
       for (const [id, index] of this.idToIndex) {
-        const attributes = this.graph.nodes.get(index) ?? shouldNeverHappen(`HistoryDag node data missing for ${id}`)
+        const attributes = this.nodeAt(index, `HistoryDag node data missing for ${id}`)
         yield { key: id, attributes }
       }
     }.call(this)
@@ -158,7 +163,15 @@ export class HistoryDag {
       return shouldNeverHappen(`HistoryDag edge references unknown nodes: ${sourceId} -> ${targetId}`)
     }
 
-    return Graph.addEdge(this.graph, sourceIndex, targetIndex, attributes)
+    const edgeIndex = Graph.addEdge(this.graph, sourceIndex, targetIndex, attributes)
+    const outgoingEdges = this.outgoingEdges.get(sourceIndex)
+    const incomingEdges = this.incomingEdges.get(targetIndex)
+    if (outgoingEdges === undefined || incomingEdges === undefined) {
+      return shouldNeverHappen(`HistoryDag edge index missing for ${sourceId} -> ${targetId}`)
+    }
+    outgoingEdges.add(edgeIndex)
+    incomingEdges.add(edgeIndex)
+    return edgeIndex
   }
 
   edges(sourceId: string, targetId: string): Array<Graph.EdgeIndex> {
@@ -169,14 +182,9 @@ export class HistoryDag {
       return []
     }
 
-    const adjacency = this.graph.adjacency.get(sourceIndex)
-    if (adjacency === undefined) {
-      return []
-    }
-
-    return adjacency.filter((edgeIndex) => {
-      const edge = this.graph.edges.get(edgeIndex)
-      return edge !== undefined && edge.target === targetIndex
+    return Array.from(this.outgoingEdges.get(sourceIndex) ?? []).filter((edgeIndex) => {
+      const edge = Option.getOrUndefined(Graph.getEdge(this.graph, edgeIndex))
+      return edge?.target === targetIndex
     })
   }
 
@@ -185,8 +193,7 @@ export class HistoryDag {
     if (index === undefined) {
       return []
     }
-    const incoming = this.graph.reverseAdjacency.get(index)
-    return incoming !== undefined ? [...incoming] : []
+    return [...(this.incomingEdges.get(index) ?? [])]
   }
 
   outboundEdgeEntries(id: string): Array<HistoryDagEdgeEntry> {
@@ -195,12 +202,7 @@ export class HistoryDag {
       return []
     }
 
-    const adjacency = this.graph.adjacency.get(index)
-    if (adjacency === undefined) {
-      return []
-    }
-
-    return adjacency
+    return [...(this.outgoingEdges.get(index) ?? [])]
       .map((edgeIndex) => this.edgeEntry(edgeIndex))
       .filter((entry): entry is HistoryDagEdgeEntry => entry !== undefined)
   }
@@ -211,19 +213,13 @@ export class HistoryDag {
       return []
     }
 
-    const adjacency = this.graph.reverseAdjacency.get(index)
-    if (adjacency === undefined) {
-      return []
-    }
-
-    return adjacency
+    return [...(this.incomingEdges.get(index) ?? [])]
       .map((edgeIndex) => this.edgeEntry(edgeIndex))
       .filter((entry): entry is HistoryDagEdgeEntry => entry !== undefined)
   }
 
   getEdgeAttributes(edgeIndex: Graph.EdgeIndex): HistoryDagEdgeAttributes {
-    const edge = this.graph.edges.get(edgeIndex)
-    return edge?.data ?? shouldNeverHappen(`HistoryDag edge ${edgeIndex} not found`)
+    return this.edgeAt(edgeIndex, `HistoryDag edge ${edgeIndex} not found`).data
   }
 
   getEdgeAttribute<TKey extends keyof HistoryDagEdgeAttributes>(
@@ -235,13 +231,13 @@ export class HistoryDag {
   }
 
   source(edgeIndex: Graph.EdgeIndex): string {
-    const edge = this.graph.edges.get(edgeIndex)
+    const edge = Option.getOrUndefined(Graph.getEdge(this.graph, edgeIndex))
     const sourceId = edge !== undefined ? this.indexToId.get(edge.source) : undefined
     return sourceId ?? shouldNeverHappen(`HistoryDag edge ${edgeIndex} missing source`)
   }
 
   target(edgeIndex: Graph.EdgeIndex): string {
-    const edge = this.graph.edges.get(edgeIndex)
+    const edge = Option.getOrUndefined(Graph.getEdge(this.graph, edgeIndex))
     const targetId = edge !== undefined ? this.indexToId.get(edge.target) : undefined
     return targetId ?? shouldNeverHappen(`HistoryDag edge ${edgeIndex} missing target`)
   }
@@ -252,9 +248,20 @@ export class HistoryDag {
       return
     }
 
+    for (const edgeIndex of this.outgoingEdges.get(index) ?? []) {
+      const edge = this.edgeAt(edgeIndex, `HistoryDag edge ${edgeIndex} missing while dropping ${id}`)
+      removeEdgeIndex(this.incomingEdges, edge.target, edgeIndex)
+    }
+    for (const edgeIndex of this.incomingEdges.get(index) ?? []) {
+      const edge = this.edgeAt(edgeIndex, `HistoryDag edge ${edgeIndex} missing while dropping ${id}`)
+      removeEdgeIndex(this.outgoingEdges, edge.source, edgeIndex)
+    }
+
     Graph.removeNode(this.graph, index)
     this.idToIndex.delete(id)
     this.indexToId.delete(index)
+    this.incomingEdges.delete(index)
+    this.outgoingEdges.delete(index)
   }
 
   get size(): number {
@@ -262,7 +269,7 @@ export class HistoryDag {
   }
 
   private edgeEntry(edgeIndex: Graph.EdgeIndex): HistoryDagEdgeEntry | undefined {
-    const edge = this.graph.edges.get(edgeIndex)
+    const edge = Option.getOrUndefined(Graph.getEdge(this.graph, edgeIndex))
     if (edge === undefined) {
       return undefined
     }
@@ -281,6 +288,25 @@ export class HistoryDag {
       attributes: edge.data,
     }
   }
+
+  private nodeAt(index: Graph.NodeIndex, message: string): HistoryDagNode {
+    return Option.getOrElse(Graph.getNode(this.graph, index), () => shouldNeverHappen(message))
+  }
+
+  private edgeAt(edgeIndex: Graph.EdgeIndex, message: string): Graph.Edge<HistoryDagEdgeAttributes> {
+    return Option.getOrElse(Graph.getEdge(this.graph, edgeIndex), () => shouldNeverHappen(message))
+  }
+}
+
+const removeEdgeIndex = (
+  edgeIndices: Map<Graph.NodeIndex, Set<Graph.EdgeIndex>>,
+  nodeIndex: Graph.NodeIndex,
+  edgeIndex: Graph.EdgeIndex,
+): void => {
+  const indices = edgeIndices.get(nodeIndex) ?? shouldNeverHappen(`HistoryDag edge index missing for node ${nodeIndex}`)
+  if (indices.delete(edgeIndex) === false) {
+    shouldNeverHappen(`HistoryDag edge ${edgeIndex} missing from node ${nodeIndex}`)
+  }
 }
 
 export const emptyHistoryDag = (): HistoryDag => HistoryDag.create({ allowSelfLoops: false })

package/src/sync/next/history-dag.ts

@@ -48,7 +48,10 @@ export const historyDagFromNodes = (dagNodes: HistoryDagNode[], options?: { skip
           const parentSeqNumStr = dag.source(parentEdge)
           const parentNode = dag.getNodeAttributes(parentSeqNumStr)
 
-          if (parentNode.factsGroup.modifySet.has(factKey) === true || parentNode.factsGroup.modifyUnset.has(factKey) === true) {
+          if (
+            parentNode.factsGroup.modifySet.has(factKey) === true ||
+            parentNode.factsGroup.modifyUnset.has(factKey) === true
+          ) {
             return parentNode
           }
 

package/src/sync/next/test/compact-events.calculator.test.ts

@@ -27,11 +27,11 @@ const facts = {
 const eventDefs = {
   add: defineEvent({
     name: 'add',
-    schema: Schema.Struct({ value: Schema.Number }),
+    schema: Schema.Struct({ value: Schema.Finite }),
   }),
   multiply: defineEvent({
     name: 'multiply',
-    schema: Schema.Struct({ value: Schema.Number }),
+    schema: Schema.Struct({ value: Schema.Finite }),
     facts: ({ value }, currentFacts) => ({
       modify: {
         set: value === 0 || currentFacts.has(facts.multiplyByZero) === true ? [facts.multiplyByZero] : [],

package/src/sync/next/test/event-fixtures.ts

@@ -146,7 +146,7 @@ export const toEventNodes = (
     const eventDef = eventDefs[partialEvent.name]!
     const eventNum = EventSequenceNumber.Client.nextPair({
       seqNum: currentEventSequenceNumber,
-      isClient: eventDef.options.clientOnly,
+      isClientOnly: eventDef.options.clientOnly,
     }).seqNum
     currentEventSequenceNumber = eventNum
 

package/src/sync/next/test/history-dag-common.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+
+import * as EventSequenceNumber from '../../../schema/EventSequenceNumber/mod.ts'
+import { HistoryDag, type HistoryDagNode } from '../history-dag-common.ts'
+
+const makeNode = (global: number, parentGlobal = global - 1): HistoryDagNode => ({
+  seqNum: EventSequenceNumber.Client.Composite.make({ global, client: 0 }),
+  parentSeqNum: EventSequenceNumber.Client.Composite.make({ global: parentGlobal, client: 0 }),
+  name: `event-${global}`,
+  args: {},
+  factsGroup: {
+    depRead: new Map(),
+    depRequire: new Map(),
+    modifySet: new Map(),
+    modifyUnset: new Map(),
+  },
+  meta: undefined,
+  clientId: 'client-id',
+  sessionId: 'session-id',
+})
+
+describe('HistoryDag', () => {
+  it('preserves parallel edge order and removes incident edges with a node', () => {
+    const dag = HistoryDag.create()
+    dag.addNode('a', makeNode(1))
+    dag.addNode('b', makeNode(2))
+    dag.addNode('c', makeNode(3))
+
+    const parentEdge = dag.addEdge('a', 'b', { type: 'parent' })
+    const factsEdge = dag.addEdge('a', 'b', { type: 'facts' })
+    const incomingEdge = dag.addEdge('c', 'b', { type: 'facts' })
+
+    expect(dag.edges('a', 'b')).toEqual([parentEdge, factsEdge])
+    expect(dag.inEdges('b')).toEqual([parentEdge, factsEdge, incomingEdge])
+    expect(dag.inboundEdgeEntries('b')).toEqual([
+      { edge: parentEdge, source: 'a', target: 'b', attributes: { type: 'parent' } },
+      { edge: factsEdge, source: 'a', target: 'b', attributes: { type: 'facts' } },
+      { edge: incomingEdge, source: 'c', target: 'b', attributes: { type: 'facts' } },
+    ])
+    expect(dag.outboundEdgeEntries('a')).toEqual([
+      { edge: parentEdge, source: 'a', target: 'b', attributes: { type: 'parent' } },
+      { edge: factsEdge, source: 'a', target: 'b', attributes: { type: 'facts' } },
+    ])
+    expect(dag.source(parentEdge)).toBe('a')
+    expect(dag.target(parentEdge)).toBe('b')
+    expect(dag.getEdgeAttribute(parentEdge, 'type')).toBe('parent')
+
+    dag.dropNode('b')
+
+    expect(dag.edges('a', 'b')).toEqual([])
+    expect(dag.outboundEdgeEntries('a')).toEqual([])
+    expect(dag.outboundEdgeEntries('c')).toEqual([])
+  })
+
+  it('keeps the adjacency indexes consistent for self-loops', () => {
+    const dag = HistoryDag.create({ allowSelfLoops: true })
+    dag.addNode('a', makeNode(1))
+
+    const edge = dag.addEdge('a', 'a', { type: 'facts' })
+
+    expect(dag.edges('a', 'a')).toEqual([edge])
+    expect(dag.inEdges('a')).toEqual([edge])
+    expect(dag.inboundEdgeEntries('a')).toEqual([{ edge, source: 'a', target: 'a', attributes: { type: 'facts' } }])
+
+    dag.dropNode('a')
+
+    expect(dag.size).toBe(0)
+    expect(dag.edges('a', 'a')).toEqual([])
+  })
+
+  it('copies nodes, facts, and edges without sharing mutable data', () => {
+    const dag = HistoryDag.create()
+    const nodeA = makeNode(1)
+    nodeA.factsGroup.modifySet = new Map([['key', 'value']])
+    dag.addNode('a', nodeA)
+    dag.addNode('b', makeNode(2))
+    dag.addEdge('a', 'b', { type: 'parent' })
+
+    const copy = dag.copy()
+    const copiedNode = copy.getNodeAttributes('a')
+
+    expect(copiedNode).not.toBe(nodeA)
+    expect(copiedNode.factsGroup.modifySet).not.toBe(nodeA.factsGroup.modifySet)
+    expect(copy.outboundEdgeEntries('a')).toMatchObject([{ source: 'a', target: 'b', attributes: { type: 'parent' } }])
+    expect(copy.getEdgeAttributes(copy.edges('a', 'b')[0]!)).not.toBe(dag.getEdgeAttributes(dag.edges('a', 'b')[0]!))
+  })
+})