@lota-sdk/core 0.1.5

package/src/db/base.service.ts

@@ -0,0 +1,55 @@
+import type { z } from 'zod'
+
+import { NotFoundError } from '../utils/errors'
+import { databaseService as defaultDatabaseService } from './service'
+import type { SurrealDBService } from './service'
+import type { DatabaseTable } from './tables'
+
+export abstract class BaseService<T extends z.ZodType> {
+  protected readonly db: SurrealDBService
+  constructor(
+    protected readonly table: DatabaseTable,
+    protected readonly schema: T,
+    protected readonly databaseService: SurrealDBService = defaultDatabaseService,
+  ) {
+    this.db = this.databaseService
+  }
+
+  async findById(id: unknown): Promise<z.infer<T> | null> {
+    return this.databaseService.findOne(this.table, { id }, this.schema)
+  }
+
+  async getById(id: unknown): Promise<z.infer<T>> {
+    const record = await this.findById(id)
+    if (!record) {
+      throw new NotFoundError(`${this.table} record not found`)
+    }
+    return record
+  }
+
+  async findAll(
+    filter: Record<string, unknown> = {},
+    options?: { limit?: number; offset?: number; orderBy?: keyof z.infer<T> & string; orderDir?: 'ASC' | 'DESC' },
+  ): Promise<z.infer<T>[]> {
+    return this.databaseService.findMany(this.table, filter, this.schema, options)
+  }
+
+  async create(data: Record<string, unknown>): Promise<z.infer<T>> {
+    return this.databaseService.create(this.table, data, this.schema)
+  }
+
+  async update(id: unknown, data: Record<string, unknown>): Promise<z.infer<T>> {
+    const updated = await this.databaseService.update(this.table, id, data, this.schema)
+    if (!updated) {
+      throw new NotFoundError(`${this.table} record not found`)
+    }
+    return updated
+  }
+
+  async delete(id: unknown): Promise<void> {
+    const deleted = await this.databaseService.deleteById(this.table, id)
+    if (!deleted) {
+      throw new NotFoundError(`${this.table} record not found`)
+    }
+  }
+}

package/src/db/cursor-pagination.ts

@@ -0,0 +1,73 @@
+import { toTimestamp } from '@lota-sdk/shared/runtime/chat-message-metadata'
+import type { ChatMessage } from '@lota-sdk/shared/schemas/chat-message'
+import type { BoundQuery, RecordId } from 'surrealdb'
+import { z } from 'zod'
+
+import type { RecordIdRef } from './record-id'
+import { databaseService } from './service'
+import type { DatabaseTable } from './tables'
+
+export const CursorRowSchema = z.object({ createdAt: z.union([z.date(), z.string(), z.number()]) })
+
+export interface MessageHistoryPage {
+  messages: ChatMessage[]
+  hasMore: boolean
+  prevCursor: string | null
+}
+
+export interface CursorPaginationConfig {
+  table: DatabaseTable
+  parentFilterField: string
+  toRowId: (parentId: RecordIdRef, messageId: string) => RecordId
+  parseRow: (row: unknown) => { messageId: string }
+  toMessage: (row: unknown) => ChatMessage
+  queryLatest: (parentId: RecordIdRef, limit: number) => BoundQuery
+  queryBefore: (parentId: RecordIdRef, cursorCreatedAt: Date, cursorId: RecordId, limit: number) => BoundQuery
+}
+
+export async function listMessageHistoryPage(
+  config: CursorPaginationConfig,
+  params: { parentId: RecordIdRef; take: number; beforeMessageId?: string },
+): Promise<MessageHistoryPage> {
+  const take = Math.max(1, params.take)
+  const beforeMessageId = params.beforeMessageId?.trim()
+  const limit = take + 1
+
+  const rows = beforeMessageId
+    ? await listRowsBefore(config, { parentId: params.parentId, beforeMessageId, take: limit })
+    : await databaseService.query<unknown>(config.queryLatest(params.parentId, limit))
+
+  const parsedRows = rows.map((row) => config.parseRow(row))
+  const hasMore = parsedRows.length > take
+  const pageRows = hasMore ? rows.slice(0, take) : rows
+
+  pageRows.reverse()
+
+  return {
+    messages: pageRows.map((row) => config.toMessage(row)),
+    hasMore,
+    prevCursor: hasMore ? config.parseRow(pageRows[0]).messageId : null,
+  }
+}
+
+async function listRowsBefore(
+  config: CursorPaginationConfig,
+  params: { parentId: RecordIdRef; beforeMessageId: string; take: number },
+): Promise<unknown[]> {
+  const cursorRow = await databaseService.findOne(
+    config.table,
+    { [config.parentFilterField]: params.parentId, messageId: params.beforeMessageId },
+    CursorRowSchema,
+  )
+
+  if (!cursorRow) {
+    throw new Error(`Cursor message not found in ${config.table}: ${params.beforeMessageId}`)
+  }
+
+  const cursorCreatedAt = new Date(toTimestamp(cursorRow.createdAt))
+  const cursorId = config.toRowId(params.parentId, params.beforeMessageId)
+
+  return await databaseService.query<unknown>(
+    config.queryBefore(params.parentId, cursorCreatedAt, cursorId, params.take),
+  )
+}

