@lota-sdk/core 0.4.8 → 0.4.10

package/src/db/service.ts

@@ -1,34 +1,35 @@
-import {
-  BoundQuery,
-  RecordId,
-  ServerError,
-  StringRecordId,
-  Surreal,
-  Table,
-  and,
-  createRemoteEngines,
-  eq,
-} from 'surrealdb'
-import type { ExprLike, Mutation, SurrealTransaction, Values } from 'surrealdb'
+import { Duration, Effect, Schedule, Semaphore } from 'effect'
+import { BoundQuery, ServerError, Surreal, Table, createRemoteEngines } from 'surrealdb'
+import type { ExprLike, SurrealTransaction, Values } from 'surrealdb'
+import { ZodError } from 'zod'
 import type { z } from 'zod'
 
 import { serverLogger } from '../config/logger'
-import { withTimeout } from '../utils/async'
-import { isRecord } from '../utils/string'
-import type { RecordIdInput } from './record-id'
-import { ensureRecordId, isSurrealRecordIdValue } from './record-id'
+import type { AwaitableEffect } from '../effect/awaitable-effect'
+import { toAwaitableEffect } from '../effect/awaitable-effect'
+import { getErrorMessage } from '../utils/errors'
+import type { RecordIdInput, ensureRecordId } from './record-id'
+import { ensureRecordIdEffect } from './record-id'
+import {
+  assertValidIdentifier,
+  buildBoundFilterClauses,
+  buildFilterExpression,
+  configureMutation,
+  describeInvalidValue,
+  normalizeBoundQuery,
+  normalizeCreateTarget,
+  normalizeMutationData,
+  normalizeQueryRows,
+  normalizeRecordIdForTable,
+  normalizeSurrealValue,
+  normalizeTableValue,
+  normalizeTransactionQuery,
+  normalizeTransactionRecordId,
+  SurrealDBError,
+} from './service-normalization'
+import type { RecordMutation } from './service-normalization'
 import type { DatabaseTable } from './tables'
