@livestore/sync-cf 0.4.0-dev.9 → 0.5.0-dev.0

package/src/cf-worker/do/pull.ts

@@ -1,9 +1,11 @@
-import { BackendIdMismatchError, InvalidPullError, SyncBackend, UnexpectedError } from '@livestore/common'
-import { Chunk, Effect, Option, Schema, Stream } from '@livestore/utils/effect'
+import { BackendIdMismatchError, SyncBackend, UnknownError } from '@livestore/common'
+import { splitArrayBySize } from '@livestore/common/sync'
+import { Effect, Option, Schema, Stream } from '@livestore/utils/effect'
+
+import { MAX_PULL_EVENTS_PER_MESSAGE, MAX_WS_MESSAGE_BYTES } from '../../common/constants.ts'
 import { SyncMessage } from '../../common/mod.ts'
-import { MAX_PULL_EVENTS_PER_MESSAGE, MAX_WS_MESSAGE_BYTES } from '../shared.ts'
-import { DoCtx } from './layer.ts'
-import { splitChunkBySize } from './ws-chunking.ts'
+import type { ForwardedHeaders } from '../shared.ts'
+import * as DoCtx from './layer.ts'
 
 const encodePullResponse = Schema.encodeSync(SyncMessage.PullResponse)
 
@@ -16,17 +18,26 @@ const encodePullResponse = Schema.encodeSync(SyncMessage.PullResponse)
 // DO RPC:
 // - Further chunks will be emitted manually in `push.ts`
 // - If the client sends a `Interrupt` RPC message, TODO
