@livestore/common 0.5.0-dev.0 → 0.5.0-dev.1

package/src/leader-thread/recreate-db.ts

@@ -11,8 +11,22 @@ import {
   UnknownError,
 } from '../index.ts'
 import type { LiveStoreSchema } from '../schema/mod.ts'
-import { configureConnection } from './connection.ts'
+import { SystemTables } from '../schema/mod.ts'
+import { configureConnection, execSql } from './connection.ts'
 import type { MaterializeEvent } from './types.ts'
+import { STATE_REBUILD_BATCH_SIZE_DEFAULT } from './types.ts'
+
+export const hasCompletedState = (db: SqliteDb): boolean => {
+  const tableNames = new Set(db.select<{ name: string }>('SELECT name FROM sqlite_master').map((_) => _.name))
+  return (
+    SystemTables.stateSystemTables.every((table) => tableNames.has(table.sqliteDef.name)) &&
+    db.select(`SELECT id FROM ${SystemTables.REBUILD_META_TABLE} WHERE id = 1`).length === 1
+  )
+}
+
+/** Marks a successfully prepared state database as safe to use without rebuilding it. */
+export const markStateAsCompleted = (db: SqliteDb): Effect.Effect<void, SqliteError> =>
+  execSql(db, `INSERT OR IGNORE INTO ${SystemTables.REBUILD_META_TABLE} (id) VALUES (1)`, {})
 
 export const recreateDb = ({
   dbState,
@@ -20,12 +34,14 @@ export const recreateDb = ({
   schema,
   bootStatusQueue,
   materializeEvent,
+  stateRebuildBatchSize = STATE_REBUILD_BATCH_SIZE_DEFAULT,
 }: {
   dbState: SqliteDb
   dbEventlog: SqliteDb
   schema: LiveStoreSchema
   bootStatusQueue: Queue.Queue<BootStatus>
   materializeEvent: MaterializeEvent
+  stateRebuildBatchSize?: number
 }): Effect.Effect<{ migrationsReport: MigrationsReport }, UnknownError | MaterializeError | SqliteError> =>
   Effect.gen(function* () {
     const hooks = schema.state.sqlite.migrations.hooks
@@ -36,50 +52,35 @@ export const recreateDb = ({
       }),
     )
 
-    // NOTE to speed up the operations below, we're creating a temporary in-memory database
-    // and later we'll overwrite the persisted database with the new data
-    // TODO bring back this optimization
-    // const tmpDb = yield* makeSqliteDb({ _tag: 'in-memory' })
-    const tmpDb = dbState
-    yield* configureConnection(tmpDb, { foreignKeys: true })
+    yield* configureConnection(dbState, { foreignKeys: true })
 
     // @effect-diagnostics-next-line anyUnknownInErrorContext:off -- user hook errors are immediately normalized to LiveStore UnknownError
-    yield* Effect.trySyncOrPromiseOrEffect(() => hooks?.init?.(tmpDb)).pipe(UnknownError.mapToUnknownError)
+    yield* Effect.trySyncOrPromiseOrEffect(() => hooks?.init?.(dbState)).pipe(UnknownError.mapToUnknownError)
 
     const migrationsReport = yield* migrateDb({
-      db: tmpDb,
+      db: dbState,
       schema,
       onProgress: ({ done, total }) => Queue.offer(bootStatusQueue, { stage: 'migrating', progress: { done, total } }),
     })
 
     // @effect-diagnostics-next-line anyUnknownInErrorContext:off -- user hook errors are immediately normalized to LiveStore UnknownError
-    yield* Effect.trySyncOrPromiseOrEffect(() => hooks?.pre?.(tmpDb)).pipe(UnknownError.mapToUnknownError)
+    yield* Effect.trySyncOrPromiseOrEffect(() => hooks?.pre?.(dbState)).pipe(UnknownError.mapToUnknownError)
 
     yield* rematerializeFromEventlog({
-      // db: tmpDb,
       dbEventlog,
+      dbState,
       schema,
       materializeEvent,
+      batchSize: stateRebuildBatchSize,
       onProgress: ({ done, total }) =>
         Queue.offer(bootStatusQueue, { stage: 'rehydrating', progress: { done, total } }),
     })
 
     // @effect-diagnostics-next-line anyUnknownInErrorContext:off -- user hook errors are immediately normalized to LiveStore UnknownError
-    yield* Effect.trySyncOrPromiseOrEffect(() => hooks?.post?.(tmpDb)).pipe(UnknownError.mapToUnknownError)
-
-    // TODO bring back
-    // Import the temporary in-memory database into the persistent database
-    // yield* Effect.sync(() => db.import(tmpDb)).pipe(
-    //   Effect.withSpan('@livestore/common:leader-thread:recreateDb:import'),
-    // )
-
-    // TODO maybe bring back re-using this initial snapshot to avoid calling `.export()` again
-    // We've disabled this for now as it made the code too complex, as we often run syncing right after
-    // so the snapshot is no longer up to date
-    // const snapshotFromTmpDb = tmpDb.export()
+    yield* Effect.trySyncOrPromiseOrEffect(() => hooks?.post?.(dbState)).pipe(UnknownError.mapToUnknownError)
 
-    // TODO bring back
-    // tmpDb.close()
+    // Keep this out of finalizers, which also run on failure and interruption.
+    yield* markStateAsCompleted(dbState)
 
     return { migrationsReport }
   }).pipe(

package/src/leader-thread/stream-events.ts

@@ -151,9 +151,7 @@ export const streamEventsWithSyncState = ({
            */
           const waitForHead = EventSequenceNumber.Client.isGreaterThanOrEqual(cursor, head)
           const maybeHead =
-            waitForHead === true
-              ? yield* Queue.take(headQueue).pipe(Effect.map(Option.some))
-              : yield* Queue.poll(headQueue)
+            waitForHead === true ? yield* Queue.take(headQueue).pipe(Effect.asSome) : yield* Queue.poll(headQueue)
           const nextHead = Option.getOrElse(maybeHead, () => head)
           const hardStop = options.until?.global ?? Number.POSITIVE_INFINITY
           const target = EventSequenceNumber.Client.Composite.make({

package/src/leader-thread/types.ts

@@ -139,6 +139,11 @@ export type InitialBlockingSyncContext = {
 export const STREAM_EVENTS_BATCH_SIZE_DEFAULT = 100
 export const STREAM_EVENTS_BATCH_SIZE_MAX = 1_000
 
+export const STATE_REBUILD_BATCH_SIZE_DEFAULT = 100
+export const StateRebuildBatchSizeSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).annotate({
+  title: 'stateRebuildBatchSize',
+})
+
 export const StreamEventsOptionsFields = {
   since: Schema.optional(EventSequenceNumber.Client.Composite),
   until: Schema.optional(EventSequenceNumber.Client.Composite),

package/src/materializer-helper.ts

@@ -55,7 +55,7 @@ export const getExecStatementsFromMaterializer = ({
       const { query, bindValues } = rawQueryOrQueryBuilder.asSql()
       const rawResults = dbState.select(query, prepareBindValues(bindValues, query))
       const resultSchema = getResultSchema(rawQueryOrQueryBuilder)
-      return Schema.decodeUnknownSync(resultSchema)(rawResults)
+      return Schema.decodeSync(resultSchema)(rawResults)
     } else {
       const { query, bindValues } = rawQueryOrQueryBuilder
       return dbState.select(query, prepareBindValues(bindValues, query))

package/src/rematerialize-from-eventlog.ts

@@ -3,8 +3,10 @@ import { Effect, Option, ReadonlyArray as EffectArray, Schema, Stream } from '@l
 
 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, SystemTables } from './schema/mod.ts'
+import { withSavepoint } from './sqlite-db-helper.ts'
 import type { PreparedBindValues } from './util.ts'
 import { sql } from './util.ts'
 
@@ -14,17 +16,26 @@ 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
 }) {
+  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
@@ -85,13 +96,11 @@ This likely means the schema has changed in an incompatible way.
     yield* materializeEvent(eventEncoded, { skipEventlog: true })
   })
 
-  const CHUNK_SIZE = 100
-
   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
@@ -101,6 +110,7 @@ LIMIT ${CHUNK_SIZE}
       const rows = stmt.select<SystemTables.EventlogMetaRow>({
         $seqNumGlobal: lastId.global,
         $seqNumClient: lastId.client,
+        $batchSize: batchSize,
       } as any as PreparedBindValues)
 
       if (EffectArray.isReadonlyArrayNonEmpty(rows) === false) {
@@ -125,14 +135,19 @@ LIMIT ${CHUNK_SIZE}
     }),
   ).pipe(
     Stream.bufferArray({ capacity: 2 }),
-    Stream.tap((row) =>
-      Effect.gen(function* () {
-        yield* processEvent(row)
-
-        processedEvents++
-        yield* onProgress({ done: processedEvents, total: eventsCount })
-      }),
+    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)),
     ),
-    Stream.runDrain,
+    Effect.ensuring(Effect.sync(() => stmt.finalize())),
   )
 }, Effect.withPerformanceMeasure('@livestore/common:rematerializeFromEventlog'))

