@livestore/common 0.4.0-dev.0 → 0.4.0-dev.10

package/src/sync/errors.ts

@@ -0,0 +1,38 @@
+import { Schema } from '@livestore/utils/effect'
+import { UnexpectedError } from '../errors.ts'
+import { EventSequenceNumber } from '../schema/mod.ts'
+
+export class IsOfflineError extends Schema.TaggedError<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 class BackendIdMismatchError extends Schema.TaggedError<BackendIdMismatchError>()('BackendIdMismatchError', {
+  expected: BackendId,
+  received: BackendId,
+}) {}
+
+export class ServerAheadError extends Schema.TaggedError<ServerAheadError>()('ServerAheadError', {
+  minimumExpectedNum: EventSequenceNumber.GlobalEventSequenceNumber,
+  providedNum: EventSequenceNumber.GlobalEventSequenceNumber,
+}) {}
+
+export class InvalidPushError extends Schema.TaggedError<InvalidPushError>()('InvalidPushError', {
+  cause: Schema.Union(UnexpectedError, ServerAheadError, BackendIdMismatchError),
+}) {}
+
+export class InvalidPullError extends Schema.TaggedError<InvalidPullError>()('InvalidPullError', {
+  cause: Schema.Defect,
+}) {}
+
+export class LeaderAheadError extends Schema.TaggedError<LeaderAheadError>()('LeaderAheadError', {
+  minimumExpectedNum: EventSequenceNumber.EventSequenceNumber,
+  providedNum: EventSequenceNumber.EventSequenceNumber,
+  /** Generation number the client session should use for subsequent pushes */
+  // nextGeneration: Schema.Number,
+}) {}
+
+export const SyncError = Schema.Union(InvalidPushError, InvalidPullError)
+export type SyncError = typeof SyncError.Type

package/src/sync/index.ts

@@ -1,3 +1,6 @@
 export * from './ClientSessionSyncProcessor.ts'
+export * from './mock-sync-backend.ts'
 export * from './sync.ts'
+export { NetworkStatus } from './sync-backend.ts'
+export * from './transport-chunking.ts'
 export * from './validate-push-payload.ts'

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

