@livestore/webmesh 0.4.0-dev.22 → 0.4.0-dev.23

package/src/node.test.ts

@@ -85,8 +85,8 @@ const maybeDelay =
       ? effect
       : Effect.sleep(delay).pipe(Effect.withSpan(`${label}:delay(${delay})`), Effect.andThen(effect))
 
-const testTimeout = IS_CI ? 30_000 : 1000
-const propTestTimeout = IS_CI ? 60_000 : 20_000
+const testTimeout = IS_CI === true ? 30_000 : 1000
+const propTestTimeout = IS_CI === true ? 60_000 : 20_000
 
 // TODO also make work without `Vitest.scopedLive` (i.e. with `Vitest.scoped`)
 // probably requires controlling the clocks
@@ -200,7 +200,7 @@ Vitest.describe('webmesh node', { timeout: testTimeout }, () => {
             yield* Effect.promise(() => nodeX.debug.requestTopology(100))
           }).pipe(
             Vitest.withTestCtx(test, {
-              suffix: `delayX=${delayX} delayY=${delayY} connectDelay=${connectDelay} channelType=${channelType} nodeNames=${nodeNames}`,
+              suffix: `delayX=${delayX} delayY=${delayY} connectDelay=${connectDelay} channelType=${channelType} nodeNames=${nodeNames.join(',')}`,
             }),
           ),
         // { fastCheck: { numRuns: 20 } },
