@livestore/common 0.0.58-dev.6 → 0.0.58-dev.7

package/src/adapter-types.ts

@@ -9,6 +9,7 @@ export interface PreparedStatement {
   execute(bindValues: PreparedBindValues | undefined, options?: { onRowsChanged?: (rowsChanged: number) => void }): void
   select<T>(bindValues: PreparedBindValues | undefined): ReadonlyArray<T>
   finalize(): void
+  sql: string
 }
 
 export type StoreAdapter = {
@@ -28,6 +29,7 @@ export type SynchronousDatabase = {
   ): void
   select<T>(queryStr: string, bindValues?: PreparedBindValues | undefined): ReadonlyArray<T>
   export(): Uint8Array
+  close(): void
 }
 
 export type ResetMode = 'all-data' | 'only-app-db'
@@ -64,9 +66,16 @@ export type Coordinator = {
   }
   // TODO is exposing the lock status really needed (or only relevant for web adapter?)
   lockStatus: SubscriptionRef.SubscriptionRef<LockStatus>
-  syncMutations: Stream.Stream<MutationEvent.AnyEncoded, UnexpectedError>
+  syncMutations: Stream.Stream<MutationEvent.Any, UnexpectedError>
   execute(queryStr: string, bindValues: PreparedBindValues | undefined): Effect.Effect<void, UnexpectedError>
-  mutate(mutationEventEncoded: MutationEvent.Any, options: { persisted: boolean }): Effect.Effect<void, UnexpectedError>
+  mutate(
+    mutationEventEncoded: MutationEvent.AnyEncoded,
+    options: { persisted: boolean },
+  ): Effect.Effect<void, UnexpectedError>
+  /** Can be called synchronously */
+  getNextMutationEventId: (opts: { localOnly: boolean }) => Effect.Effect<EventId, UnexpectedError>
+  /** Used to initially get the current mutation event id to use as `parentId` for the next mutation event */
+  getCurrentMutationEventId: Effect.Effect<EventId, UnexpectedError>
   export: Effect.Effect<Uint8Array | undefined, UnexpectedError>
   getMutationLogData: Effect.Effect<Uint8Array, UnexpectedError>
   networkStatus: SubscriptionRef.SubscriptionRef<NetworkStatus>
@@ -74,10 +83,25 @@ export type Coordinator = {
 
 export type LockStatus = 'has-lock' | 'no-lock'
 
+/**
+ * LiveStore event id value consisting of a globally unique event sequence number
+ * and a local sequence number.
+ *
+ * The local sequence number is only used for localOnly mutations and starts from 0 for each global sequence number.
+ */
+export type EventId = { global: number; local: number }
+
+export const EventId = Schema.Struct({
+  global: Schema.Number,
+  local: Schema.Number,
+}).annotations({ title: 'LiveStore.EventId' })
+
+export const ROOT_ID = { global: -1, local: 0 } satisfies EventId
+
 export type BootDb = {
   _tag: 'BootDb'
   execute(queryStr: string, bindValues?: PreparedBindValues): void
-  mutate: <const TMutationArg extends ReadonlyArray<MutationEvent.Any>>(...list: TMutationArg) => void
+  mutate: <const TMutationArg extends ReadonlyArray<MutationEvent.PartialAny>>(...list: TMutationArg) => void
   select<T>(queryStr: string, bindValues?: PreparedBindValues): ReadonlyArray<T>
   txn(callback: () => void): void
 }

package/src/derived-mutations.test.ts

@@ -94,7 +94,8 @@ describe('derived mutations', () => {
   })
 })
 