@@ -0,0 +1,184 @@
+import type { Schema, Scope } from '@livestore/utils/effect'
+import { Effect, Mailbox, Option, Queue, Stream, SubscriptionRef } from '@livestore/utils/effect'
+import { UnexpectedError } from '../errors.ts'
+import { EventSequenceNumber, type LiveStoreEvent } from '../schema/mod.ts'
+import { InvalidPushError } from './errors.ts'
+import * as SyncBackend from './sync-backend.ts'
+import { validatePushPayload } from './validate-push-payload.ts'
+
+export interface MockSyncBackend {
+  pushedEvents: Stream.Stream<LiveStoreEvent.AnyEncodedGlobal>
+  connect: Effect.Effect<void>
+  disconnect: Effect.Effect<void>
+  makeSyncBackend: Effect.Effect<SyncBackend.SyncBackend, UnexpectedError, Scope.Scope>
+  advance: (...batch: LiveStoreEvent.AnyEncodedGlobal[]) => Effect.Effect<void>
+  /** Fail the next N push calls with an InvalidPushError (or custom error) */
+  failNextPushes: (
+    count: number,
+    error?: (batch: ReadonlyArray<LiveStoreEvent.AnyEncodedGlobal>) => Effect.Effect<never, InvalidPushError>,
+  ) => Effect.Effect<void>
+}
+
+export interface MockSyncBackendOptions {
+  /** Chunk size for non-live pulls; defaults to 100 */
+  nonLiveChunkSize?: number
+  /** Initial connected state; defaults to false */
+  startConnected?: boolean
+  // TODO add a "flaky" mode to simulate transient network / server failures for pull/push
+}
+
+export const makeMockSyncBackend = (
+  options?: MockSyncBackendOptions,
+): Effect.Effect<MockSyncBackend, UnexpectedError, Scope.Scope> =>
+  Effect.gen(function* () {
+    const syncEventSequenceNumberRef = { current: EventSequenceNumber.ROOT.global }
+    const syncPullQueue = yield* Queue.unbounded<LiveStoreEvent.AnyEncodedGlobal>()
+    const pushedEventsQueue = yield* Mailbox.make<LiveStoreEvent.AnyEncodedGlobal>()
+    const syncIsConnectedRef = yield* SubscriptionRef.make(options?.startConnected ?? false)
+    const allEventsRef: { current: LiveStoreEvent.AnyEncodedGlobal[] } = { current: [] }
+
+    const span = yield* Effect.currentSpan.pipe(Effect.orDie)
+
+    const semaphore = yield* Effect.makeSemaphore(1)
+
+    // TODO improve the API and implementation of simulating errors
+    const failCounterRef = yield* SubscriptionRef.make(0)
+    const failEffectRef = yield* SubscriptionRef.make<
+      ((batch: ReadonlyArray<LiveStoreEvent.AnyEncodedGlobal>) => Effect.Effect<never, InvalidPushError>) | undefined
+    >(undefined)
+
+    const makeSyncBackend = Effect.gen(function* () {
+      const nonLiveChunkSize = Math.max(1, options?.nonLiveChunkSize ?? 100)
+
+      // 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.
+      return SyncBackend.of<Schema.JsonValue>({
+        isConnected: syncIsConnectedRef,
+        connect: SubscriptionRef.set(syncIsConnectedRef, true),
+        ping: Effect.void,
+        pull: (cursor, options) =>
+          (options?.live
+            ? 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,
+                  })),
+                ),
+              )
+            : Stream.fromEffect(
+                Effect.sync(() => {
+                  const lastSeen = cursor.pipe(
+                    Option.match({
+                      onNone: () => EventSequenceNumber.ROOT.global,
+                      onSome: (_) => _.eventSequenceNumber,
+                    }),
+                  )
+                  // All events with seqNum greater than lastSeen
+                  const slice = allEventsRef.current.filter((e) => e.seqNum > lastSeen)
+                  // Split into configured chunk size
+                  const chunks: { events: LiveStoreEvent.AnyEncodedGlobal[]; remaining: number }[] = []
+                  for (let i = 0; i < slice.length; i += nonLiveChunkSize) {
+                    const end = Math.min(i + nonLiveChunkSize, slice.length)
+                    const remaining = Math.max(slice.length - end, 0)
+                    chunks.push({ events: slice.slice(i, end), remaining })
+                  }
+                  if (chunks.length === 0) {
+                    chunks.push({ events: [], remaining: 0 })
+                  }
+                  return chunks
+                }),
+              ).pipe(
+                Stream.flatMap((chunks) =>
+                  Stream.fromIterable(chunks).pipe(
+                    Stream.map(({ events, remaining }) => ({
+                      batch: events.map((eventEncoded) => ({ eventEncoded, metadata: Option.none() })),
+                      pageInfo: remaining > 0 ? SyncBackend.pageInfoMoreKnown(remaining) : SyncBackend.pageInfoNoMore,
+                    })),
+                  ),
+                ),
+              )
+          ).pipe(Stream.withSpan('MockSyncBackend:pull', { parent: span })),
+        push: (batch) =>
+          Effect.gen(function* () {
+            yield* validatePushPayload(batch, syncEventSequenceNumberRef.current)
+
+            const remaining = yield* SubscriptionRef.get(failCounterRef)
+            if (remaining > 0) {
+              const maybeFail = yield* SubscriptionRef.get(failEffectRef)
+              // decrement counter first
+              yield* SubscriptionRef.set(failCounterRef, remaining - 1)
+              if (maybeFail) {
+                return yield* maybeFail(batch)
+              }
+              return yield* new InvalidPushError({
+                cause: new UnexpectedError({ cause: new Error('MockSyncBackend: simulated push failure') }),
+              })
+            }
+
+            yield* Effect.sleep(10).pipe(Effect.withSpan('MockSyncBackend:push:sleep')) // Simulate network latency
+
+            yield* pushedEventsQueue.offerAll(batch)
+            yield* syncPullQueue.offerAll(batch)
+            allEventsRef.current = allEventsRef.current.concat(batch)
+
+            syncEventSequenceNumberRef.current = batch.at(-1)!.seqNum
+          }).pipe(
+            Effect.withSpan('MockSyncBackend:push', {
+              parent: span,
+              attributes: {
+                nums: batch.map((_) => _.seqNum),
+              },
+            }),
+            semaphore.withPermits(1),
+          ),
+        metadata: {
+          name: '@livestore/mock-sync',
+          description: 'Just a mock sync backend',
+        },
+        supports: {
+          pullPageInfoKnown: true,
+          pullLive: true,
+        },
+      })
+    })
+
+    const advance = (...batch: LiveStoreEvent.AnyEncodedGlobal[]) =>
+      Effect.gen(function* () {
+        syncEventSequenceNumberRef.current = batch.at(-1)!.seqNum
+        allEventsRef.current = allEventsRef.current.concat(batch)
+        yield* syncPullQueue.offerAll(batch)
+      }).pipe(
+        Effect.withSpan('MockSyncBackend:advance', {
+          parent: span,
+          attributes: { nums: batch.map((_) => _.seqNum) },
+        }),
+        semaphore.withPermits(1),
+      )
+
+    const connect = SubscriptionRef.set(syncIsConnectedRef, true)
+    const disconnect = SubscriptionRef.set(syncIsConnectedRef, false)
+
+    const failNextPushes = (
+      count: number,
+      error?: (batch: ReadonlyArray<LiveStoreEvent.AnyEncodedGlobal>) => Effect.Effect<never, InvalidPushError>,
+    ) =>
+      Effect.gen(function* () {
+        yield* SubscriptionRef.set(failCounterRef, count)
+        yield* SubscriptionRef.set(failEffectRef, error)
+      })
+
+    return {
+      syncEventSequenceNumberRef,
+      syncPullQueue,
+      pushedEvents: Mailbox.toStream(pushedEventsQueue),
+      connect,
+      disconnect,
+      makeSyncBackend,
+      advance,
+      failNextPushes,
+    }
+  }).pipe(Effect.withSpanScoped('MockSyncBackend'))

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

