@livestore/common 0.4.0 → 0.5.0-dev.1

package/src/rematerialize-from-eventlog.ts

@@ -1,135 +1,153 @@
 import { memoizeByRef } from '@livestore/utils'
-import { Chunk, Effect, Option, Schema, Stream } from '@livestore/utils/effect'
+import { Effect, Option, ReadonlyArray as EffectArray, Schema, Stream } from '@livestore/utils/effect'
 
 import { type SqliteDb, UnknownError } from './adapter-types.ts'
 import type { MaterializeEvent } from './leader-thread/mod.ts'
+import { STATE_REBUILD_BATCH_SIZE_DEFAULT, StateRebuildBatchSizeSchema } from './leader-thread/types.ts'
 import type { EventDef, LiveStoreSchema } from './schema/mod.ts'
-import { EventSequenceNumber, LiveStoreEvent, resolveEventDef, SystemTables } from './schema/mod.ts'
+import { EventSequenceNumber, LiveStoreEvent, SystemTables } from './schema/mod.ts'
+import { withSavepoint } from './sqlite-db-helper.ts'
 import type { PreparedBindValues } from './util.ts'
 import { sql } from './util.ts'
 
 /** Parse JSON string to unknown value */
-const jsonParse = Schema.decodeUnknownSync(Schema.parseJson())
+const jsonParse = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown))
 
 export const rematerializeFromEventlog = Effect.fn('@livestore/common:rematerializeFromEventlog')(function* ({
   dbEventlog,
   // TODO re-use this db when bringing back the boot in-memory db implementation
-  // db,
+  dbState,
   schema,
   onProgress,
   materializeEvent,
+  batchSize = STATE_REBUILD_BATCH_SIZE_DEFAULT,
 }: {
   dbEventlog: SqliteDb
-  // db: SqliteDb
+  dbState: SqliteDb
   schema: LiveStoreSchema
   onProgress: (_: { done: number; total: number }) => Effect.Effect<void>
   materializeEvent: MaterializeEvent
+  batchSize?: number
 }) {
-    const eventsCount = dbEventlog.select<{ count: number }>(
-      `SELECT COUNT(*) AS count FROM ${SystemTables.EVENTLOG_META_TABLE}`,
-    )[0]!.count
-
-    const hashEventDef = memoizeByRef((event: EventDef.AnyWithoutFn) => Schema.hash(event.schema))
-
-    const processEvent = Effect.fn(`@livestore/common:rematerializeFromEventlog:processEvent`)(function* (
-      row: SystemTables.EventlogMetaRow,
-    ) {
-      const args = jsonParse(row.argsJson)
-      const eventEncoded = LiveStoreEvent.Client.EncodedWithMeta.make({
-        name: row.name,
-        args,
-        seqNum: {
-          global: row.seqNumGlobal,
-          client: row.seqNumClient,
-          rebaseGeneration: row.seqNumRebaseGeneration,
-        },
-        parentSeqNum: {
-          global: row.parentSeqNumGlobal,
-          client: row.parentSeqNumClient,
-          rebaseGeneration: row.parentSeqNumRebaseGeneration,
-        },
-        clientId: row.clientId,
-        sessionId: row.sessionId,
-      })
-
-      const resolution = yield* resolveEventDef(schema, {
-        operation: '@livestore/common:rematerializeFromEventlog:processEvent',
-        event: eventEncoded,
-      }).pipe(UnknownError.mapToUnknownError)
-
-      if (resolution._tag === 'unknown') {
-        // Old snapshots can contain newer events. Skip until the runtime has
-        // been updated; the event stays in the log for future replays.
-        return
-      }
+  if (Schema.is(StateRebuildBatchSizeSchema)(batchSize) === false) {
+    return yield* UnknownError.make({
+      cause: `Invalid stateRebuildBatchSize: ${String(batchSize)}. Expected a positive integer.`,
+      payload: { batchSize },
+    })
+  }
+
+  const eventsCount = dbEventlog.select<{ count: number }>(
+    `SELECT COUNT(*) AS count FROM ${SystemTables.EVENTLOG_META_TABLE}`,
+  )[0]!.count
+
+  const hashEventDef = memoizeByRef((event: EventDef.AnyWithoutFn) => Schema.hash(event.schema))
+
+  const processEvent = Effect.fn(`@livestore/common:rematerializeFromEventlog:processEvent`)(function* (
+    row: SystemTables.EventlogMetaRow,
+  ) {
+    const args = jsonParse(row.argsJson)
+    const eventEncoded = LiveStoreEvent.Client.EncodedWithMeta.make({
+      name: row.name,
+      args,
+      seqNum: {
+        global: row.seqNumGlobal,
+        client: row.seqNumClient,
+        rebaseGeneration: row.seqNumRebaseGeneration,
+      },
+      parentSeqNum: {
+        global: row.parentSeqNumGlobal,
+        client: row.parentSeqNumClient,
+        rebaseGeneration: row.parentSeqNumRebaseGeneration,
+      },
+      clientId: row.clientId,
+      sessionId: row.sessionId,
+    })
 
-      const { eventDef } = resolution
+    const eventDef = schema.eventsDefsMap.get(row.name)
+    const materializer = schema.state.materializers.get(row.name)
 
-      if (hashEventDef(eventDef) !== row.schemaHash) {
-        yield* Effect.logWarning(
-          `Schema hash mismatch for event definition ${row.name}. Trying to materialize event anyway.`,
-        )
-      }
+    if (eventDef === undefined || materializer === undefined) {
+      // Route unknown events through the normal materialization boundary so
+      // they advance the state snapshot head as no-ops.
+      yield* materializeEvent(eventEncoded, { skipEventlog: true })
+      return
+    }
 
-      // Checking whether the schema has changed in an incompatible way
-      yield* Schema.decodeUnknown(eventDef.schema)(args).pipe(
-        Effect.mapError((cause) =>
-          UnknownError.make({
-            cause,
-            note: `\
+    if (hashEventDef(eventDef) !== row.schemaHash) {
+      yield* Effect.logWarning(
+        `Schema hash mismatch for event definition ${row.name}. Trying to materialize event anyway.`,
+      )
+    }
+
+    // Checking whether the schema has changed in an incompatible way
+    yield* Schema.decodeUnknownEffect(eventDef.schema)(args).pipe(
+      Effect.mapError((cause) =>
+        UnknownError.make({
+          cause,
+          note: `\
 There was an error during rematerializing from the eventlog while decoding
 the persisted event args for event definition "${row.name}".
 This likely means the schema has changed in an incompatible way.
 `,
-          }),
-        ),
-      )
-
-      yield* materializeEvent(eventEncoded, { skipEventlog: true })
-    })
+        }),
+      ),
+    )
 
-    const CHUNK_SIZE = 100
+    yield* materializeEvent(eventEncoded, { skipEventlog: true })
+  })
 
-    const stmt = dbEventlog.prepare(sql`\
+  const stmt = dbEventlog.prepare(sql`\
 SELECT * FROM ${SystemTables.EVENTLOG_META_TABLE} 
 WHERE seqNumGlobal > $seqNumGlobal OR (seqNumGlobal = $seqNumGlobal AND seqNumClient > $seqNumClient)
 ORDER BY seqNumGlobal ASC, seqNumClient ASC
-LIMIT ${CHUNK_SIZE}
+LIMIT $batchSize
 `)
 
-    let processedEvents = 0
-
-    yield* Stream.unfoldChunk<
-      Chunk.Chunk<SystemTables.EventlogMetaRow> | { _tag: 'Initial' },
-      SystemTables.EventlogMetaRow
-    >({ _tag: 'Initial' }, (item) => {
-      // End stream if no more rows
-      if (Chunk.isChunk(item) === true && item.length === 0) return Option.none()
-
-      const lastId = Chunk.isChunk(item) === true
-        ? Chunk.last(item).pipe(
-            Option.map((_) => ({ global: _.seqNumGlobal, client: _.seqNumClient })),
-            Option.getOrElse(() => EventSequenceNumber.Client.ROOT),
-          )
-        : EventSequenceNumber.Client.ROOT
-      const nextItem = Chunk.fromIterable(
-        stmt.select<SystemTables.EventlogMetaRow>({
-          $seqNumGlobal: lastId?.global,
-          $seqNumClient: lastId?.client,
-        } as any as PreparedBindValues),
-      )
-      const prevItem = Chunk.isChunk(item) === true ? item : Chunk.empty()
-      return Option.some([prevItem, nextItem])
-    }).pipe(
-      Stream.bufferChunks({ capacity: 2 }),
-      Stream.tap((row) =>
-        Effect.gen(function* () {
-          yield* processEvent(row)
-
-          processedEvents++
-          yield* onProgress({ done: processedEvents, total: eventsCount })
-        }),
-      ),
-      Stream.runDrain,
-    )
+  let processedEvents = 0
+
+  yield* Stream.paginate(EventSequenceNumber.Client.ROOT, (lastId) =>
+    Effect.sync(() => {
+      const rows = stmt.select<SystemTables.EventlogMetaRow>({
+        $seqNumGlobal: lastId.global,
+        $seqNumClient: lastId.client,
+        $batchSize: batchSize,
+      } as any as PreparedBindValues)
+
+      if (EffectArray.isReadonlyArrayNonEmpty(rows) === false) {
+        const done: readonly [
+          ReadonlyArray<SystemTables.EventlogMetaRow>,
+          Option.Option<EventSequenceNumber.Client.Composite>,
+        ] = [rows, Option.none()]
+        return done
+      }
+
+      const lastRow = EffectArray.lastNonEmpty(rows)
+      const nextCursor = EventSequenceNumber.Client.Composite.make({
+        global: lastRow.seqNumGlobal,
+        client: lastRow.seqNumClient,
+        rebaseGeneration: lastRow.seqNumRebaseGeneration,
+      })
+      const next: readonly [
+        ReadonlyArray<SystemTables.EventlogMetaRow>,
+        Option.Option<EventSequenceNumber.Client.Composite>,
+      ] = [rows, Option.some(nextCursor)]
+      return next
+    }),
+  ).pipe(
+    Stream.bufferArray({ capacity: 2 }),
+    Stream.runForEachArray((rows) =>
+      Effect.forEach(
+        rows,
+        (row) =>
+          Effect.gen(function* () {
+            yield* processEvent(row)
+
+            processedEvents++
+            yield* onProgress({ done: processedEvents, total: eventsCount })
+          }),
+        { discard: true },
+      ).pipe(withSavepoint(dbState)),
+    ),
+    Effect.ensuring(Effect.sync(() => stmt.finalize())),
+  )
 }, Effect.withPerformanceMeasure('@livestore/common:rematerializeFromEventlog'))

package/src/schema/EventDef/define.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from 'vitest'
+
+import { Schema } from '@livestore/utils/effect'
+
+import { synced } from './define.ts'
+
+describe('synced event wire schema', () => {
+  const occurredAt = new Date('2026-07-17T10:15:30.000Z')
+  const event = synced({
+    name: 'v1.Occurred',
+    schema: Schema.Struct({
+      occurredAt: Schema.DateFromString,
+    }),
+  })
+  const jsonSchema = Schema.fromJsonString(event.schema)
+
+  test('roundtrips a valid date through JSON', () => {
+    const encoded = Schema.encodeSync(jsonSchema)({ occurredAt })
+
+    expect(encoded).toBe('{"occurredAt":"2026-07-17T10:15:30.000Z"}')
+    expect(Schema.decodeSync(jsonSchema)(encoded)).toEqual({ occurredAt })
+  })
+
+  test('rejects invalid dates on encode and decode', () => {
+    expect(() => Schema.encodeSync(jsonSchema)({ occurredAt: new Date(Number.NaN) })).toThrow()
+    expect(() => Schema.decodeSync(jsonSchema)('{"occurredAt":"not-a-date"}')).toThrow()
+  })
+})

package/src/schema/EventDef/define.ts

@@ -29,7 +29,7 @@
  */
 
 import { shouldNeverHappen } from '@livestore/utils'
-import { Schema } from '@livestore/utils/effect'
+import { Result, Schema } from '@livestore/utils/effect'
 
 import type { EventDef } from './event-def.ts'
 import type { EventDefFactInput, EventDefFacts } from './facts.ts'
@@ -105,15 +105,15 @@ export type DefineEventOptions<TTo, TDerived extends boolean = false> = {
 export const defineEvent = <TName extends string, TType, TEncoded = TType, TDerived extends boolean = false>(
   args: {
     name: TName
-    schema: Schema.Schema<TType, TEncoded>
+    schema: Schema.Codec<TType, TEncoded>
   } & DefineEventOptions<TType, TDerived>,
 ): EventDef<TName, TType, TEncoded, TDerived> => {
   const { name, schema, ...options } = args
 
   const makePartialEvent = (args: TType) => {
-    const res = Schema.validateEither(schema)(args)
-    if (res._tag === 'Left') {
-      shouldNeverHappen(`Invalid event args for event '${name}':`, res.left.message, '\n')
+    const res = Schema.decodeResult(Schema.toType(schema))(args)
+    if (Result.isFailure(res) === true) {
+      shouldNeverHappen(`Invalid event args for event '${name}':`, res.failure.message, '\n')
     }
     return { name: name, args }
   }
@@ -127,18 +127,19 @@ export const defineEvent = <TName extends string, TType, TEncoded = TType, TDeri
   Object.defineProperty(makePartialEvent, 'options', {
     value: {
       clientOnly: options?.clientOnly ?? false,
-      facts: options?.facts !== undefined
-        ? (args, currentFacts) => {
-            const res = options.facts!(args, currentFacts)
-            return {
-              modify: {
-                set: res.modify?.set !== undefined ? new Set(res.modify.set) : new Set(),
-                unset: res.modify?.unset !== undefined ? new Set(res.modify.unset) : new Set(),
-              },
-              require: res.require !== undefined ? new Set(res.require) : new Set(),
+      facts:
+        options?.facts !== undefined
+          ? (args, currentFacts) => {
+              const res = options.facts!(args, currentFacts)
+              return {
+                modify: {
+                  set: res.modify?.set !== undefined ? new Set(res.modify.set) : new Set(),
+                  unset: res.modify?.unset !== undefined ? new Set(res.modify.unset) : new Set(),
+                },
+                require: res.require !== undefined ? new Set(res.require) : new Set(),
+              }
             }
-          }
-        : undefined,
+          : undefined,
       derived: options?.derived ?? false,
       deprecated: options?.deprecated,
     } satisfies EventDef.Any['options'],
@@ -178,7 +179,7 @@ export const defineEvent = <TName extends string, TType, TEncoded = TType, TDeri
 export const synced = <TName extends string, TType, TEncoded = TType>(
   args: {
     name: TName
-    schema: Schema.Schema<TType, TEncoded>
+    schema: Schema.Codec<TType, TEncoded>
   } & Omit<DefineEventOptions<TType>, 'derived' | 'clientOnly'>,
 ): EventDef<TName, TType, TEncoded> => defineEvent({ ...args, clientOnly: false })
 
@@ -201,7 +202,7 @@ export const synced = <TName extends string, TType, TEncoded = TType>(
  *   name: 'UiStateSet',
  *   schema: Schema.Struct({
  *     selectedTodoId: Schema.NullOr(Schema.String),
- *     filterMode: Schema.Literal('all', 'active', 'completed'),
+ *     filterMode: Schema.Literals(['all', 'active', 'completed']),
  *   }),
  * })
  *
@@ -212,6 +213,6 @@ export const synced = <TName extends string, TType, TEncoded = TType>(
 export const clientOnly = <TName extends string, TType, TEncoded = TType>(
   args: {
     name: TName
-    schema: Schema.Schema<TType, TEncoded>
+    schema: Schema.Codec<TType, TEncoded>
   } & Omit<DefineEventOptions<TType>, 'derived' | 'clientOnly'>,
 ): EventDef<TName, TType, TEncoded> => defineEvent({ ...args, clientOnly: true })

package/src/schema/EventDef/deprecated.test.ts

@@ -60,14 +60,7 @@ describe('logDeprecationWarnings', () => {
 
   const run = (effect: Effect.Effect<void>) =>
     Effect.runSync(
-      effect.pipe(
-        Effect.provide(
-          Logger.replace(
-            Logger.defaultLogger,
-            Logger.make(({ message }) => logs.push(message as unknown[])),
-          ),
-        ),
-      ),
+      effect.pipe(Effect.provide(Logger.layer([Logger.make(({ message }) => logs.push(message as unknown[]))]))),
     )
 
   test('logs event deprecation warning', () => {

package/src/schema/EventDef/deprecated.ts

@@ -30,20 +30,19 @@
  * @module
  */
 
-import type { Schema } from '@livestore/utils/effect'
-import { Effect, Option, SchemaAST } from '@livestore/utils/effect'
+import { type Schema, Effect, Option, SchemaAST } from '@livestore/utils/effect'
 
 import type { EventDef } from './event-def.ts'
 
-/** Symbol used to mark schemas as deprecated. */
-export const DeprecatedId = Symbol.for('livestore/schema/annotations/deprecated')
+/** Annotation key used to mark schemas as deprecated. */
+export const DeprecatedId = 'livestore/schema/annotations/deprecated'
 
 /**
  * Marks a schema field as deprecated with a reason message.
  * When an event is committed with a deprecated field that has a value,
  * a warning will be logged.
  *
- * Works with both Schema types and PropertySignatures (from Schema.optional).
+ * Works with Schema fields, including optional fields from Schema.optional.
  *
  * @param reason - Explanation of why this field is deprecated and what to use instead
  * @returns A function that adds the deprecation annotation to the schema
@@ -58,8 +57,8 @@ export const DeprecatedId = Symbol.for('livestore/schema/annotations/deprecated'
  */
 export const deprecated =
   (reason: string) =>
-  <T extends { annotations: (annotations: { readonly [DeprecatedId]?: string }) => T }>(schema: T): T =>
-    schema.annotations({ [DeprecatedId]: reason })
+  <T extends Schema.Top>(schema: T): T['Rebuild'] =>
+    schema.annotate({ [DeprecatedId]: reason })
 
 /**
  * Checks if a schema has a deprecation annotation.
@@ -67,8 +66,8 @@ export const deprecated =
  * @param schema - The schema to check
  * @returns The deprecation reason if deprecated, None otherwise
  */
-export const getDeprecatedReason = <A, I, R>(schema: Schema.Schema<A, I, R>): Option.Option<string> =>
-  SchemaAST.getAnnotation<string>(DeprecatedId)(schema.ast)
+export const getDeprecatedReason = (schema: Schema.Top): Option.Option<string> =>
+  Option.fromUndefinedOr(SchemaAST.resolveAt<string>(DeprecatedId)(schema.ast))
 
 /**
  * Checks if a schema is deprecated.
@@ -76,8 +75,7 @@ export const getDeprecatedReason = <A, I, R>(schema: Schema.Schema<A, I, R>): Op
  * @param schema - The schema to check
  * @returns true if the schema is deprecated
  */
-export const isDeprecated = <A, I, R>(schema: Schema.Schema<A, I, R>): boolean =>
-  Option.isSome(getDeprecatedReason(schema))
+export const isDeprecated = (schema: Schema.Top): boolean => Option.isSome(getDeprecatedReason(schema))
 
 /**
  * Finds deprecated fields with values in the given event arguments.
@@ -88,28 +86,27 @@ export const isDeprecated = <A, I, R>(schema: Schema.Schema<A, I, R>): boolean =
  * @returns Array of objects containing field name and deprecation reason
  */
 export const findDeprecatedFieldsWithValues = (
-  schema: Schema.Schema.All,
+  schema: Schema.Top,
   args: Record<string, unknown>,
 ): Array<{ field: string; reason: string }> => {
   const result: Array<{ field: string; reason: string }> = []
-  const ast = schema.ast
+  const ast = SchemaAST.toType(schema.ast)
 
-  // Handle TypeLiteral (Struct) schemas
-  if (ast._tag === 'TypeLiteral') {
+  // Handle Objects (Struct) schemas
+  if (SchemaAST.isObjects(ast) === true) {
     for (const prop of ast.propertySignatures) {
       const fieldName = String(prop.name)
       const fieldValue = args[fieldName]
 
       // Only check fields that have a value (not undefined)
       if (fieldValue !== undefined) {
-        // Check deprecation on the property signature itself (for Schema.optional(...).pipe(deprecated(...)))
-        const propAnnotations = prop.annotations as Record<symbol, unknown> | undefined
-        const deprecationReason = propAnnotations?.[DeprecatedId] as string | undefined
+        // Check deprecation on the property key itself (for Schema.optional(...).pipe(deprecated(...)))
+        const deprecationReason = prop.type.context?.annotations?.[DeprecatedId] as string | undefined
 
         // Also check deprecation on the type (for direct field deprecation)
-        const typeDeprecation = SchemaAST.getAnnotation<string>(DeprecatedId)(prop.type)
+        const typeDeprecation = SchemaAST.resolveAt<string>(DeprecatedId)(prop.type)
 
-        const reason = deprecationReason ?? (Option.isSome(typeDeprecation) === true ? typeDeprecation.value : undefined)
+        const reason = deprecationReason ?? typeDeprecation
         if (reason !== undefined) {
           result.push({ field: fieldName, reason })
         }

package/src/schema/EventDef/event-def.ts

@@ -34,7 +34,7 @@ export type EventDef<TName extends string, TType, TEncoded = TType, TDerived ext
   name: TName
 
   /** Effect Schema used for validating and encoding/decoding event arguments. */
-  schema: Schema.Schema<TType, TEncoded>
+  schema: Schema.Codec<TType, TEncoded>
 
   options: {
     /**
@@ -62,9 +62,7 @@ export type EventDef<TName extends string, TType, TEncoded = TType, TDerived ext
    * Callable signature - creates a partial event with decoded arguments.
    * The returned object can be passed directly to `store.commit()`.
    */
-  (
-    args: TType,
-  ): {
+  (args: TType): {
     name: TName
     args: TType
   }

package/src/schema/EventSequenceNumber/client.ts

@@ -8,7 +8,7 @@ export type Type = Brand.Branded<number, 'ClientEventSequenceNumber'>
 const ClientBrand = Brand.nominal<Type>()
 
 /** Effect Schema for encoding/decoding client sequence numbers. */
-export const Schema = S.fromBrand(ClientBrand)(S.Int)
+export const Schema = S.fromBrand('ClientEventSequenceNumber', ClientBrand)(S.Int)
 
 /**
  * Creates a branded client sequence number from a plain number.
@@ -177,27 +177,13 @@ const CompositeSchema = S.Struct({
   client: Schema,
   // Client only
   rebaseGeneration: S.Int,
-}).annotations({
-  title: 'EventSequenceNumber.Composite',
-  pretty: () => (seqNum) => toString(seqNum),
 })
-
-/**
- * Creates a validated Composite sequence number from input.
- * If rebaseGeneration is omitted, defaults to REBASE_GENERATION_DEFAULT (0).
- */
-const makeComposite = (seqNum: CompositeInput): Composite => {
-  return S.is(CompositeSchema)(seqNum) === true
-    ? seqNum
-    : S.decodeSync(CompositeSchema)({
-        ...seqNum,
-        rebaseGeneration: seqNum.rebaseGeneration ?? REBASE_GENERATION_DEFAULT,
-      })
-}
+  .annotate({ title: 'EventSequenceNumber.Composite' })
+  .pipe(S.overrideToFormatter(() => (seqNum) => toString(seqNum)))
 
 /**
  * Effect Schema for the composite event sequence number (global + client + rebaseGeneration).
- * Also includes a `make` helper for creating validated Composite values.
+ * Its `make` validates input and defaults an omitted rebaseGeneration to REBASE_GENERATION_DEFAULT (0).
  *
  * @example
  * ```ts
@@ -210,7 +196,17 @@ const makeComposite = (seqNum: CompositeInput): Composite => {
  * const validated = EventSequenceNumber.Client.Composite.make({ global: 5, client: 0, rebaseGeneration: 0 })
  * ```
  */
-export const Composite = Object.assign(CompositeSchema, { make: makeComposite })
+export const Composite: typeof CompositeSchema & { make(seqNum: CompositeInput): Composite } =
+  class extends CompositeSchema {
+    static override make(seqNum: CompositeInput): Composite {
+      return S.is(CompositeSchema)(seqNum) === true
+        ? seqNum
+        : S.decodeSync(CompositeSchema)({
+            ...seqNum,
+            rebaseGeneration: seqNum.rebaseGeneration ?? REBASE_GENERATION_DEFAULT,
+          })
+    }
+  }
 
 /** The root sequence number (global=0, client=0, rebaseGeneration=0). Parent of the first event. */
 export const ROOT = {
@@ -222,19 +218,19 @@ export const ROOT = {
 /**
  * Computes the next sequence number and its parent based on the current position.
  *
- * For client-local events (isClient=true): increments the client component, keeps global.
- * For global events (isClient=false): increments global, resets client to 0.
+ * For client-only events (isClientOnly=true): increments the client component, keeps global.
+ * For global events (isClientOnly=false): increments global, resets client to 0.
  */
 export const nextPair = ({
   seqNum,
-  isClient,
+  isClientOnly,
   rebaseGeneration,
 }: {
   seqNum: Composite
-  isClient: boolean
+  isClientOnly: boolean
   rebaseGeneration?: number
 }): CompositePair => {
-  if (isClient === true) {
+  if (isClientOnly === true) {
     return {
       seqNum: {
         global: seqNum.global,

package/src/schema/EventSequenceNumber/global.ts

@@ -6,7 +6,7 @@ export type Type = Brand.Branded<number, 'GlobalEventSequenceNumber'>
 const GlobalBrand = Brand.nominal<Type>()
 
 /** Effect Schema for encoding/decoding global sequence numbers. */
-export const Schema = S.fromBrand(GlobalBrand)(S.Int)
+export const Schema = S.fromBrand('GlobalEventSequenceNumber', GlobalBrand)(S.Int)
 
 /**
  * Creates a branded global sequence number from a plain number.

package/src/schema/EventSequenceNumber.test.ts

@@ -7,12 +7,12 @@ import { EventSequenceNumber } from './mod.ts'
 Vitest.describe('EventSequenceNumber', () => {
   Vitest.test('nextPair (no rebase)', () => {
     const e_0_0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 })
-    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClient: false }).seqNum).toStrictEqual({
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClientOnly: false }).seqNum).toStrictEqual({
       global: 1,
       client: 0,
       rebaseGeneration: 0,
     })
-    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClient: true }).seqNum).toStrictEqual({
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClientOnly: true }).seqNum).toStrictEqual({
       global: 0,
       client: 1,
       rebaseGeneration: 0,
@@ -22,14 +22,14 @@ Vitest.describe('EventSequenceNumber', () => {
   Vitest.test('nextPair (rebase)', () => {
     const e_0_0 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0 })
     expect(
-      EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClient: false, rebaseGeneration: 1 }).seqNum,
+      EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClientOnly: false, rebaseGeneration: 1 }).seqNum,
     ).toStrictEqual({
       global: 1,
       client: 0,
       rebaseGeneration: 1,
     })
     expect(
-      EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClient: true, rebaseGeneration: 1 }).seqNum,
+      EventSequenceNumber.Client.nextPair({ seqNum: e_0_0, isClientOnly: true, rebaseGeneration: 1 }).seqNum,
     ).toStrictEqual({
       global: 0,
       client: 1,
@@ -37,7 +37,7 @@ Vitest.describe('EventSequenceNumber', () => {
     })
 
     const e_0_0_g1 = EventSequenceNumber.Client.Composite.make({ global: 0, client: 0, rebaseGeneration: 2 })
-    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0_g1, isClient: false }).seqNum).toStrictEqual({
+    expect(EventSequenceNumber.Client.nextPair({ seqNum: e_0_0_g1, isClientOnly: false }).seqNum).toStrictEqual({
       global: 1,
       client: 0,
       rebaseGeneration: 2,