@livestore/common 0.4.0-dev.2 → 0.4.0-dev.20

package/src/schema/schema.ts

@@ -1,15 +1,19 @@
 import { isReadonlyArray, shouldNeverHappen } from '@livestore/utils'
 
 import type { MigrationOptions } from '../adapter-types.ts'
-import type { EventDef, EventDefRecord, Materializer } from './EventDef.ts'
+import type { EventDef, EventDefRecord, Materializer } from './EventDef/mod.ts'
 import { tableIsClientDocumentTable } from './state/sqlite/client-document-def.ts'
 import type { SqliteDsl } from './state/sqlite/db-schema/mod.ts'
-import { stateSystemTables } from './state/sqlite/system-tables.ts'
+import { stateSystemTables } from './state/sqlite/system-tables/state-tables.ts'
 import type { TableDef } from './state/sqlite/table-def.ts'
+import type { UnknownEvents } from './unknown-events.ts'
+import { normalizeUnknownEventHandling } from './unknown-events.ts'
 
 export const LiveStoreSchemaSymbol = Symbol.for('livestore.LiveStoreSchema')
 export type LiveStoreSchemaSymbol = typeof LiveStoreSchemaSymbol
 
+export const UNKNOWN_EVENT_SCHEMA_HASH = -1
+
 export interface LiveStoreSchema<
   TDbSchema extends SqliteDsl.DbSchema = SqliteDsl.DbSchema,
   TEventsDefRecord extends EventDefRecord = EventDefRecord,
@@ -22,6 +26,7 @@ export interface LiveStoreSchema<
 
   readonly state: InternalState
   readonly eventsDefsMap: Map<string, EventDef.AnyWithoutFn>