package/src/db/memory-query-builder.ts

@@ -0,0 +1,207 @@
+/**
+ * Query builder for SurrealDB memory operations
+ * Builds type-safe SQL queries with proper parameterization
+ */
+
+import { validateKnnLimit } from '../config/constants'
+import { VECTOR_SEARCH_OVERFETCH_MULTIPLIER } from '../config/search'
+import { TABLES } from './tables'
+
+const MEMORY_TABLE = TABLES.MEMORY
+
+interface VectorSearchParams {
+  embedding: number[]
+  scopeId: string
+  limit: number
+  memoryType?: string
+  pointInTime?: string
+}
+
+interface HybridSearchParams extends VectorSearchParams {
+  query: string
+}
+
+interface LinearSearchParams extends HybridSearchParams {
+  weights: [number, number]
+  normalization: 'minmax' | 'zscore' | 'none'
+}
+
+class MemoryQueryBuilder {
+  private buildTypeFilter(memoryType?: string): string {
+    return memoryType ? 'AND memoryType = $memoryType' : ''
+  }
+
+  private buildTemporalPredicate(pointInTime?: string): string {
+    if (pointInTime) {
+      return 'archivedAt IS NONE AND validFrom <= $pointInTime AND IF validUntil IS NONE { true } ELSE { validUntil > $pointInTime }'
+    }
+    return 'archivedAt IS NONE AND IF validUntil IS NONE { true } ELSE { validUntil > time::now() }'
+  }
+
+  private buildTemporalFilter(pointInTime?: string): string {
+    if (pointInTime) {
+      return 'AND archivedAt IS NONE AND validFrom <= $pointInTime AND IF validUntil IS NONE { true } ELSE { validUntil > $pointInTime }'
+    }
+    return 'AND archivedAt IS NONE AND IF validUntil IS NONE { true } ELSE { validUntil > time::now() }'
+  }
+
+  /**
+   * Build vector similarity search query
+   */
+  buildVectorSearch(params: VectorSearchParams): { sql: string; bindVars: Record<string, unknown> } {
+    const typeFilter = this.buildTypeFilter(params.memoryType)
+    const temporalPredicate = this.buildTemporalPredicate(params.pointInTime)
+    const fetchLimit = validateKnnLimit(params.limit * VECTOR_SEARCH_OVERFETCH_MULTIPLIER)
+
+    const sql = `
+      LET $vectorCandidates = (
+        SELECT
+          id,
+          content,
+          metadata,
+          archivedAt,
+          validFrom,
+          validUntil,
+          vector::distance::knn() AS distance
+        FROM ${MEMORY_TABLE}
+        WHERE scopeId = $scopeId ${typeFilter}
+          AND embedding <|${fetchLimit}|> $embedding
+        ORDER BY distance ASC
+        LIMIT $fetchLimit
+      );
+
+      SELECT
+        id,
+        content,
+        metadata,
+        distance
+      FROM $vectorCandidates
+      WHERE ${temporalPredicate}
+      ORDER BY distance ASC
+      LIMIT $fetchLimit
+    `
+
+    return {
+      sql,
+      bindVars: {
+        embedding: params.embedding,
+        scopeId: params.scopeId,
+        memoryType: params.memoryType,
+        pointInTime: params.pointInTime,
+        fetchLimit,
+      },
+    }
+  }
+
+  /**
+   * Build hybrid search query using RRF (Reciprocal Rank Fusion)
+   * Combines vector similarity + full-text search
+   */
+  buildHybridSearch(params: HybridSearchParams): { sql: string; bindVars: Record<string, unknown> } {
+    const typeFilter = this.buildTypeFilter(params.memoryType)
+    const temporalFilter = this.buildTemporalFilter(params.pointInTime)
+    const fetchLimit = validateKnnLimit(params.limit * VECTOR_SEARCH_OVERFETCH_MULTIPLIER)
+
+    const sql = `
+      LET $vs = (
+        SELECT
+          id,
+          content,
+          metadata,
+          vector::distance::knn() AS distance,
+          (1 / (1 + vector::distance::knn())) AS score
+        FROM ${MEMORY_TABLE}
+        WHERE scopeId = $scopeId ${typeFilter} ${temporalFilter}
+          AND embedding <|${fetchLimit}|> $embedding
+        ORDER BY distance ASC
+        LIMIT $fetchLimit
+      );
+
+      LET $ft_raw = (
+        SELECT id, content, metadata, search::score(1) AS score
+        FROM ${MEMORY_TABLE}
+        WHERE scopeId = $scopeId ${typeFilter} ${temporalFilter}
+          AND content @1@ $query
+        ORDER BY score DESC
+        LIMIT $fetchLimit
+      );
+
+      LET $ft = IF array::len($ft_raw) > 0 { $ft_raw } ELSE { (SELECT id, content, metadata, 0 AS score FROM $vs) };
+
+      SELECT id, content, metadata, rrf_score AS rrfScore
+      FROM search::rrf([$vs, $ft], ${fetchLimit}, 60)
+      ORDER BY rrfScore DESC
+      LIMIT $fetchLimit
+    `
+
+    return {
+      sql,
+      bindVars: {
+        embedding: params.embedding,
+        query: params.query,
+        scopeId: params.scopeId,
+        memoryType: params.memoryType,
+        pointInTime: params.pointInTime,
+        fetchLimit,
+      },
+    }
+  }
+
+  /**
+   * Build linear combination search query
+   * Allows weighted combination of vector + text scores
+   */
+  buildLinearSearch(params: LinearSearchParams): { sql: string; bindVars: Record<string, unknown> } {
+    const typeFilter = this.buildTypeFilter(params.memoryType)
+    const temporalFilter = this.buildTemporalFilter(params.pointInTime)
+    const fetchLimit = validateKnnLimit(params.limit * VECTOR_SEARCH_OVERFETCH_MULTIPLIER)
+
+    const sql = `
+      LET $vs = (
+        SELECT
+          id,
+          content,
+          metadata,
+          vector::distance::knn() AS distance,
+          (1 / (1 + vector::distance::knn())) AS score
+        FROM ${MEMORY_TABLE}
+        WHERE scopeId = $scopeId ${typeFilter} ${temporalFilter}
+          AND embedding <|${fetchLimit}|> $embedding
+        ORDER BY distance ASC
+        LIMIT $fetchLimit
+      );
+
+      LET $ft_raw = (
+        SELECT id, content, metadata, search::score(1) AS score
+        FROM ${MEMORY_TABLE}
+        WHERE scopeId = $scopeId ${typeFilter} ${temporalFilter}
+          AND content @1@ $query
+        ORDER BY score DESC
+        LIMIT $fetchLimit
+      );
+
+      LET $ft = IF array::len($ft_raw) > 0 { $ft_raw } ELSE { (SELECT id, content, metadata, 0 AS score FROM $vs) };
+
+      SELECT id, content, metadata, linear_score AS linearScore
+      FROM search::linear([$vs, $ft], $weights, ${fetchLimit}, $normalization)
+      ORDER BY linearScore DESC
+      LIMIT $fetchLimit
+    `
+
+    return {
+      sql,
+      bindVars: {
+        embedding: params.embedding,
+        query: params.query,
+        scopeId: params.scopeId,
+        memoryType: params.memoryType,
+        pointInTime: params.pointInTime,
+        weights: params.weights,
+        normalization: params.normalization,
+        fetchLimit,
+      },
+    }
+  }
+}
+
+export const memoryQueryBuilder = new MemoryQueryBuilder()