package/src/schema/EventSequenceNumber/client.ts

@@ -181,22 +181,9 @@ const CompositeSchema = S.Struct({
   .annotate({ title: 'EventSequenceNumber.Composite' })
   .pipe(S.overrideToFormatter(() => (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,
-      })
-}
-
 /**
  * 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
@@ -209,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 = {

package/src/schema/schema.ts

@@ -73,7 +73,7 @@ export interface InternalState {
     readonly tables: Map<string, TableDef.Any>
     readonly migrations: MigrationOptions
     /** Compound hash of all table defs etc */
-    readonly hash: number
+    readonly hash: string
   }
   readonly materializers: Map<string, Materializer>
 }

package/src/schema/state/sqlite/client-document-def.test.ts

@@ -10,9 +10,25 @@ import {
   createOptimisticEventSchema,
   mergeDefaultValues,
 } from './client-document-def.ts'
+import { fingerprint } from './db-schema/ast/fingerprint.ts'
 import { getResultSchema } from './query-builder/impl.ts'
 
 describe('client document table', () => {
+  test('tracks application value-schema changes in the storage fingerprint', () => {
+    const first = clientDocument({
+      name: 'documents',
+      schema: Schema.Struct({ title: Schema.String.check(Schema.isMinLength(1)) }),
+      default: { id: 'default', value: { title: 'valid' } },
+    })
+    const second = clientDocument({
+      name: 'documents',
+      schema: Schema.Struct({ title: Schema.String.check(Schema.isMinLength(2)) }),
+      default: { id: 'default', value: { title: 'valid' } },
+    })
+
+    expect(fingerprint(first.sqliteDef.ast)).not.toBe(fingerprint(second.sqliteDef.ast))
+  })
+
   test('set event', () => {
     expect(patchId(tables.UiState.set({ showSidebar: false }, 'session-1'))).toMatchInlineSnapshot(`
       {
@@ -302,7 +318,7 @@ describe('client document table', () => {
       })
       const rowSchema = Schema.fromJsonString(optimisticSchema)
 
-      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(value))).toEqual(defaultValue)
+      expect(Schema.decodeSync(rowSchema)(JSON.stringify(value))).toEqual(defaultValue)
     })
 
     test('decodes valid persisted JSON (encoded shape)', () => {
@@ -313,7 +329,7 @@ describe('client document table', () => {
       })
       const rowSchema = Schema.fromJsonString(optimisticSchema)
 
-      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(validPayload))).toEqual({
+      expect(Schema.decodeSync(rowSchema)(JSON.stringify(validPayload))).toEqual({
         createdAt: new Date(42),
         avatar: new Uint8Array([1, 2]),
       })
@@ -327,7 +343,7 @@ describe('client document table', () => {
       })
       const rowSchema = Schema.fromJsonString(optimisticSchema)
 
-      expect(Schema.decodeUnknownSync(rowSchema)(JSON.stringify(extraFieldsPayload))).toEqual({
+      expect(Schema.decodeSync(rowSchema)(JSON.stringify(extraFieldsPayload))).toEqual({
         createdAt: new Date(42),
         avatar: new Uint8Array([1, 2]),
       })
@@ -345,7 +361,7 @@ describe('client document table', () => {
         value: JSON.stringify(value),
       }
 
-      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({ id: 'row-1', value: defaultValue })
+      expect(Schema.decodeSync(Doc.rowSchema)(row)).toEqual({ id: 'row-1', value: defaultValue })
     })
 
     test('decodes clientDocument rowSchema with valid encoded JSON', () => {
@@ -360,7 +376,7 @@ describe('client document table', () => {
         value: JSON.stringify(validPayload),
       }
 
-      expect(Schema.decodeUnknownSync(Doc.rowSchema)(row)).toEqual({
+      expect(Schema.decodeSync(Doc.rowSchema)(row)).toEqual({
         id: 'row-1',
         value: { createdAt: new Date(42), avatar: new Uint8Array([1, 2]) },
       })
@@ -382,7 +398,7 @@ describe('client document table', () => {
         },
       ]
 
-      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual(defaultValue)
+      expect(Schema.decodeSync(resultSchema)(rawDbResults)).toEqual(defaultValue)
     })
 
     test('decodes RowQuery result schema with valid encoded JSON', () => {
@@ -401,7 +417,7 @@ describe('client document table', () => {
         },
       ]
 
-      expect(Schema.decodeUnknownSync(resultSchema)(rawDbResults)).toEqual({
+      expect(Schema.decodeSync(resultSchema)(rawDbResults)).toEqual({
         createdAt: new Date(42),
         avatar: new Uint8Array([1, 2]),
       })

package/src/schema/state/sqlite/client-document-def.ts

@@ -241,7 +241,7 @@ export const createOptimisticEventSchema = ({
 
               if (hasValidFields === true) {
                 try {
-                  const decoded = Schema.decodeUnknownSync(targetSchema)(partialResult)
+                  const decoded = Schema.decodeSync(targetSchema)(partialResult)
                   return encodeTarget(decoded)
                 } catch {
                   // Even filtered fields don't match schema
@@ -264,7 +264,7 @@ export const createOptimisticEventSchema = ({
 
               // Try to decode the merged value
               try {
-                const decoded = Schema.decodeUnknownSync(valueSchema)(merged)
+                const decoded = Schema.decodeSync(valueSchema)(merged)
                 return encodeTarget(decoded)
               } catch {
                 // Merged value still doesn't match (e.g., type changes)

package/src/schema/state/sqlite/column-def.test.ts

@@ -1,7 +1,7 @@
 import { TestSchema } from 'effect/testing'
 import { assert, describe, expect, it } from 'vitest'
 
-import { Schema, SchemaAST, Struct } from '@livestore/utils/effect'
+import { Schema, SchemaAST, SchemaTransformation, Struct } from '@livestore/utils/effect'
 
 import * as State from '../mod.ts'
 import { withAutoIncrement, withColumnType, withDefault, withPrimaryKey, withUnique } from './column-annotations.ts'
@@ -26,6 +26,9 @@ describe('getColumnDefForSchema', () => {
     it('should map Schema.Date to text column', () => {
       const columnDef = State.SQLite.getColumnDefForSchema(Schema.Date)
       expect(columnDef.columnType).toBe('text')
+      const date = new Date('2026-01-02T03:04:05.678Z')
+      expect(Schema.encodeUnknownSync(columnDef.schema)(date)).toBe(date.toISOString())
+      expect(Schema.decodeSync(columnDef.schema)(date.toISOString())).toEqual(date)
       expect(Schema.toEncoded(columnDef.schema).ast._tag).toBe('String')
       expect(
         SchemaAST.resolveAt<{ readonly id: string }>('representation')(Schema.toType(columnDef.schema).ast)?.id,
@@ -47,6 +50,84 @@ describe('getColumnDefForSchema', () => {
       expect(State.SQLite.getColumnDefForSchema(schema).columnType).toBe('integer')
     })
 
+    it('should preserve bare Date checks on encoding and decoding', () => {
+      const schema = Schema.Date.check(Schema.isGreaterThanDate(new Date(0)))
+      const columnDef = State.SQLite.getColumnDefForSchema(schema)
+      const date = new Date('2026-01-02T03:04:05.678Z')
+
+      expect(Schema.encodeUnknownSync(columnDef.schema)(date)).toBe(date.toISOString())
+      expect(Schema.decodeSync(columnDef.schema)(date.toISOString())).toEqual(date)
+      expect(() => Schema.encodeUnknownSync(columnDef.schema)(new Date(0))).toThrow()
+      expect(() => Schema.decodeSync(columnDef.schema)(new Date(0).toISOString())).toThrow()
+    })
+
+    it('should round-trip transformations with an encoded Date', () => {
+      const schema = Schema.Date.pipe(
+        Schema.decodeTo(
+          Schema.String,
+          SchemaTransformation.transform({
+            decode: (date) => date.toISOString(),
+            encode: (value) => new Date(value),
+          }),
+        ),
+      )
+      const columnDef = State.SQLite.getColumnDefForSchema(schema)
+      const value = '2026-01-02T03:04:05.678Z'
+
+      expect(columnDef.columnType).toBe('text')
+      expect(Schema.encodeUnknownSync(columnDef.schema)(value)).toBe(value)
+      expect(Schema.decodeSync(columnDef.schema)(value)).toBe(value)
+    })
+
+    it.each(['nullable', 'optional'] as const)(
+      'should round-trip %s transformations with an encoded Date',
+      (wrapper) => {
+        const schema = Schema.Date.pipe(
+          Schema.decodeTo(
+            Schema.String,
+            SchemaTransformation.transform({
+              decode: (date) => date.toISOString(),
+              encode: (value) => new Date(value),
+            }),
+          ),
+        )
+        const field = wrapper === 'nullable' ? Schema.NullOr(schema) : Schema.optional(schema)
+        const { columns } = State.SQLite.table({ name: 'stamps', schema: Schema.Struct({ value: field }) }).sqliteDef
+        const columnDef = columns.value
+        const value = '2026-01-02T03:04:05.678Z'
+
+        expect(columnDef.nullable).toBe(true)
+        expect(columnDef.columnType).toBe('text')
+        const encoded = Schema.encodeUnknownSync(columnDef.schema)(value)
+        expect(Schema.decodeSync(columnDef.schema)(encoded)).toBe(value)
+        expect(encoded).toBe(value)
+        expect(Schema.encodeUnknownSync(columnDef.schema)(null)).toBeNull()
+        expect(Schema.decodeSync(columnDef.schema)(null)).toBeNull()
+      },
+    )
+
+    it('should round-trip transformations with an encoded nullable Date', () => {
+      const schema = Schema.NullOr(Schema.Date).pipe(
+        Schema.decodeTo(
+          Schema.String,
+          SchemaTransformation.transform({
+            decode: (date) => (date === null ? 'none' : date.toISOString()),
+            encode: (value) => (value === 'none' ? null : new Date(value)),
+          }),
+        ),
+      )
+      const { columns } = State.SQLite.table({ name: 'stamps', schema: Schema.Struct({ value: schema }) }).sqliteDef
+      const columnDef = columns.value
+      const value = '2026-01-02T03:04:05.678Z'
+      const encoded = Schema.encodeUnknownSync(columnDef.schema)(value)
+
+      expect(Schema.decodeSync(columnDef.schema)(encoded)).toBe(value)
+      expect(encoded).toBe(value)
+      expect(columnDef.nullable).toBe(true)
+      expect(Schema.encodeUnknownSync(columnDef.schema)('none')).toBeNull()
+      expect(Schema.decodeSync(columnDef.schema)(null)).toBe('none')
+    })
+
     it('should map Schema.BigInt to text column', () => {
       const columnDef = State.SQLite.getColumnDefForSchema(Schema.BigInt)
       expect(columnDef.columnType).toBe('text')
@@ -322,8 +403,8 @@ describe('getColumnDefForSchema', () => {
 
       expect(columnDef.columnType).toBe('blob')
       expect(columnDef.schema).toBe(schema)
-      expect(Schema.decodeUnknownSync(columnDef.schema)(new Uint8Array([1]))).toEqual(new Uint8Array([1]))
-      expect(() => Schema.decodeUnknownSync(columnDef.schema)(new Uint8Array())).toThrow()
+      expect(Schema.decodeSync(columnDef.schema)(new Uint8Array([1]))).toEqual(new Uint8Array([1]))
+      expect(() => Schema.decodeSync(columnDef.schema)(new Uint8Array())).toThrow()
     })
   })
 

package/src/schema/state/sqlite/column-def.ts

@@ -167,6 +167,21 @@ const getColumnForSchema = (schema: Schema.Top, nullable = false): SqliteDsl.Col
   // Get the encoded AST - what actually gets stored in SQLite
   const encodedAst = Schema.toEncoded(coreSchema).ast
 
+  // Adapt Date values on the encoded side to ISO text, then run the original
+  // codec so its checks and transformations are preserved in both directions.
+  if (hasDateRepresentation(stripNullable(encodedAst)) === true) {
+    const encodedNullable = hasNull(encodedAst)
+    const dateStorage = encodedNullable === true ? Schema.NullOr(Schema.DateFromString) : Schema.DateFromString
+    const adaptedSchema = dateStorage.pipe(Schema.decodeTo(coreSchema))
+    return {
+      ...SqliteDsl.text(),
+      schema: nullable === true ? Schema.NullOr(adaptedSchema) : adaptedSchema,
+      // Encoded nulls may decode to non-null values, so allow SQL NULL without
+      // bypassing the original codec's null transformation.
+      nullable: nullable === true || encodedNullable === true,
+    }
+  }
+
   // Check if the encoded type matches SQLite native types
   if (SchemaAST.isString(encodedAst) === true) {
     return SqliteDsl.text({ schema: coreSchema, nullable })
@@ -210,7 +225,7 @@ const stripNullable = (ast: SchemaAST.AST): SchemaAST.AST => {
     return coreTypes[0]!
   }
 
-  return new SchemaAST.Union(coreTypes, ast.mode, ast.annotations)
+  return new SchemaAST.Union(coreTypes, ast.options, ast.annotations)
 }
 
 const getLiteralColumnDefinition = (

package/src/schema/state/sqlite/db-schema/ast/fingerprint-digest.ts

@@ -0,0 +1,6 @@
+import { sha256 } from '@noble/hashes/sha2.js'
+
+import { Base64Url } from '@livestore/utils/effect'
+
+/** Preserve every digest bit while staying inside the 56-character SQLite VFS filename limit. */
+export const digestToFingerprint = (bytes: Uint8Array): string => Base64Url.encode(sha256(bytes))