@@ -231,8 +231,7 @@ Vitest.describe('webmesh node', { timeout: testTimeout }, () => {
             // TODO also optionally delay the edge
             yield* connectNodes(nodeA, nodeB)
 
-            const waitForBToBeOffline =
-              waitForOfflineDelay === undefined ? undefined : yield* Deferred.make<void, never>()
+            const waitForBToBeOffline = waitForOfflineDelay === undefined ? undefined : yield* Deferred.make<void>()
 
             const nodeACode = Effect.gen(function* () {
               const channelAToB = yield* createChannel(nodeA, 'B', { mode })
@@ -392,7 +391,7 @@ Vitest.describe('webmesh node', { timeout: testTimeout }, () => {
             yield* Effect.all([nodeXCode, nodeYCode], { concurrency: 'unbounded' })
           }).pipe(
             Vitest.withTestCtx(test, {
-              suffix: `channelType=${channelType} nodeNames=${nodeNames}`,
+              suffix: `channelType=${channelType} nodeNames=${nodeNames.join(',')}`,
             }),
           ),
         { fastCheck: { numRuns: 10 } },
@@ -622,6 +621,270 @@ Vitest.describe('webmesh node', { timeout: testTimeout }, () => {
       }).pipe(Vitest.withTestCtx(test)),
     )
 
+    /**
+     * Pattern test: ACK sending must not block message processing.
+     *
+     * This test documents the pattern where ACKs are sent fire-and-forget using `Effect.forkScoped`
+     * to avoid blocking the message processing loop.
+     *
+     * Background: Before the fix, ACKs were sent with `await` which blocked message processing.
+     * This caused heartbeat timeouts in devtools after ~30 seconds ("Connection to app lost").
+     *
+     * Note: This unit test passes both with and without the fix because in-memory channels
+     * complete ACK sends instantly. The actual regression test is the Playwright test
+     * `node-adapter-timeout.play.ts` which uses real network conditions.
+     *
+     * This test exists to:
+     * 1. Document the expected pattern (high message throughput via proxy channels)
+     * 2. Verify the pattern works correctly with forked ACKs
+     * 3. Serve as a reference for the fix in proxy-channel.ts
+     */
+    Vitest.scopedLive('ACK sending should not block message processing', (test) =>
+      Effect.gen(function* () {
+        const nodeA = yield* makeMeshNode('A')
+        const nodeB = yield* makeMeshNode('B')
+        const nodeC = yield* makeMeshNode('C')
+
+        yield* connectNodesViaBroadcastChannel(nodeA, nodeB)
+        yield* connectNodesViaBroadcastChannel(nodeB, nodeC)
+
+        // Send many messages to stress the ACK handling
+        const messageCount = 10
+
+        const nodeACode = Effect.gen(function* () {
+          const channelAToC = yield* createChannel(nodeA, 'C', { mode: 'proxy' })
+          // Send multiple messages concurrently
+          yield* Effect.forEach(
+            Chunk.makeBy(messageCount, (i) => ({ message: `A${i}` })),
+            channelAToC.send,
+            { concurrency: 'unbounded' },
+          )
+          // Receive responses
+          const responses = yield* channelAToC.listen.pipe(
+            Stream.flatten(),
+            Stream.take(messageCount),
+            Stream.runCollect,
+          )
+          expect(Chunk.size(responses)).toBe(messageCount)
+        })
+
+        const nodeCCode = Effect.gen(function* () {
+          const channelCToA = yield* createChannel(nodeC, 'A', { mode: 'proxy' })
+          // Send multiple messages concurrently
+          yield* Effect.forEach(
+            Chunk.makeBy(messageCount, (i) => ({ message: `C${i}` })),
+            channelCToA.send,
+            { concurrency: 'unbounded' },
+          )
+          // Receive responses
+          const responses = yield* channelCToA.listen.pipe(
+            Stream.flatten(),
+            Stream.take(messageCount),
+            Stream.runCollect,
+          )
+          expect(Chunk.size(responses)).toBe(messageCount)
+        })
+
+        yield* Effect.all([nodeACode, nodeCCode], { concurrency: 'unbounded' })
+      }).pipe(Vitest.withTestCtx(test)),
+    )
+
+    Vitest.describe('ACK forkScoped regression tests', { timeout: 10_000 }, () => {
+      /**
+       * REGRESSION TEST: ACK sends must be forked (non-blocking) to allow message processing to continue.
+       *
+       * This test uses simulation parameters to inject a delay BEFORE the ACK send.
+       * It then measures when messages arrive at the receiver's listen queue.
+       *
+       * With the fix (Effect.forkScoped):
+       * - ACK send is forked in the background
+       * - Message is added to listen queue IMMEDIATELY (before ACK send completes)
+       * - Multiple messages arrive close together regardless of ACK delay
+       *
+       * Without the fix (blocking yield*):
+       * - ACK send blocks the processing loop
+       * - Message is added to listen queue AFTER ACK send completes
+       * - Messages arrive spread out by the ACK delay
+       *
+       * To verify this test catches the regression:
+       * 1. Temporarily change `Effect.forkScoped` to `yield*` in proxy-channel.ts:319
+       * 2. Run this test - it should FAIL because messages arrive too slowly
+       * 3. Revert the change - test should PASS
+       */
+      /**
+       * This test verifies the fix works: messages should arrive at the listen queue
+       * without being blocked by slow ACK sends. We measure how long it takes to receive
+       * all messages - with forked ACKs it should be fast, with blocking ACKs it would be slow.
+       */
+      Vitest.scopedLive('messages arrive in listen queue without waiting for ACK send', (test) =>
+        Effect.gen(function* () {
+          const ACK_DELAY_MS = 50
+          const MESSAGE_COUNT = 5
+
+          const nodeA = yield* makeMeshNode('A')
+          const nodeB = yield* makeMeshNode('B')
+
+          yield* connectNodesViaMessageChannel(nodeA, nodeB)
+
+          const receivedMessages: string[] = []
+
+          const senderCode = Effect.gen(function* () {
+            const channelAToB = yield* nodeA.makeChannel({
+              target: 'B',
+              channelName: 'test-ack-timing',
+              schema: ExampleSchema,
+              mode: 'proxy',
+              timeout: 3000,
+            })
+
+            // Send all messages concurrently - this is key!
+            // With forked ACKs, all messages get processed immediately at receiver
+            // With blocking ACKs, messages would be processed one at a time with delays
+            yield* Effect.forEach(
+              Chunk.makeBy(MESSAGE_COUNT, (i) => ({ message: `msg${i}` })),
+              channelAToB.send,
+              { concurrency: 'unbounded' },
+            )
+          })
+
+          const receiverCode = Effect.gen(function* () {
+            const channelBToA = yield* nodeB.makeChannel({
+              target: 'A',
+              channelName: 'test-ack-timing',
+              schema: ExampleSchema,
+              mode: 'proxy',
+              timeout: 3000,
+              // KEY: Inject delay BEFORE ACK send
+              // With forkScoped: message arrives in queue immediately, then ACK is sent in background
+              // Without forkScoped: message waits for ACK delay before being added to queue
+              simulation: {
+                onPayload: {
+                  beforeAckSend: ACK_DELAY_MS,
+                  afterAckFork: 0,
+                  afterListenQueueOffer: 0,
+                },
+              },
+            })
+
+            yield* channelBToA.listen.pipe(
+              Stream.flatten(),
+              Stream.tap((msg) =>
+                Effect.sync(() => {
+                  receivedMessages.push(msg.message)
+                }),
+              ),
+              Stream.take(MESSAGE_COUNT),
+              Stream.runDrain,
+            )
+          })
+
+          const startTime = Date.now()
+          yield* Effect.all([senderCode, receiverCode], { concurrency: 'unbounded' })
+          const elapsed = Date.now() - startTime
+
+          console.log(`[regression-test-1] Received ${receivedMessages.length} messages in ${elapsed}ms`)
+          console.log(`[regression-test-1] Messages: ${receivedMessages.join(', ')}`)
+
+          expect(receivedMessages.length).toBe(MESSAGE_COUNT)
+
+          // With forked ACKs, elapsed time should be much less than MESSAGE_COUNT * ACK_DELAY_MS
+          // because ACKs don't block message processing
+          const blockingTime = MESSAGE_COUNT * ACK_DELAY_MS
+          console.log(`[regression-test-1] Elapsed: ${elapsed}ms, Blocking estimate: ${blockingTime}ms`)
+
+          // The test passes if messages arrive faster than they would with blocking ACKs
+          // Allow some margin for test overhead (2x faster than blocking)
+          if (elapsed > blockingTime / 2) {
+            throw new Error(
+              `REGRESSION DETECTED: Processing took ${elapsed}ms, blocking estimate: ${blockingTime}ms. ` +
+                `With forked ACKs, processing should be much faster. ` +
+                `Check that proxy-channel.ts uses Effect.forkScoped for ACK sends.`,
+            )
+          }
+        }).pipe(Vitest.withTestCtx(test)),
+      )
+
+      /**
+       * Additional test: Verify message processing continues during slow ACK sends.
+       *
+       * This test sends multiple messages concurrently and verifies they're all
+       * processed even when ACK sends are slow.
+       */
+      Vitest.scopedLive('concurrent messages processed despite slow ACK sends', (test) =>
+        Effect.gen(function* () {
+          const ACK_DELAY_MS = 50
+          const MESSAGE_COUNT = 5
+
+          const nodeA = yield* makeMeshNode('A')
+          const nodeB = yield* makeMeshNode('B')
+
+          yield* connectNodesViaMessageChannel(nodeA, nodeB)
+
+          const receivedMessages: string[] = []
+
+          const senderCode = Effect.gen(function* () {
+            const channelAToB = yield* nodeA.makeChannel({
+              target: 'B',
+              channelName: 'test-concurrent',
+              schema: ExampleSchema,
+              mode: 'proxy',
+              timeout: 3000,
+            })
+
+            // Send all messages concurrently
+            yield* Effect.forEach(
+              Chunk.makeBy(MESSAGE_COUNT, (i) => ({ message: `msg${i}` })),
+              channelAToB.send,
+              { concurrency: 'unbounded' },
+            )
+          })
+
+          const receiverCode = Effect.gen(function* () {
+            const channelBToA = yield* nodeB.makeChannel({
+              target: 'A',
+              channelName: 'test-concurrent',
+              schema: ExampleSchema,
+              mode: 'proxy',
+              timeout: 3000,
+              simulation: {
+                onPayload: {
+                  beforeAckSend: ACK_DELAY_MS,
+                  afterAckFork: 0,
+                  afterListenQueueOffer: 0,
+                },
+              },
+            })
+
+            yield* channelBToA.listen.pipe(
+              Stream.flatten(),
+              Stream.tap((msg) =>
+                Effect.sync(() => {
+                  receivedMessages.push(msg.message)
+                }),
+              ),
+              Stream.take(MESSAGE_COUNT),
+              Stream.runDrain,
+            )
+          })
+
+          const startTime = Date.now()
+          yield* Effect.all([senderCode, receiverCode], { concurrency: 'unbounded' })
+          const elapsed = Date.now() - startTime
+
+          console.log(`[regression-test] Received ${receivedMessages.length} messages in ${elapsed}ms`)
+          console.log(`[regression-test] Messages: ${receivedMessages.join(', ')}`)
+
+          // All messages should be received
+          expect(receivedMessages.length).toBe(MESSAGE_COUNT)
+
+          // With forked ACKs, elapsed time should be much less than MESSAGE_COUNT * ACK_DELAY_MS
+          // because ACKs don't block message processing
+          const blockingTime = MESSAGE_COUNT * ACK_DELAY_MS
+          console.log(`[regression-test] Elapsed: ${elapsed}ms, Blocking estimate: ${blockingTime}ms`)
+        }).pipe(Vitest.withTestCtx(test)),
+      )
+    })
+
     Vitest.scopedLive('should fail with timeout due to missing edge', (test) =>
       Effect.gen(function* () {
         const nodeA = yield* makeMeshNode('A')
@@ -944,7 +1207,7 @@ Vitest.describe('webmesh node', { timeout: testTimeout }, () => {
             const nodeB = yield* makeMeshNode('B')
             const nodeC = yield* makeMeshNode('C')
 
-            const mode = channelType.includes('proxy') ? 'proxy' : 'direct'
+            const mode = channelType.includes('proxy') === true ? 'proxy' : 'direct'
             const connect = channelType === 'direct' ? connectNodesViaMessageChannel : connectNodesViaBroadcastChannel
             yield* connect(nodeA, nodeB).pipe(maybeDelay(delayConnectAB, 'delayConnectAB'))
             yield* connect(nodeB, nodeC).pipe(maybeDelay(delayConnectBC, 'delayConnectBC'))

package/src/node.ts

@@ -16,7 +16,7 @@ import {
 } from '@livestore/utils/effect'
 
 import { makeDirectChannel } from './channel/direct-channel.ts'
-import { makeProxyChannel } from './channel/proxy-channel.ts'
+import { makeProxyChannel, type ProxyChannelSimulationParams } from './channel/proxy-channel.ts'
 import type { ChannelKey, ListenForChannelResult, MeshNodeName, MessageQueueItem, ProxyQueueItem } from './common.ts'
 import { EdgeAlreadyExistsError, packetAsOtelAttributes } from './common.ts'
 import * as WebmeshSchema from './mesh-schema.ts'
@@ -114,6 +114,11 @@ export interface MeshNode<TName extends MeshNodeName = MeshNodeName> {
      * @default false
      */
     closeExisting?: boolean
+    /**
+     * Optional simulation parameters for testing timing-sensitive behavior.
+     * Only used when mode is 'proxy'.
+     */
+    simulation?: ProxyChannelSimulationParams
   }) => Effect.Effect<WebChannel.WebChannel<MsgListen, MsgSend>, never, Scope.Scope>
 
   listenForChannel: Stream.Stream<ListenForChannelResult>
@@ -173,7 +178,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
         (packet._tag === 'DirectChannelRequest' &&
           (edgeChannels.size === 0 || // Either if direct edge does not support transferables ...
             edgeChannels.get(packet.target)?.channel.supportsTransferables === false)) || // ... or if no forward-edges support transferables
-        ![...edgeChannels.values()].some((c) => c.channel.supportsTransferables === true)
+        [...edgeChannels.values()].some((c) => c.channel.supportsTransferables) === false
       ) {
         return WebmeshSchema.DirectChannelResponseNoTransferables.make({
           reqId: packet.id,
@@ -187,13 +192,14 @@ export const makeMeshNode = <TName extends MeshNodeName>(
           hops: [],
         })
       }
+      return undefined
     }
 
     const sendPacket = (packet: typeof WebmeshSchema.Packet.Type) =>
       Effect.gen(function* () {
         // yield* Effect.log(`${nodeName}: sendPacket:${packet._tag} [${packet.id}]`)
 
-        if (Schema.is(WebmeshSchema.NetworkEdgeAdded)(packet)) {
+        if (Schema.is(WebmeshSchema.NetworkEdgeAdded)(packet) === true) {
           yield* Effect.spanEvent('NetworkEdgeAdded', { packet, nodeName })
           yield* PubSub.publish(newEdgeAvailablePubSub, packet.target)
 
@@ -205,7 +211,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
           return
         }
 
-        if (Schema.is(WebmeshSchema.BroadcastChannelPacket)(packet)) {
+        if (Schema.is(WebmeshSchema.BroadcastChannelPacket)(packet) === true) {
           const edgesToForwardTo = Array.from(edgeChannels)
             .filter(([name]) => !packet.hops.includes(name))
             .map(([_, con]) => con.channel)
@@ -231,7 +237,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
           return
         }
 
-        if (Schema.is(WebmeshSchema.NetworkTopologyRequest)(packet)) {
+        if (Schema.is(WebmeshSchema.NetworkTopologyRequest)(packet) === true) {
           if (packet.source !== nodeName) {
             const backEdgeName =
               packet.hops.at(-1) ?? shouldNeverHappen(`${nodeName}: Expected hops for packet`, packet)
@@ -265,7 +271,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
           return
         }
 
-        if (Schema.is(WebmeshSchema.NetworkTopologyResponse)(packet)) {
+        if (Schema.is(WebmeshSchema.NetworkTopologyResponse)(packet) === true) {
           if (packet.source === nodeName) {
             const topologyRequestItem = topologyRequestsMap.get(packet.reqId)!
             topologyRequestItem.set(packet.nodeName, new Set(packet.edges))
@@ -289,7 +295,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
         }
 
         // We have a direct edge to the target node
-        if (edgeChannels.has(packet.target)) {
+        if (edgeChannels.has(packet.target) === true) {
           const edgeChannel = edgeChannels.get(packet.target)!.channel
           const hops = packet.source === nodeName ? [] : [...packet.hops, nodeName]
           yield* Effect.annotateCurrentSpan({ hasDirectEdge: true })
@@ -325,7 +331,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
             .map(([name, con]) => ({ name, channel: con.channel }))
 
           // TODO if hops-depth=0, we should fail right away with no route found
-          if (hops.length === 0 && edgesToForwardTo.length === 0 && LS_DEV) {
+          if (hops.length === 0 && edgesToForwardTo.length === 0 && LS_DEV === true) {
             yield* Effect.logWarning(nodeName, 'no route found to', packet.target, packet._tag, 'TODO handle better')
             // TODO return a expected failure
           }
@@ -348,8 +354,8 @@ export const makeMeshNode = <TName extends MeshNodeName>(
 
     const addEdge: MeshNode['addEdge'] = ({ target: targetNodeName, edgeChannel, replaceIfExists = false }) =>
       Effect.gen(function* () {
-        if (edgeChannels.has(targetNodeName)) {
-          if (replaceIfExists) {
+        if (edgeChannels.has(targetNodeName) === true) {
+          if (replaceIfExists === true) {
             yield* removeEdge(targetNodeName).pipe(Effect.orDie)
           } else {
             return yield* new EdgeAlreadyExistsError({ target: targetNodeName })
@@ -365,7 +371,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
 
               // console.debug(nodeName, 'recv', packet._tag, packet.source, packet.target)
 
-              if (handledPacketIds.has(packet.id)) return
+              if (handledPacketIds.has(packet.id) === true) return
               handledPacketIds.add(packet.id)
 
               switch (packet._tag) {
@@ -380,7 +386,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
                   if (packet.target === nodeName) {
                     const channelKey = `target:${packet.source}, channelName:${packet.channelName}` satisfies ChannelKey
 
-                    if (!channelMap.has(channelKey)) {
+                    if (channelMap.has(channelKey) === false) {
                       const channelQueue = yield* Queue.unbounded<MessageQueueItem | ProxyQueueItem>().pipe(
                         Effect.acquireRelease(Queue.shutdown),
                       )
@@ -400,9 +406,9 @@ export const makeMeshNode = <TName extends MeshNodeName>(
                           Effect.orDie,
                         )
 
-                    if (Schema.is(WebmeshSchema.ProxyChannelPacket)(packet)) {
+                    if (Schema.is(WebmeshSchema.ProxyChannelPacket)(packet) === true) {
                       yield* Queue.offer(channelQueue, { packet, respondToSender })
-                    } else if (Schema.is(WebmeshSchema.DirectChannelPacket)(packet)) {
+                    } else if (Schema.is(WebmeshSchema.DirectChannelPacket)(packet) === true) {
                       yield* Queue.offer(channelQueue, { packet, respondToSender })
                     }
 
@@ -414,7 +420,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
                       })
                     }
                   } else {
-                    if (Schema.is(WebmeshSchema.DirectChannelPacket)(packet)) {
+                    if (Schema.is(WebmeshSchema.DirectChannelPacket)(packet) === true) {
                       const noTransferableResponse = checkTransferableEdges(packet)
                       if (noTransferableResponse !== undefined) {
                         yield* Effect.spanEvent(`No transferable edges found for ${packet.source}→${packet.target}`)
@@ -455,7 +461,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
 
     const removeEdge: MeshNode['removeEdge'] = (targetNodeName) =>
       Effect.gen(function* () {
-        if (!edgeChannels.has(targetNodeName)) {
+        if (edgeChannels.has(targetNodeName) === false) {
           return yield* new Cause.NoSuchElementException(`No edge found for ${targetNodeName}`)
         }
 
@@ -477,15 +483,16 @@ export const makeMeshNode = <TName extends MeshNodeName>(
       mode,
       timeout = Duration.seconds(1),
       closeExisting = false,
+      simulation,
     }) =>
       Effect.gen(function* () {
         const schema = WebChannel.mapSchema(inputSchema)
         const channelKey = `target:${target}, channelName:${channelName}` satisfies ChannelKey
 
-        if (channelMap.has(channelKey)) {
+        if (channelMap.has(channelKey) === true) {
           const existingChannel = channelMap.get(channelKey)!.debugInfo?.channel
-          if (existingChannel) {
-            if (closeExisting) {
+          if (existingChannel !== undefined) {
+            if (closeExisting === true) {
               yield* existingChannel.shutdown
               channelMap.delete(channelKey)
             } else {
@@ -546,6 +553,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
             schema,
             queue: channelQueue,
             sendPacket,
+            ...(simulation !== undefined ? { simulation } : {}),
           })
 
           channelMap.set(channelKey, { queue: channelQueue, debugInfo: { channel, target } })
@@ -564,7 +572,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
     // TODO also provide a way to allow for reconnects
     let listenAlreadyStarted = false
     const listenForChannel: MeshNode['listenForChannel'] = Stream.suspend(() => {
-      if (listenAlreadyStarted) {
+      if (listenAlreadyStarted === true) {
         return shouldNeverHappen('listenForChannel already started')
       }
       listenAlreadyStarted = true
@@ -576,7 +584,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
       return Stream.fromQueue(channelRequestsQueue).pipe(
         Stream.filter((res) => {
           const hashed = hash(res)
-          if (seen.has(hashed)) {
+          if (seen.has(hashed) === true) {
             return false
           }
           seen.add(hashed)
@@ -588,7 +596,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
     const makeBroadcastChannel: MeshNode['makeBroadcastChannel'] = ({ channelName, schema }) =>
       Effect.scopeWithCloseable((scope) =>
         Effect.gen(function* () {
-          if (broadcastChannelListenQueueMap.has(channelName)) {
+          if (broadcastChannelListenQueueMap.has(channelName) === true) {
             return shouldNeverHappen(
               `Broadcast channel ${channelName} already exists`,
               broadcastChannelListenQueueMap.get(channelName),
@@ -657,7 +665,7 @@ export const makeMeshNode = <TName extends MeshNodeName>(
               supportsTransferables: value.debugInfo?.channel.supportsTransferables,
               ...value.debugInfo?.channel.debugInfo,
             })
-              .map(([key, value]) => indent(`${key}=${value}`, 4))
+              .map(([key, value]) => indent(`${key}=${String(value)}`, 4))
               .join('\n'),
             '    ',
             value.debugInfo?.channel,

package/src/websocket-edge.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for websocket-edge.ts
+ *
+ * These tests verify basic WebSocket edge functionality.
+ */
+
+import { expect } from 'vitest'
+
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { Effect, Either, Schema, WebChannel } from '@livestore/utils/effect'
+
+import * as MeshSchema from './mesh-schema.ts'
+import { MessageMsgPack, WSEdgeInit, WSEdgePayload } from './websocket-edge.ts'
+
+Vitest.describe('websocket-edge', () => {
+  /**
+   * Test that WSEdgeInit messages can be encoded/decoded via MessageMsgPack.
+   */
+  Vitest.scopedLive('should encode/decode WSEdgeInit', (test) =>
+    Effect.gen(function* () {
+      const initMessage = WSEdgeInit.make({ from: 'test-node' })
+
+      // Encode to msgpack
+      const encoded = yield* Schema.encode(MessageMsgPack)(initMessage)
+
+      // Decode back
+      const decoded = yield* Schema.decode(MessageMsgPack)(encoded)
+
+      expect(decoded._tag).toBe('WSEdgeInit')
+      if (decoded._tag === 'WSEdgeInit') {
+        expect(decoded.from).toBe('test-node')
+      }
+    }).pipe(Vitest.withTestCtx(test)),
+  )
+
+  /**
+   * Test that WSEdgePayload messages with valid Packet payloads work correctly.
+   */
+  Vitest.scopedLive('should encode/decode WSEdgePayload with Packet', (test) =>
+    Effect.gen(function* () {
+      const packet = {
+        _tag: 'NetworkEdgeAdded' as const,
+        id: 'test-id',
+        source: 'node-a',
+        target: 'node-b',
+      }
+      const wsMessage = WSEdgePayload.make({ from: 'test-node', payload: packet })
+
+      // Encode to msgpack
+      const encoded = yield* Schema.encode(MessageMsgPack)(wsMessage)
+
+      // Decode back
+      const decoded = yield* Schema.decode(MessageMsgPack)(encoded)
+
+      expect(decoded._tag).toBe('WSEdgePayload')
+      if (decoded._tag === 'WSEdgePayload') {
+        expect(decoded.from).toBe('test-node')
+        expect(decoded.payload).toEqual(packet)
+      }
+    }).pipe(Vitest.withTestCtx(test)),
+  )
+
+  /**
+   * Test that mapSchema(Packet) includes WebChannel internal messages.
+   * This is important because channels can send/receive WebChannel.Ping/Pong/DebugPing.
+   */
+  Vitest.scopedLive('mapSchema should include WebChannel messages in schema', (test) =>
+    Effect.gen(function* () {
+      const schema = WebChannel.mapSchema(MeshSchema.Packet)
+
+      // WebChannel.Ping should be decodable via the wrapped listen schema
+      const pingPayload = { _tag: 'WebChannel.Ping' as const, requestId: 'test-123' }
+      const result = Schema.decodeUnknownEither(schema.listen)(pingPayload)
+
+      // mapSchema adds WebChannel messages to the schema
+      expect(Either.isRight(result)).toBe(true)
+    }).pipe(Vitest.withTestCtx(test)),
+  )
+
+  /**
+   * Test that valid webmesh packets can be decoded.
+   */
+  Vitest.scopedLive('should decode valid webmesh packets', (test) =>
+    Effect.gen(function* () {
+      const schema = WebChannel.mapSchema(MeshSchema.Packet)
+
+      const packet = {
+        _tag: 'NetworkEdgeAdded' as const,
+        id: 'test-id',
+        source: 'node-a',
+        target: 'node-b',
+      }
+
+      const result = yield* Schema.decodeUnknown(schema.listen)(packet)
+      expect(result._tag).toBe('NetworkEdgeAdded')
+    }).pipe(Vitest.withTestCtx(test)),
+  )
+})