@livestore/common 0.4.0-dev.9 → 0.5.0-dev.0

package/src/schema/state/sqlite/query-builder/impl.ts

@@ -1,6 +1,5 @@
-/** biome-ignore-all lint/complexity/noArguments: using arguments is fine here */
 import { casesHandled, shouldNeverHappen } from '@livestore/utils'
-import { Match, Option, Predicate, Schema } from '@livestore/utils/effect'
+import { Match, Option, Predicate, Schema, Struct } from '@livestore/utils/effect'
 
 import type { TableDefBase } from '../table-def.ts'
 import type { QueryBuilder, QueryBuilderAst } from './api.ts'
@@ -9,7 +8,7 @@ import { astToSql } from './astToSql.ts'
 export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
   tableDef: TTableDef,
   ast: QueryBuilderAst = emptyAst(tableDef),
-): QueryBuilder<TResult, TTableDef, never> => {
+): QueryBuilder<TResult, TTableDef> => {
   const api = {
     select() {
       assertSelectQueryBuilderAst(ast)
@@ -18,24 +17,26 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
 
       // Pluck if there's only one column selected
       if (params.length === 1) {
+        // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- arguments-based overload dispatch requires manual narrowing
         const [col] = params as any as [string]
         return makeQueryBuilder(tableDef, {
           ...ast,
-          resultSchemaSingle: ast.resultSchemaSingle.pipe(Schema.pluck(col)),
+          resultSchemaSingle: ast.tableDef.rowSchema.pipe(Schema.pluck(col)),
           select: { columns: [col] },
         })
       }
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- arguments-based overload dispatch requires manual narrowing
       const columns = params as unknown as ReadonlyArray<string>
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         ...ast,
         resultSchemaSingle:
-          columns.length === 0 ? ast.resultSchemaSingle : ast.resultSchemaSingle.pipe(Schema.pick(...columns)),
+          columns.length === 0 ? ast.resultSchemaSingle : ast.tableDef.rowSchema.mapFields(Struct.pick(columns)),
         select: { columns },
       }) as any
     },