-
-export class SurrealDBError extends Error {
-  constructor(
-    message: string,
-    public readonly query?: string,
-    options?: ErrorOptions,
-  ) {
-    super(message, options)
-    this.name = 'SurrealDBError'
-  }
-}
+import { isRetriableTransactionConflict } from './transaction-conflict'
 
 export interface SurrealDatabaseConfig {
   url: string
@@ -51,75 +52,97 @@ interface FindManyOptions {
   orderDir?: 'ASC' | 'DESC'
 }
 
-type MutationBuilder = {
+type MutationBuilderSource = {
+  content: (data: Record<string, unknown>) => MutationBuilderSource
+  replace: (data: Record<string, unknown>) => MutationBuilderSource
+  merge: (data: Record<string, unknown>) => MutationBuilderSource
+  output: (mode: 'after' | 'before') => unknown
+}
+
+export type MutationBuilder = {
   content: (data: Record<string, unknown>) => MutationBuilder
   replace: (data: Record<string, unknown>) => MutationBuilder
   merge: (data: Record<string, unknown>) => MutationBuilder
-  output: (mode: 'after' | 'before') => Promise<unknown>
+  output: (mode: 'after' | 'before') => AwaitableEffect<unknown, SurrealDBError>
 }
 
-type RecordMutation = Extract<Mutation, 'content' | 'replace' | 'merge'>
+type CreateBuilderSource = {
+  content: (data: Record<string, unknown>) => CreateBuilderSource
+  output: (mode: 'after' | 'before') => unknown
+}
+
+type PendingMutation = { mutation: RecordMutation; data: Record<string, unknown> }
 
 export type CreateMutationBuilder = {
   content: (data: Record<string, unknown>) => CreateMutationBuilder
-  output: (mode: 'after' | 'before') => Promise<unknown>
+  output: (mode: 'after' | 'before') => AwaitableEffect<unknown, SurrealDBError>
 }
 
 export interface DatabaseTransaction {
-  query: (query: unknown) => Promise<unknown>
+  query: (query: unknown) => AwaitableEffect<unknown, SurrealDBError>
   create: (target: unknown) => CreateMutationBuilder
   update: (target: unknown) => MutationBuilder
-  delete: (target: unknown) => Promise<unknown>
-  relate: (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) => Promise<unknown>
-  commit: () => Promise<void>
-  cancel: () => Promise<void>
-}
-
-function configureMutation(
-  builder: MutationBuilder,
-  mutation: RecordMutation,
-  data: Record<string, unknown>,
-): MutationBuilder {
-  if (mutation === 'content') {
-    return builder.content(data)
-  }
-  if (mutation === 'replace') {
-    return builder.replace(data)
-  }
-  return builder.merge(data)
+  delete: (target: unknown) => AwaitableEffect<unknown, SurrealDBError>
+  relate: (
+    from: unknown,
+    edgeTable: unknown,
+    to: unknown,
+    data?: Values<Record<string, unknown>>,
+  ) => AwaitableEffect<unknown, SurrealDBError>
+  commit: () => AwaitableEffect<void, SurrealDBError>
+  cancel: () => AwaitableEffect<void, SurrealDBError>
 }
 
 const CONNECT_MAX_ATTEMPTS = 5
 const CONNECT_RETRY_BASE_DELAY_MS = 100
-const CONNECT_RETRY_JITTER_MS = 50
 const CONNECT_ATTEMPT_TIMEOUT_MS = 5_000
 
+function isRetriableConnectError(error: unknown): boolean {
+  if (isRetriableTransactionConflict(error)) {
+    return true
+  }
+
+  const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
+  return /(timed out connecting to SurrealDB|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|network|socket|connection)/i.test(
+    message,
+  )
+}
+
+function isSurrealDBError(error: unknown): error is SurrealDBError {
+  return typeof error === 'object' && error !== null && (error as { _tag?: unknown })._tag === 'SurrealDBError'
+}
+
 export class SurrealDBService {
   private client: Surreal | null = null
   private isConnected = false
-  private connectPromise: Promise<void> | null = null
+  // Single-permit semaphore acts as a mutex so only one connect attempt runs at a time.
+  // Subsequent waiters re-check `isConnected` after acquiring the permit and become no-ops.
+  private readonly connectMutex = Semaphore.makeUnsafe(1)
 
   constructor(
     private readonly config: SurrealDatabaseConfig,
     private readonly logger?: SurrealDatabaseLogger,
   ) {}
 
-  private toSurrealError(error: unknown, query?: string): never {
-    if (error instanceof SurrealDBError) {
-      throw error
+  private toSurrealError(error: unknown, query?: string): SurrealDBError {
+    if (isSurrealDBError(error)) {
+      return error
+    }
+
+    if (error instanceof ZodError) {
+      return new SurrealDBError({ message: error.message, query: query, cause: error })
     }
 
     if (error instanceof ServerError) {
-      throw new SurrealDBError(`${error.name}: ${error.message}`, query, { cause: error })
+      return new SurrealDBError({ message: `${error.name}: ${error.message}`, query: query, cause: error })
     }
 
     if (error instanceof Error) {
-      throw new SurrealDBError(error.message, query, { cause: error })
+      return new SurrealDBError({ message: error.message, query: query, cause: error })
     }
 
-    throw new SurrealDBError(String(error), query)
+    return new SurrealDBError({ message: String(error), query })
   }
-
   private isEmbeddedEngine(url: string) {
     return (
       url === 'mem://' ||
@@ -130,433 +153,471 @@ export class SurrealDBService {
     )
   }
 
-  private async getOrCreateClient(): Promise<Surreal> {
+  private getOrCreateClient(): Effect.Effect<Surreal, SurrealDBError> {
     if (this.client) {
-      return this.client
+      return Effect.succeed(this.client)
     }
 
     const codecOptions = { useNativeDates: true }
 
-    if (this.isEmbeddedEngine(this.config.url)) {
-      const { createNodeEngines } = await import('@surrealdb/node')
-      this.client = new Surreal({
-        engines: { ...createRemoteEngines(), ...createNodeEngines() } as NonNullable<
-          ConstructorParameters<typeof Surreal>[0]
-        >['engines'],
-        codecOptions,
-      })
-      return this.client
-    }
+    return Effect.gen(
+      function* (this: SurrealDBService) {
+        if (this.client) {
+          return this.client
+        }
 
-    this.client = new Surreal({ engines: createRemoteEngines(), codecOptions })
-    return this.client
-  }
+        if (this.isEmbeddedEngine(this.config.url)) {
+          const { createNodeEngines } = yield* Effect.tryPromise({
+            try: () => import('@surrealdb/node'),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to load embedded SurrealDB engine: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })
+          this.client = new Surreal({
+            engines: { ...createRemoteEngines(), ...createNodeEngines() } as NonNullable<
+              ConstructorParameters<typeof Surreal>[0]
+            >['engines'],
+            codecOptions,
+          })
+          return this.client
+        }
 
-  private async resetClient(): Promise<void> {
-    if (!this.client) {
-      return
-    }
+        this.client = new Surreal({ engines: createRemoteEngines(), codecOptions })
+        return this.client
+      }.bind(this),
+    )
+  }
 
-    try {
-      await this.client.close()
-    } catch (error) {
-      serverLogger.warn`Failed to close database client: ${error}`
-    } finally {
-      this.client = null
-    }
+  private resetClient(): Effect.Effect<void, never> {
+    if (this.client === null) {
+      return Effect.void
+    }
+
+    const client = this.client
+
+    return Effect.tryPromise({
+      try: () => client.close(),
+      catch: (error) =>
+        new SurrealDBError({ message: `Failed to close database client: ${getErrorMessage(error)}`, cause: error }),
+    }).pipe(
+      Effect.catch((error: SurrealDBError) =>
+        Effect.sync(() => {
+          serverLogger.warn`Failed to close database client: ${error.message}`
+        }),
+      ),
+      Effect.asVoid,
+      Effect.ensuring(
+        Effect.sync(() => {
+          this.client = null
+        }),
+      ),
+    )
   }
 
-  private isRetriableConnectConflict(error: unknown): boolean {
-    if (!(error instanceof Error)) {
-      return false
-    }
+  connect(): AwaitableEffect<void, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          // Fast path: already connected. Cheap, runs inside the Effect so callers
+          // observe the same memory barrier the slow path relies on.
+          if (this.isConnected) {
+            return
+          }
 
-    const message = error.message.toLowerCase()
-    return (
-      message.includes('transaction conflict') ||
-      message.includes('transaction read conflict') ||
-      message.includes('read or write conflict') ||
-      message.includes('write conflict') ||
-      message.includes('resource busy') ||
-      message.includes('this transaction can be retried')
+          // Slow path: serialize concurrent connect attempts behind a single permit
+          // so only one client.connect() ever runs. Late waiters double-check
+          // isConnected after acquiring the permit and become no-ops.
+          yield* this.connectMutex.withPermits(1)(this.connectLockedEffect())
+        }.bind(this),
+      ),
     )
   }
 
-  async connect(): Promise<void> {
-    if (this.isConnected) {
-      return
-    }
-
-    if (this.connectPromise) {
-      await this.connectPromise
-      return
-    }
+  private connectLockedEffect(): Effect.Effect<void, SurrealDBError> {
+    return Effect.gen(
+      function* (this: SurrealDBService) {
+        if (this.isConnected) {
+          return
+        }
 
-    this.connectPromise = (async () => {
-      let lastError: unknown = null
+        const connectEffect = this.getOrCreateClient().pipe(
+          Effect.flatMap((client) =>
+            Effect.tryPromise({
+              try: () =>
+                client.connect(this.config.url, {
+                  namespace: this.config.namespace,
+                  database: this.config.database,
+                  authentication: this.isEmbeddedEngine(this.config.url)
+                    ? undefined
+                    : { username: this.config.username ?? '', password: this.config.password ?? '' },
+                }),
+              catch: (error) =>
+                new SurrealDBError({
+                  message: `Failed to connect to SurrealDB (${this.config.url}): ${getErrorMessage(error)}`,
+                  cause: error,
+                }),
+            }).pipe(
+              Effect.timeout(Duration.millis(CONNECT_ATTEMPT_TIMEOUT_MS)),
+              Effect.catchTag('TimeoutError', () =>
+                Effect.fail(new SurrealDBError({ message: `Timed out connecting to SurrealDB (${this.config.url})` })),
+              ),
+            ),
+          ),
+          Effect.tap(() =>
+            Effect.sync(() => {
+              this.isConnected = true
+              this.logger?.info?.('Connected to SurrealDB')
+            }),
+          ),
+          Effect.tapError(() =>
+            Effect.sync(() => {
+              this.isConnected = false
+            }).pipe(Effect.andThen(this.resetClient())),
+          ),
+          Effect.retry({
+            times: CONNECT_MAX_ATTEMPTS - 1,
+            schedule: Schedule.jittered(Schedule.exponential(Duration.millis(CONNECT_RETRY_BASE_DELAY_MS), 2)),
+            while: isRetriableConnectError,
+          }),
+          Effect.asVoid,
+        )
 
-      for (let attempt = 1; attempt <= CONNECT_MAX_ATTEMPTS; attempt += 1) {
-        try {
-          const client = await this.getOrCreateClient()
+        yield* connectEffect
+      }.bind(this),
+    )
+  }
 
-          await withTimeout(
-            client.connect(this.config.url, {
-              namespace: this.config.namespace,
-              database: this.config.database,
-              authentication: this.isEmbeddedEngine(this.config.url)
-                ? undefined
-                : { username: this.config.username ?? '', password: this.config.password ?? '' },
-            }),
-            CONNECT_ATTEMPT_TIMEOUT_MS,
-            `SurrealDB connect (${this.config.url})`,
-          )
+  disconnect(): AwaitableEffect<void, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          if (!this.isConnected) {
+            return
+          }
 
-          this.isConnected = true
-          this.logger?.info?.('Connected to SurrealDB')
-          return
-        } catch (error) {
-          lastError = error
           this.isConnected = false
-          await this.resetClient()
 
-          const retriable = this.isRetriableConnectConflict(error)
-          const hasMoreAttempts = attempt < CONNECT_MAX_ATTEMPTS
-          if (!retriable || !hasMoreAttempts) {
-            break
+          const client = this.client
+          if (!client) {
+            this.client = null
+            return
           }
 
-          const backoffMs =
-            CONNECT_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * CONNECT_RETRY_JITTER_MS)
-          this.logger?.warn?.(
-            `Retrying SurrealDB connect after retryable transaction conflict (${attempt + 1}/${CONNECT_MAX_ATTEMPTS})`,
+          yield* Effect.tryPromise({
+            try: () => client.close(),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to close database client: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          }).pipe(
+            Effect.ensuring(
+              Effect.sync(() => {
+                this.client = null
+              }),
+            ),
           )
-          await Bun.sleep(backoffMs)
-        }
-      }
-
-      return this.toSurrealError(lastError)
-    })()
-
-    try {
-      await this.connectPromise
-    } finally {
-      this.connectPromise = null
-    }
+        }.bind(this),
+      ),
+    )
   }
 
-  async disconnect(): Promise<void> {
-    if (this.connectPromise) {
-      try {
-        await this.connectPromise
-      } catch (error) {
-        this.logger?.warn?.(
-          `Disconnect observed failed in-flight connect: ${error instanceof Error ? error.message : String(error)}`,
-        )
-        return
-      }
-    }
-
-    if (!this.isConnected) {
-      return
+  private ensureConnectedEffect(query?: string): Effect.Effect<Surreal, SurrealDBError, never> {
+    if (this.client === null || !this.isConnected) {
+      return this.connect().pipe(
+        Effect.flatMap(() => this.getOrCreateClient()),
+        Effect.mapError((error) =>
+          isSurrealDBError(error)
+            ? error
+            : new SurrealDBError({ message: 'Database not connected', query, cause: error }),
+        ),
+      )
     }
 
-    this.isConnected = false
-
-    try {
-      await this.client?.close()
-    } finally {
-      this.client = null
-    }
+    return Effect.succeed(this.client)
   }
 
-  private async ensureConnected(): Promise<Surreal> {
-    if (this.connectPromise) {
-      await this.connectPromise
-    }
-
-    if (this.client === null) {
-      throw new SurrealDBError('Database not connected')
-    }
-
-    return this.client
-  }
-
-  private normalizeRecordId(id: unknown, table: DatabaseTable): ReturnType<typeof ensureRecordId> {
-    try {
-      const recordId = ensureRecordId(id as RecordIdInput, table)
-      const resolvedTable = String(recordId.table)
-      if (resolvedTable !== table) {
-        throw new SurrealDBError(`Record id table mismatch: expected "${table}" but got "${resolvedTable}"`)
-      }
-      return recordId
-    } catch (error) {
-      if (error instanceof SurrealDBError) {
-        throw error
-      }
-      if (error instanceof Error) {
-        throw new SurrealDBError(`Invalid record id for table "${table}": ${error.message}`, undefined, {
-          cause: error,
-        })
-      }
-      throw new SurrealDBError(`Invalid record id for table "${table}"`)
-    }
+  private normalizeRecordIdEffect(
+    id: unknown,
+    table: DatabaseTable,
+  ): Effect.Effect<ReturnType<typeof ensureRecordId>, SurrealDBError> {
+    return normalizeRecordIdForTable(id, table)
   }
 
   private normalizeQueryRows(statement: unknown, schema?: z.ZodTypeAny): unknown[] {
-    if (Array.isArray(statement)) {
-      return schema ? statement.map((row) => this.parseSchema(schema, row)) : (statement as unknown[])
-    }
-    if (statement === null || statement === undefined) {
-      return []
-    }
-    return schema ? [this.parseSchema(schema, statement)] : [statement]
+    return normalizeQueryRows(statement, schema, (schemaValue, value) => this.parseSchema(schemaValue, value))
   }
 
-  private normalizeParseValue(value: unknown): unknown {
-    if (
-      value instanceof Date ||
-      value instanceof RecordId ||
-      value instanceof StringRecordId ||
-      value instanceof Table
-    ) {
-      return value
-    }
-
-    if (Array.isArray(value)) {
-      return value.map((entry) => this.normalizeParseValue(entry))
-    }
-
-    if (isSurrealRecordIdValue(value)) {
-      return ensureRecordId(value as RecordIdInput)
-    }
+  private normalizeQueryRowsEffect(
+    statement: unknown,
+    schema?: z.ZodTypeAny,
+  ): Effect.Effect<unknown[], SurrealDBError> {
+    return Effect.try({
+      try: () => this.normalizeQueryRows(statement, schema),
+      catch: (error) => this.toSurrealError(error),
+    })
+  }
 
-    if (!isRecord(value)) {
-      return value
-    }
+  private normalizeParseValue(value: unknown): unknown {
+    return normalizeSurrealValue(value)
+  }
 
-    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, this.normalizeParseValue(entry)]))
+  private normalizeParseValueEffect(value: unknown): Effect.Effect<unknown, SurrealDBError> {
+    return Effect.try({ try: () => this.normalizeParseValue(value), catch: (error) => this.toSurrealError(error) })
   }
 
   private parseSchema<TSchema extends z.ZodTypeAny>(schema: TSchema, value: unknown): z.infer<TSchema> {
     return schema.parse(this.normalizeParseValue(value))
   }
 
-  private buildFilterExpression(filter: Record<string, unknown>): ExprLike | undefined {
-    const entries = Object.entries(filter)
-    if (entries.length === 0) {
-      return undefined
-    }
-
-    const expressions = entries.map(([key, value]) => eq(key, this.normalizeRuntimeValue(value)))
-    if (expressions.length === 1) {
-      return expressions[0]
-    }
-
-    return and(...expressions)
-  }
-
-  private assertValidIdentifier(name: string, context: string): void {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(name)) {
-      throw new SurrealDBError(`Invalid ${context}: "${name}"`)
-    }
+  private parseSchemaEffect<TSchema extends z.ZodTypeAny>(
+    schema: TSchema,
+    value: unknown,
+  ): Effect.Effect<z.infer<TSchema>, SurrealDBError> {
+    return Effect.try({ try: () => this.parseSchema(schema, value), catch: (error) => this.toSurrealError(error) })
   }
 
-  private buildBoundFilterClauses(filter: Record<string, unknown>): {
-    clause: string
-    bindings: Record<string, unknown>
-  } {
-    const entries = Object.entries(filter)
-    if (entries.length === 0) {
-      throw new SurrealDBError('Expected a non-empty filter')
+  private parseOptionalSchema<TSchema extends z.ZodTypeAny>(schema: TSchema, value: unknown): z.infer<TSchema> | null {
+    if (value === null || value === undefined) {
+      return null
     }
 
-    const bindings: Record<string, unknown> = {}
-    const clauses = entries.map(([field, value], index) => {
-      this.assertValidIdentifier(field, 'filter field')
+    return this.parseSchema(schema, value)
+  }
 
-      const bindingKey = `filter_${index}`
-      bindings[bindingKey] = this.normalizeRuntimeValue(value)
-      return `${field} = $${bindingKey}`
+  private parseOptionalSchemaEffect<TSchema extends z.ZodTypeAny>(
+    schema: TSchema,
+    value: unknown,
+  ): Effect.Effect<z.infer<TSchema> | null, SurrealDBError> {
+    return Effect.try({
+      try: () => this.parseOptionalSchema(schema, value),
+      catch: (error) => this.toSurrealError(error),
     })
-
-    return { clause: clauses.join(' AND '), bindings }
   }
 
-  private normalizeBoundQuery(query: BoundQuery): BoundQuery {
-    return new BoundQuery(query.query, this.normalizeBindings(query.bindings))
+  private buildFilterExpression(filter: Record<string, unknown>): ExprLike | undefined {
+    return buildFilterExpression(filter)
   }
 
-  private normalizeRuntimeValue(value: unknown): unknown {
-    if (value === null || value === undefined) {
-      return value
-    }
-
-    if (
-      value instanceof Date ||
-      value instanceof RecordId ||
-      value instanceof StringRecordId ||
-      value instanceof Table
-    ) {
-      return value
-    }
-
-    if (Array.isArray(value)) {
-      return value.map((entry) => this.normalizeRuntimeValue(entry))
-    }
-
-    if (isSurrealRecordIdValue(value)) {
-      return ensureRecordId(value as RecordIdInput)
-    }
-
-    if (!isRecord(value)) {
-      return value
-    }
-
-    if ('tb' in value && 'id' in value && Object.keys(value).length === 2) {
-      return ensureRecordId(value as unknown as RecordIdInput)
-    }
-
-    const entries = Object.entries(value)
-    if (entries.length === 0) {
-      return value
-    }
-
-    return Object.fromEntries(entries.map(([key, entryValue]) => [key, this.normalizeRuntimeValue(entryValue)]))
+  private buildFilterExpressionEffect(
+    filter: Record<string, unknown>,
+  ): Effect.Effect<ExprLike | undefined, SurrealDBError> {
+    return Effect.try({ try: () => this.buildFilterExpression(filter), catch: (error) => this.toSurrealError(error) })
   }
 
-  // Cast is safe: normalizeRuntimeValue preserves Record shape when input is a Record
-  // (non-array objects are mapped entry-by-entry and returned as Object.fromEntries)
-  private normalizeBindings(bindings?: Record<string, unknown>): Record<string, unknown> | undefined {
-    if (!bindings) {
-      return undefined
-    }
-
-    return this.normalizeRuntimeValue(bindings) as Record<string, unknown>
+  private buildBoundFilterClausesEffect(
+    filter: Record<string, unknown>,
+  ): Effect.Effect<{ clause: string; bindings: Record<string, unknown> }, SurrealDBError> {
+    return buildBoundFilterClauses(filter)
   }
 
-  private normalizeMutationFieldValue(value: unknown): unknown {
-    if (value === undefined) {
-      return undefined
-    }
+  private assertValidIdentifierEffect(name: string, context: string): Effect.Effect<void, SurrealDBError> {
+    return assertValidIdentifier(name, context)
+  }
 
-    if (value === null) {
-      return null
-    }
+  private normalizeBoundQueryEffect<T extends unknown[] = unknown[]>(
+    query: BoundQuery<T>,
+  ): Effect.Effect<BoundQuery<T>, SurrealDBError> {
+    return normalizeBoundQuery(query)
+  }
 
-    return this.normalizeRuntimeValue(value)
+  private normalizeTransactionQueryEffect(query: unknown): Effect.Effect<BoundQuery, SurrealDBError> {
+    return normalizeTransactionQuery(query)
   }
 
-  // Cast is safe: normalizeRuntimeValue preserves Record shape when input is a Record
   private normalizeMutationData(data: Record<string, unknown>): Record<string, unknown> {
-    return Object.fromEntries(
-      Object.entries(data)
-        .map(([key, value]) => [key, this.normalizeMutationFieldValue(value)] as const)
-        .filter((entry): entry is readonly [string, unknown] => entry[1] !== undefined),
-    ) as Record<string, unknown>
+    return normalizeMutationData(data)
   }
 
-  private normalizeTableValue(value: unknown): Table {
-    if (value instanceof Table) {
-      return value as Table<string>
-    }
-
-    if (typeof value === 'string' && value.length > 0) {
-      return new Table(value)
-    }
-
-    throw new SurrealDBError('Invalid table value')
+  private normalizeMutationDataEffect(
+    data: Record<string, unknown>,
+  ): Effect.Effect<Record<string, unknown>, SurrealDBError> {
+    return Effect.try({ try: () => this.normalizeMutationData(data), catch: (error) => this.toSurrealError(error) })
   }
 
-  private isRecordIdLike(value: unknown): boolean {
-    if (value instanceof RecordId || value instanceof StringRecordId) {
-      return true
-    }
-
-    if (isSurrealRecordIdValue(value)) {
-      return true
-    }
-
-    if (typeof value === 'string') {
-      return /^[a-zA-Z][a-zA-Z0-9_]*:/.test(value)
-    }
-
-    if (value && typeof value === 'object') {
-      const record = value as { tb?: unknown; id?: unknown }
-      return typeof record.tb === 'string' && record.id !== undefined && Object.keys(value).length === 2
-    }
-
-    return false
+  private normalizeTableValueEffect(value: unknown): Effect.Effect<Table<string>, SurrealDBError> {
+    return normalizeTableValue(value)
   }
 
-  private normalizeCreateTarget(value: unknown): Table | RecordId {
-    if (this.isRecordIdLike(value)) {
-      return ensureRecordId(value as RecordIdInput)
-    }
+  private normalizeCreateTargetEffect(
+    value: unknown,
+  ): Effect.Effect<Table<string> | ReturnType<typeof ensureRecordId>, SurrealDBError> {
+    return normalizeCreateTarget(value)
+  }
 
-    return this.normalizeTableValue(value)
+  private normalizeTransactionRecordIdEffect(
+    value: unknown,
+    context: string,
+  ): Effect.Effect<ReturnType<typeof ensureRecordId>, SurrealDBError> {
+    return normalizeTransactionRecordId(value, context)
   }
 
-  private wrapMutationBuilder(builder: MutationBuilder): MutationBuilder {
+  private wrapMutationBuilder(
+    builderEffect: Effect.Effect<MutationBuilderSource, SurrealDBError>,
+    pendingMutation?: PendingMutation,
+  ): MutationBuilder {
     return {
-      content: (data) => this.wrapMutationBuilder(builder.content(this.normalizeMutationData(data))),
-      replace: (data) => this.wrapMutationBuilder(builder.replace(this.normalizeMutationData(data))),
-      merge: (data) => this.wrapMutationBuilder(builder.merge(this.normalizeMutationData(data))),
-      output: async (mode) => this.normalizeParseValue(await builder.output(mode)),
+      content: (data) => this.wrapMutationBuilder(builderEffect, { mutation: 'content', data }),
+      replace: (data) => this.wrapMutationBuilder(builderEffect, { mutation: 'replace', data }),
+      merge: (data) => this.wrapMutationBuilder(builderEffect, { mutation: 'merge', data }),
+      output: (mode) =>
+        toAwaitableEffect(
+          Effect.gen(
+            function* (this: SurrealDBService) {
+              const builder = yield* builderEffect
+              let configuredBuilder = builder
+              if (pendingMutation) {
+                const normalizedData = yield* this.normalizeMutationDataEffect(pendingMutation.data)
+                configuredBuilder = configureMutation(builder, pendingMutation.mutation, normalizedData)
+              }
+              const value = yield* Effect.tryPromise({
+                try: () => Promise.resolve(configuredBuilder.output(mode)),
+                catch: (error) =>
+                  new SurrealDBError({
+                    message: `Failed to finish mutation output: ${getErrorMessage(error)}`,
+                    cause: error,
+                  }),
+              })
+              return yield* this.normalizeParseValueEffect(value)
+            }.bind(this),
+          ),
+        ),
     }
   }
 
-  private wrapCreateBuilder(builder: CreateMutationBuilder): CreateMutationBuilder {
+  private wrapCreateBuilder(
+    builderEffect: Effect.Effect<CreateBuilderSource, SurrealDBError>,
+    pendingData?: Record<string, unknown>,
+  ): CreateMutationBuilder {
     return {
-      content: (data) => this.wrapCreateBuilder(builder.content(this.normalizeMutationData(data))),
-      output: async (mode) => this.normalizeParseValue(await builder.output(mode)),
+      content: (data) => this.wrapCreateBuilder(builderEffect, data),
+      output: (mode) =>
+        toAwaitableEffect(
+          Effect.gen(
+            function* (this: SurrealDBService) {
+              const builder = yield* builderEffect
+              const configuredBuilder = pendingData
+                ? builder.content(yield* this.normalizeMutationDataEffect(pendingData))
+                : builder
+              const value = yield* Effect.tryPromise({
+                try: () => Promise.resolve(configuredBuilder.output(mode)),
+                catch: (error) =>
+                  new SurrealDBError({
+                    message: `Failed to finish create output: ${getErrorMessage(error)}`,
+                    cause: error,
+                  }),
+              })
+              return yield* this.normalizeParseValueEffect(value)
+            }.bind(this),
+          ),
+        ),
     }
   }
 
   private wrapTransaction(tx: SurrealTransaction): DatabaseTransaction {
     return {
-      query: async (query: unknown) => {
-        const boundQuery = this.normalizeBoundQuery(query as BoundQuery)
-        const queryText = this.resolveQueryText(boundQuery)
-
-        try {
-          const responses = await tx.query(boundQuery).responses()
-          const first = responses.at(0)
-          if (!first) {
-            return []
-          }
-          if (!first.success) {
-            throw new SurrealDBError(first.error.message, queryText, { cause: first.error })
-          }
-
-          return this.normalizeQueryRows(first.result)
-        } catch (error) {
-          return this.toSurrealError(error, queryText)
-        }
-      },
-      create: (target: unknown) => {
-        const normalizedTarget = this.normalizeCreateTarget(target)
-        const builder = normalizedTarget instanceof Table ? tx.create(normalizedTarget) : tx.create(normalizedTarget)
-        // Cast needed: SurrealDB SDK transaction builder type differs nominally from internal CreateMutationBuilder interface
-        return this.wrapCreateBuilder(builder as unknown as CreateMutationBuilder)
-      },
+      query: (query: unknown) =>
+        toAwaitableEffect(
+          Effect.gen(
+            function* (this: SurrealDBService) {
+              const boundQuery = yield* this.normalizeTransactionQueryEffect(query)
+              const queryText = this.resolveQueryText(boundQuery)
+              const responses = yield* Effect.tryPromise({
+                try: () => tx.query(boundQuery).responses(),
+                catch: (error) =>
+                  new SurrealDBError({
+                    message: `Failed to run transaction query: ${getErrorMessage(error)}`,
+                    query: queryText,
+                    cause: error,
+                  }),
+              })
+              const first = responses.at(0)
+              if (!first) {
+                return []
+              }
+              if (!first.success) {
+                return yield* new SurrealDBError({ message: first.error.message, query: queryText, cause: first.error })
+              }
+
+              return yield* this.normalizeQueryRowsEffect(first.result)
+            }.bind(this),
+          ),
+        ),
+      create: (target: unknown) =>
+        this.wrapCreateBuilder(
+          Effect.gen(
+            function* (this: SurrealDBService) {
+              const normalizedTarget = yield* this.normalizeCreateTargetEffect(target)
+              return normalizedTarget instanceof Table ? tx.create(normalizedTarget) : tx.create(normalizedTarget)
+            }.bind(this),
+          ),
+        ),
       update: (target: unknown) =>
-        // Cast needed: SurrealDB SDK transaction builder type differs nominally from internal MutationBuilder interface
-        this.wrapMutationBuilder(tx.update(ensureRecordId(target as RecordIdInput)) as unknown as MutationBuilder),
-      delete: async (target: unknown) =>
-        this.normalizeParseValue(await tx.delete(ensureRecordId(target as RecordIdInput))),
-      relate: async (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) =>
-        this.normalizeParseValue(
-          await tx.relate(
-            ensureRecordId(from as RecordIdInput),
-            this.normalizeTableValue(edgeTable),
-            ensureRecordId(to as RecordIdInput),
-            data
-              ? (this.normalizeMutationData(data as Record<string, unknown>) as Values<Record<string, unknown>>)
-              : undefined,
+        this.wrapMutationBuilder(
+          Effect.gen(
+            function* (this: SurrealDBService) {
+              const recordId = yield* this.normalizeTransactionRecordIdEffect(target, 'transaction update')
+              return tx.update(recordId)
+            }.bind(this),
+          ),
+        ),
+      delete: (target: unknown) =>
+        toAwaitableEffect(
+          Effect.gen(
+            function* (this: SurrealDBService) {
+              const recordId = yield* this.normalizeTransactionRecordIdEffect(target, 'transaction delete')
+              const value = yield* Effect.tryPromise({
+                try: () => tx.delete(recordId),
+                catch: (error) =>
+                  new SurrealDBError({
+                    message: `Failed to delete transaction target: ${getErrorMessage(error)}`,
+                    cause: error,
+                  }),
+              })
+              return yield* this.normalizeParseValueEffect(value)
+            }.bind(this),
           ),
         ),
-      commit: () => tx.commit(),
-      cancel: () => tx.cancel(),
+      relate: (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) =>
+        toAwaitableEffect(
+          Effect.gen(
+            function* (this: SurrealDBService) {
+              const fromRecordId = yield* this.normalizeTransactionRecordIdEffect(from, 'transaction relate source')
+              const normalizedEdgeTable = yield* this.normalizeTableValueEffect(edgeTable)
+              const toRecordId = yield* this.normalizeTransactionRecordIdEffect(to, 'transaction relate target')
+              const normalizedData = data
+                ? yield* this.normalizeMutationDataEffect(data as Record<string, unknown>)
+                : undefined
+              const value = yield* Effect.tryPromise({
+                try: () => tx.relate(fromRecordId, normalizedEdgeTable, toRecordId, normalizedData),
+                catch: (error) =>
+                  new SurrealDBError({
+                    message: `Failed to relate transaction records: ${getErrorMessage(error)}`,
+                    cause: error,
+                  }),
+              })
+              return yield* this.normalizeParseValueEffect(value)
+            }.bind(this),
+          ),
+        ),
+      commit: () =>
+        toAwaitableEffect(
+          Effect.tryPromise({
+            try: () => tx.commit(),
+            catch: (error) =>
+              new SurrealDBError({ message: `Failed to commit transaction: ${getErrorMessage(error)}`, cause: error }),
+          }),
+        ),
+      cancel: () =>
+        toAwaitableEffect(
+          Effect.tryPromise({
+            try: () => tx.cancel(),
+            catch: (error) =>
+              new SurrealDBError({ message: `Failed to cancel transaction: ${getErrorMessage(error)}`, cause: error }),
+          }),
+        ),
     }
   }
 
@@ -564,459 +625,531 @@ export class SurrealDBService {
     return query.query
   }
 
-  async query<T>(query: BoundQuery): Promise<T[]> {
-    const statements = await this.queryAll<T>(query)
-    return statements.at(0) ?? []
+  query<T>(query: BoundQuery): AwaitableEffect<T[], SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const boundQuery = yield* this.normalizeBoundQueryEffect(query)
+          const statements = yield* this.queryAll<T>(boundQuery)
+          return statements.at(0) ?? []
+        }.bind(this),
+      ),
+    )
   }
 
-  async queryAll<T>(query: BoundQuery, schema?: z.ZodTypeAny): Promise<T[][]> {
-    const client = await this.ensureConnected()
-    const boundQuery = this.normalizeBoundQuery(query)
-    const queryText = this.resolveQueryText(boundQuery)
-
-    try {
-      const responses = await client.query(boundQuery).responses()
-
-      return responses.map((response, index) => {
-        if (!response.success) {
-          const failure = response.error
-          throw new SurrealDBError(`Statement ${index + 1}: ${failure.message}`, queryText, { cause: failure })
-        }
-        return this.normalizeQueryRows(response.result, schema) as T[]
-      })
-    } catch (error) {
-      return this.toSurrealError(error, queryText)
-    }
+  queryAll<T>(query: BoundQuery, schema?: z.ZodTypeAny): AwaitableEffect<T[][], SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const boundQuery = yield* this.normalizeBoundQueryEffect(query)
+          const queryText = this.resolveQueryText(boundQuery)
+          const client = yield* this.ensureConnectedEffect(queryText)
+          const responses = yield* Effect.tryPromise({
+            try: () => client.query(boundQuery).responses(),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to run query: ${getErrorMessage(error)}`,
+                query: queryText,
+                cause: error,
+              }),
+          })
+          return yield* Effect.forEach(responses, (response, index) =>
+            Effect.gen(
+              function* (this: SurrealDBService) {
+                if (!response.success) {
+                  const failure = response.error
+                  return yield* new SurrealDBError({
+                    message: `Statement ${index + 1}: ${failure.message}`,
+                    query: queryText,
+                    cause: failure,
+                  })
+                }
+                return (yield* this.normalizeQueryRowsEffect(response.result, schema)) as T[]
+              }.bind(this),
+            ),
+          )
+        }.bind(this),
+      ),
+    )
   }
 
-  async queryOne<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): Promise<z.infer<T> | null> {
-    const results = await this.query<unknown>(query)
-    const first = results.at(0)
-    return first ? this.parseSchema(schema, first) : null
+  queryOne<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): AwaitableEffect<z.infer<T> | null, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const boundQuery = yield* this.normalizeBoundQueryEffect(query)
+          const results = yield* this.query<unknown>(boundQuery)
+          const first = results.at(0)
+          return first ? yield* this.parseSchemaEffect(schema, first) : null
+        }.bind(this),
+      ),
+    )
   }
 
-  async queryMany<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): Promise<z.infer<T>[]> {
-    const results = await this.query<unknown>(query)
-    return results.map((row) => this.parseSchema(schema, row))
+  queryMany<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): AwaitableEffect<z.infer<T>[], SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const boundQuery = yield* this.normalizeBoundQueryEffect(query)
+          const results = yield* this.query<unknown>(boundQuery)
+          return yield* Effect.forEach(results, (row) => this.parseSchemaEffect(schema, row))
+        }.bind(this),
+      ),
+    )
   }
 
-  private async runSqlFile(file: Bun.BunFile): Promise<void> {
-    const sql = (await file.text()).trim()
-    if (!sql) {
-      return
-    }
+  private runSqlFile(file: Bun.BunFile): Effect.Effect<void, SurrealDBError> {
+    return Effect.gen(
+      function* (this: SurrealDBService) {
+        const sql = (yield* Effect.tryPromise({
+          try: () => file.text(),
+          catch: (error) =>
+            new SurrealDBError({ message: `Failed to read schema file: ${getErrorMessage(error)}`, cause: error }),
+        })).trim()
+        if (!sql) {
+          return
+        }
 
-    await this.queryAll<unknown>(new BoundQuery(sql))
+        yield* this.queryAll<unknown>(new BoundQuery(sql))
+      }.bind(this),
+    )
   }
 
-  async applySchema(schemaFiles: readonly Bun.BunFile[]): Promise<void> {
-    for (const schemaFile of schemaFiles) {
-      await this.runSqlFile(schemaFile)
-    }
+  applySchema(schemaFiles: readonly Bun.BunFile[]): AwaitableEffect<void, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.forEach(schemaFiles, (schemaFile) => this.runSqlFile(schemaFile), { discard: true }),
+    )
   }
 
-  async findOne<T extends z.ZodTypeAny>(
+  findOne<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     filter: Record<string, unknown>,
     schema: T,
-  ): Promise<z.infer<T> | null> {
-    const client = await this.ensureConnected()
-    const selection = this.buildFilterExpression(filter)
-
-    try {
-      let query = client.select<unknown>(new Table(table))
-      if (selection) {
-        query = query.where(selection)
-      }
-
-      const rows = await query.limit(1)
-      const first = rows.at(0)
-      return first ? this.parseSchema(schema, first) : null
-    } catch (error) {
-      return this.toSurrealError(error, `SELECT * FROM ${table} LIMIT 1`)
-    }
+  ): AwaitableEffect<z.infer<T> | null, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const selection = yield* this.buildFilterExpressionEffect(filter)
+          const client = yield* this.ensureConnectedEffect(`SELECT * FROM ${table} LIMIT 1`)
+          let query = client.select<unknown>(new Table(table))
+          if (selection) {
+            query = query.where(selection)
+          }
+
+          const rows = yield* Effect.tryPromise({
+            try: () => query.limit(1),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to find record in ${table}: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })
+          const first = rows.at(0)
+          return first ? yield* this.parseSchemaEffect(schema, first) : null
+        }.bind(this),
+      ),
+    )
   }
 
-  async findMany<T extends z.ZodTypeAny>(
+  findMany<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     filter: Record<string, unknown>,
     schema: T,
     options?: FindManyOptions,
-  ): Promise<z.infer<T>[]> {
-    const filterKeys = Object.keys(filter)
-
-    const client = await this.ensureConnected()
-    const selection = this.buildFilterExpression(filter)
-    const orderBy = options?.orderBy
-
-    if (orderBy !== undefined) {
-      this.assertValidIdentifier(orderBy, 'orderBy field')
-      this.assertValidIdentifier(table, 'table name')
-      for (const key of filterKeys) {
-        this.assertValidIdentifier(key, 'filter field')
-      }
-      const rawOrderDir: unknown = options?.orderDir
-      if (rawOrderDir !== undefined && rawOrderDir !== 'ASC' && rawOrderDir !== 'DESC') {
-        throw new SurrealDBError(`Invalid orderDir value: ${this.describeInvalidValue(rawOrderDir)}`)
-      }
-      const orderDir = rawOrderDir ?? 'ASC'
-      const limit = options?.limit
-      const offset = options?.offset
-      const vars: Record<string, unknown> = this.normalizeMutationData(filter)
-      let sql = `SELECT * FROM ${table}`
-      if (filterKeys.length > 0) {
-        const conditions = filterKeys.map((key) => `${key} = $${key}`).join(' AND ')
-        sql += ` WHERE ${conditions}`
-      }
-      sql += ` ORDER BY ${orderBy} ${orderDir}`
-      if (limit !== undefined) {
-        sql += ' LIMIT $limitParam'
-        vars.limitParam = limit
-      }
-      if (offset !== undefined) {
-        sql += ' START $offsetParam'
-        vars.offsetParam = offset
-      }
-      const rows = await this.query<unknown>(new BoundQuery(sql, vars))
-      return rows.map((row) => this.parseSchema(schema, row))
-    }
-
-    try {
-      let query = client.select<unknown>(new Table(table))
-      if (selection) {
-        query = query.where(selection)
-      }
-      if (options?.offset !== undefined) {
-        query = query.start(options.offset)
-      }
-      if (options?.limit !== undefined) {
-        query = query.limit(options.limit)
-      }
-
-      const rows = await query
-      return rows.map((row) => this.parseSchema(schema, row))
-    } catch (error) {
-      return this.toSurrealError(error, `SELECT * FROM ${table}`)
-    }
-  }
+  ): AwaitableEffect<z.infer<T>[], SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const filterKeys = Object.keys(filter)
+          const selection = yield* this.buildFilterExpressionEffect(filter)
+          const orderBy = options?.orderBy
+
+          if (orderBy !== undefined) {
+            yield* this.assertValidIdentifierEffect(orderBy, 'orderBy field')
+            yield* this.assertValidIdentifierEffect(table, 'table name')
+            for (const key of filterKeys) {
+              yield* this.assertValidIdentifierEffect(key, 'filter field')
+            }
+            const rawOrderDir: unknown = options?.orderDir
+            if (rawOrderDir !== undefined && rawOrderDir !== 'ASC' && rawOrderDir !== 'DESC') {
+              return yield* new SurrealDBError({
+                message: `Invalid orderDir value: ${describeInvalidValue(rawOrderDir)}`,
+              })
+            }
+            const orderDir = rawOrderDir ?? 'ASC'
+            const limit = options?.limit
+            const offset = options?.offset
+            const vars: Record<string, unknown> = yield* this.normalizeMutationDataEffect(filter)
+            let sql = `SELECT * FROM ${table}`
+            if (filterKeys.length > 0) {
+              const conditions = filterKeys.map((key) => `${key} = $${key}`).join(' AND ')
+              sql += ` WHERE ${conditions}`
+            }
+            sql += ` ORDER BY ${orderBy} ${orderDir}`
+            if (limit !== undefined) {
+              sql += ' LIMIT $limitParam'
+              vars.limitParam = limit
+            }
+            if (offset !== undefined) {
+              sql += ' START $offsetParam'
+              vars.offsetParam = offset
+            }
+            const rows = yield* this.query<unknown>(new BoundQuery(sql, vars))
+            return yield* Effect.forEach(rows, (row) => this.parseSchemaEffect(schema, row))
+          }
 
-  private describeInvalidValue(value: unknown): string {
-    if (typeof value === 'string') {
-      return value
-    }
+          const client = yield* this.ensureConnectedEffect(`SELECT * FROM ${table}`)
+          let query = client.select<unknown>(new Table(table))
+          if (selection) {
+            query = query.where(selection)
+          }
+          if (options?.offset !== undefined) {
+            query = query.start(options.offset)
+          }
+          if (options?.limit !== undefined) {
+            query = query.limit(options.limit)
+          }
 
-    try {
-      const serialized = JSON.stringify(value)
-      if (typeof serialized === 'string') {
-        return serialized
-      }
-      return Object.prototype.toString.call(value)
-    } catch {
-      return Object.prototype.toString.call(value)
-    }
+          const rows = yield* Effect.tryPromise({
+            try: () => query,
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to run findMany query for ${table}: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })
+          return yield* Effect.forEach(rows, (row) => this.parseSchemaEffect(schema, row))
+        }.bind(this),
+      ),
+    )
   }
 
-  async create<T extends z.ZodTypeAny>(
+  create<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     data: Record<string, unknown>,
     schema: T,
-  ): Promise<z.infer<T>> {
-    const keys = Object.keys(data)
-    if (keys.length === 0) {
-      throw new SurrealDBError(`Cannot create record in ${table} with empty data`)
-    }
-
-    const client = await this.ensureConnected()
+  ): AwaitableEffect<z.infer<T>, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const keys = Object.keys(data)
+          if (keys.length === 0) {
+            return yield* new SurrealDBError({ message: `Cannot create record in ${table} with empty data` })
+          }
 
-    try {
-      const created = await client
-        .create<unknown>(new Table(table))
-        .content(this.normalizeMutationData(data))
-        .output('after')
-      const first = Array.isArray(created) ? created.at(0) : created
+          const client = yield* this.ensureConnectedEffect(`CREATE ${table}`)
+          const normalizedData = yield* this.normalizeMutationDataEffect(data)
+          const created = yield* Effect.tryPromise({
+            try: () => client.create<unknown>(new Table(table)).content(normalizedData).output('after'),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to create record in ${table}: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })
+          const first = Array.isArray(created) ? created.at(0) : created
 
-      if (!first) {
-        throw new SurrealDBError(`Failed to create record in ${table}`)
-      }
+          if (!first) {
+            return yield* new SurrealDBError({ message: `Failed to create record in ${table}` })
+          }
 
-      return this.parseSchema(schema, first)
-    } catch (error) {
-      return this.toSurrealError(error, `CREATE ${table}`)
-    }
+          return yield* this.parseSchemaEffect(schema, first)
+        }.bind(this),
+      ),
+    )
   }
 
-  async createWithId<T extends z.ZodTypeAny>(
+  createWithId<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     id: unknown,
     data: Record<string, unknown>,
     schema: T,
-  ): Promise<z.infer<T>> {
-    const keys = Object.keys(data)
-    if (keys.length === 0) {
-      throw new SurrealDBError(`Cannot create record in ${table} with empty data`)
-    }
-
-    const recordId = this.normalizeRecordId(id, table)
-    const client = await this.ensureConnected()
+  ): AwaitableEffect<z.infer<T>, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const recordId = yield* this.normalizeRecordIdEffect(id, table)
+          const keys = Object.keys(data)
+          if (keys.length === 0) {
+            return yield* new SurrealDBError({ message: `Cannot create record in ${table} with empty data` })
+          }
 
-    try {
-      const created = await client.create<unknown>(recordId).content(this.normalizeMutationData(data)).output('after')
-      return this.parseSchema(schema, created)
-    } catch (error) {
-      return this.toSurrealError(error, `CREATE ${recordId.toString()}`)
-    }
+          const client = yield* this.ensureConnectedEffect(`CREATE ${recordId.toString()}`)
+          const normalizedData = yield* this.normalizeMutationDataEffect(data)
+          const created = yield* Effect.tryPromise({
+            try: () => client.create<unknown>(recordId).content(normalizedData).output('after'),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to create record in ${table}: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })
+          return yield* this.parseSchemaEffect(schema, created)
+        }.bind(this),
+      ),
+    )
   }
 
-  async update<T extends z.ZodTypeAny>(
+  update<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     id: unknown,
     data: Record<string, unknown>,
     schema: T,
     options?: { mutation?: RecordMutation },
-  ): Promise<z.infer<T> | null> {
-    const recordId = this.normalizeRecordId(id, table)
-
-    const keys = Object.keys(data)
-    if (keys.length === 0) {
-      throw new SurrealDBError('Cannot update record with empty data')
-    }
-
-    const client = await this.ensureConnected()
-    const mutation = options?.mutation ?? 'merge'
+  ): AwaitableEffect<z.infer<T> | null, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const recordId = yield* this.normalizeRecordIdEffect(id, table)
+          const keys = Object.keys(data)
+          if (keys.length === 0) {
+            return yield* new SurrealDBError({ message: 'Cannot update record with empty data' })
+          }
 
-    try {
-      const builder = client.update<unknown>(recordId)
-      const configured = configureMutation(builder, mutation, this.normalizeMutationData(data))
-      const updated = await configured.output('after')
-      return updated ? this.parseSchema(schema, updated) : null
-    } catch (error) {
-      return this.toSurrealError(error, `UPDATE ${recordId.toString()}`)
-    }
+          const mutation = options?.mutation ?? 'merge'
+          const client = yield* this.ensureConnectedEffect(`UPDATE ${recordId.toString()}`)
+          const builder = client.update<unknown>(recordId)
+          const normalizedData = yield* this.normalizeMutationDataEffect(data)
+          const updated: Record<string, unknown> | null | undefined = yield* Effect.tryPromise({
+            try: () => configureMutation(builder, mutation, normalizedData).output('after'),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to update record in ${table}: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })
+          return yield* this.parseOptionalSchemaEffect(schema, updated)
+        }.bind(this),
+      ),
+    )
   }
 
-  async upsert<T extends z.ZodTypeAny>(
+  upsert<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     id: unknown,
     data: Record<string, unknown>,
     schema: T,
     options?: { mutation?: RecordMutation },
-  ): Promise<z.infer<T>> {
-    const recordId = this.normalizeRecordId(id, table)
-    const keys = Object.keys(data)
-    if (keys.length === 0) {
-      throw new SurrealDBError('Cannot upsert record with empty data')
-    }
+  ): AwaitableEffect<z.infer<T>, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const recordId = yield* this.normalizeRecordIdEffect(id, table)
+          const keys = Object.keys(data)
+          if (keys.length === 0) {
+            return yield* new SurrealDBError({ message: 'Cannot upsert record with empty data' })
+          }
 
-    const client = await this.ensureConnected()
-    const mutation = options?.mutation ?? 'merge'
-
-    try {
-      const builder = client.upsert<unknown>(recordId)
-      const configured = configureMutation(builder, mutation, this.normalizeMutationData(data))
-      const upserted = await configured.output('after')
-      if (!upserted) {
-        throw new SurrealDBError(`Failed to upsert record in ${table}`)
-      }
-      return this.parseSchema(schema, upserted)
-    } catch (error) {
-      return this.toSurrealError(error, `UPSERT ${recordId.toString()}`)
-    }
+          const mutation = options?.mutation ?? 'merge'
+          const client = yield* this.ensureConnectedEffect(`UPSERT ${recordId.toString()}`)
+          const builder = client.upsert<unknown>(recordId)
+          const normalizedData = yield* this.normalizeMutationDataEffect(data)
+          const upserted: Record<string, unknown> | null | undefined = yield* Effect.tryPromise({
+            try: () => configureMutation(builder, mutation, normalizedData).output('after'),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to upsert record in ${table}: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })
+          const parsed = yield* this.parseOptionalSchemaEffect(schema, upserted)
+          if (parsed === null) {
+            return yield* new SurrealDBError({ message: `Failed to upsert record in ${table}` })
+          }
+          return parsed
+        }.bind(this),
+      ),
+    )
   }
 
-  async deleteById(table: DatabaseTable, id: unknown): Promise<boolean> {
-    const recordId = this.normalizeRecordId(id, table)
-
-    try {
-      const result = await this.query<unknown>(new BoundQuery(`DELETE $recordId RETURN BEFORE`, { recordId }))
-      return result.length > 0
-    } catch (error) {
-      if (error instanceof Error && error.message.includes('does not exist')) {
-        return false
-      }
-      return this.toSurrealError(error, `DELETE ${recordId.toString()}`)
-    }
+  deleteById(table: DatabaseTable, id: unknown): AwaitableEffect<boolean, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const recordId = yield* this.normalizeRecordIdEffect(id, table)
+          return yield* this.query<unknown>(new BoundQuery(`DELETE $recordId RETURN BEFORE`, { recordId })).pipe(
+            Effect.map((result) => result.length > 0),
+            Effect.catchTag('SurrealDBError', (error) => {
+              if (error.message.includes('does not exist')) {
+                return Effect.succeed(false)
+              }
+
+              return Effect.fail(this.toSurrealError(error, `DELETE ${recordId.toString()}`))
+            }),
+          )
+        }.bind(this),
+      ),
+    )
   }
 
-  async deleteWhere(table: DatabaseTable, filter: Record<string, unknown>): Promise<number> {
-    this.assertValidIdentifier(table, 'table name')
-    const filterKeys = Object.keys(filter)
-    if (filterKeys.length === 0) {
-      throw new SurrealDBError(`Refusing to delete all records in ${table} without a filter`)
-    }
-    const { clause, bindings } = this.buildBoundFilterClauses(filter)
-
-    try {
-      return await this.withTransaction(async (tx) => {
-        const matched = (await tx.query(new BoundQuery(`SELECT id FROM ${table} WHERE ${clause}`, bindings))) as Array<{
-          id: unknown
-        }>
-
-        if (matched.length === 0) {
-          return 0
-        }
-
-        for (const row of matched) {
-          await tx.delete(this.normalizeRecordId(row.id, table))
-        }
-
-        return matched.length
-      })
-    } catch (error) {
-      return this.toSurrealError(error, `DELETE ${table} WHERE ...`)
-    }
+  deleteWhere(table: DatabaseTable, filter: Record<string, unknown>): AwaitableEffect<number, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          yield* this.assertValidIdentifierEffect(table, 'table name')
+          const filterKeys = Object.keys(filter)
+          if (filterKeys.length === 0) {
+            return yield* new SurrealDBError({ message: `Refusing to delete all records in ${table} without a filter` })
+          }
+          const { clause, bindings } = yield* this.buildBoundFilterClausesEffect(filter)
+          return yield* this.withTransaction((tx) =>
+            Effect.gen(
+              function* (this: SurrealDBService) {
+                const matchedRows = (yield* tx.query(
+                  new BoundQuery(`SELECT id FROM ${table} WHERE ${clause}`, bindings),
+                )) as Array<{ id: unknown }>
+
+                if (matchedRows.length === 0) {
+                  return 0
+                }
+
+                for (const row of matchedRows) {
+                  const recordId = yield* this.normalizeRecordIdEffect(row.id, table)
+                  yield* tx.delete(recordId)
+                }
+
+                return matchedRows.length
+              }.bind(this),
+            ),
+          )
+        }.bind(this),
+      ),
+    )
   }
 
-  async updateWhere(table: DatabaseTable, where: ExprLike, data: Record<string, unknown>): Promise<number> {
-    if (!where) {
-      throw new SurrealDBError(`Refusing to update records in ${table} without a where clause`)
-    }
-    const keys = Object.keys(data)
-    if (keys.length === 0) {
-      throw new SurrealDBError(`Cannot update records in ${table} with empty data`)
-    }
+  updateWhere(
+    table: DatabaseTable,
+    where: ExprLike,
+    data: Record<string, unknown>,
+  ): AwaitableEffect<number, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          if (!where) {
+            return yield* new SurrealDBError({
+              message: `Refusing to update records in ${table} without a where clause`,
+            })
+          }
+          const keys = Object.keys(data)
+          if (keys.length === 0) {
+            return yield* new SurrealDBError({ message: `Cannot update records in ${table} with empty data` })
+          }
 
-    const client = await this.ensureConnected()
-
-    try {
-      const updated = await client
-        .update<unknown>(new Table(table))
-        .where(where)
-        .merge(this.normalizeMutationData(data))
-        .output('after')
-      if (Array.isArray(updated)) {
-        return updated.length
-      }
-      return 1
-    } catch (error) {
-      return this.toSurrealError(error, `UPDATE ${table} WHERE ...`)
-    }
+          const client = yield* this.ensureConnectedEffect(`UPDATE ${table} WHERE ...`)
+          const normalizedData = yield* this.normalizeMutationDataEffect(data)
+          const updated = yield* Effect.tryPromise({
+            try: () => client.update<unknown>(new Table(table)).where(where).merge(normalizedData).output('after'),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to update records in ${table}: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })
+          return Array.isArray(updated) ? updated.length : 1
+        }.bind(this),
+      ),
+    )
   }
 
-  async insert<T extends Record<string, unknown>>(
+  insert<T extends Record<string, unknown>>(
     table: DatabaseTable,
     data: Values<T> | Array<Values<T>>,
-  ): Promise<T[]> {
-    const client = await this.ensureConnected()
-
-    try {
-      const normalized = Array.isArray(data)
-        ? data.map((item) => this.normalizeMutationData(item as Record<string, unknown>))
-        : this.normalizeMutationData(data as Record<string, unknown>)
-      const inserted = await client
-        .insert<T>(new Table(table), normalized as Values<T> | Array<Values<T>>)
-        .output('after')
-      return inserted as T[]
-    } catch (error) {
-      return this.toSurrealError(error, `INSERT ${table}`)
-    }
+  ): AwaitableEffect<T[], SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const client = yield* this.ensureConnectedEffect(`INSERT ${table}`)
+          const normalized = Array.isArray(data)
+            ? yield* Effect.forEach(data, (item) => this.normalizeMutationDataEffect(item as Record<string, unknown>))
+            : yield* this.normalizeMutationDataEffect(data as Record<string, unknown>)
+          const inserted = yield* Effect.tryPromise({
+            try: () => client.insert<T>(new Table(table), normalized as Values<T> | Array<Values<T>>).output('after'),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to insert rows into ${table}: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })
+          return inserted as T[]
+        }.bind(this),
+      ),
+    )
   }
 
-  async relate<T extends Record<string, unknown>>(
+  relate<T extends Record<string, unknown>>(
     from: RecordIdInput,
     edgeTable: DatabaseTable,
     to: RecordIdInput,
     data?: Values<T>,
-  ): Promise<T | null> {
-    const client = await this.ensureConnected()
-    const fromRef = ensureRecordId(from)
-    const toRef = ensureRecordId(to)
-
-    try {
-      const normalizedData = data
-        ? (this.normalizeMutationData(data as Record<string, unknown>) as Values<T>)
-        : undefined
-      const related = (await client.relate<T>(fromRef, new Table(edgeTable), toRef, normalizedData).output('after')) as
-        | T
-        | T[]
-        | null
-      if (related === null) {
-        return null
-      }
-      if (Array.isArray(related)) {
-        return related.at(0) ?? null
-      }
-      return related
-    } catch (error) {
-      return this.toSurrealError(error, `RELATE ${fromRef.toString()}->${edgeTable}->${toRef.toString()}`)
-    }
+  ): AwaitableEffect<T | null, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const fromRef = yield* ensureRecordIdEffect(from).pipe(Effect.mapError((error) => this.toSurrealError(error)))
+          const toRef = yield* ensureRecordIdEffect(to).pipe(Effect.mapError((error) => this.toSurrealError(error)))
+          const client = yield* this.ensureConnectedEffect(
+            `RELATE ${fromRef.toString()}->${edgeTable}->${toRef.toString()}`,
+          )
+          const normalizedData = data
+            ? ((yield* this.normalizeMutationDataEffect(data as Record<string, unknown>)) as Values<T>)
+            : undefined
+          const related = (yield* Effect.tryPromise({
+            try: () => client.relate<T>(fromRef, new Table(edgeTable), toRef, normalizedData).output('after'),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to relate records ${fromRef.toString()} -> ${edgeTable} -> ${toRef.toString()}: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          })) as T | T[] | null
+          if (related === null) {
+            return null
+          }
+          if (Array.isArray(related)) {
+            return related.at(0) ?? null
+          }
+          return related
+        }.bind(this),
+      ),
+    )
   }
 
-  async beginTransaction(): Promise<DatabaseTransaction> {
-    const client = await this.ensureConnected()
-    try {
-      return this.wrapTransaction(await client.beginTransaction())
-    } catch (error) {
-      return this.toSurrealError(error, 'BEGIN TRANSACTION')
-    }
+  beginTransaction(): AwaitableEffect<DatabaseTransaction, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.gen(
+        function* (this: SurrealDBService) {
+          const client = yield* this.ensureConnectedEffect('BEGIN TRANSACTION')
+          const tx = yield* Effect.tryPromise({
+            try: () => client.beginTransaction(),
+            catch: (error) =>
+              new SurrealDBError({ message: `Failed to begin transaction: ${getErrorMessage(error)}`, cause: error }),
+          })
+          return this.wrapTransaction(tx)
+        }.bind(this),
+      ),
+    )
   }
 
-  async withTransaction<T>(work: (tx: DatabaseTransaction) => Promise<T>): Promise<T> {
-    const tx = await this.beginTransaction()
-    try {
-      const result = await work(tx)
-      await tx.commit()
-      return result
-    } catch (error) {
-      try {
-        await tx.cancel()
-      } catch (cancelError) {
-        this.logger?.warn?.(
-          `Failed to cancel transaction after error: ${
-            cancelError instanceof Error ? cancelError.message : String(cancelError)
-          }`,
+  withTransaction<T, E, R>(
+    work: (tx: DatabaseTransaction) => Effect.Effect<T, E, R>,
+  ): Effect.Effect<T, SurrealDBError | E, R> {
+    return Effect.gen(
+      function* (this: SurrealDBService) {
+        const tx = yield* this.beginTransaction()
+        const cancelEffect = tx.cancel().pipe(
+          Effect.catch((cancelError: SurrealDBError) =>
+            Effect.sync(() => {
+              this.logger?.warn?.(`Failed to cancel transaction after error: ${cancelError.message}`)
+            }),
+          ),
+          Effect.asVoid,
         )
-      }
-      throw error
-    }
-  }
-}
 
-let currentDatabaseService: SurrealDBService | undefined
-const databaseServiceOverrides = new Map<PropertyKey, unknown>()
-
-function bindTargetMethod(
-  target: Record<PropertyKey, unknown>,
-  value: (...args: unknown[]) => unknown,
-): (...args: unknown[]) => unknown {
-  return (...args) => Reflect.apply(value, target, args)
-}
-
-function resolveConfiguredDatabaseService(): SurrealDBService {
-  if (!currentDatabaseService) {
-    throw new SurrealDBError('Database service not configured')
-  }
-
-  return currentDatabaseService
-}
-
-export const databaseService = new Proxy({} as SurrealDBService, {
-  get(_target, property) {
-    if (databaseServiceOverrides.has(property)) {
-      return databaseServiceOverrides.get(property)
-    }
-
-    const resolved = resolveConfiguredDatabaseService()
-    const value: unknown = Reflect.get(resolved, property)
-    if (typeof value === 'function') {
-      // SurrealDB SDK type gap — Reflect.get returns unknown, but we know the resolved target shape
-      return bindTargetMethod(
-        resolved as unknown as Record<PropertyKey, unknown>,
-        value as (...args: unknown[]) => unknown,
-      )
-    }
-
-    return value
-  },
-  set(_target, property, value) {
-    databaseServiceOverrides.set(property, value)
-    return true
-  },
-})
-
-export function setDatabaseService(db: SurrealDBService): void {
-  if (db === databaseService) {
-    return
+        return yield* Effect.gen(function* () {
+          const result = yield* work(tx)
+          yield* tx.commit()
+          return result
+        }).pipe(Effect.onError(() => cancelEffect))
+      }.bind(this),
+    )
   }
-
-  currentDatabaseService = db
 }