@lota-sdk/core 0.4.13 → 0.4.14

package/src/db/memory.ts

@@ -3,6 +3,7 @@ import { Effect } from 'effect'
 import type { z } from 'zod'
 
 import { aiLogger } from '../config/logger'
+import { ERROR_TAGS } from '../effect/errors'
 import type { CreateHelperAgentFn, HelperModelRuntime } from '../runtime/helper-model'
 import { formatResults } from '../runtime/memory/memory-format'
 import {
@@ -16,8 +17,8 @@ import { getFactRetrievalMessages } from '../runtime/memory/memory-prompts-fact'
 import { parseMessages } from '../runtime/memory/memory-prompts-parse'
 import { getClassifyMemoryDeltaPrompt } from '../runtime/memory/memory-prompts-update'
 import type { ResolvedLotaRuntimeConfig } from '../runtime/runtime-config'
-import type { BackgroundWorkService } from '../services/background-work.service'
-import { MemoryServiceError, tryMemoryPromise } from '../services/memory/memory-errors'
+import type { BackgroundWorkServiceTag } from '../services/background-work.service'
+import { MemoryServiceError } from '../services/memory/memory-errors'
 import { sha256Hex } from '../utils/crypto'
 import { compactWhitespace, truncateText } from '../utils/string'
 import type { SurrealMemoryStore } from './memory-store'
@@ -70,7 +71,8 @@ export class Memory {
       db: SurrealDBService
       runtimeConfig: ResolvedLotaRuntimeConfig
       helperModelRuntime: HelperModelRuntime
-      background: Context.Service.Shape<typeof BackgroundWorkService>
+      background: Context.Service.Shape<typeof BackgroundWorkServiceTag>
+      runPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>
     },
     agent: { createAgent: CreateHelperAgentFn; maxOutputTokens?: number },
     config: MemoryConfig = {},
@@ -80,6 +82,7 @@ export class Memory {
       {
         embeddingModel: deps.runtimeConfig.aiGateway.embeddingModel,
         openRouterApiKey: deps.runtimeConfig.aiGateway.openRouterApiKey,
+        runPromise: deps.runPromise,
       },
       deps.background,
     )
@@ -115,25 +118,25 @@ export class Memory {
       durability?: Durability
     },
   ): Effect.Effect<string, MemoryServiceError, never> {
-    return tryMemoryPromise('Failed to insert memory.', () =>
-      this.store.insert(
+    return this.store
+      .insert(
         content,
         options.scopeId,
         options.memoryType,
         options.metadata ?? {},
         options.importance ?? 1,
         options.durability ?? 'standard',
-      ),
-    )
+      )
+      .pipe(Effect.mapError((cause) => new MemoryServiceError({ message: 'Failed to insert memory.', cause })))
   }
 
   search(query: string, options: SearchOptions): Effect.Effect<string, MemoryServiceError, never> {
     return Effect.gen(
       function* (this: Memory) {
         const limit = options.limit ?? this.runtimeConfig.memory.searchK
-        const results = yield* tryMemoryPromise('Failed to search memory.', () =>
-          this.store.search(query, options.scopeId, limit, options.memoryType),
-        )
+        const results = yield* this.store
+          .search(query, options.scopeId, limit, options.memoryType)
+          .pipe(Effect.mapError((cause) => new MemoryServiceError({ message: 'Failed to search memory.', cause })))
         return formatResults(results)
       }.bind(this),
     )
@@ -143,9 +146,11 @@ export class Memory {
     return Effect.gen(
       function* (this: Memory) {
         const limit = options.limit ?? this.runtimeConfig.memory.searchK
-        const results = yield* tryMemoryPromise('Failed to perform hybrid search.', () =>
-          this.store.hybridSearch(query, options.scopeId, limit, options.memoryType),
-        )
+        const results = yield* this.store
+          .hybridSearch(query, options.scopeId, limit, options.memoryType)
+          .pipe(
+            Effect.mapError((cause) => new MemoryServiceError({ message: 'Failed to perform hybrid search.', cause })),
+          )
         return formatResults(results)
       }.bind(this),
     )
@@ -158,15 +163,19 @@ export class Memory {
     return Effect.gen(
       function* (this: Memory) {
         const limit = options.limit ?? this.runtimeConfig.memory.searchK
-        const results = yield* tryMemoryPromise('Failed to perform weighted hybrid search.', () =>
-          this.store.hybridSearchWeighted(query, {
+        const results = yield* this.store
+          .hybridSearchWeighted(query, {
             scopeId: options.scopeId,
             limit,
             memoryType: options.memoryType,
             weights: options.weights,
             normalization: options.normalization,
-          }),
-        )
+          })
+          .pipe(
+            Effect.mapError(
+              (cause) => new MemoryServiceError({ message: 'Failed to perform weighted hybrid search.', cause }),
+            ),
+          )
         return formatResults(results)
       }.bind(this),
     )
@@ -179,24 +188,32 @@ export class Memory {
     return Effect.gen(
       function* (this: Memory) {
         const limit = options.limit ?? this.runtimeConfig.memory.searchK
-        const results = yield* tryMemoryPromise('Failed to search memory candidates.', () =>
-          this.store.hybridSearchWeighted(query, {
+        const results = yield* this.store
+          .hybridSearchWeighted(query, {
             scopeId: options.scopeId,
             limit,
             memoryType: options.memoryType,
             weights: options.weights,
             normalization: options.normalization,
             fastMode: options.fastMode,
-          }),
-        )
+          })
+          .pipe(
+            Effect.mapError(
+              (cause) => new MemoryServiceError({ message: 'Failed to search memory candidates.', cause }),
+            ),
+          )
 
         if (options.fastMode || options.includeNeighborContext === false) {
           return results
         }
 
-        return yield* tryMemoryPromise('Failed to enrich memory candidates.', () =>
-          this.store.enrichWithNeighbors(results),
-        )
+        return yield* this.store
+          .enrichWithNeighbors(results)
+          .pipe(
+            Effect.mapError(
+              (cause) => new MemoryServiceError({ message: 'Failed to enrich memory candidates.', cause }),
+            ),
+          )
       }.bind(this),
     )
   }
@@ -208,15 +225,21 @@ export class Memory {
     durability?: Durability
     minImportance?: number
   }): Effect.Effect<MemoryRecord[], MemoryServiceError, never> {
-    return tryMemoryPromise('Failed to list top memories.', () => this.store.listTopMemories(options))
+    return this.store
+      .listTopMemories(options)
+      .pipe(Effect.mapError((cause) => new MemoryServiceError({ message: 'Failed to list top memories.', cause })))
   }
 
   list(options: MemoryListOptions): Effect.Effect<MemoryRecord[], MemoryServiceError, never> {
-    return tryMemoryPromise('Failed to list memories.', () => this.store.list(options))
+    return this.store
+      .list(options)
+      .pipe(Effect.mapError((cause) => new MemoryServiceError({ message: 'Failed to list memories.', cause })))
   }
 
   updateMemory(id: string, newContent: string): Effect.Effect<void, MemoryServiceError, never> {
-    return tryMemoryPromise(`Failed to update memory ${id}.`, () => this.store.update(id, newContent))
+    return this.store
+      .update(id, newContent)
+      .pipe(Effect.mapError((cause) => new MemoryServiceError({ message: `Failed to update memory ${id}.`, cause })))
   }
 
   addRelation(
@@ -225,13 +248,19 @@ export class Memory {
     relationType: RelationType,
     confidence = 1,
   ): Effect.Effect<void, MemoryServiceError, never> {
-    return tryMemoryPromise(`Failed to add ${relationType} relation.`, () =>
-      this.store.addRelation(fromId, toId, relationType, confidence),
-    )
+    return this.store
+      .addRelation(fromId, toId, relationType, confidence)
+      .pipe(
+        Effect.mapError(
+          (cause) => new MemoryServiceError({ message: `Failed to add ${relationType} relation.`, cause }),
+        ),
+      )
   }
 
   getStaleMemories(scopeId: string, limit?: number): Effect.Effect<MemorySearchResult[], MemoryServiceError, never> {
-    return tryMemoryPromise('Failed to load stale memories.', () => this.store.getStaleMemories(scopeId, limit))
+    return this.store
+      .getStaleMemories(scopeId, limit)
+      .pipe(Effect.mapError((cause) => new MemoryServiceError({ message: 'Failed to load stale memories.', cause })))
   }
 
   extractFactsFromMessages(
@@ -277,8 +306,8 @@ export class Memory {
     return Effect.forEach(
       prepared,
       (item) =>
-        tryMemoryPromise('Failed to apply memory updates', () =>
-          this.applyUpdates(item.updates, item.options, item.factMaps, item.existingMemories),
+        this.applyUpdates(item.updates, item.options, item.factMaps, item.existingMemories).pipe(
+          Effect.mapError((cause) => new MemoryServiceError({ message: 'Failed to apply memory updates', cause })),
         ),
       { concurrency: 2, discard: true },
     )
@@ -296,9 +325,14 @@ export class Memory {
         const factContents = facts.map((fact) => fact.content)
         const scopePayloads = yield* Effect.all(
           scopes.map((scopeOptions) =>
-            tryMemoryPromise(`Failed to list memories for scope ${scopeOptions.scopeId}.`, () =>
-              this.store.list({ scopeId: scopeOptions.scopeId, memoryType: scopeOptions.memoryType }),
-            ).pipe(
+            this.store.list({ scopeId: scopeOptions.scopeId, memoryType: scopeOptions.memoryType }).pipe(
+              Effect.mapError(
+                (cause) =>
+                  new MemoryServiceError({
+                    message: `Failed to list memories for scope ${scopeOptions.scopeId}.`,
+                    cause,
+                  }),
+              ),
               Effect.map((existingMemories) => {
                 const normalizedMemories = existingMemories.map((memory) => ({ id: memory.id, text: memory.content }))
                 const scopeMemoryIdsByUnionId: Record<string, string[]> = {}
@@ -378,7 +412,7 @@ export class Memory {
         )
       }.bind(this),
     ).pipe(
-      Effect.catchTag('MemoryServiceError', (error) =>
+      Effect.catchTag(ERROR_TAGS.MemoryServiceError, (error) =>
         Effect.sync(() => {
           aiLogger.warn`Failed to extract facts: ${error.message}`
           return []
@@ -564,37 +598,45 @@ export class Memory {
               const metadata = { ...options.metadata, memoryCategory: action.category }
               const hash = hashContent(action.text, options.scopeId, options.memoryType)
 
-              const newId = yield* tryMemoryPromise(`Failed to insert memory for scope ${options.scopeId}.`, () =>
-                this.store.insert(
+              const newId = yield* this.store
+                .insert(
                   action.text,
                   options.scopeId,
                   options.memoryType,
                   metadata,
                   action.importance,
                   action.durability as Durability,
-                ),
-              ).pipe(
-                Effect.catchTag('MemoryServiceError', (error) => {
-                  if (!isUniqueIndexConflict(error.cause, 'memoryHashIdx')) {
-                    return Effect.fail(error)
-                  }
-
-                  return tryMemoryPromise(`Failed to look up memory hash ${hash}.`, () =>
-                    this.store.getByHash(hash),
-                  ).pipe(
-                    Effect.flatMap((existing) => {
-                      if (!existing) {
-                        return Effect.fail(error)
-                      }
-
-                      return Effect.sync(() => {
-                        aiLogger.debug`Skipped duplicate memory insert due to hash conflict: ${existing.id}`
-                        return existing.id
-                      })
-                    }),
-                  )
-                }),
-              )
+                )
+                .pipe(
+                  Effect.mapError(
+                    (cause) =>
+                      new MemoryServiceError({
+                        message: `Failed to insert memory for scope ${options.scopeId}.`,
+                        cause,
+                      }),
+                  ),
+                  Effect.catchTag(ERROR_TAGS.MemoryServiceError, (error) => {
+                    if (!isUniqueIndexConflict(error.cause, 'memoryHashIdx')) {
+                      return Effect.fail(error)
+                    }
+
+                    return this.store.getByHash(hash).pipe(
+                      Effect.mapError(
+                        (cause) => new MemoryServiceError({ message: `Failed to look up memory hash ${hash}.`, cause }),
+                      ),
+                      Effect.flatMap((existing) => {
+                        if (!existing) {
+                          return Effect.fail(error)
+                        }
+
+                        return Effect.sync(() => {
+                          aiLogger.debug`Skipped duplicate memory insert due to hash conflict: ${existing.id}`
+                          return existing.id
+                        })
+                      }),
+                    )
+                  }),
+                )
 
               idMap.set(action.refId, newId)
               aiLogger.debug`Added new memory (memoryType: ${options.memoryType}, category: ${action.category}, durability: ${action.durability}, importance: ${action.importance.toFixed(2)}, content: ${truncatedContent})`
@@ -603,20 +645,30 @@ export class Memory {
 
             case 'update': {
               const metadata = { ...options.metadata, ...(action.category ? { memoryCategory: action.category } : {}) }
-              yield* tryMemoryPromise(`Failed to update memory ${action.refId}.`, () =>
-                this.store.update(action.refId, action.text, {
+              yield* this.store
+                .update(action.refId, action.text, {
                   importance: action.importance,
                   durability: action.durability as Durability | undefined,
                   metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
-                }),
-              )
+                })
+                .pipe(
+                  Effect.mapError(
+                    (cause) => new MemoryServiceError({ message: `Failed to update memory ${action.refId}.`, cause }),
+                  ),
+                )
               idMap.set(action.refId, action.refId)
               aiLogger.debug`Updated memory ${action.refId}: ${truncateText(action.text, 50)}`
               break
             }
 
             case 'delete':
-              yield* tryMemoryPromise(`Failed to delete memory ${action.refId}.`, () => this.store.delete(action.refId))
+              yield* this.store
+                .delete(action.refId)
+                .pipe(
+                  Effect.mapError(
+                    (cause) => new MemoryServiceError({ message: `Failed to delete memory ${action.refId}.`, cause }),
+                  ),
+                )
               aiLogger.debug`Deleted memory ${action.refId}`
               break
           }
@@ -627,15 +679,17 @@ export class Memory {
           if (!fromId) continue
 
           const toId = idMap.get(relation.toRefId) ?? relation.toRefId
-          yield* tryMemoryPromise(`Failed to create memory relation ${relation.relation}.`, () =>
-            this.store.addRelation(fromId, toId, relation.relation),
-          ).pipe(
+          yield* this.store.addRelation(fromId, toId, relation.relation).pipe(
+            Effect.mapError(
+              (cause) =>
+                new MemoryServiceError({ message: `Failed to create memory relation ${relation.relation}.`, cause }),
+            ),
             Effect.tap(() =>
               Effect.sync(() => {
                 aiLogger.debug`Created ${relation.relation} relation: ${fromId} -> ${toId}`
               }),
             ),
-            Effect.catchTag('MemoryServiceError', (error) =>
+            Effect.catchTag(ERROR_TAGS.MemoryServiceError, (error) =>
               Effect.sync(() => {
                 aiLogger.warn`Failed to create memory relation (non-fatal, graph may be incomplete): ${error.message}`
               }),

package/src/db/schema-fingerprint.ts

@@ -1,15 +1,16 @@
 import { Schema, Effect } from 'effect'
 
+import { ERROR_TAGS } from '../effect/errors'
 import { createSha256Hasher } from '../utils/crypto'
 
 function toSchemaFilePath(value: string | URL): string {
   return value instanceof URL ? value.pathname : value
 }
 
-class SchemaFingerprintError extends Schema.TaggedErrorClass<SchemaFingerprintError>()('SchemaFingerprintError', {
-  message: Schema.String,
-  cause: Schema.Defect,
-}) {}
+class SchemaFingerprintError extends Schema.TaggedErrorClass<SchemaFingerprintError>()(
+  ERROR_TAGS.SchemaFingerprintError,
+  { message: Schema.String, cause: Schema.Defect },
+) {}
 
 export function computeSchemaFingerprint(schemaFiles: readonly (string | URL)[]): Promise<string> {
   return Effect.runPromise(

package/src/db/service-normalization.ts

@@ -2,7 +2,7 @@
  * Normalization helpers for SurrealDB service inputs.
  *
  * Helpers that can fail return `Effect<T, SurrealDBError>` so callers can
- * `yield*` them inside `Effect.gen` and use `catchTag('SurrealDBError')`
+ * `yield*` them inside `Effect.gen` and use `catchTag('@lota-sdk/core/SurrealDBError')`
  * without losing the typed failure channel.
  */
 import { Effect, Schema } from 'effect'
@@ -10,12 +10,13 @@ import { BoundQuery, RecordId, StringRecordId, Table, and, eq } from 'surrealdb'
 import type { ExprLike, Mutation } from 'surrealdb'
 import type { z } from 'zod'
 
+import { ERROR_TAGS } from '../effect/errors'
 import { isRecord } from '../utils/string'
 import type { RecordIdInput } from './record-id'
 import { ensureRecordId, isRecordIdInput, isSurrealRecordIdValue } from './record-id'
 import type { DatabaseTable } from './tables'
 
-export class SurrealDBError extends Schema.TaggedErrorClass<SurrealDBError>()('SurrealDBError', {
+export class SurrealDBError extends Schema.TaggedErrorClass<SurrealDBError>()(ERROR_TAGS.SurrealDBError, {
   message: Schema.String,
   query: Schema.optional(Schema.String),
   cause: Schema.optional(Schema.Defect),
@@ -28,7 +29,7 @@ type TransactionQueryDescriptor = { query: string; bindings?: Record<string, unk
 type ParseSchema = <TSchema extends z.ZodTypeAny>(schema: TSchema, value: unknown) => z.infer<TSchema>
 
 function isSurrealDBError(error: unknown): error is SurrealDBError {
-  return isRecord(error) && error._tag === 'SurrealDBError'
+  return isRecord(error) && error._tag === ERROR_TAGS.SurrealDBError
 }
 
 function toSurrealDBError(error: unknown, fallbackMessage: string): SurrealDBError {

package/src/db/service.ts

@@ -5,6 +5,7 @@ import { ZodError } from 'zod'
 import type { z } from 'zod'
 
 import { serverLogger } from '../config/logger'
+import { ERROR_TAGS } from '../effect/errors'
 import { getErrorMessage } from '../utils/errors'
 import type { RecordIdInput, ensureRecordId } from './record-id'
 import { ensureRecordIdEffect } from './record-id'
@@ -107,7 +108,7 @@ function isRetriableConnectError(error: unknown): boolean {
 }
 
 function isSurrealDBError(error: unknown): error is SurrealDBError {
-  return typeof error === 'object' && error !== null && (error as { _tag?: unknown })._tag === 'SurrealDBError'
+  return typeof error === 'object' && error !== null && (error as { _tag?: unknown })._tag === ERROR_TAGS.SurrealDBError
 }
 
 export class SurrealDBService {
@@ -926,7 +927,7 @@ export class 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) => {
+          Effect.catchTag(ERROR_TAGS.SurrealDBError, (error) => {
             if (error.message.includes('does not exist')) {
               return Effect.succeed(false)
             }

package/src/db/startup.ts

@@ -4,7 +4,6 @@ import { BoundQuery, RecordId } from 'surrealdb'
 import { z } from 'zod'
 
 import { DatabaseError } from '../effect/errors'
-import { effectTryPromise } from '../effect/helpers'
 import { nowDate } from '../utils/date-time'
 import { getErrorMessage } from '../utils/errors'
 import type { SurrealDBService, SurrealDatabaseLogger } from './service'
@@ -35,7 +34,7 @@ function shouldLogRetry(attempt: number): boolean {
 }
 
 function connectWithStartupRetryEffectInternal(params: {
-  connect: () => PromiseLike<void> | Effect.Effect<void, SurrealDBError>
+  connect: () => Promise<void>
   label: string
   logger?: StartupLogger
   retryDelayMs?: number
@@ -46,10 +45,11 @@ function connectWithStartupRetryEffectInternal(params: {
 
   let attempt = 0
 
-  const connectEffect = effectTryPromise(
-    () => params.connect(),
-    (error) => new DatabaseError({ message: `Waiting for ${params.label}: ${getErrorMessage(error)}`, cause: error }),
-  )
+  const connectEffect = Effect.tryPromise({
+    try: () => params.connect(),
+    catch: (error) =>
+      new DatabaseError({ message: `Waiting for ${params.label}: ${getErrorMessage(error)}`, cause: error }),
+  })
 
   return connectEffect.pipe(
     Effect.tapError((error) =>
@@ -75,7 +75,7 @@ function connectWithStartupRetryEffectInternal(params: {
 }
 
 export function connectWithStartupRetry(params: {
-  connect: () => PromiseLike<void> | Effect.Effect<void, SurrealDBError>
+  connect: () => Promise<void>
   label: string
   logger?: StartupLogger
   retryDelayMs?: number
@@ -104,7 +104,7 @@ function waitForDatabaseBootstrapEffectInternal(params: {
   expectedFingerprint?: string | null
   label: string
   logger?: StartupLogger
-  connect?: () => PromiseLike<void> | Effect.Effect<void, SurrealDBError>
+  connect?: () => Promise<void>
   retryDelayMs?: number
   maxWaitMs?: number
 }): Effect.Effect<void, DatabaseError> {
@@ -120,15 +120,14 @@ function waitForDatabaseBootstrapEffectInternal(params: {
   const readBootstrapRecord = Effect.gen(function* () {
     const connect = params.connect
     if (connect) {
-      yield* effectTryPromise(
-        () => connect(),
-        (error): BootstrapWaitFailure => ({ _tag: 'read-failed', cause: error }),
-      )
+      yield* Effect.tryPromise({
+        try: () => connect(),
+        catch: (error): BootstrapWaitFailure => ({ _tag: 'read-failed', cause: error }),
+      })
     }
 
-    return yield* effectTryPromise(
-      () => readDatabaseBootstrapRecord(params.databaseService),
-      (error): BootstrapWaitFailure => ({ _tag: 'read-failed', cause: error }),
+    return yield* readDatabaseBootstrapRecord(params.databaseService).pipe(
+      Effect.mapError((error): BootstrapWaitFailure => ({ _tag: 'read-failed', cause: error })),
     )
   })
 
@@ -194,7 +193,7 @@ export function waitForDatabaseBootstrap(params: {
   expectedFingerprint?: string | null
   label: string
   logger?: StartupLogger
-  connect?: () => PromiseLike<void> | Effect.Effect<void, SurrealDBError>
+  connect?: () => Promise<void>
   retryDelayMs?: number
   maxWaitMs?: number
 }): Promise<void> {