package/src/db/memory-store.helpers.ts

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto'
+
+import type { BasicSearchRow, SurrealMemoryRow } from './memory-store.rows'
+import type { MemoryRecord, MemorySearchResult } from './memory-types'
+import { recordIdToString } from './record-id'
+import { TABLES } from './tables'
+
+export function isUniqueIndexConflict(error: unknown, indexName: string): boolean {
+  if (!(error instanceof Error)) return false
+  const message = error.message
+  return message.includes(indexName) && message.includes('already contains')
+}
+
+const coerceDate = (value: unknown): Date => {
+  if (value instanceof Date) return value
+  if (typeof value === 'number') {
+    const millis = value < 1_000_000_000_000 ? value * 1000 : value
+    return new Date(millis)
+  }
+  return new Date(String(value))
+}
+
+export function mapRowToMemoryRecord(row: SurrealMemoryRow): MemoryRecord {
+  return {
+    id: recordIdToString(row.id, TABLES.MEMORY),
+    content: row.content,
+    embedding: row.embedding,
+    hash: row.hash,
+    scopeId: row.scopeId,
+    memoryType: row.memoryType,
+    durability: row.durability,
+    metadata: row.metadata,
+    importance: row.importance,
+    accessCount: row.accessCount,
+    needsReview: row.needsReview,
+    lastAccessedAt: row.lastAccessedAt !== undefined ? coerceDate(row.lastAccessedAt) : undefined,
+    createdAt: coerceDate(row.createdAt),
+    updatedAt: row.updatedAt !== undefined ? coerceDate(row.updatedAt) : undefined,
+    validFrom: coerceDate(row.validFrom),
+    validUntil: row.validUntil !== undefined ? coerceDate(row.validUntil) : undefined,
+    archivedAt: row.archivedAt !== undefined ? coerceDate(row.archivedAt) : undefined,
+  }
+}
+
+function calculateAdjustedScore(options: {
+  baseScore: number
+  supportCount: number
+  contradictCount: number
+  supportMultiplier: number
+  contradictMultiplier: number
+}): number {
+  const supportBoost = options.supportCount * options.supportMultiplier
+  const contradictPenalty = options.contradictCount * options.contradictMultiplier
+  return Math.max(0, options.baseScore + supportBoost - contradictPenalty)
+}
+
+export interface RelationCounts {
+  supersedeCount: number
+  supportCount: number
+  contradictCount: number
+  contradictions: string[]
+}
+
+export function processGraphAwareRows<T extends BasicSearchRow>(
+  rows: T[],
+  relationCounts: Map<string, RelationCounts>,
+  limit: number,
+  baseScore: (row: T) => number,
+  multipliers: { support: number; contradict: number },
+  minimumScore: number,
+): MemorySearchResult[] {
+  return rows
+    .filter((row) => {
+      const id = recordIdToString(row.id, TABLES.MEMORY)
+      const counts = relationCounts.get(id)
+      return !counts || counts.supersedeCount === 0
+    })
+    .map((row) => {
+      const id = recordIdToString(row.id, TABLES.MEMORY)
+      const counts = relationCounts.get(id) ?? {
+        supportCount: 0,
+        contradictCount: 0,
+        supersedeCount: 0,
+        contradictions: [],
+      }
+      const score = calculateAdjustedScore({
+        baseScore: baseScore(row),
+        supportCount: counts.supportCount,
+        contradictCount: counts.contradictCount,
+        supportMultiplier: multipliers.support,
+        contradictMultiplier: multipliers.contradict,
+      })
+      const relationCount = counts.supportCount + counts.contradictCount + counts.supersedeCount
+      const result: MemorySearchResult = {
+        id,
+        content: row.content,
+        score,
+        metadata: {
+          ...row.metadata,
+          supportCount: counts.supportCount,
+          contradictCount: counts.contradictCount,
+          supersedeCount: counts.supersedeCount,
+          relationCount,
+        },
+      }
+      if (counts.contradictions.length > 0) {
+        result.contradictions = counts.contradictions
+      }
+      return result
+    })
+    .filter((result) => result.score >= minimumScore)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+}
+
+export function hashContent(content: string, scopeId: string, memoryType: string): string {
+  return createHash('sha256').update(`${scopeId}:${memoryType}:${content}`).digest('hex')
+}

package/src/db/memory-store.rows.ts

@@ -0,0 +1,29 @@
+import type { Durability, MemoryType } from './memory-types'
+import type { RecordIdInput } from './record-id'
+
+export interface SurrealMemoryRow {
+  id: RecordIdInput
+  content: string
+  embedding: number[]
+  hash: string
+  scopeId: string
+  memoryType: MemoryType
+  durability: Durability
+  metadata: Record<string, unknown>
+  importance: number
+  accessCount: number
+  needsReview: boolean
+  lastAccessedAt?: Date | string
+  createdAt: Date | string
+  updatedAt?: Date | string
+  validFrom: Date | string
+  validUntil?: Date | string
+  archivedAt?: Date | string
+}
+
+export interface BasicSearchRow {
+  id: RecordIdInput
+  content: string
+  metadata: Record<string, unknown>
+  createdAt?: Date | string
+}