+  readonly unknownEventHandling: UnknownEvents.HandlingConfig
   readonly devtools: {
     /** @default 'default' */
     readonly alias: string
@@ -32,6 +37,30 @@ export namespace LiveStoreSchema {
   export type Any = LiveStoreSchema<any, any>
 }
 
+/**
+ * Runtime type guard for LiveStoreSchema.
+ *
+ * The guard intentionally performs lightweight structural checks that are
+ * stable across implementations. It verifies the identifying symbol marker
+ * and the presence of core maps/state used at runtime.
+ */
+export const isLiveStoreSchema = (value: unknown): value is LiveStoreSchema<any, any> => {
+  if (typeof value !== 'object' || value === null) return false
+
+  const v: any = value
+
+  // Identity marker must match exactly
+  if (v.LiveStoreSchemaSymbol !== LiveStoreSchemaSymbol) return false
+
+  // Core structures used at runtime
+  const hasEventsMap = v.eventsDefsMap instanceof Map
+  const hasStateSqliteTables = v.state?.sqlite?.tables instanceof Map
+  const hasStateMaterializers = v.state?.materializers instanceof Map
+  const hasDevtoolsAlias = typeof v.devtools?.alias === 'string'
+
+  return hasEventsMap && hasStateSqliteTables && hasStateMaterializers && hasDevtoolsAlias
+}
+
 // TODO abstract this further away from sqlite/tables
 export interface InternalState {
   readonly sqlite: {
@@ -55,6 +84,10 @@ export interface InputSchema {
      */
     readonly alias?: string
   }
+  /**
+   * Configures how unknown events should be handled. Defaults to `{ strategy: 'warn' }`.
+   */
+  readonly unknownEventHandling?: UnknownEvents.HandlingConfig
 }
 
 export const makeSchema = <TInputSchema extends InputSchema>(
@@ -89,12 +122,15 @@ export const makeSchema = <TInputSchema extends InputSchema>(
     }
   }
 
+  const unknownEventHandling = normalizeUnknownEventHandling(inputSchema.unknownEventHandling)
+
   return {
     LiveStoreSchemaSymbol,
     _DbSchemaType: Symbol.for('livestore.DbSchemaType') as any,
     _EventDefMapType: Symbol.for('livestore.EventDefMapType') as any,
     state,
     eventsDefsMap,
+    unknownEventHandling,
     devtools: {
       alias: inputSchema.devtools?.alias ?? 'default',
     },
@@ -110,7 +146,7 @@ export const getEventDef = <TSchema extends LiveStoreSchema>(
 } => {
   const eventDef = schema.eventsDefsMap.get(eventName)
   if (eventDef === undefined) {
-    return shouldNeverHappen(`No mutation definition found for \`${eventName}\`.`)
+    return shouldNeverHappen(`No event definition found for \`${eventName}\`.`)
   }
   const materializer = schema.state.materializers.get(eventName)
   if (materializer === undefined) {

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

@@ -2,7 +2,7 @@ import { Schema } from '@livestore/utils/effect'
 import { describe, expect, test } from 'vitest'
 
 import { tables } from '../../../__tests__/fixture.ts'
-import type * as LiveStoreEvent from '../../LiveStoreEvent.ts'
+import type * as LiveStoreEvent from '../../LiveStoreEvent/mod.ts'
 import { ClientDocumentTableDefSymbol, clientDocument, mergeDefaultValues } from './client-document-def.ts'
 
 describe('client document table', () => {
@@ -50,6 +50,7 @@ describe('client document table', () => {
         currentFacts: new Map(),
         query: {} as any, // unused
         eventDef: Doc[ClientDocumentTableDefSymbol].derived.setEventDef,
+        event: {} as any, // unused in this test
       })
     }
 
@@ -230,10 +231,26 @@ describe('client document table', () => {
         }
       `)
     })
+
+    test('any value (Schema.Any) should fully replace', () => {
+      expect(forSchema(Schema.Any, { a: 1 }, 'id1')).toMatchInlineSnapshot(`
+        {
+          "bindValues": [
+            "id1",
+            "{"a":1}",
+            "{"a":1}",
+          ],
+          "sql": "INSERT INTO 'test' (id, value) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET value = ?",
+          "writeTables": Set {
+            "test",
+          },
+        }
+      `)
+    })
   })
 })
 
-const patchId = (muationEvent: LiveStoreEvent.PartialAnyDecoded) => {
+const patchId = (muationEvent: LiveStoreEvent.Input.Decoded) => {
   // TODO use new id paradigm
   const id = `00000000-0000-0000-0000-000000000000`
   return { ...muationEvent, id }

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

@@ -1,11 +1,11 @@
 import { shouldNeverHappen } from '@livestore/utils'
 import type { Option, Types } from '@livestore/utils/effect'
-import { Schema, SchemaAST } from '@livestore/utils/effect'
+import { Schema } from '@livestore/utils/effect'
 
 import { SessionIdSymbol } from '../../../adapter-types.ts'
 import { sql } from '../../../util.ts'
-import type { EventDef, Materializer } from '../../EventDef.ts'
-import { defineEvent, defineMaterializer } from '../../EventDef.ts'
+import type { EventDef, Materializer } from '../../EventDef/mod.ts'
+import { defineEvent, defineMaterializer } from '../../EventDef/mod.ts'
 import { SqliteDsl } from './db-schema/mod.ts'
 import type { QueryBuilder, QueryBuilderAst } from './query-builder/mod.ts'
 import { QueryBuilderAstSymbol, QueryBuilderTypeId } from './query-builder/mod.ts'
@@ -62,9 +62,16 @@ export const clientDocument = <
     },
   } satisfies ClientDocumentTableOptions<TType>
 
+  // Column needs optimistic schema to read historical data formats
+  const optimisticColumnSchema = createOptimisticEventSchema({
+    valueSchema,
+    defaultValue: options.default.value,
+    partialSet: false, // Column always stores full documents
+  })
+
   const columns = {
     id: SqliteDsl.text({ primaryKey: true }),
-    value: SqliteDsl.json({ schema: valueSchema }),
+    value: SqliteDsl.json({ schema: optimisticColumnSchema }),
   }
 
   const tableDef = table({ name, columns })
@@ -140,6 +147,105 @@ export const mergeDefaultValues = <T>(defaultValues: T, explicitDefaultValues: T
   }, {} as any)
 }
 
+/**
+ * Creates an optimistic schema that accepts historical event formats
+ * and transforms them to the current schema, preserving data and intent.
+ *
+ * Decision Matrix for Schema Changes:
+ *
+ * | Change Type         | Partial Set         | Full Set                        | Strategy                |
+ * |---------------------|---------------------|----------------------------------|-------------------------|
+ * | **Compatible Changes**                                                                                 |
+ * | Add optional field  | Preserve existing   | Preserve existing, new field undefined | Direct decode or merge   |
+ * | Add required field  | Preserve existing   | Preserve existing, new field from default | Merge with defaults      |
+ * | **Incompatible Changes**                                                                              |
+ * | Remove field        | Drop removed field  | Drop removed field, preserve others     | Filter & decode         |
+ * | Type change         | Use default for field | Use default for changed field         | Selective merge         |
+ * | Rename field        | Use default         | Use default (can't detect rename)       | Fall back to default    |
+ * | **Edge Cases**                                                                                       |
+ * | Empty event         | Return {}           | Return full default                     | Fallback handling       |
+ * | Invalid structure   | Return {}           | Return full default                     | Fallback handling       |
+ */
+export const createOptimisticEventSchema = ({
+  valueSchema,
+  defaultValue,
+  partialSet,
+}: {
+  valueSchema: Schema.Schema<any, any>
+  defaultValue: any
+  partialSet: boolean
+}) => {
+  const targetSchema = partialSet ? Schema.partial(valueSchema) : valueSchema
+
+  return Schema.transform(
+    Schema.Unknown, // Accept any historical event structure
+    targetSchema, // Output current schema
+    {
+      decode: (eventValue) => {
+        // Try direct decode first (for current schema events)
+        try {
+          return Schema.decodeUnknownSync(targetSchema)(eventValue)
+        } catch {
+          // Optimistic decoding for historical events
+
+          // Handle null/undefined/non-object cases
+          if (typeof eventValue !== 'object' || eventValue === null) {
+            console.warn(`Client document: Non-object event value, using ${partialSet ? 'empty partial' : 'defaults'}`)
+            return partialSet ? {} : defaultValue
+          }
+
+          if (partialSet) {
+            // For partial sets: only preserve fields that exist in new schema
+            const partialResult: Record<string, unknown> = {}
+            let hasValidFields = false
+
+            for (const [key, value] of Object.entries(eventValue as Record<string, unknown>)) {
+              if (key in defaultValue) {
+                partialResult[key] = value
+                hasValidFields = true
+              }
+              // Drop fields that don't exist in new schema
+            }
+
+            if (hasValidFields) {
+              try {
+                return Schema.decodeUnknownSync(targetSchema)(partialResult)
+              } catch {
+                // Even filtered fields don't match schema
+                console.warn('Client document: Partial fields incompatible, returning empty partial')
+                return {}
+              }
+            }
+            return {}
+          } else {
+            // Full set: merge old data with new defaults
+            const merged: Record<string, unknown> = { ...defaultValue }
+
+            // Override defaults with valid fields from old event
+            for (const [key, value] of Object.entries(eventValue as Record<string, unknown>)) {
+              if (key in defaultValue) {
+                merged[key] = value
+              }
+              // Drop fields that don't exist in new schema
+            }
+
+            // Try to decode the merged value
+            try {
+              return Schema.decodeUnknownSync(valueSchema)(merged)
+            } catch {
+              // Merged value still doesn't match (e.g., type changes)
+              // Fall back to pure defaults
+              console.warn('Client document: Could not preserve event data, using defaults')
+              return defaultValue
+            }
+          }
+        }
+      },
+      encode: (value) => value, // Pass-through for encoding
+    },
+  )
+}
+
 export const deriveEventAndMaterializer = ({
   name,
   valueSchema,
@@ -155,7 +261,7 @@ export const deriveEventAndMaterializer = ({
     name: `${name}Set`,
     schema: Schema.Struct({
       id: Schema.Union(Schema.String, Schema.UniqueSymbolFromSelf(SessionIdSymbol)),
-      value: partialSet ? Schema.partial(valueSchema) : valueSchema,
+      value: createOptimisticEventSchema({ valueSchema, defaultValue, partialSet }),
     }).annotations({ title: `${name}Set:Args` }),
     clientOnly: true,
     derived: true,
@@ -167,7 +273,7 @@ export const deriveEventAndMaterializer = ({
     }
 
     // Override the full value if it's not an object or no partial set is allowed
-    const schemaProps = SchemaAST.getPropertySignatures(valueSchema.ast)
+    const schemaProps = Schema.getResolvedPropertySignatures(valueSchema)
     if (schemaProps.length === 0 || partialSet === false) {
       const valueColJsonSchema = Schema.parseJson(valueSchema)
       const encodedInsertValue = Schema.encodeSyncDebug(valueColJsonSchema)(value ?? defaultValue)
@@ -281,8 +387,14 @@ export namespace ClientDocumentTableOptions {
     }
   }
 
+  type IsStructLike<T> = T extends {} ? true : false
+
   export type WithDefaults<TInput extends Input<any>> = {
-    partialSet: TInput['partialSet'] extends false ? false : true
+    partialSet: TInput['partialSet'] extends false
+      ? false
+      : IsStructLike<TInput['default']['value']> extends true
+        ? true
+        : false
     default: {
       id: TInput['default']['id'] extends string | SessionIdSymbol ? TInput['default']['id'] : undefined
       value: TInput['default']['value']
@@ -467,5 +579,5 @@ export namespace ClientDocumentTableDef {
       ) => QueryBuilder<TType, ClientDocumentTableDef.TableDefBase_<TName, TType>, QueryBuilder.ApiFeature>
 }
 
-export const ClientDocumentTableDefSymbol = Symbol('ClientDocumentTableDef')
+export const ClientDocumentTableDefSymbol = Symbol.for('livestore.ClientDocumentTableDef')
 export type ClientDocumentTableDefSymbol = typeof ClientDocumentTableDefSymbol

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

@@ -65,7 +65,7 @@ describe.concurrent('annotations', () => {
       })
 
       test('Union of same type with compatible column type', () => {
-        const unionSchema = Schema.Union(Schema.Literal('a'), Schema.Literal('b'))
+        const unionSchema = Schema.Literal('a', 'b')
         expect(() => withColumnType(unionSchema, 'text')).not.toThrow()
       })
 

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

@@ -1,5 +1,5 @@
 import type { Schema } from '@livestore/utils/effect'
-import { dual } from '@livestore/utils/effect'
+import { dual, Option, SchemaAST } from '@livestore/utils/effect'
 import type { SqliteDsl } from './db-schema/mod.ts'
 
 export const PrimaryKeyId = Symbol.for('livestore/state/sqlite/annotations/primary-key')
@@ -32,7 +32,7 @@ Here are the knobs you can turn per-column when you CREATE TABLE (or ALTER TABLE
  * Adds a primary key annotation to a schema.
  */
 export const withPrimaryKey = <T extends Schema.Schema.All>(schema: T) =>
-  schema.annotations({ [PrimaryKeyId]: true }) as T
+  applyAnnotations(schema, { [PrimaryKeyId]: true })
 
 /**
  * Adds a column type annotation to a schema.
@@ -43,19 +43,19 @@ export const withColumnType: {
   <T extends Schema.Schema.All>(schema: T, type: SqliteDsl.FieldColumnType): T
 } = dual(2, <T extends Schema.Schema.All>(schema: T, type: SqliteDsl.FieldColumnType) => {
   validateSchemaColumnTypeCompatibility(schema, type)
-  return schema.annotations({ [ColumnType]: type }) as T
+  return applyAnnotations(schema, { [ColumnType]: type })
 })
 
 /**
  * Adds an auto-increment annotation to a schema.
  */
 export const withAutoIncrement = <T extends Schema.Schema.All>(schema: T) =>
-  schema.annotations({ [AutoIncrement]: true }) as T
+  applyAnnotations(schema, { [AutoIncrement]: true })
 
 /**
  * Adds a unique constraint annotation to a schema.
  */
-export const withUnique = <T extends Schema.Schema.All>(schema: T) => schema.annotations({ [Unique]: true }) as T
+export const withUnique = <T extends Schema.Schema.All>(schema: T) => applyAnnotations(schema, { [Unique]: true })
 
 /**
  * Adds a default value annotation to a schema.
@@ -64,7 +64,7 @@ export const withDefault: {
   // TODO make type safe
   <T extends Schema.Schema.All>(schema: T, value: unknown): T
   (value: unknown): <T extends Schema.Schema.All>(schema: T) => T
-} = dual(2, <T extends Schema.Schema.All>(schema: T, value: unknown) => schema.annotations({ [Default]: value }) as T)
+} = dual(2, <T extends Schema.Schema.All>(schema: T, value: unknown) => applyAnnotations(schema, { [Default]: value }))
 
 /**
  * Validates that a schema is compatible with the specified SQLite column type
@@ -75,3 +75,13 @@ const validateSchemaColumnTypeCompatibility = (
 ): void => {
   // TODO actually implement this
 }
+
+const applyAnnotations = <T extends Schema.Schema.All>(schema: T, overrides: Record<PropertyKey, unknown>): T => {
+  const identifier = SchemaAST.getIdentifierAnnotation(schema.ast)
+  const shouldPreserveIdentifier = Option.isSome(identifier) && !(SchemaAST.IdentifierAnnotationId in overrides)
+  const annotations: Record<PropertyKey, unknown> = shouldPreserveIdentifier
+    ? { ...overrides, [SchemaAST.IdentifierAnnotationId]: identifier.value }
+    : overrides
+
+  return schema.annotations(annotations) as T
+}

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

@@ -1,5 +1,5 @@
 import { Schema } from '@livestore/utils/effect'
-import { describe, expect, it } from 'vitest'
+import { assert, describe, expect, it } from 'vitest'
 
 import * as State from '../mod.ts'
 import { withAutoIncrement, withColumnType, withDefault, withPrimaryKey, withUnique } from './column-annotations.ts'
@@ -273,17 +273,34 @@ describe('getColumnDefForSchema', () => {
         INACTIVE: 'inactive',
       })
 
-      const StatusUnion = Schema.Union(Schema.Literal('pending'), Schema.Literal('active'), Schema.Literal('inactive'))
+      const StatusUnion = Schema.Literal('pending', 'active', 'inactive')
 
       expect(State.SQLite.getColumnDefForSchema(StatusEnum).columnType).toBe('text')
       expect(State.SQLite.getColumnDefForSchema(StatusUnion).columnType).toBe('text')
     })
+
+    it('should handle unions of numeric literals as integer column', () => {
+      const IntervalSchema = Schema.Literal(1, 5, 15, 30)
+
+      const columnDef = State.SQLite.getColumnDefForSchema(IntervalSchema)
+
+      expect(columnDef.columnType).toBe('integer')
+    })
+
+    it('should handle unions of non-integer numeric literals as real column', () => {
+      const PercentSchema = Schema.Literal(0.1, 0.2, 0.25)
+
+      const columnDef = State.SQLite.getColumnDefForSchema(PercentSchema)
+
+      expect(columnDef.columnType).toBe('real')
+    })
   })
 
   describe('binary data', () => {
     it('should handle Uint8Array as blob column', () => {
       const columnDef = State.SQLite.getColumnDefForSchema(Schema.Uint8Array)
-      expect(columnDef.columnType).toBe('text') // Stored as JSON
+      expect(columnDef.columnType).toBe('blob')
+      expect(columnDef.schema.toString()).toBe('Uint8ArrayFromSelf')
     })
   })
 
@@ -381,6 +398,19 @@ describe('getColumnDefForSchema', () => {
       expect((table.rowSchema as any).fields.count.toString()).toBe('Int | null')
     })
 
+    it('should treat unions of string literals as text columns without JSON parsing', () => {
+      const schema = Schema.Struct({
+        id: Schema.String,
+        status: Schema.Literal('idle', 'running', 'stopped'),
+      })
+
+      const table = State.SQLite.table({ name: 'timers', schema })
+
+      expect(table.sqliteDef.columns.status.columnType).toBe('text')
+      expect(table.sqliteDef.columns.status.schema.toString()).toBe('"idle" | "running" | "stopped"')
+      expect((table.rowSchema as any).fields.status.toString()).toBe('"idle" | "running" | "stopped"')
+    })
+
     it('should handle Schema.NullOr with complex types', () => {
       const schema = Schema.Struct({
         data: Schema.NullOr(Schema.Struct({ value: Schema.Number })),
@@ -539,7 +569,7 @@ describe('getColumnDefForSchema', () => {
 
       it('should work with column type annotation', () => {
         const UserSchema = Schema.Struct({
-          id: Schema.Number.pipe(withColumnType('integer')).pipe(withPrimaryKey),
+          id: Schema.Number.pipe(withColumnType('integer'), withPrimaryKey),
           name: Schema.String,
         })
 
@@ -571,7 +601,7 @@ describe('getColumnDefForSchema', () => {
     describe('withAutoIncrement', () => {
       it('should add autoIncrement annotation to schema', () => {
         const UserSchema = Schema.Struct({
-          id: Schema.Int.pipe(withPrimaryKey).pipe(withAutoIncrement),
+          id: Schema.Int.pipe(withPrimaryKey, withAutoIncrement),
           name: Schema.String,
         })
         const userTable = State.SQLite.table({
@@ -623,6 +653,29 @@ describe('getColumnDefForSchema', () => {
           table2.sqliteDef.columns.count.default._tag === 'Some' && table2.sqliteDef.columns.count.default.value,
         ).toBe(0)
       })
+
+      it('should support thunk defaults without eager evaluation', () => {
+        let counter = 0
+        const UserSchema = Schema.Struct({
+          id: Schema.String.pipe(
+            withDefault(() => {
+              counter += 1
+              return `user-${counter}`
+            }),
+          ),
+        })
+
+        const table = State.SQLite.table({ name: 'users_with_thunk', schema: UserSchema })
+
+        expect(counter).toBe(0)
+        expect(table.sqliteDef.columns.id.default._tag).toBe('Some')
+        if (table.sqliteDef.columns.id.default._tag === 'Some') {
+          const defaultThunk = table.sqliteDef.columns.id.default.value
+          assert(typeof defaultThunk === 'function')
+          expect(defaultThunk()).toBe('user-1')
+          expect(defaultThunk()).toBe('user-2')
+        }
+      })
     })
 
     describe('withUnique', () => {
@@ -668,7 +721,7 @@ describe('getColumnDefForSchema', () => {
 
     describe('combined annotations', () => {
       it('should work with multiple annotations', () => {
-        const schema = Schema.Uint8ArrayFromBase64.pipe(withColumnType('blob')).pipe(withPrimaryKey)
+        const schema = Schema.Uint8ArrayFromBase64.pipe(withColumnType('blob'), withPrimaryKey)
 
         const UserSchema = Schema.Struct({
           id: schema,
@@ -686,7 +739,7 @@ describe('getColumnDefForSchema', () => {
 
       it('should combine all annotations', () => {
         const UserSchema = Schema.Struct({
-          id: Schema.Int.pipe(withPrimaryKey).pipe(withAutoIncrement),
+          id: Schema.Int.pipe(withPrimaryKey, withAutoIncrement),
           email: Schema.String.pipe(withUnique),
           status: Schema.String.pipe(withDefault('active')),
           metadata: Schema.Unknown.pipe(withColumnType('text')),

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

@@ -179,26 +179,17 @@ const getColumnForSchema = (schema: Schema.Schema.AnyNoContext, nullable = false
     return SqliteDsl.real({ schema: coreSchema, nullable })
   }
 
-  // Literals based on their type
-  if (SchemaAST.isLiteral(coreAst)) {
-    const value = coreAst.literal
-    if (typeof value === 'boolean') return SqliteDsl.boolean({ nullable })
-  }
-
-  // Literals based on their encoded type
-  if (SchemaAST.isLiteral(encodedAst)) {
-    const value = encodedAst.literal
-    if (typeof value === 'string') return SqliteDsl.text({ schema: coreSchema, nullable })
-    if (typeof value === 'number') {
-      // Check if the original schema is Int
-      const id = SchemaAST.getIdentifierAnnotation(coreAst).pipe(Option.getOrElse(() => ''))
-      if (id === 'Int') {
-        return SqliteDsl.integer({ schema: coreSchema, nullable })
-      }
-      return SqliteDsl.real({ schema: coreSchema, nullable })
-    }
+  if (isUint8ArraySchema(coreAst) || isUint8ArraySchema(encodedAst)) {
+    return SqliteDsl.blob({ schema: Schema.Uint8ArrayFromSelf as Schema.Schema<Uint8Array<ArrayBuffer>>, nullable })
   }
 
+  const literalColumn = getLiteralColumnDefinition(encodedAst, coreSchema, nullable, coreAst)
+  if (literalColumn) return literalColumn
+
+  // Fallback to checking the original AST in case the encoded schema differs
+  const coreLiteralColumn = getLiteralColumnDefinition(coreAst, coreSchema, nullable, coreAst)
+  if (coreLiteralColumn) return coreLiteralColumn
+
   // Everything else needs JSON encoding
   return SqliteDsl.json({ schema: coreSchema, nullable })
 }
@@ -206,10 +197,86 @@ const getColumnForSchema = (schema: Schema.Schema.AnyNoContext, nullable = false
 const stripNullable = (ast: SchemaAST.AST): SchemaAST.AST => {
   if (!SchemaAST.isUnion(ast)) return ast
 
-  // Find non-null/undefined type
-  const core = ast.types.find(
+  // Filter out null/undefined members while preserving any annotations on the union
+  const coreTypes = ast.types.filter(
     (type) => !(SchemaAST.isLiteral(type) && type.literal === null) && !SchemaAST.isUndefinedKeyword(type),
   )
 
-  return core || ast
+  if (coreTypes.length === 0 || coreTypes.length === ast.types.length) {
+    return ast
+  }
+
+  if (coreTypes.length === 1) {
+    return coreTypes[0]!
+  }
+
+  return SchemaAST.Union.make(coreTypes, ast.annotations)
+}
+
+const getLiteralColumnDefinition = (
+  ast: SchemaAST.AST,
+  schema: Schema.Schema.AnyNoContext,
+  nullable: boolean,
+  sourceAst: SchemaAST.AST,
+): SqliteDsl.ColumnDefinition.Any | null => {
+  const literalValues = extractLiteralValues(ast)
+  if (!literalValues) return null
+
+  const literalType = getLiteralValueType(literalValues)
+  switch (literalType) {
+    case 'string':
+      return SqliteDsl.text({ schema, nullable })
+    case 'number': {
+      const id = SchemaAST.getIdentifierAnnotation(sourceAst).pipe(Option.getOrElse(() => ''))
+      if (id === 'Int' || id === 'DateFromNumber') {
+        return SqliteDsl.integer({ schema, nullable })
+      }
+
+      const useIntegerColumn =
+        literalValues.length > 1 && literalValues.every((value) => typeof value === 'number' && Number.isInteger(value))
+
+      return useIntegerColumn ? SqliteDsl.integer({ schema, nullable }) : SqliteDsl.real({ schema, nullable })
+    }
+    case 'boolean':
+      return SqliteDsl.boolean({ nullable })
+    case 'bigint':
+      return SqliteDsl.integer({ schema, nullable })
+    default:
+      return null
+  }
+}
+
+const extractLiteralValues = (ast: SchemaAST.AST): ReadonlyArray<SchemaAST.LiteralValue> | null => {
+  if (SchemaAST.isLiteral(ast)) return [ast.literal]
+
+  if (SchemaAST.isUnion(ast) && ast.types.length > 0 && ast.types.every((type) => SchemaAST.isLiteral(type))) {
+    return ast.types.map((type) => (type as SchemaAST.Literal).literal)
+  }
+
+  return null
+}
+
+const getLiteralValueType = (
+  literals: ReadonlyArray<SchemaAST.LiteralValue>,
+): 'string' | 'number' | 'boolean' | 'bigint' | null => {
+  const literalTypes = new Set(literals.map((value) => (value === null ? 'null' : typeof value)))
+  if (literalTypes.size !== 1) return null
+
+  const [literalType] = literalTypes
+  return literalType === 'string' || literalType === 'number' || literalType === 'boolean' || literalType === 'bigint'
+    ? literalType
+    : null
+}
+
+const isUint8ArraySchema = (ast: SchemaAST.AST): boolean => {
+  const identifier = SchemaAST.getIdentifierAnnotation(ast)
+  if (Option.isSome(identifier) && identifier.value.includes('Uint8Array')) {
+    return true
+  }
+
+  if (SchemaAST.isTupleType(ast)) {
+    return ast.elements.length === 0 && ast.rest.length === 1 && SchemaAST.isNumberKeyword(ast.rest[0]!.type)
+  }
+
+  return false
 }