-export const makeEndingPullStream = (
-  req: SyncMessage.PullRequest,
-  payload: Schema.JsonValue | undefined,
-): Stream.Stream<SyncMessage.PullResponse, InvalidPullError, DoCtx> =>
+export const makeEndingPullStream = ({
+  req,
+  payload,
+  headers,
+}: {
+  req: SyncMessage.PullRequest
+  payload: Schema.Json | undefined
+  headers: ForwardedHeaders | undefined
+}): Stream.Stream<SyncMessage.PullResponse, UnknownError | BackendIdMismatchError, DoCtx.DoCtx> =>
   Effect.gen(function* () {
-    const { doOptions, backendId, storeId, storage } = yield* DoCtx
+    const { doOptions, backendId, storeId, storage } = yield* DoCtx.DoCtx
 
-    if (doOptions?.onPull) {
-      yield* Effect.tryAll(() => doOptions!.onPull!(req, { storeId, payload })).pipe(
-        UnexpectedError.mapToUnexpectedError,
-      )
+    if (doOptions?.onPull !== undefined) {
+      yield* Effect.trySyncOrPromiseOrEffect(() =>
+        doOptions.onPull!(req, {
+          storeId,
+          ...(payload !== undefined ? { payload } : {}),
+          ...(headers !== undefined ? { headers } : {}),
+        }),
+      ).pipe(UnknownError.mapToUnknownError)
     }
 
     if (req.cursor._tag === 'Some' && req.cursor.value.backendId !== backendId) {
@@ -38,8 +49,8 @@ export const makeEndingPullStream = (
     )
 
     return storedEvents.pipe(
-      Stream.mapChunks(
-        splitChunkBySize({
+      Stream.mapArrayEffect(
+        splitArrayBySize({
           maxItems: MAX_PULL_EVENTS_PER_MESSAGE,
           maxBytes: MAX_WS_MESSAGE_BYTES,
           encode: (batch) =>
@@ -48,23 +59,27 @@ export const makeEndingPullStream = (
             ),
         }),
       ),
-      Stream.mapAccum(total, (remaining, chunk) => {
-        const asArray = Chunk.toReadonlyArray(chunk)
-        const nextRemaining = Math.max(0, remaining - asArray.length)
+      Stream.mapAccum(
+        () => total,
+        (remaining, array) => {
+          const nextRemaining = Math.max(0, remaining - array.length)
 
-        return [
-          nextRemaining,
-          SyncMessage.PullResponse.make({
-            batch: asArray,
-            pageInfo: nextRemaining > 0 ? SyncBackend.pageInfoMoreKnown(nextRemaining) : SyncBackend.pageInfoNoMore,
-            backendId,
-          }),
-        ] as const
-      }),
+          return [
+            nextRemaining,
+            [
+              SyncMessage.PullResponse.make({
+                batch: array,
+                pageInfo: nextRemaining > 0 ? SyncBackend.pageInfoMoreKnown(nextRemaining) : SyncBackend.pageInfoNoMore,
+                backendId,
+              }),
+            ],
+          ] as const
+        },
+      ),
       Stream.tap(
         Effect.fn(function* (res) {
-          if (doOptions?.onPullRes) {
-            yield* Effect.tryAll(() => doOptions.onPullRes!(res)).pipe(UnexpectedError.mapToUnexpectedError)
+          if (doOptions?.onPullRes !== undefined) {
+            yield* Effect.trySyncOrPromiseOrEffect(() => doOptions.onPullRes!(res)).pipe(UnknownError.mapToUnknownError)
           }
         }),
       ),
@@ -72,6 +87,8 @@ export const makeEndingPullStream = (
     )
   }).pipe(
     Stream.unwrap,
-    Stream.mapError((cause) => InvalidPullError.make({ cause })),
+    Stream.mapError((cause) =>
+      cause._tag === 'BackendIdMismatchError' || cause._tag === 'UnknownError' ? cause : new UnknownError({ cause }),
+    ),
     Stream.withSpan('cloudflare-provider:pull'),
   )

package/src/cf-worker/do/push.test.ts

@@ -0,0 +1,40 @@
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { Deferred, Duration, Effect, Fiber, Semaphore } from '@livestore/utils/effect'
+
+import { runSerializedPushAdmission } from './push.ts'
+
+Vitest.describe('sync-cf push admission', () => {
+  Vitest.live('publishes an admitted push before honoring interruption', () =>
+    Effect.gen(function* () {
+      const semaphore = yield* Semaphore.make(1)
+      const persisted = yield* Deferred.make<void>()
+      const allowBroadcast = yield* Deferred.make<void>()
+      const broadcasted = yield* Deferred.make<void>()
+
+      const admissionFiber = yield* runSerializedPushAdmission(
+        semaphore,
+        Effect.gen(function* () {
+          yield* Deferred.succeed(persisted, undefined)
+          yield* Deferred.await(allowBroadcast)
+          yield* Deferred.succeed(broadcasted, undefined)
+        }),
+      ).pipe(Effect.forkChild)
+
+      // Reproduce cancellation after persistence but before the pull broadcast handoff.
+      yield* Deferred.await(persisted)
+      const interruptStarted = yield* Deferred.make<void>()
+      const interruptFiber = yield* Effect.gen(function* () {
+        yield* Deferred.succeed(interruptStarted, undefined)
+        yield* Fiber.interrupt(admissionFiber)
+      }).pipe(Effect.forkChild)
+      yield* Deferred.await(interruptStarted)
+      yield* Effect.yieldNow
+
+      yield* Deferred.succeed(allowBroadcast, undefined)
+      yield* Deferred.await(broadcasted).pipe(Effect.timeout(Duration.seconds(1)))
+      yield* Fiber.join(interruptFiber)
+
+      Vitest.expect(yield* Deferred.isDone(broadcasted)).toBe(true)
+    }),
+  )
+})

package/src/cf-worker/do/push.ts

@@ -1,36 +1,38 @@
-import {
-  BackendIdMismatchError,
-  InvalidPushError,
-  ServerAheadError,
-  SyncBackend,
-  UnexpectedError,
-} from '@livestore/common'
+import { BackendIdMismatchError, ServerAheadError, SyncBackend, UnknownError } from '@livestore/common'
 import { type CfTypes, emitStreamResponse } from '@livestore/common-cf'
-import { Chunk, Effect, Option, type RpcMessage, Schema } from '@livestore/utils/effect'
+import { splitArrayBySize } from '@livestore/common/sync'
+import { Effect, Option, ReadonlyArray as EffectArray, type RpcMessage, Schema } from '@livestore/utils/effect'
+
+import { MAX_PUSH_EVENTS_PER_REQUEST, MAX_WS_MESSAGE_BYTES } from '../../common/constants.ts'
 import { SyncMessage } from '../../common/mod.ts'
 import {
   type Env,
-  MAX_PULL_EVENTS_PER_MESSAGE,
-  MAX_WS_MESSAGE_BYTES,
+  type ForwardedHeaders,
   type MakeDurableObjectClassOptions,
+  rpcSubscriptionKeyPrefix,
+  type RpcSubscription,
   type StoreId,
   WebSocketAttachmentSchema,
 } from '../shared.ts'
-import { DoCtx } from './layer.ts'
-import { splitChunkBySize } from './ws-chunking.ts'
+import * as DoCtx from './layer.ts'
 
-const encodePullResponse = Schema.encodeSync(SyncMessage.PullResponse)
+const pullResponseJsonSchema = Schema.toCodecJson(SyncMessage.PullResponse)
+const encodePullResponse = Schema.encodeSync(pullResponseJsonSchema)
+const jsonStringify = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown))
 type PullBatchItem = SyncMessage.PullResponse['batch'][number]
+type PushBatchItem = SyncMessage.PushRequest['batch'][number]
 
 export const makePush =
   ({
     payload,
+    headers,
     options,
     storeId,
     ctx,
     env,
   }: {
-    payload: Schema.JsonValue | undefined
+    payload: Schema.Json | undefined
+    headers: ForwardedHeaders | undefined
     options: MakeDurableObjectClassOptions | undefined
     storeId: StoreId
     ctx: CfTypes.DurableObjectState
@@ -39,59 +41,64 @@ export const makePush =
   (pushRequest: Omit<SyncMessage.PushRequest, '_tag'>) =>
     Effect.gen(function* () {
       // yield* Effect.log(`Pushing ${decodedMessage.batch.length} events`, decodedMessage.batch)
-      const { backendId, storage, currentHeadRef, updateCurrentHead, rpcSubscriptions } = yield* DoCtx
+      const { backendId, storage, currentHeadRef, updateCurrentHead, pushSemaphore } = yield* DoCtx.DoCtx
 
       if (pushRequest.batch.length === 0) {
         return SyncMessage.PushAck.make({})
       }
 
-      if (options?.onPush) {
-        yield* Effect.tryAll(() => options.onPush!(pushRequest, { storeId, payload })).pipe(
-          UnexpectedError.mapToUnexpectedError,
-        )
+      if (options?.onPush !== undefined) {
+        yield* Effect.trySyncOrPromiseOrEffect(() =>
+          options.onPush!(pushRequest, {
+            storeId,
+            ...(payload !== undefined ? { payload } : {}),
+            ...(headers !== undefined ? { headers } : {}),
+          }),
+        ).pipe(UnknownError.mapToUnknownError)
       }
 
       if (pushRequest.backendId._tag === 'Some' && pushRequest.backendId.value !== backendId) {
         return yield* new BackendIdMismatchError({ expected: backendId, received: pushRequest.backendId.value })
       }
 
-      // This part of the code needs to run sequentially to avoid race conditions
-      const { createdAt } = yield* Effect.gen(function* () {
-        const currentHead = currentHeadRef.current
-        // TODO handle clientId unique conflict
-        // Validate the batch
-        const firstEventParent = pushRequest.batch[0]!.parentSeqNum
-        if (firstEventParent !== currentHead) {
-          // yield* Effect.logDebug('ServerAheadError: backend head mismatch', {
-          //   expectedHead: currentHead,
-          //   providedHead: firstEventParent,
-          //   batchSize: pushRequest.batch.length,
-          //   backendId,
-          // })
-
-          return yield* new ServerAheadError({ minimumExpectedNum: currentHead, providedNum: firstEventParent })
-        }
-
-        const createdAt = new Date().toISOString()
-
-        // TODO possibly model this as a queue in order to speed up subsequent pushes
-        yield* storage.appendEvents(pushRequest.batch, createdAt)
-
-        updateCurrentHead(pushRequest.batch.at(-1)!.seqNum)
-
-        return { createdAt }
-      }).pipe(blockConcurrencyWhile(ctx))
-
-      // Run in background but already return the push ack to the client
-      yield* Effect.gen(function* () {
-        const connectedClients = ctx.getWebSockets()
-
-        // Preparing chunks of responses to make sure we don't exceed the WS message size limit.
-        const responses = Chunk.fromIterable(pushRequest.batch).pipe(
-          splitChunkBySize({
-            maxItems: MAX_PULL_EVENTS_PER_MESSAGE,
+      // A push is one ordered admit → persist → publish operation. `blockConcurrencyWhile` below protects
+      // the Durable Object state transition, while this semaphore keeps later pushes from overtaking this
+      // push during broadcasting without holding Cloudflare's concurrency gate across network I/O.
+      yield* runSerializedPushAdmission(
+        pushSemaphore,
+        Effect.gen(function* () {
+          // Keep the head check, durable append, and in-memory head update atomic with respect to other
+          // Durable Object requests. Broadcasting intentionally happens after this gate is released.
+          const { createdAt } = yield* Effect.gen(function* () {
+            const currentHead = currentHeadRef.current
+            // TODO handle clientId unique conflict
+            // Validate the batch
+            const firstEventParent = pushRequest.batch[0]!.parentSeqNum
+            if (firstEventParent !== currentHead) {
+              return yield* new ServerAheadError({ minimumExpectedNum: currentHead, providedNum: firstEventParent })
+            }
+
+            const createdAt = new Date().toISOString()
+
+            // TODO possibly model this as a queue in order to speed up subsequent pushes
+            yield* storage.appendEvents(pushRequest.batch, createdAt)
+
+            updateCurrentHead(pushRequest.batch.at(-1)!.seqNum)
+
+            return { createdAt }
+          }).pipe(blockConcurrencyWhile(ctx))
+
+          const connectedClients = ctx.getWebSockets()
+
+          // Preparing chunks of responses to make sure we don't exceed the WS message size limit.
+          if (EffectArray.isReadonlyArrayNonEmpty(pushRequest.batch) === false) {
+            return
+          }
+
+          const responses = yield* splitArrayBySize({
+            maxItems: MAX_PUSH_EVENTS_PER_REQUEST,
             maxBytes: MAX_WS_MESSAGE_BYTES,
-            encode: (items) =>
+            encode: (items: ReadonlyArray<PushBatchItem>) =>
               encodePullResponse(
                 SyncMessage.PullResponse.make({
                   batch: items.map(
@@ -104,105 +111,136 @@ export const makePush =
                   backendId,
                 }),
               ),
-          }),
-          Chunk.map((eventsChunk) => {
-            const batchWithMetadata = Chunk.toReadonlyArray(eventsChunk).map((eventEncoded) => ({
-              eventEncoded,
-              metadata: Option.some(SyncMessage.SyncMetadata.make({ createdAt })),
-            }))
-
-            const response = SyncMessage.PullResponse.make({
-              batch: batchWithMetadata,
-              pageInfo: SyncBackend.pageInfoNoMore,
-              backendId,
-            })
-
-            return {
-              response,
-              encoded: Schema.encodeSync(SyncMessage.PullResponse)(response),
-            }
-          }),
-        )
-
-        // Dual broadcasting: WebSocket + RPC clients
+          })(pushRequest.batch).pipe(
+            Effect.map((eventBatch) =>
+              eventBatch.map((events) => {
+                const batchWithMetadata = events.map((eventEncoded) => ({
+                  eventEncoded,
+                  metadata: Option.some(SyncMessage.SyncMetadata.make({ createdAt })),
+                }))
+
+                const response = SyncMessage.PullResponse.make({
+                  batch: batchWithMetadata,
+                  pageInfo: SyncBackend.pageInfoNoMore,
+                  backendId,
+                })
 
-        // Broadcast to WebSocket clients
-        if (connectedClients.length > 0) {
-          for (const { response, encoded } of responses) {
-            // Only calling once for now.
-            if (options?.onPullRes) {
-              yield* Effect.tryAll(() => options.onPullRes!(response)).pipe(UnexpectedError.mapToUnexpectedError)
-            }
+                return {
+                  response,
+                  encoded: encodePullResponse(response),
+                }
+              }),
+            ),
+          )
+
+          // Dual broadcasting: WebSocket + RPC clients
+
+          // Broadcast to WebSocket clients
+          if (connectedClients.length > 0) {
+            for (const { response, encoded } of responses) {
+              // Only calling once for now.
+              if (options?.onPullRes !== undefined) {
+                yield* Effect.trySyncOrPromiseOrEffect(() => options.onPullRes!(response)).pipe(
+                  UnknownError.mapToUnknownError,
+                )
+              }
 
-            // NOTE we're also sending the pullRes chunk to the pushing ws client as confirmation
-            for (const conn of connectedClients) {
-              const attachment = Schema.decodeSync(WebSocketAttachmentSchema)(conn.deserializeAttachment())
-
-              // We're doing something a bit "advanced" here as we're directly emitting Effect RPC-compatible
-              // response messsages on the Effect RPC-managed websocket connection to the WS client.
-              // For this we need to get the RPC `requestId` from the WebSocket attachment.
-              for (const requestId of attachment.pullRequestIds) {
-                const res: RpcMessage.ResponseChunkEncoded = {
-                  _tag: 'Chunk',
-                  requestId,
-                  values: [encoded],
+              // NOTE we're also sending the pullRes chunk to the pushing ws client as confirmation
+              for (const conn of connectedClients) {
+                const attachment = yield* Schema.decodeEffect(WebSocketAttachmentSchema)(conn.deserializeAttachment())
+
+                // We're doing something a bit "advanced" here as we're directly emitting Effect RPC-compatible
+                // response messsages on the Effect RPC-managed websocket connection to the WS client.
+                // For this we need to get the RPC `requestId` from the WebSocket attachment.
+                for (const requestId of attachment.pullRequestIds) {
+                  const res: RpcMessage.ResponseChunkEncoded = {
+                    _tag: 'Chunk',
+                    requestId,
+                    values: [encoded],
+                  }
+                  conn.send(jsonStringify(res))
                 }
-                conn.send(JSON.stringify(res))
               }
             }
+
+            yield* Effect.logDebug(`Broadcasted to ${connectedClients.length} WebSocket clients`)
           }
 
-          yield* Effect.logDebug(`Broadcasted to ${connectedClients.length} WebSocket clients`)
-        }
-
-        // RPC broadcasting would require reconstructing client stubs from clientIds
-        if (rpcSubscriptions.size > 0) {
-          for (const subscription of rpcSubscriptions.values()) {
-            for (const { encoded } of responses) {
-              yield* emitStreamResponse({
-                callerContext: subscription.callerContext,
-                env,
-                requestId: subscription.requestId,
-                values: [encoded],
-              }).pipe(Effect.tapCauseLogPretty, Effect.exit)
+          // Subscribers live in the DO's KV storage (single source of truth), so fan-out survives reconstruction.
+          // emitStreamResponse reconstructs each client stub from its callerContext.
+          const rpcSubscriptions = Array.from(
+            ctx.storage.kv.list<RpcSubscription>({ prefix: rpcSubscriptionKeyPrefix }),
+          )
+          if (rpcSubscriptions.length > 0) {
+            for (const [, subscription] of rpcSubscriptions) {
+              for (const { encoded } of responses) {
+                yield* emitStreamResponse({
+                  callerContext: subscription.callerContext,
+                  env,
+                  requestId: subscription.requestId,
+                  storeId: subscription.storeId,
+                  values: [encoded],
+                }).pipe(Effect.tapCauseLogPretty, Effect.exit)
+              }
             }
-          }
 
-          yield* Effect.logDebug(`Broadcasted to ${rpcSubscriptions.size} RPC clients`)
-        }
-      }).pipe(
-        Effect.tapCauseLogPretty,
-        Effect.withSpan('push-rpc-broadcast'),
-        Effect.uninterruptible, // We need to make sure Effect RPC doesn't interrupt this fiber
-        Effect.fork,
+            yield* Effect.logDebug(`Broadcasted to ${rpcSubscriptions.length} RPC clients`)
+          }
+        }).pipe(Effect.tapCauseLogPretty, Effect.withSpan('push-rpc-broadcast')),
       )
 
-      // We need to yield here to make sure the fork above is kicked off before we let Effect RPC finish the request
-      yield* Effect.yieldNow()
-
+      // Acknowledge only after the committed batch has been published, so a client cannot observe an
+      // advanced server head while the corresponding pull response is still waiting in a detached fiber.
       return SyncMessage.PushAck.make({})
     }).pipe(
       Effect.tap(
         Effect.fn(function* (message) {
-          if (options?.onPushRes) {
-            yield* Effect.tryAll(() => options.onPushRes!(message)).pipe(UnexpectedError.mapToUnexpectedError)
+          if (options?.onPushRes !== undefined) {
+            yield* Effect.trySyncOrPromiseOrEffect(() => options.onPushRes!(message)).pipe(
+              UnknownError.mapToUnknownError,
+            )
           }
         }),
       ),
-      Effect.mapError((cause) => InvalidPushError.make({ cause })),
+      Effect.mapError((cause) =>
+        cause._tag === 'BackendIdMismatchError' || cause._tag === 'ServerAheadError' || cause._tag === 'UnknownError'
+          ? cause
+          : new UnknownError({ cause }),
+      ),
       Effect.withSpan('sync-cf:do:push', { attributes: { storeId, batchSize: pushRequest.batch.length } }),
     )
 
 /**
+ * Serializes the complete push admission lifecycle, including publication to pull subscribers.
+ *
+ * This complements `blockConcurrencyWhile`: that Cloudflare primitive makes the durable state transition
+ * atomic with respect to other Durable Object requests, whereas this semaphore preserves push order after
+ * the storage gate is released and broadcasting begins. Keeping broadcast outside `blockConcurrencyWhile`
+ * avoids holding Cloudflare's concurrency gate across network I/O.
+ *
+ * Once admitted, the effect is uninterruptible so cancellation cannot leave a committed head without its
+ * matching pull response. Such a gap would make later pushers receive `ServerAhead` while waiting for a
+ * response that was never published.
+ */
+export const runSerializedPushAdmission = <A, E, R>(
+  semaphore: DoCtx.Service['pushSemaphore'],
+  admission: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> => semaphore.withPermits(1)(admission.pipe(Effect.uninterruptible))
+
+/**
+ * Runs the storage-backed state transition behind Cloudflare's Durable Object concurrency gate.
+ * This scope should remain limited to local persistence and head mutation; ordered publication is handled
+ * separately by `runSerializedPushAdmission` so outbound work does not block unrelated Durable Object events.
+ *
  * @see https://developers.cloudflare.com/durable-objects/api/state/#blockconcurrencywhile
  */
 const blockConcurrencyWhile =
   (ctx: CfTypes.DurableObjectState) =>
   <A, E, R>(eff: Effect.Effect<A, E, R>) =>
     Effect.gen(function* () {
-      const runtime = yield* Effect.runtime<R>()
+      const services = yield* Effect.context<R>()
       const exit = yield* Effect.promise(() =>
-        ctx.blockConcurrencyWhile(() => eff.pipe(Effect.provide(runtime), Effect.runPromiseExit)),
+        ctx.blockConcurrencyWhile(() => eff.pipe(Effect.runPromiseExitWith(services))),
       )
 
       return yield* exit

package/src/cf-worker/do/sqlite.ts

@@ -1,15 +1,21 @@
 import { EventSequenceNumber, State } from '@livestore/common/schema'
 import { Schema } from '@livestore/utils/effect'
+
 import { PERSISTENCE_FORMAT_VERSION } from '../shared.ts'
 
+/**
+ * Main event log table storing all LiveStore events.
+ *
+ * ⚠️  IMPORTANT: Any changes to this schema require bumping PERSISTENCE_FORMAT_VERSION in shared.ts
+ */
 export const eventlogTable = State.SQLite.table({
   // NOTE actual table name is determined at runtime to use proper storeId
   name: `eventlog_${PERSISTENCE_FORMAT_VERSION}_$storeId`,
   columns: {
-    seqNum: State.SQLite.integer({ primaryKey: true, schema: EventSequenceNumber.GlobalEventSequenceNumber }),
-    parentSeqNum: State.SQLite.integer({ schema: EventSequenceNumber.GlobalEventSequenceNumber }),
+    seqNum: State.SQLite.integer({ primaryKey: true, schema: EventSequenceNumber.Global.Schema }),
+    parentSeqNum: State.SQLite.integer({ schema: EventSequenceNumber.Global.Schema }),
     name: State.SQLite.text({}),
-    args: State.SQLite.text({ schema: Schema.parseJson(Schema.Any), nullable: true }),
+    args: State.SQLite.text({ schema: Schema.fromJsonString(Schema.Any), nullable: true }),
     /** ISO date format. Currently only used for debugging purposes. */
     createdAt: State.SQLite.text({}),
     clientId: State.SQLite.text({}),
@@ -17,12 +23,16 @@ export const eventlogTable = State.SQLite.table({
   },
 })
 
-/** Will only ever have one row per durable object. */
+/**
+ * Context metadata table - one row per Durable Object.
+ *
+ * ⚠️  IMPORTANT: Any changes to this schema require bumping PERSISTENCE_FORMAT_VERSION in shared.ts
+ */
 export const contextTable = State.SQLite.table({
   name: `context_${PERSISTENCE_FORMAT_VERSION}`,
   columns: {
     storeId: State.SQLite.text({ primaryKey: true }),
-    currentHead: State.SQLite.integer({ schema: EventSequenceNumber.GlobalEventSequenceNumber }),
+    currentHead: State.SQLite.integer({ schema: EventSequenceNumber.Global.Schema }),
     backendId: State.SQLite.text({}),
   },
 })