-const patchId = (muationEvent: MutationEvent.Any) => {
+const patchId = (muationEvent: MutationEvent.PartialAny) => {
+  // TODO use new id paradigm
   const id = `00000000-0000-0000-0000-000000000000`
   return { ...muationEvent, id }
 }

package/src/derived-mutations.ts

@@ -140,8 +140,8 @@ export namespace DerivedMutationHelperFns {
   > = SqliteDsl.AnyIfConstained<
     TColumns,
     UseShortcut<TOptions> extends true
-      ? (values?: GetValForKey<SqliteDsl.FromColumns.InsertRowDecoded<TColumns>, 'value'>) => MutationEvent.Any
-      : (values: SqliteDsl.FromColumns.InsertRowDecoded<TColumns>) => MutationEvent.Any
+      ? (values?: GetValForKey<SqliteDsl.FromColumns.InsertRowDecoded<TColumns>, 'value'>) => MutationEvent.PartialAny
+      : (values: SqliteDsl.FromColumns.InsertRowDecoded<TColumns>) => MutationEvent.PartialAny
   >
 
   export type UpdateMutationFn<
@@ -150,17 +150,17 @@ export namespace DerivedMutationHelperFns {
   > = SqliteDsl.AnyIfConstained<
     TColumns,
     UseShortcut<TOptions> extends true
-      ? (values: Partial<GetValForKey<SqliteDsl.FromColumns.RowDecoded<TColumns>, 'value'>>) => MutationEvent.Any
+      ? (values: Partial<GetValForKey<SqliteDsl.FromColumns.RowDecoded<TColumns>, 'value'>>) => MutationEvent.PartialAny
       : (args: {
           where: Partial<SqliteDsl.FromColumns.RowDecoded<TColumns>>
           values: Partial<SqliteDsl.FromColumns.RowDecoded<TColumns>>
-        }) => MutationEvent.Any
+        }) => MutationEvent.PartialAny
   >
 
   export type DeleteMutationFn<
     TColumns extends SqliteDsl.ConstraintColumns,
     _TOptions extends DbSchema.TableOptions,
-  > = (args: { where: Partial<SqliteDsl.FromColumns.RowDecoded<TColumns>> }) => MutationEvent.Any
+  > = (args: { where: Partial<SqliteDsl.FromColumns.RowDecoded<TColumns>> }) => MutationEvent.PartialAny
 
   type UseShortcut<TOptions extends DbSchema.TableOptions> = TOptions['isSingleColumn'] extends true
     ? TOptions['isSingleton'] extends true

package/src/devtools/devtools-bridge.ts

@@ -9,5 +9,5 @@ export type PrepareDevtoolsBridge = {
   appHostId: string
   copyToClipboard: (text: string) => Effect.Effect<void>
   sendEscapeKey?: Effect.Effect<void>
-  isLeaderTab: boolean
+  isLeader: boolean
 }

package/src/devtools/devtools-messages.ts

@@ -74,7 +74,7 @@ export class MutationBroadcast extends LSDMessage('LSD.MutationBroadcast', {
 }) {}
 
 export class RunMutationReq extends LSDReqResMessage('LSD.RunMutationReq', {
-  mutationEventEncoded: mutationEventSchemaEncodedAny,
+  mutationEventEncoded: mutationEventSchemaEncodedAny.pipe(Schema.omit('id', 'parentId')),
   persisted: Schema.Boolean,
 }) {}
 
@@ -158,12 +158,19 @@ export class SyncingInfoRes extends LSDReqResMessage('LSD.SyncingInfoRes', {
   syncingInfo: SyncingInfo,
 }) {}
 
+export class SyncHistorySubscribe extends LSDReqResMessage('LSD.SyncHistorySubscribe', {}) {}
+export class SyncHistoryUnsubscribe extends LSDReqResMessage('LSD.SyncHistoryUnsubscribe', {}) {}
+export class SyncHistoryRes extends LSDReqResMessage('LSD.SyncHistoryRes', {
+  mutationEventEncoded: mutationEventSchemaEncodedAny,
+  metadata: Schema.Option(Schema.JsonValue),
+}) {}
+
 export class DevtoolsReady extends LSDMessage('LSD.DevtoolsReady', {}) {}
 
 export class DevtoolsConnected extends LSDChannelMessage('LSD.DevtoolsConnected', {}) {}
 
 export class AppHostReady extends LSDChannelMessage('LSD.AppHostReady', {
-  isLeaderTab: Schema.Boolean,
+  isLeader: Schema.Boolean,
 }) {}
 
 export class Disconnect extends LSDChannelMessage('LSD.Disconnect', {}) {}
@@ -186,6 +193,8 @@ export const MessageToAppHostCoordinator = Schema.Union(
   RunMutationReq,
   Ping,
   DatabaseFileInfoReq,
+  SyncHistorySubscribe,
+  SyncHistoryUnsubscribe,
   SyncingInfoReq,
 ).annotations({ identifier: 'LSD.MessageToAppHostCoordinator' })
 
@@ -219,6 +228,7 @@ export const MessageFromAppHostCoordinator = Schema.Union(
   RunMutationRes,
   Pong,
   DatabaseFileInfoRes,
+  SyncHistoryRes,
   SyncingInfoRes,
 ).annotations({ identifier: 'LSD.MessageFromAppHostCoordinator' })
 

package/src/devtools/index.ts

@@ -8,6 +8,7 @@ export * from './devtools-bridge.js'
 export namespace WebBridge {
   export class AppHostReady extends Schema.TaggedStruct('LSD.WebBridge.AppHostReady', {
     appHostId: Schema.String,
+    // storeId: Schema.String,
     isLeader: Schema.Boolean,
   }) {}
 
@@ -24,6 +25,7 @@ export namespace WebBridge {
      */
     webBridgeId: Schema.String,
     isLeader: Schema.Boolean,
+    storeId: Schema.String,
   }) {}
 
   export class AppHostWillDisconnect extends Schema.TaggedStruct('LSD.WebBridge.AppHostWillDisconnect', {

package/src/rehydrate-from-mutationlog.ts

@@ -3,7 +3,7 @@ import { Chunk, Effect, Option, Schema, Stream } from '@livestore/utils/effect'
 
 import { type MigrationOptionsFromMutationLog, type SynchronousDatabase, UnexpectedError } from './adapter-types.js'
 import { getExecArgsFromMutation } from './mutation.js'
-import type { LiveStoreSchema, MutationDef, MutationLogMetaRow } from './schema/index.js'
+import type { LiveStoreSchema, MutationDef, MutationEvent, MutationLogMetaRow } from './schema/index.js'
 import { MUTATION_LOG_META_TABLE } from './schema/index.js'
 import type { PreparedBindValues } from './util.js'
 import { sql } from './util.js'
@@ -54,10 +54,11 @@ This likely means the schema has changed in an incompatible way.
         )
 
         const mutationEventDecoded = {
-          id: row.id,
+          id: { global: row.idGlobal, local: row.idLocal },
+          parentId: { global: row.parentIdGlobal, local: row.parentIdLocal },
           mutation: row.mutation,
           args: argsDecoded,
-        }
+        } satisfies MutationEvent.Any
 
         const execArgsArr = getExecArgsFromMutation({ mutationDef, mutationEventDecoded })
 
@@ -84,8 +85,8 @@ This likely means the schema has changed in an incompatible way.
 
     const stmt = logDb.prepare(sql`\
 SELECT * FROM ${MUTATION_LOG_META_TABLE} 
-WHERE id > COALESCE($id, '') 
-ORDER BY id ASC
+WHERE idGlobal > COALESCE($idGlobal, '') AND idLocal > COALESCE($idLocal, '')
+ORDER BY idGlobal ASC, idLocal ASC
 LIMIT ${CHUNK_SIZE}
 `)
 
@@ -97,9 +98,17 @@ LIMIT ${CHUNK_SIZE}
         // End stream if no more rows
         if (Chunk.isChunk(item) && item.length === 0) return Option.none()
 
-        const lastId = Chunk.isChunk(item) ? Chunk.last(item).pipe(Option.getOrUndefined)?.id : undefined
+        const lastId = Chunk.isChunk(item)
+          ? Chunk.last(item).pipe(
+              Option.map((_) => ({ global: _.idGlobal, local: _.idLocal })),
+              Option.getOrUndefined,
+            )
+          : undefined
         const nextItem = Chunk.fromIterable(
-          stmt.select<MutationLogMetaRow>({ $id: lastId } as any as PreparedBindValues),
+          stmt.select<MutationLogMetaRow>({
+            $idGlobal: lastId?.global,
+            $idLocal: lastId?.local,
+          } as any as PreparedBindValues),
         )
         const prevItem = Chunk.isChunk(item) ? item : Chunk.empty()
         return Option.some([prevItem, nextItem])

package/src/schema/mutations.ts

@@ -1,7 +1,7 @@
 import { memoizeByRef } from '@livestore/utils'
-import { cuid } from '@livestore/utils/cuid'
 import { Schema } from '@livestore/utils/effect'
 
+import { EventId } from '../adapter-types.js'
 import type { BindValues } from '../sql-queries/sql-queries.js'
 import type { LiveStoreSchema } from './index.js'
 
@@ -35,42 +35,131 @@ export type SingleOrReadonlyArray<T> = T | ReadonlyArray<T>
 export type MutationDef<TName extends string, TFrom, TTo> = {
   name: TName
   schema: Schema.Schema<TTo, TFrom>
-  sql: MutationDefSqlResult<TTo>
+  sql: MutationDefSqlResult<NoInfer<TTo>>
   options: {
+    /** Warning: This feature is not fully implemented yet */
+    historyId: string
     /**
      * When set to true, the mutation won't be synced over the network
      */
     localOnly: boolean
+    /** Warning: This feature is not fully implemented yet */
+    facts: FactsCallback<TTo> | undefined
   }
 
-  /** Helper function to construct mutation event */
-  (args: TTo): { mutation: TName; args: TTo; id: string }
+  /** Helper function to construct a partial mutation event */
+  (
+    args: TTo,
+    options?: {
+      id?: number
+    },
+  ): {
+    mutation: TName
+    args: TTo
+    // TODO remove/clean up after sync-next is fully implemented
+    id?: EventId
+  }
+}
+
+export type FactsCallback<TTo> = (
+  args: TTo,
+  currentFacts: MutationEventFacts,
+) => {
+  modify: {
+    set: Iterable<MutationEventFactInput>
+    unset: Iterable<MutationEventFactInput>
+  }
+  require: Iterable<MutationEventFactInput>
 }
 
 export namespace MutationDef {
   export type Any = MutationDef<string, any, any>
 }
 
+export type MutationEventKey = string
+export type MutationEventFact = string
+export type MutationEventFacts = ReadonlyMap<string, any>
+
+export type MutationEventFactsGroup = {
+  modifySet: MutationEventFacts
+  modifyUnset: MutationEventFacts
+
+  /**
+   * Events on independent "dependency" branches are commutative which can facilitate more prioritized syncing
+   */
+  depRequire: MutationEventFacts
+  depRead: MutationEventFacts
+}
+
+export type MutationEventFactsSnapshot = Map<string, any>
+
+export type MutationEventFactInput = string | readonly [string, any]
+
+export const defineFacts = <
+  TRecord extends Record<string, MutationEventFactInput | ((...args: any[]) => MutationEventFactInput)>,
+>(
+  record: TRecord,
+): TRecord => record
+
+export type DefineMutationOptions<TTo> = {
+  historyId?: string
+  /** Warning: This feature is not fully implemented yet */
+  facts?: (
+    args: TTo,
+    currentFacts: MutationEventFacts,
+  ) => {
+    modify?: {
+      set?: Iterable<MutationEventFactInput>
+      unset?: Iterable<MutationEventFactInput>
+    }
+    /**
+     * Two purposes: constrain history and constrain compaction
+     */
+    require?: Iterable<MutationEventFactInput>
+  }
+  /**
+   * When set to true, the mutation won't be synced over the network
+   */
+  localOnly?: boolean
+}
+
 // TODO possibly also allow for mutation event subsumption behaviour
 export const defineMutation = <TName extends string, TFrom, TTo>(
   name: TName,
   schema: Schema.Schema<TTo, TFrom>,
-  sql: MutationDefSqlResult<TTo>,
-  options?: {
-    /**
-     * When set to true, the mutation won't be synced over the network
-     */
-    localOnly?: boolean
-  },
+  sql: MutationDefSqlResult<NoInfer<TTo>>,
+  options?: DefineMutationOptions<TTo>,
 ): MutationDef<TName, TFrom, TTo> => {
-  const makeEvent = (args: TTo) => ({ mutation: name, args, id: cuid() })
+  const makePartialEvent = (
+    args: TTo,
+    options?: {
+      id?: EventId
+    },
+  ) => ({ mutation: name, args, ...options })
 
-  Object.defineProperty(makeEvent, 'name', { value: name })
-  Object.defineProperty(makeEvent, 'schema', { value: schema })
-  Object.defineProperty(makeEvent, 'sql', { value: sql })
-  Object.defineProperty(makeEvent, 'options', { value: { localOnly: options?.localOnly ?? false } })
+  Object.defineProperty(makePartialEvent, 'name', { value: name })
+  Object.defineProperty(makePartialEvent, 'schema', { value: schema })
+  Object.defineProperty(makePartialEvent, 'sql', { value: sql })
+  Object.defineProperty(makePartialEvent, 'options', {
+    value: {
+      historyId: options?.historyId ?? 'main',
+      localOnly: options?.localOnly ?? false,
+      facts: options?.facts
+        ? (args, currentFacts) => {
+            const res = options.facts!(args, currentFacts)
+            return {
+              modify: {
+                set: res.modify?.set ? new Set(res.modify.set) : new Set(),
+                unset: res.modify?.unset ? new Set(res.modify.unset) : new Set(),
+              },
+              require: res.require ? new Set(res.require) : new Set(),
+            }
+          }
+        : undefined,
+    } satisfies MutationDef.Any['options'],
+  })
 
-  return makeEvent as MutationDef<TName, TFrom, TTo>
+  return makePartialEvent as MutationDef<TName, TFrom, TTo>
 }
 
 export const makeMutationDefRecord = <TInputRecord extends Record<string, MutationDef.Any>>(
@@ -102,22 +191,41 @@ export const rawSqlMutation = defineMutation(
 export type RawSqlMutation = typeof rawSqlMutation
 export type RawSqlMutationEvent = ReturnType<typeof rawSqlMutation>
 
+export type MutationEventPartial<TMutationsDef extends MutationDef.Any> = {
+  mutation: TMutationsDef['name']
+  args: Schema.Schema.Type<TMutationsDef['schema']>
+}
+
+export type MutationEventPartialEncoded<TMutationsDef extends MutationDef.Any> = {
+  mutation: TMutationsDef['name']
+  args: Schema.Schema.Encoded<TMutationsDef['schema']>
+}
+
 export type MutationEvent<TMutationsDef extends MutationDef.Any> = {
   mutation: TMutationsDef['name']
   args: Schema.Schema.Type<TMutationsDef['schema']>
-  id: string
+  id: EventId
+  parentId: EventId
 }
 
 export type MutationEventEncoded<TMutationsDef extends MutationDef.Any> = {
   mutation: TMutationsDef['name']
   args: Schema.Schema.Encoded<TMutationsDef['schema']>
-  id: string
+  id: EventId
+  parentId: EventId
 }
 
 export namespace MutationEvent {
   export type Any = MutationEvent<MutationDef.Any>
   export type AnyEncoded = MutationEventEncoded<MutationDef.Any>
 
+  export type PartialAny = MutationEventPartial<MutationDef.Any>
+  export type PartialAnyEncoded = MutationEventPartialEncoded<MutationDef.Any>
+
+  export type PartialForSchema<TSchema extends LiveStoreSchema> = {
+    [K in keyof TSchema['_MutationDefMapType']]: MutationEventPartial<TSchema['_MutationDefMapType'][K]>
+  }[keyof TSchema['_MutationDefMapType']]
+
   export type ForSchema<TSchema extends LiveStoreSchema> = {
     [K in keyof TSchema['_MutationDefMapType']]: MutationEvent<TSchema['_MutationDefMapType'][K]>
   }[keyof TSchema['_MutationDefMapType']]
@@ -128,14 +236,31 @@ export type MutationEventSchema<TMutationsDefRecord extends MutationDefRecord> =
     [K in keyof TMutationsDefRecord]: {
       mutation: K
       args: Schema.Schema.Type<TMutationsDefRecord[K]['schema']>
-      id: string
+      id: EventId
+      parentId: EventId
+    }
+  }[keyof TMutationsDefRecord],
+  {
+    [K in keyof TMutationsDefRecord]: {
+      mutation: K
+      args: Schema.Schema.Encoded<TMutationsDefRecord[K]['schema']>
+      id: EventId
+      parentId: EventId
+    }
+  }[keyof TMutationsDefRecord]
+>
+
+export type MutationEventPartialSchema<TMutationsDefRecord extends MutationDefRecord> = Schema.Schema<
+  {
+    [K in keyof TMutationsDefRecord]: {
+      mutation: K
+      args: Schema.Schema.Type<TMutationsDefRecord[K]['schema']>
     }
   }[keyof TMutationsDefRecord],
   {
     [K in keyof TMutationsDefRecord]: {
       mutation: K
       args: Schema.Schema.Encoded<TMutationsDefRecord[K]['schema']>
-      id: string
     }
   }[keyof TMutationsDefRecord]
 >
@@ -148,21 +273,37 @@ export const makeMutationEventSchema = <TSchema extends LiveStoreSchema>(
       Schema.Struct({
         mutation: Schema.Literal(def.name),
         args: def.schema,
-        id: Schema.String,
+        id: EventId,
+        parentId: EventId,
       }),
     ),
   ).annotations({ title: 'MutationEventSchema' }) as any
 
+export const makeMutationEventPartialSchema = <TSchema extends LiveStoreSchema>(
+  schema: TSchema,
+): MutationEventPartialSchema<TSchema['_MutationDefMapType']> =>
+  Schema.Union(
+    ...[...schema.mutations.values()].map((def) =>
+      Schema.Struct({
+        mutation: Schema.Literal(def.name),
+        args: def.schema,
+      }),
+    ),
+  ).annotations({ title: 'MutationEventSchemaPartial' }) as any
+
 export const makeMutationEventSchemaMemo = memoizeByRef(makeMutationEventSchema)
 
-export const mutationEventSchemaDecodedAny = Schema.Struct({
+export const mutationEventSchemaAny = Schema.Struct({
   mutation: Schema.String,
   args: Schema.Any,
-  id: Schema.String,
-}).annotations({ title: 'MutationEventSchema.DecodedAny' })
+  id: EventId,
+  parentId: EventId,
+}).annotations({ title: 'MutationEventSchema.Any' })
 
-export const mutationEventSchemaEncodedAny = Schema.Struct({
-  mutation: Schema.String,
-  args: Schema.Any,
-  id: Schema.String,
-}).annotations({ title: 'MutationEventSchema.EncodedAny' })
+export const mutationEventSchemaDecodedAny = Schema.typeSchema(mutationEventSchemaAny).annotations({
+  title: 'MutationEventSchema.DecodedAny',
+})
+
+export const mutationEventSchemaEncodedAny = Schema.encodedSchema(mutationEventSchemaAny).annotations({
+  title: 'MutationEventSchema.EncodedAny',
+})

package/src/schema/system-tables.ts

@@ -36,7 +36,25 @@ export const schemaMutationsMetaTable = table(
 
 export type SchemaMutationsMetaRow = FromTable.RowDecoded<typeof schemaMutationsMetaTable>
 
-export const systemTables = [schemaMetaTable, schemaMutationsMetaTable]
+/**
+ * Table which stores SQLite changeset blobs which is used for rolling back
+ * read-model state during rebasing.
+ */
+export const SESSION_CHANGESET_META_TABLE = '__livestore_session_changeset'
+
+export const sessionChangesetMetaTable = table(
+  SESSION_CHANGESET_META_TABLE,
+  {
+    idGlobal: SqliteDsl.integer({ primaryKey: true }),
+    idLocal: SqliteDsl.integer({ primaryKey: true }),
+    changeset: SqliteDsl.blob({}),
+  },
+  { disableAutomaticIdColumn: true },
+)
+
+export type SessionChangesetMetaRow = FromTable.RowDecoded<typeof sessionChangesetMetaTable>
+
+export const systemTables = [schemaMetaTable, schemaMutationsMetaTable, sessionChangesetMetaTable]
 
 /// Mutation log DB
 
@@ -48,17 +66,21 @@ export const MUTATION_LOG_META_TABLE = 'mutation_log'
 export const mutationLogMetaTable = table(
   MUTATION_LOG_META_TABLE,
   {
-    // TODO add parent ids (see https://vlcn.io/blog/crdt-substrate)
-    id: SqliteDsl.text({ primaryKey: true }),
-    mutation: SqliteDsl.text({ nullable: false }),
-    argsJson: SqliteDsl.text({ nullable: false, schema: Schema.parseJson(Schema.Any) }),
-    schemaHash: SqliteDsl.integer({ nullable: false }),
+    idGlobal: SqliteDsl.integer({ primaryKey: true }),
+    idLocal: SqliteDsl.integer({ primaryKey: true }),
+    parentIdGlobal: SqliteDsl.integer({}),
+    parentIdLocal: SqliteDsl.integer({}),
+    mutation: SqliteDsl.text({}),
+    argsJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Any) }),
+    schemaHash: SqliteDsl.integer({}),
+    /** Local only, used for ordered queries to avoid recursive id traversal */
+    orderKey: SqliteDsl.integer({}),
     /** ISO date format */
-    createdAt: SqliteDsl.text({ nullable: false }),
+    createdAt: SqliteDsl.text({}),
     syncStatus: SqliteDsl.text({ schema: SyncStatus }),
     syncMetadataJson: SqliteDsl.text({ schema: Schema.parseJson(Schema.Option(Schema.JsonValue)) }),
   },
-  { disableAutomaticIdColumn: true },
+  { disableAutomaticIdColumn: true, indexes: [{ columns: ['orderKey'], name: 'mutation_log_order_key_idx' }] },
 )
 
 export type MutationLogMetaRow = FromTable.RowDecoded<typeof mutationLogMetaTable>

package/src/schema-management/migrations.ts

@@ -155,7 +155,7 @@ export const migrateTable = ({
 
 const createIndexFromDefinition = (tableName: string, index: SqliteAst.Index) => {
   const uniqueStr = index.unique ? 'UNIQUE' : ''
-  return sql`create ${uniqueStr} index ${index.name} on ${tableName} (${index.columns.join(', ')})`
+  return sql`create ${uniqueStr} index if not exists ${index.name} on ${tableName} (${index.columns.join(', ')})`
 }
 
 export const makeColumnSpec = (tableAst: SqliteAst.Table) => {

package/src/sync/next/ambient.d.ts

@@ -0,0 +1,3 @@
+declare module 'graphology' {
+  export * from 'graphology-types'
+}