-    // biome-ignore lint/complexity/useArrowFunction: prefer function over arrow function for this case
     where: function () {
       if (ast._tag === 'InsertQuery') return invalidQueryBuilder('Cannot use where with insert')
       if (ast._tag === 'RowQuery') return invalidQueryBuilder('Cannot use where with row')
@@ -45,8 +46,9 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         const newOps = Object.entries(params)
           .filter(([, value]) => value !== undefined)
           .map<QueryBuilderAst.Where>(([col, value]) =>
-            Predicate.hasProperty(value, 'op') && Predicate.hasProperty(value, 'value')
-              ? ({ col, op: value.op, value: value.value } as any)
+            Predicate.hasProperty(value, 'op') === true && Predicate.hasProperty(value, 'value') === true
+              ? // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- where clause construction; shape validated at runtime
+                ({ col, op: value.op, value: value.value } as any)
               : { col, op: '=', value },
           )
 
@@ -55,6 +57,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
           case 'SelectQuery':
           case 'UpdateQuery':
           case 'DeleteQuery': {
+            // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
             return makeQueryBuilder(tableDef, {
               ...ast,
               where: [...ast.where, ...newOps],
@@ -75,6 +78,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         case 'SelectQuery':
         case 'UpdateQuery':
         case 'DeleteQuery': {
+          // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
           return makeQueryBuilder(tableDef, {
             ...ast,
             where: [...ast.where, { col, op, value }],
@@ -92,6 +96,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       if (arguments.length === 0 || arguments.length > 2) return invalidQueryBuilder()
 
       if (arguments.length === 1) {
+        // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- arguments-based overload dispatch requires manual narrowing
         const params = arguments[0] as QueryBuilder.OrderByParams<TTableDef>
         return makeQueryBuilder(tableDef, {
           ...ast,
@@ -99,8 +104,10 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         })
       }
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- arguments-based overload dispatch requires manual narrowing
       const [col, direction] = arguments as any as [keyof TTableDef['sqliteDef']['columns'] & string, 'asc' | 'desc']
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         ...ast,
         orderBy: [...ast.orderBy, { col, direction }],
@@ -117,14 +124,19 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       return makeQueryBuilder(tableDef, { ...ast, offset: Option.some(offset) })
     },
     count: () => {
-      if (isRowQuery(ast) || ast._tag === 'InsertQuery' || ast._tag === 'UpdateQuery' || ast._tag === 'DeleteQuery')
+      if (
+        isRowQuery(ast) === true ||
+        ast._tag === 'InsertQuery' ||
+        ast._tag === 'UpdateQuery' ||
+        ast._tag === 'DeleteQuery'
+      )
         return invalidQueryBuilder()
 
       return makeQueryBuilder(tableDef, {
         _tag: 'CountQuery',
         tableDef,
         where: ast.where,
-        resultSchema: Schema.Struct({ count: Schema.Number }).pipe(
+        resultSchema: Schema.Struct({ count: Schema.Finite }).pipe(
           Schema.pluck('count'),
           Schema.Array,
           Schema.headOrElse(),
@@ -172,6 +184,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
     insert: (values) => {
       const filteredValues = Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined))
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         _tag: 'InsertQuery',
         tableDef,
@@ -186,7 +199,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       action: 'ignore' | 'replace' | 'update',
       updateValues?: Record<string, unknown>,
     ) => {
-      const targets = Array.isArray(targetOrTargets) ? targetOrTargets : [targetOrTargets]
+      const targets = Array.isArray(targetOrTargets) === true ? targetOrTargets : [targetOrTargets]
 
       assertInsertQueryBuilderAst(ast)
 
@@ -200,6 +213,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
         Match.exhaustive,
       )
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         ...ast,
         onConflict,
@@ -209,10 +223,11 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
     returning: (...columns) => {
       assertWriteQueryBuilderAst(ast)
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         ...ast,
         returning: columns,
-        resultSchema: tableDef.rowSchema.pipe(Schema.pick(...columns), Schema.Array),
+        resultSchema: tableDef.rowSchema.mapFields(Struct.pick(columns)).pipe(Schema.Array),
       }) as any
     },
 
@@ -222,6 +237,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       // Preserve where clauses if coming from a SelectQuery
       const whereClause = ast._tag === 'SelectQuery' ? ast.where : []
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         _tag: 'UpdateQuery',
         tableDef,
@@ -236,6 +252,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
       // Preserve where clauses if coming from a SelectQuery
       const whereClause = ast._tag === 'SelectQuery' ? ast.where : []
 
+      // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- query builder return type depends on AST state; consumer type safety enforced by api.ts
       return makeQueryBuilder(tableDef, {
         _tag: 'DeleteQuery',
         tableDef,
@@ -249,6 +266,7 @@ export const makeQueryBuilder = <TResult, TTableDef extends TableDefBase>(
   return {
     [QueryBuilderTypeId]: QueryBuilderTypeId,
     [QueryBuilderAstSymbol]: ast,
+    // oxlint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- phantom type field for generic inference only
     ResultType: 'only-for-type-inference' as TResult,
     asSql: () => astToSql(ast),
     toString: () => {
@@ -278,19 +296,19 @@ const emptyAst = (tableDef: TableDefBase): QueryBuilderAst.SelectQuery => ({
 
 // Helper functions
 
-function assertSelectQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.SelectQuery {
+const assertSelectQueryBuilderAst: (ast: QueryBuilderAst) => asserts ast is QueryBuilderAst.SelectQuery = (ast) => {
   if (ast._tag !== 'SelectQuery') {
     return shouldNeverHappen(`Expected SelectQuery but got ${ast._tag}`)
   }
 }
 
-function assertInsertQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.InsertQuery {
+const assertInsertQueryBuilderAst: (ast: QueryBuilderAst) => asserts ast is QueryBuilderAst.InsertQuery = (ast) => {
   if (ast._tag !== 'InsertQuery') {
     return shouldNeverHappen(`Expected InsertQuery but got ${ast._tag}`)
   }
 }
 
-function assertWriteQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryBuilderAst.WriteQuery {
+const assertWriteQueryBuilderAst: (ast: QueryBuilderAst) => asserts ast is QueryBuilderAst.WriteQuery = (ast) => {
   if (ast._tag !== 'InsertQuery' && ast._tag !== 'UpdateQuery' && ast._tag !== 'DeleteQuery') {
     return shouldNeverHappen(`Expected WriteQuery but got ${ast._tag}`)
   }
@@ -299,10 +317,10 @@ function assertWriteQueryBuilderAst(ast: QueryBuilderAst): asserts ast is QueryB
 const isRowQuery = (ast: QueryBuilderAst): ast is QueryBuilderAst.RowQuery => ast._tag === 'RowQuery'
 
 export const invalidQueryBuilder = (msg?: string) => {
-  return shouldNeverHappen(`Invalid query builder${msg ? `: ${msg}` : ''}`)
+  return shouldNeverHappen(`Invalid query builder${msg !== undefined ? `: ${msg}` : ''}`)
 }
 
-export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<any> => {
+export const getResultSchema = (qb: QueryBuilder<any, any, any>) => {
   const queryAst = qb[QueryBuilderAstSymbol]
   switch (queryAst._tag) {
     case 'SelectQuery': {
@@ -317,36 +335,35 @@ export const getResultSchema = (qb: QueryBuilder<any, any, any>): Schema.Schema<
         return arraySchema.pipe(Schema.headOrElse())
       } else {
         const fallbackValue = queryAst.pickFirst.fallback()
-        return Schema.Union(arraySchema, Schema.Tuple(Schema.Literal(fallbackValue))).pipe(
+        return Schema.Array(Schema.Union([queryAst.resultSchemaSingle, Schema.Literal(fallbackValue)])).pipe(
           Schema.headOrElse(() => fallbackValue),
         )
       }
     }
     case 'CountQuery': {
-      return Schema.Struct({ count: Schema.Number }).pipe(Schema.pluck('count'), Schema.Array, Schema.headOrElse())
+      return Schema.Struct({ count: Schema.Finite }).pipe(Schema.pluck('count'), Schema.Array, Schema.headOrElse())
     }
     case 'InsertQuery':
     case 'UpdateQuery':
     case 'DeleteQuery': {
       // For write operations with RETURNING clause, we need to return the appropriate schema
-      if (queryAst.returning && queryAst.returning.length > 0) {
+      if (queryAst.returning !== undefined && queryAst.returning.length > 0) {
         // Create a schema for the returned columns
-        return queryAst.tableDef.rowSchema.pipe(Schema.pick(...queryAst.returning), Schema.Array)
+        return queryAst.tableDef.rowSchema.mapFields(Struct.pick(queryAst.returning)).pipe(Schema.Array)
       }
 
       // For write operations without RETURNING, the result is the number of affected rows
-      return Schema.Number
+      return Schema.Finite
     }
     case 'RowQuery': {
       return queryAst.tableDef.rowSchema.pipe(
         Schema.pluck('value'),
-        Schema.annotations({ title: `${queryAst.tableDef.sqliteDef.name}.value` }),
+        Schema.annotate({ title: `${queryAst.tableDef.sqliteDef.name}.value` }),
         Schema.Array,
         Schema.headOrElse(),
       )
     }
-    default: {
-      casesHandled(queryAst)
-    }
+    default:
+      return casesHandled(queryAst)
   }
 }

package/src/schema/state/sqlite/schema-helpers.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+
+import * as State from '../mod.ts'
+import { getDefaultValuesDecoded, getDefaultValuesEncoded } from './schema-helpers.ts'
+
+describe('schema-helpers', () => {
+  it('resolves thunk defaults when decoding values', () => {
+    let counter = 0
+    const table = State.SQLite.table({
+      name: 'sessions',
+      columns: {
+        id: State.SQLite.text({ primaryKey: true }),
+        token: State.SQLite.text({ default: () => `token-${++counter}` }),
+      },
+    })
+
+    expect(counter).toBe(0)
+
+    const firstDefaults = getDefaultValuesDecoded(table)
+    const secondDefaults = getDefaultValuesDecoded(table)
+
+    expect(firstDefaults.token).toBe('token-1')
+    expect(secondDefaults.token).toBe('token-2')
+  })
+
+  it('resolves thunk defaults when encoding values', () => {
+    let counter = 0
+    const table = State.SQLite.table({
+      name: 'sessions_encoded',
+      columns: {
+        id: State.SQLite.text({ primaryKey: true }),
+        token: State.SQLite.text({ default: () => `encoded-${++counter}` }),
+      },
+    })
+
+    expect(counter).toBe(0)
+
+    const firstDefaults = getDefaultValuesEncoded(table)
+    const secondDefaults = getDefaultValuesEncoded(table)
+
+    expect(firstDefaults.token).toBe('encoded-1')
+    expect(secondDefaults.token).toBe('encoded-2')
+  })
+})

package/src/schema/state/sqlite/schema-helpers.ts

@@ -2,9 +2,9 @@ import { shouldNeverHappen } from '@livestore/utils'
 import { pipe, ReadonlyRecord, Schema } from '@livestore/utils/effect'
 
 import { SqliteDsl } from './db-schema/mod.ts'
-import type { TableDef, TableDefBase } from './table-def.ts'
+import type { TableDefBase } from './table-def.ts'
 
-export const getDefaultValuesEncoded = <TTableDef extends TableDef>(
+export const getDefaultValuesEncoded = <TTableDef extends TableDefBase>(
   tableDef: TTableDef,
   fallbackValues?: Record<string, any>,
 ) =>
@@ -13,17 +13,21 @@ export const getDefaultValuesEncoded = <TTableDef extends TableDef>(
     ReadonlyRecord.filter((col, key) => {
       if (fallbackValues?.[key] !== undefined) return true
       if (key === 'id') return false
-      return col!.default._tag === 'None' || SqliteDsl.isSqlDefaultValue(col!.default.value) === false
+      return col!.default._tag === 'None' || !SqliteDsl.isSqlDefaultValue(col!.default.value)
+    }),
+    ReadonlyRecord.map((column, columnName) => {
+      if (fallbackValues?.[columnName] !== undefined) return fallbackValues[columnName]
+      if (column!.default._tag === 'None') {
+        return column!.nullable === true
+          ? null
+          : shouldNeverHappen(`Column ${columnName} has no default value and is not nullable`)
+      }
+
+      const defaultValue = column!.default.value
+      const resolvedDefault = SqliteDsl.resolveColumnDefault(defaultValue)
+
+      return Schema.encodeSync(column!.schema)(resolvedDefault)
     }),
-    ReadonlyRecord.map((column, columnName) =>
-      fallbackValues?.[columnName] === undefined
-        ? column!.default._tag === 'None'
-          ? column!.nullable === true
-            ? null
-            : shouldNeverHappen(`Column ${columnName} has no default value and is not nullable`)
-          : Schema.encodeSync(column!.schema)(column!.default.value)
-        : fallbackValues[columnName],
-    ),
   )
 
 export const getDefaultValuesDecoded = <TTableDef extends TableDefBase>(
@@ -35,15 +39,19 @@ export const getDefaultValuesDecoded = <TTableDef extends TableDefBase>(
     ReadonlyRecord.filter((col, key) => {
       if (fallbackValues?.[key] !== undefined) return true
       if (key === 'id') return false
-      return col!.default._tag === 'None' || SqliteDsl.isSqlDefaultValue(col!.default.value) === false
+      return col!.default._tag === 'None' || !SqliteDsl.isSqlDefaultValue(col!.default.value)
+    }),
+    ReadonlyRecord.map((column, columnName) => {
+      if (fallbackValues?.[columnName] !== undefined) return fallbackValues[columnName]
+      if (column!.default._tag === 'None') {
+        return column!.nullable === true
+          ? null
+          : shouldNeverHappen(`Column ${columnName} has no default value and is not nullable`)
+      }
+
+      const defaultValue = column!.default.value
+      const resolvedDefault = SqliteDsl.resolveColumnDefault(defaultValue)
+
+      return Schema.decodeSync(Schema.toType(column!.schema))(resolvedDefault)
     }),
-    ReadonlyRecord.map((column, columnName) =>
-      fallbackValues?.[columnName] === undefined
-        ? column!.default._tag === 'None'
-          ? column!.nullable === true
-            ? null
-            : shouldNeverHappen(`Column ${columnName} has no default value and is not nullable`)
-          : Schema.validateSync(column!.schema)(column!.default.value)
-        : fallbackValues[columnName],
-    ),
   )

package/src/schema/state/sqlite/system-tables/eventlog-tables.ts

@@ -0,0 +1,64 @@
+import { Schema } from '@livestore/utils/effect'
+
+import * as EventSequenceNumber from '../../../EventSequenceNumber/mod.ts'
+import { SqliteDsl } from '../db-schema/mod.ts'
+import { table } from '../table-def.ts'
+
+/**
+ * EVENTLOG DATABASE SYSTEM TABLES
+ *
+ * ⚠️  CRITICAL: NEVER modify eventlog schemas without bumping `liveStoreStorageFormatVersion`!
+ * Eventlog is the source of truth - schema changes cause permanent data loss.
+ *
+ * TODO: Implement proper eventlog versioning system to prevent accidental data loss
+ */
+
+export const EVENTLOG_META_TABLE = 'eventlog'
+
+/**
+ * Main client-side event log storing all events (global and local/rebased).
+ */
+export const eventlogMetaTable = table({
+  name: EVENTLOG_META_TABLE,
+  columns: {
+    // TODO Adjust modeling so a global event never needs a client id component
+    seqNumGlobal: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.Global.Schema }),
+    seqNumClient: SqliteDsl.integer({ primaryKey: true, schema: EventSequenceNumber.Client.Schema }),
+    seqNumRebaseGeneration: SqliteDsl.integer({ primaryKey: true }),
+    parentSeqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.Global.Schema }),
+    parentSeqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.Client.Schema }),
+    parentSeqNumRebaseGeneration: SqliteDsl.integer({}),
+    /** Event definition name */
+    name: SqliteDsl.text({}),
+    argsJson: SqliteDsl.text({ schema: Schema.fromJsonString(Schema.Any) }),
+    clientId: SqliteDsl.text({}),
+    sessionId: SqliteDsl.text({}),
+    schemaHash: SqliteDsl.integer({}),
+    syncMetadataJson: SqliteDsl.text({ schema: Schema.fromJsonString(Schema.toCodecJson(Schema.Option(Schema.Json))) }),
+  },
+  indexes: [
+    { columns: ['seqNumGlobal'], name: 'idx_eventlog_seqNumGlobal' },
+    { columns: ['seqNumGlobal', 'seqNumClient', 'seqNumRebaseGeneration'], name: 'idx_eventlog_seqNum' },
+  ],
+})
+
+export type EventlogMetaRow = typeof eventlogMetaTable.Type
+
+export const SYNC_STATUS_TABLE = '__livestore_sync_status'
+
+/**
+ * Tracks sync status including the remote head position and backend identity.
+ */
+// TODO support sync backend identity (to detect if sync backend changes)
+export const syncStatusTable = table({
+  name: SYNC_STATUS_TABLE,
+  columns: {
+    head: SqliteDsl.integer({ primaryKey: true }),
+    // Null means the sync backend is not yet connected and we haven't yet seen a backend ID
+    backendId: SqliteDsl.text({ nullable: true }),
+  },
+})
+
+export type SyncStatusRow = typeof syncStatusTable.Type
+
+export const eventlogSystemTables = [eventlogMetaTable, syncStatusTable] as const

package/src/schema/state/sqlite/system-tables/mod.ts

@@ -0,0 +1,2 @@
+export * from './eventlog-tables.ts'
+export * from './state-tables.ts'

package/src/schema/state/sqlite/system-tables/state-tables.ts

@@ -0,0 +1,109 @@
+import * as EventSequenceNumber from '../../../EventSequenceNumber/mod.ts'
+import { SqliteDsl } from '../db-schema/mod.ts'
+import { table } from '../table-def.ts'
+
+/**
+ * STATE DATABASE SYSTEM TABLES
+ *
+ * ⚠️  SAFE TO CHANGE: State tables are automatically rebuilt from eventlog when schema changes.
+ * No need to bump `liveStoreStorageFormatVersion` (uses hash-based migration via SqliteAst.hash()).
+ */
+
+export const SCHEMA_META_TABLE = '__livestore_schema'
+
+/**
+ * Tracks schema hashes for user-defined tables to detect schema changes.
+ */
+export const schemaMetaTable = table({
+  name: SCHEMA_META_TABLE,
+  columns: {
+    tableName: SqliteDsl.text({ primaryKey: true }),
+    schemaHash: SqliteDsl.integer({ nullable: false }),
+    /** ISO date format */
+    updatedAt: SqliteDsl.text({ nullable: false }),
+  },
+})
+
+export type SchemaMetaRow = typeof schemaMetaTable.Type
+
+export const SCHEMA_EVENT_DEFS_META_TABLE = '__livestore_schema_event_defs'
+
+/**
+ * Tracks schema hashes for event definitions to detect event schema changes.
+ */
+export const schemaEventDefsMetaTable = table({
+  name: SCHEMA_EVENT_DEFS_META_TABLE,
+  columns: {
+    eventName: SqliteDsl.text({ primaryKey: true }),
+    schemaHash: SqliteDsl.integer({ nullable: false }),
+    /** ISO date format */
+    updatedAt: SqliteDsl.text({ nullable: false }),
+  },
+})
+
+export type SchemaEventDefsMetaRow = typeof schemaEventDefsMetaTable.Type
+
+export const STATE_HEAD_META_TABLE = '__livestore_state_head'
+
+/**
+ * Single-row marker for the latest event sequence number reflected by the state DB.
+ *
+ * @remarks
+ * This is separate from the session changeset table because confirmed changesets
+ * can be removed after they are no longer needed for rollback.
+ */
+export const stateHeadMetaTable = table({
+  name: STATE_HEAD_META_TABLE,
+  columns: {
+    id: SqliteDsl.integer({ primaryKey: true }),
+    seqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.Global.Schema }),
+    seqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.Client.Schema }),
+    seqNumRebaseGeneration: SqliteDsl.integer({}),
+  },
+})
+
+export type StateHeadMetaRow = typeof stateHeadMetaTable.Type
+
+/**
+ * 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({
+  name: SESSION_CHANGESET_META_TABLE,
+  columns: {
+    // TODO bring back primary key
+    seqNumGlobal: SqliteDsl.integer({ schema: EventSequenceNumber.Global.Schema }),
+    seqNumClient: SqliteDsl.integer({ schema: EventSequenceNumber.Client.Schema }),
+    seqNumRebaseGeneration: SqliteDsl.integer({}),
+    changeset: SqliteDsl.blob({ nullable: true }),
+    debug: SqliteDsl.json({ nullable: true }),
+  },
+  indexes: [{ columns: ['seqNumGlobal', 'seqNumClient'], name: 'idx_session_changeset_id' }],
+})
+
+export type SessionChangesetMetaRow = typeof sessionChangesetMetaTable.Type
+
+// TODO: Rename the physical table once legacy session changeset consumers have been migrated.
+export const MATERIALIZATION_JOURNAL_META_TABLE = SESSION_CHANGESET_META_TABLE
+
+/**
+ * Materialization journal used to roll back state database changes during rebasing.
+ *
+ * @remarks
+ * This aliases the legacy table definition until all session changeset consumers
+ * have adopted the journal service.
+ */
+export const materializationJournalMetaTable = sessionChangesetMetaTable
+
+export type MaterializationJournalMetaRow = SessionChangesetMetaRow
+
+export const stateSystemTables = [
+  schemaMetaTable,
+  schemaEventDefsMetaTable,
+  stateHeadMetaTable,
+  sessionChangesetMetaTable,
+] as const
+
+export const isStateSystemTable = (tableName: string) => stateSystemTables.some((_) => _.sqliteDef.name === tableName)