@@ -1,6 +1,5 @@
 import { EventSequenceNumber } from '../../schema/mod.ts'
 import { replacesFacts } from './facts.ts'
-import { graphologyDag } from './graphology_.ts'
 import type { HistoryDag } from './history-dag-common.ts'
 import { emptyHistoryDag } from './history-dag-common.ts'
 
@@ -17,7 +16,7 @@ export const compactEvents = (inputDag: HistoryDag): { dag: HistoryDag; compacte
   const dag = inputDag.copy()
   const compactedEventCount = 0
 
-  const orderedEventSequenceNumberStrs = graphologyDag.topologicalSort(dag).reverse()
+  const orderedEventSequenceNumberStrs = dag.topologicalNodeIds().reverse()
 
   // drop root
   orderedEventSequenceNumberStrs.pop()
@@ -116,7 +115,7 @@ const findSubDagsInHistory = (
   const subDags: HistoryDag[] = []
   const allOutsideDependencies: string[][] = []
 
-  for (const eventNumStr of graphologyDag.topologicalSort(inputDag)) {
+  for (const eventNumStr of inputDag.topologicalNodeIds()) {
     if (eventNumStr === upToExclEventSequenceNumberStr) {
       break
     }
@@ -189,8 +188,8 @@ const dagReplacesDag = (dagA: HistoryDag, dagB: HistoryDag): boolean => {
   }
 
   // TODO write tests that covers deterministic order when DAGs have branches
-  const nodeEntriesA = graphologyDag.topologicalSort(dagA).map((nodeId) => dagA.getNodeAttributes(nodeId))
-  const nodeEntriesB = graphologyDag.topologicalSort(dagB).map((nodeId) => dagB.getNodeAttributes(nodeId))
+  const nodeEntriesA = dagA.topologicalNodeIds().map((nodeId) => dagA.getNodeAttributes(nodeId))
+  const nodeEntriesB = dagB.topologicalNodeIds().map((nodeId) => dagB.getNodeAttributes(nodeId))
 
   for (let i = 0; i < nodeEntriesA.length; i++) {
     const nodeA = nodeEntriesA[i]!

package/src/sync/next/facts.ts

@@ -1,5 +1,4 @@
 import { notYetImplemented } from '@livestore/utils'
-
 import type {
   EventDefFactInput,
   EventDefFacts,
@@ -8,7 +7,6 @@ import type {
   FactsCallback,
 } from '../../schema/EventDef.ts'
 import type * as EventSequenceNumber from '../../schema/EventSequenceNumber.ts'
-import { graphologyDag } from './graphology_.ts'
 import { EMPTY_FACT_VALUE, type HistoryDag, type HistoryDagNode } from './history-dag-common.ts'
 
 export const factsSnapshotForEvents = (
@@ -34,7 +32,7 @@ export const factsSnapshotForDag = (
 ): EventDefFactsSnapshot => {
   const facts = new Map<string, any>()
 
-  const orderedEventSequenceNumberStrs = graphologyDag.topologicalSort(dag)
+  const orderedEventSequenceNumberStrs = dag.topologicalNodeIds()
 
   for (let i = 0; i < orderedEventSequenceNumberStrs.length; i++) {
     const event = dag.getNodeAttributes(orderedEventSequenceNumberStrs[i]!)

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

@@ -1,30 +1,11 @@
+import { shouldNeverHappen } from '@livestore/utils'
+import { Graph } from '@livestore/utils/effect'
 import type { EventDefFactsGroup } from '../../schema/EventDef.ts'
 import * as EventSequenceNumber from '../../schema/EventSequenceNumber.ts'
-import { graphology } from './graphology_.ts'
 
 export const connectionTypeOptions = ['parent', 'facts'] as const
 export type ConnectionType = (typeof connectionTypeOptions)[number]
 
-/**
- * Eventlog represented as a multi-DAG including edges for
- * - total-order (parent) relationships
- * - dependency (requires/reads facts) relationships
- */
-export type HistoryDag = graphology.IGraph<HistoryDagNode, { type: ConnectionType }>
-
-export const emptyHistoryDag = (): HistoryDag =>
-  new graphology.Graph({
-    allowSelfLoops: false,
-    multi: true,
-    type: 'directed',
-  })
-
-// TODO consider making `ROOT_ID` parent to itself
-export const rootParentNum = EventSequenceNumber.make({
-  global: EventSequenceNumber.ROOT.global - 1,
-  client: EventSequenceNumber.clientDefault,
-})
-
 export type HistoryDagNode = {
   seqNum: EventSequenceNumber.EventSequenceNumber
   parentSeqNum: EventSequenceNumber.EventSequenceNumber
@@ -37,6 +18,276 @@ export type HistoryDagNode = {
   sessionId: string | undefined
 }
 
+type HistoryDagEdgeAttributes = { type: ConnectionType }
+
+type HistoryDagEdgeEntry = {
+  edge: Graph.EdgeIndex
+  source: string
+  target: string
+  attributes: HistoryDagEdgeAttributes
+}
+
+type HistoryDagOptions = {
+  allowSelfLoops: boolean
+}
+
+const defaultOptions: HistoryDagOptions = {
+  allowSelfLoops: false,
+}
+
+const cloneFactsGroup = (factsGroup: EventDefFactsGroup): EventDefFactsGroup => ({
+  depRead: new Map(factsGroup.depRead),
+  depRequire: new Map(factsGroup.depRequire),
+  modifySet: new Map(factsGroup.modifySet),
+  modifyUnset: new Map(factsGroup.modifyUnset),
+})
+
+const cloneHistoryDagNode = (node: HistoryDagNode): HistoryDagNode => ({
+  ...node,
+  // Copy the event sequence numbers to avoid accidental aliasing
+  parentSeqNum: { ...node.parentSeqNum },
+  seqNum: { ...node.seqNum },
+  // Facts are represented via maps which should not be shared across DAG copies
+  factsGroup: cloneFactsGroup(node.factsGroup),
+})
+
+/**
+ * Mutable DAG wrapper that retains the previous string-based node ids API
+ * while delegating storage and algorithms to Effect's graph module.
+ */
+export class HistoryDag {
+  private readonly options: HistoryDagOptions
+  private readonly idToIndex: Map<string, Graph.NodeIndex>
+  private readonly indexToId: Map<Graph.NodeIndex, string>
+  private readonly graph: Graph.MutableDirectedGraph<HistoryDagNode, HistoryDagEdgeAttributes>
+
+  private constructor({
+    graph,
+    idToIndex,
+    indexToId,
+    options,
+  }: {
+    graph: Graph.MutableDirectedGraph<HistoryDagNode, HistoryDagEdgeAttributes>
+    idToIndex?: Map<string, Graph.NodeIndex>
+    indexToId?: Map<Graph.NodeIndex, string>
+    options?: Partial<HistoryDagOptions>
+  }) {
+    this.graph = graph
+    this.options = { ...defaultOptions, ...options }
+    this.idToIndex = idToIndex ? new Map(idToIndex) : new Map()
+    this.indexToId = indexToId ? new Map(indexToId) : new Map()
+  }
+
+  static create(options?: Partial<HistoryDagOptions>): HistoryDag {
+    const graph = Graph.beginMutation(Graph.directed<HistoryDagNode, HistoryDagEdgeAttributes>())
+    return options ? new HistoryDag({ graph, options }) : new HistoryDag({ graph })
+  }
+
+  copy(): 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}`)
+      clone.addNode(id, cloneHistoryDagNode(node))
+    }
+
+    for (const edge of this.graph.edges.values()) {
+      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 })
+    }
+
+    return clone
+  }
+
+  topologicalNodeIds(): Array<string> {
+    const walker = Graph.topo(this.graph)
+    const indices = Array.from(Graph.indices(walker))
+    return indices.map((index) => this.indexToId.get(index) ?? shouldNeverHappen(`Missing node id for index ${index}`))
+  }
+
+  addNode(id: string, attributes: HistoryDagNode): void {
+    if (this.idToIndex.has(id)) {
+      shouldNeverHappen(`HistoryDag node ${id} already exists`)
+    }
+
+    const nodeIndex = Graph.addNode(this.graph, attributes)
+    this.idToIndex.set(id, nodeIndex)
+    this.indexToId.set(nodeIndex, id)
+  }
+
+  hasNode(id: string): boolean {
+    return this.idToIndex.has(id)
+  }
+
+  getNodeAttributes(id: string): HistoryDagNode {
+    const index = this.idToIndex.get(id)
+    if (index === undefined) {
+      return shouldNeverHappen(`HistoryDag node ${id} not found`)
+    }
+
+    const node = this.graph.nodes.get(index)
+    return node ?? shouldNeverHappen(`HistoryDag node data missing for ${id}`)
+  }
+
+  nodes(): IterableIterator<string> {
+    return this.idToIndex.keys()
+  }
+
+  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}`)
+        yield { key: id, attributes }
+      }
+    }.call(this)
+  }
+
+  addEdge(sourceId: string, targetId: string, attributes: HistoryDagEdgeAttributes): Graph.EdgeIndex {
+    if (this.options.allowSelfLoops === false && sourceId === targetId) {
+      return shouldNeverHappen('HistoryDag self-loops are disabled')
+    }
+
+    const sourceIndex = this.idToIndex.get(sourceId)
+    const targetIndex = this.idToIndex.get(targetId)
+
+    if (sourceIndex === undefined || targetIndex === undefined) {
+      return shouldNeverHappen(`HistoryDag edge references unknown nodes: ${sourceId} -> ${targetId}`)
+    }
+
+    return Graph.addEdge(this.graph, sourceIndex, targetIndex, attributes)
+  }
+
+  edges(sourceId: string, targetId: string): Array<Graph.EdgeIndex> {
+    const sourceIndex = this.idToIndex.get(sourceId)
+    const targetIndex = this.idToIndex.get(targetId)
+
+    if (sourceIndex === undefined || targetIndex === undefined) {
+      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
+    })
+  }
+
+  inEdges(id: string): Array<Graph.EdgeIndex> {
+    const index = this.idToIndex.get(id)
+    if (index === undefined) {
+      return []
+    }
+    const incoming = this.graph.reverseAdjacency.get(index)
+    return incoming ? [...incoming] : []
+  }
+
+  outboundEdgeEntries(id: string): Array<HistoryDagEdgeEntry> {
+    const index = this.idToIndex.get(id)
+    if (index === undefined) {
+      return []
+    }
+
+    const adjacency = this.graph.adjacency.get(index)
+    if (adjacency === undefined) {
+      return []
+    }
+
+    return adjacency
+      .map((edgeIndex) => this.edgeEntry(edgeIndex))
+      .filter((entry): entry is HistoryDagEdgeEntry => entry !== undefined)
+  }
+
+  inboundEdgeEntries(id: string): Array<HistoryDagEdgeEntry> {
+    const index = this.idToIndex.get(id)
+    if (index === undefined) {
+      return []
+    }
+
+    const adjacency = this.graph.reverseAdjacency.get(index)
+    if (adjacency === undefined) {
+      return []
+    }
+
+    return adjacency
+      .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`)
+  }
+
+  getEdgeAttribute<TKey extends keyof HistoryDagEdgeAttributes>(
+    edgeIndex: Graph.EdgeIndex,
+    key: TKey,
+  ): HistoryDagEdgeAttributes[TKey] {
+    const attributes = this.getEdgeAttributes(edgeIndex)
+    return attributes[key]
+  }
+
+  source(edgeIndex: Graph.EdgeIndex): string {
+    const edge = this.graph.edges.get(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 targetId = edge !== undefined ? this.indexToId.get(edge.target) : undefined
+    return targetId ?? shouldNeverHappen(`HistoryDag edge ${edgeIndex} missing target`)
+  }
+
+  dropNode(id: string): void {
+    const index = this.idToIndex.get(id)
+    if (index === undefined) {
+      return
+    }
+
+    Graph.removeNode(this.graph, index)
+    this.idToIndex.delete(id)
+    this.indexToId.delete(index)
+  }
+
+  get size(): number {
+    return this.idToIndex.size
+  }
+
+  private edgeEntry(edgeIndex: Graph.EdgeIndex): HistoryDagEdgeEntry | undefined {
+    const edge = this.graph.edges.get(edgeIndex)
+    if (edge === undefined) {
+      return undefined
+    }
+
+    const source = this.indexToId.get(edge.source)
+    const target = this.indexToId.get(edge.target)
+
+    if (source === undefined || target === undefined) {
+      return undefined
+    }
+
+    return {
+      edge: edgeIndex,
+      source,
+      target,
+      attributes: edge.data,
+    }
+  }
+}
+
+export const emptyHistoryDag = (): HistoryDag => HistoryDag.create({ allowSelfLoops: false })
+
+// TODO consider making `ROOT_ID` parent to itself
+export const rootParentNum = EventSequenceNumber.make({
+  global: EventSequenceNumber.ROOT.global - 1,
+  client: EventSequenceNumber.clientDefault,
+})
+
 export const rootEventNode: HistoryDagNode = {
   seqNum: EventSequenceNumber.ROOT,
   parentSeqNum: rootParentNum,

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

@@ -18,7 +18,9 @@ export const historyDagFromNodes = (dagNodes: HistoryDagNode[], options?: { skip
 
   const dag = emptyHistoryDag()
 
-  dagNodes.forEach((node) => dag.addNode(EventSequenceNumber.toString(node.seqNum), node))
+  dagNodes.forEach((node) => {
+    dag.addNode(EventSequenceNumber.toString(node.seqNum), node)
+  })
 
   dagNodes.forEach((node) => {
     if (EventSequenceNumber.toString(node.parentSeqNum) !== EventSequenceNumber.toString(rootParentNum)) {

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

@@ -0,0 +1,22 @@
+import { Effect, KeyValueStore, Option } from '@livestore/utils/effect'
+import { UnexpectedError } from '../errors.ts'
+
+export const makeBackendIdHelper = Effect.gen(function* () {
+  const kv = yield* KeyValueStore.KeyValueStore
+
+  const backendIdKey = `backendId`
+  const backendIdRef = { current: yield* kv.get(backendIdKey).pipe(UnexpectedError.mapToUnexpectedError) }
+
+  const setBackendId = (backendId: string) =>
+    Effect.gen(function* () {
+      if (backendIdRef.current._tag === 'None' || backendIdRef.current.value !== backendId) {
+        backendIdRef.current = Option.some(backendId)
+        yield* kv.set(backendIdKey, backendId)
+      }
+    }).pipe(UnexpectedError.mapToUnexpectedError)
+
+  return {
+    lazySet: setBackendId,
+    get: () => backendIdRef.current,
+  }
+})