@lota-sdk/core 0.1.15 → 0.1.16

package/src/db/memory.ts

@@ -12,7 +12,7 @@ import { getFactRetrievalMessages } from '../runtime/memory-prompts-fact'
 import { parseMessages } from '../runtime/memory-prompts-parse'
 import { getClassifyMemoryDeltaPrompt } from '../runtime/memory-prompts-update'
 import { getRuntimeConfig } from '../runtime/runtime-config'
-import { compactWhitespace } from '../utils/string'
+import { compactWhitespace, truncateText } from '../utils/string'
 import type { SurrealMemoryStore } from './memory-store'
 import { getDefaultMemoryStore } from './memory-store'
 import { hashContent, isUniqueIndexConflict } from './memory-store.helpers'
@@ -82,7 +82,7 @@ export class Memory {
       durability?: Durability
     },
   ): Promise<string> {
-    return await this.store.insert(
+    return this.store.insert(
       content,
       options.scopeId,
       options.memoryType,
@@ -137,7 +137,7 @@ export class Memory {
       return results
     }
 
-    return await this.store.enrichWithNeighbors(results)
+    return this.store.enrichWithNeighbors(results)
   }
 
   async listTopMemories(options: {
@@ -147,11 +147,11 @@ export class Memory {
     durability?: Durability
     minImportance?: number
   }): Promise<MemoryRecord[]> {
-    return await this.store.listTopMemories(options)
+    return this.store.listTopMemories(options)
   }
 
   async list(options: MemoryListOptions): Promise<MemoryRecord[]> {
-    return await this.store.list(options)
+    return this.store.list(options)
   }
 
   async updateMemory(id: string, newContent: string): Promise<void> {
@@ -163,7 +163,7 @@ export class Memory {
   }
 
   async getStaleMemories(scopeId: string, limit?: number): Promise<MemorySearchResult[]> {
-    return await this.store.getStaleMemories(scopeId, limit)
+    return this.store.getStaleMemories(scopeId, limit)
   }
 
   async add(
@@ -244,12 +244,12 @@ export class Memory {
     const factMaps = buildMemoryFactMaps(facts)
 
     const existingMemories = await this.store.list({ scopeId: options.scopeId, memoryType: options.memoryType })
-    const oldMemoryFormat = existingMemories.map((m) => ({ id: m.id, text: m.content }))
+    const memoryDeltaInput = existingMemories.map((m) => ({ id: m.id, text: m.content }))
 
     const factContents = facts.map((f) => f.content)
-    const updates = await this.determineUpdates(oldMemoryFormat, factContents)
+    const updates = await this.determineUpdates(memoryDeltaInput, factContents)
 
-    return { options, updates, factMaps, existingMemories: oldMemoryFormat }
+    return { options, updates, factMaps, existingMemories: memoryDeltaInput }
   }
 
   private async extractFacts(
@@ -317,8 +317,8 @@ export class Memory {
   private normalizeMemoryDeltaText(value: string, maxChars?: number): string {
     const normalized = compactWhitespace(value)
     if (!normalized) return ''
-    if (typeof maxChars !== 'number' || normalized.length <= maxChars) return normalized
-    return `${normalized.slice(0, maxChars - 3)}...`
+    if (typeof maxChars !== 'number') return normalized
+    return truncateText(normalized, maxChars)
   }
 
   private tokenizeMemoryDeltaText(value: string): string[] {
@@ -442,7 +442,7 @@ export class Memory {
     for (const action of plan.actions) {
       switch (action.type) {
         case 'add': {
-          const truncatedContent = action.text.length > 50 ? `${action.text.slice(0, 50)}...` : action.text
+          const truncatedContent = truncateText(action.text, 50)
           const metadata = { ...options.metadata, memoryCategory: action.category }
           const hash = hashContent(action.text, options.scopeId, options.memoryType)
           let newId: string
@@ -483,7 +483,7 @@ export class Memory {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
           })
           idMap.set(action.refId, action.refId)
-          aiLogger.debug`Updated memory ${action.refId}: ${action.text.slice(0, 50)}...`
+          aiLogger.debug`Updated memory ${action.refId}: ${truncateText(action.text, 50)}`
           break
         }
 

package/src/db/service.ts

@@ -12,6 +12,7 @@ import {
 import type { ExprLike, Mutation, SurrealTransaction, Values } from 'surrealdb'
 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'
@@ -185,7 +186,8 @@ export class SurrealDBService {
 
     try {
       await this.client.close()
-    } catch {
+    } catch (error) {
+      serverLogger.warn`Failed to close database client: ${error}`
     } finally {
       this.client = null
     }
@@ -327,14 +329,39 @@ export class SurrealDBService {
     }
   }
 
-  private normalizeQueryRows<T>(statement: unknown, schema?: z.ZodType<T>): T[] {
+  private normalizeQueryRows(statement: unknown, schema?: z.ZodTypeAny): unknown[] {
     if (Array.isArray(statement)) {
-      return schema ? statement.map((row) => schema.parse(row)) : (statement as T[])
+      return schema ? statement.map((row) => this.parseSchema(schema, row)) : (statement as unknown[])
     }
     if (statement === null || statement === undefined) {
       return []
     }
-    return schema ? [schema.parse(statement)] : [statement as T]
+    return schema ? [this.parseSchema(schema, statement)] : [statement]
+  }
+
+  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 (!isRecord(value)) {
+      return value
+    }
+
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, this.normalizeParseValue(entry)]))
+  }
+
+  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 {
@@ -351,6 +378,33 @@ export class SurrealDBService {
     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 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')
+    }
+
+    const bindings: Record<string, unknown> = {}
+    const clauses = entries.map(([field, value], index) => {
+      this.assertValidIdentifier(field, 'filter field')
+
+      const bindingKey = `filter_${index}`
+      bindings[bindingKey] = this.normalizeRuntimeValue(value)
+      return `${field} = $${bindingKey}`
+    })
+
+    return { clause: clauses.join(' AND '), bindings }
+  }
+
   private normalizeBoundQuery(query: BoundQuery | BoundQueryLike): BoundQuery {
     if (!(query instanceof BoundQuery) && !isBoundQueryLike(query)) {
       throw new SurrealDBError('Invalid query object: expected a BoundQuery-like value')
@@ -385,7 +439,7 @@ export class SurrealDBService {
       return value
     }
 
-    if ('tb' in value && 'id' in value) {
+    if ('tb' in value && 'id' in value && Object.keys(value).length === 2) {
       return ensureRecordId(value as RecordIdInput)
     }
 
@@ -412,25 +466,19 @@ export class SurrealDBService {
     return this.normalizeRuntimeValue(bindings) as Record<string, unknown>
   }
 
+  private normalizeMutationFieldValue(value: unknown): unknown {
+    if (value === null || value === undefined) {
+      return undefined
+    }
+
+    return this.normalizeRuntimeValue(value)
+  }
+
   // Cast is safe: normalizeRuntimeValue preserves Record shape when input is a Record
   private normalizeMutationData(data: Record<string, unknown>): Record<string, unknown> {
-    const normalized = this.normalizeRuntimeValue(data) as Record<string, unknown>
-    return this.stripNullValues(normalized)
-  }
-
-  /**
-   * SurrealDB v3 `option<T>` fields expect `NONE` (key omitted), not `null`.
-   * Strip top-level `null` values so they are omitted from the serialized payload,
-   * which the driver interprets as NONE.
-   */
-  private stripNullValues(data: Record<string, unknown>): Record<string, unknown> {
-    const result: Record<string, unknown> = {}
-    for (const [key, value] of Object.entries(data)) {
-      if (value !== null) {
-        result[key] = value
-      }
-    }
-    return result
+    return Object.fromEntries(
+      Object.entries(data).map(([key, value]) => [key, this.normalizeMutationFieldValue(value)]),
+    ) as Record<string, unknown>
   }
 
   private normalizeTableValue(value: unknown): Table {
@@ -461,7 +509,7 @@ export class SurrealDBService {
 
     if (value && typeof value === 'object') {
       const record = value as { tb?: unknown; id?: unknown }
-      if (typeof record.tb === 'string' && record.id !== undefined) {
+      if (typeof record.tb === 'string' && record.id !== undefined && Object.keys(value).length === 2) {
         return true
       }
 
@@ -487,20 +535,38 @@ export class SurrealDBService {
       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: (mode) => builder.output(mode),
+      output: async (mode) => this.normalizeParseValue(await builder.output(mode)),
     }
   }
 
   private wrapCreateBuilder(builder: CreateMutationBuilder): CreateMutationBuilder {
     return {
       content: (data) => this.wrapCreateBuilder(builder.content(this.normalizeMutationData(data))),
-      output: (mode) => builder.output(mode),
+      output: async (mode) => this.normalizeParseValue(await builder.output(mode)),
     }
   }
 
   private wrapTransaction(tx: SurrealTransaction): DatabaseTransaction {
     return {
-      query: (query: unknown) => tx.query(this.normalizeBoundQuery(query as BoundQuery | BoundQueryLike)),
+      query: async (query: unknown) => {
+        const boundQuery = this.normalizeBoundQuery(query as BoundQuery | BoundQueryLike)
+        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)
@@ -510,15 +576,18 @@ export class SurrealDBService {
       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: (target: unknown) => tx.delete(ensureRecordId(target as RecordIdInput)),
-      relate: (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) =>
-        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,
+      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,
+          ),
         ),
       commit: () => tx.commit(),
       cancel: () => tx.cancel(),
@@ -534,7 +603,7 @@ export class SurrealDBService {
     return statements.at(0) ?? []
   }
 
-  async queryAll<T>(query: BoundQuery | BoundQueryLike, schema?: z.ZodType<T>): Promise<T[][]> {
+  async queryAll<T>(query: BoundQuery | BoundQueryLike, schema?: z.ZodTypeAny): Promise<T[][]> {
     const client = await this.ensureConnected()
     const boundQuery = this.normalizeBoundQuery(query)
     const queryText = this.resolveQueryText(boundQuery)
@@ -547,22 +616,22 @@ export class SurrealDBService {
           const failure = response.error
           throw new SurrealDBError(`Statement ${index + 1}: ${failure.message}`, queryText, { cause: failure })
         }
-        return this.normalizeQueryRows<T>(response.result, schema)
+        return this.normalizeQueryRows(response.result, schema) as T[]
       })
     } catch (error) {
       return this.toSurrealError(error, queryText)
     }
   }
 
-  async queryOne<T extends z.ZodType>(query: BoundQuery | BoundQueryLike, schema: T): Promise<z.infer<T> | null> {
+  async queryOne<T extends z.ZodTypeAny>(query: BoundQuery | BoundQueryLike, schema: T): Promise<z.infer<T> | null> {
     const results = await this.query<unknown>(query)
     const first = results.at(0)
-    return first ? schema.parse(first) : null
+    return first ? this.parseSchema(schema, first) : null
   }
 
-  async queryMany<T extends z.ZodType>(query: BoundQuery | BoundQueryLike, schema: T): Promise<z.infer<T>[]> {
+  async queryMany<T extends z.ZodTypeAny>(query: BoundQuery | BoundQueryLike, schema: T): Promise<z.infer<T>[]> {
     const results = await this.query<unknown>(query)
-    return results.map((row) => schema.parse(row))
+    return results.map((row) => this.parseSchema(schema, row))
   }
 
   private async runSqlFile(file: Bun.BunFile): Promise<void> {
@@ -574,13 +643,13 @@ export class SurrealDBService {
     await this.queryAll<unknown>(new BoundQuery(sql))
   }
 
-  async applySchemaAndMigrations(schemaFiles: readonly Bun.BunFile[]): Promise<void> {
+  async applySchema(schemaFiles: readonly Bun.BunFile[]): Promise<void> {
     for (const schemaFile of schemaFiles) {
       await this.runSqlFile(schemaFile)
     }
   }
 
-  async findOne<T extends z.ZodType>(
+  async findOne<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     filter: Record<string, unknown>,
     schema: T,
@@ -596,13 +665,13 @@ export class SurrealDBService {
 
       const rows = await query.limit(1)
       const first = rows.at(0)
-      return first ? schema.parse(first) : null
+      return first ? this.parseSchema(schema, first) : null
     } catch (error) {
       return this.toSurrealError(error, `SELECT * FROM ${table} LIMIT 1`)
     }
   }
 
-  async findMany<T extends z.ZodType>(
+  async findMany<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     filter: Record<string, unknown>,
     schema: T,
@@ -614,8 +683,15 @@ export class SurrealDBService {
     const selection = this.buildFilterExpression(filter)
     const orderBy = options?.orderBy
 
-    if (options && orderBy) {
-      const { orderDir = 'ASC', limit, offset } = options
+    if (orderBy !== undefined) {
+      this.assertValidIdentifier(orderBy, 'orderBy field')
+      this.assertValidIdentifier(table, 'table name')
+      for (const key of filterKeys) {
+        this.assertValidIdentifier(key, 'filter field')
+      }
+      const orderDir = options?.orderDir ?? '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) {
@@ -632,7 +708,7 @@ export class SurrealDBService {
         vars.offsetParam = offset
       }
       const rows = await this.query<unknown>(new BoundQuery(sql, vars))
-      return rows.map((row) => schema.parse(row))
+      return rows.map((row) => this.parseSchema(schema, row))
     }
 
     try {
@@ -648,13 +724,13 @@ export class SurrealDBService {
       }
 
       const rows = await query
-      return rows.map((row) => schema.parse(row))
+      return rows.map((row) => this.parseSchema(schema, row))
     } catch (error) {
       return this.toSurrealError(error, `SELECT * FROM ${table}`)
     }
   }
 
-  async create<T extends z.ZodType>(
+  async create<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     data: Record<string, unknown>,
     schema: T,
@@ -677,13 +753,13 @@ export class SurrealDBService {
         throw new SurrealDBError(`Failed to create record in ${table}`)
       }
 
-      return schema.parse(first)
+      return this.parseSchema(schema, first)
     } catch (error) {
       return this.toSurrealError(error, `CREATE ${table}`)
     }
   }
 
-  async createWithId<T extends z.ZodType>(
+  async createWithId<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     id: unknown,
     data: Record<string, unknown>,
@@ -699,13 +775,13 @@ export class SurrealDBService {
 
     try {
       const created = await client.create<unknown>(recordId).content(this.normalizeMutationData(data)).output('after')
-      return schema.parse(created)
+      return this.parseSchema(schema, created)
     } catch (error) {
       return this.toSurrealError(error, `CREATE ${recordId.toString()}`)
     }
   }
 
-  async update<T extends z.ZodType>(
+  async update<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     id: unknown,
     data: Record<string, unknown>,
@@ -726,13 +802,13 @@ export class SurrealDBService {
       const builder = client.update<unknown>(recordId)
       const configured = configureMutation(builder, mutation, this.normalizeMutationData(data))
       const updated = await configured.output('after')
-      return updated ? schema.parse(updated) : null
+      return updated ? this.parseSchema(schema, updated) : null
     } catch (error) {
       return this.toSurrealError(error, `UPDATE ${recordId.toString()}`)
     }
   }
 
-  async upsert<T extends z.ZodType>(
+  async upsert<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     id: unknown,
     data: Record<string, unknown>,
@@ -755,7 +831,7 @@ export class SurrealDBService {
       if (!upserted) {
         throw new SurrealDBError(`Failed to upsert record in ${table}`)
       }
-      return schema.parse(upserted)
+      return this.parseSchema(schema, upserted)
     } catch (error) {
       return this.toSurrealError(error, `UPSERT ${recordId.toString()}`)
     }
@@ -763,45 +839,42 @@ export class SurrealDBService {
 
   async deleteById(table: DatabaseTable, id: unknown): Promise<boolean> {
     const recordId = this.normalizeRecordId(id, table)
-    const client = await this.ensureConnected()
 
     try {
-      const matched = await client.select<{ id: unknown }>(new Table(table)).where(eq('id', recordId)).limit(1)
-      if (matched.length === 0) {
+      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
       }
-      await client.delete<unknown>(recordId).output('before')
-      return true
-    } catch (error) {
       return this.toSurrealError(error, `DELETE ${recordId.toString()}`)
     }
   }
 
   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 selection = this.buildFilterExpression(filter)
-    if (!selection) {
-      throw new SurrealDBError(`Invalid delete filter for table ${table}`)
-    }
-
-    const client = await this.ensureConnected()
+    const { clause, bindings } = this.buildBoundFilterClauses(filter)
 
     try {
-      const matched = await client.select<{ id: unknown }>(new Table(table)).where(selection)
-      if (matched.length === 0) {
-        return 0
-      }
+      return await this.withTransaction(async (tx) => {
+        const matched = (await tx.query(new BoundQuery(`SELECT id FROM ${table} WHERE ${clause}`, bindings))) as Array<{
+          id: unknown
+        }>
 
-      for (const row of matched) {
-        const id = this.normalizeRecordId(row.id, table)
-        await client.delete(id)
-      }
+        if (matched.length === 0) {
+          return 0
+        }
+
+        for (const row of matched) {
+          await tx.delete(this.normalizeRecordId(row.id, table))
+        }
 
-      return matched.length
+        return matched.length
+      })
     } catch (error) {
       return this.toSurrealError(error, `DELETE ${table} WHERE ...`)
     }
@@ -939,6 +1012,7 @@ export const databaseService = new Proxy({} as SurrealDBService, {
     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,

package/src/db/startup.ts

@@ -1,3 +1,4 @@
+import { recordIdSchema } from '@lota-sdk/shared'
 import { BoundQuery, RecordId } from 'surrealdb'
 import { z } from 'zod'
 
@@ -11,11 +12,11 @@ const DEFAULT_MAX_WAIT_MS = 3 * 60 * 1_000
 const RETRY_LOG_INTERVAL = 5
 
 const RuntimeBootstrapRecordSchema = z.object({
-  id: z.unknown(),
+  id: recordIdSchema,
   key: z.string(),
   schemaFingerprint: z.string(),
-  readyAt: z.union([z.date(), z.string(), z.number()]),
-  updatedAt: z.union([z.date(), z.string(), z.number()]),
+  readyAt: z.coerce.date(),
+  updatedAt: z.coerce.date().optional().nullable(),
 })
 
 type StartupLogger = Pick<SurrealDatabaseLogger, 'info' | 'warn' | 'error'>
@@ -62,7 +63,7 @@ export async function connectWithStartupRetry(params: {
 async function readDatabaseBootstrapRecord(
   databaseService: SurrealDBService,
 ): Promise<z.infer<typeof RuntimeBootstrapRecordSchema> | null> {
-  return await databaseService.queryOne(
+  return databaseService.queryOne(
     new BoundQuery(
       `SELECT *
        FROM ${TABLES.RUNTIME_BOOTSTRAP}
@@ -141,12 +142,7 @@ export async function publishDatabaseBootstrap(params: {
   await params.databaseService.upsert(
     TABLES.RUNTIME_BOOTSTRAP,
     new RecordId(TABLES.RUNTIME_BOOTSTRAP, DATABASE_BOOTSTRAP_KEY),
-    {
-      key: DATABASE_BOOTSTRAP_KEY,
-      schemaFingerprint: params.schemaFingerprint,
-      readyAt: new Date(),
-      updatedAt: new Date(),
-    },
+    { key: DATABASE_BOOTSTRAP_KEY, schemaFingerprint: params.schemaFingerprint, readyAt: new Date() },
     RuntimeBootstrapRecordSchema,
   )
 }

package/src/db/surreal-mutation.ts

@@ -0,0 +1,43 @@
+export type SurrealSetClause = { bindingEntries: Record<string, unknown>; statement: string }
+
+export function buildRequiredSurrealSetClause(field: string, bindingName: string, value: unknown): SurrealSetClause {
+  return { statement: `${field} = $${bindingName}`, bindingEntries: { [bindingName]: value } }
+}
+
+export function buildOptionalSurrealSetClause(field: string, value: unknown): SurrealSetClause
+export function buildOptionalSurrealSetClause(field: string, bindingName: string, value: unknown): SurrealSetClause
+export function buildOptionalSurrealSetClause(
+  field: string,
+  bindingNameOrValue: unknown,
+  value?: unknown,
+): SurrealSetClause {
+  const hasExplicitBinding = arguments.length === 3
+  const resolvedValue = hasExplicitBinding ? value : bindingNameOrValue
+  const resolvedBindingName = hasExplicitBinding
+    ? (bindingNameOrValue as string)
+    : `resource_${field.replace(/[^a-zA-Z0-9]+/g, '_')}`
+
+  if (resolvedValue === null || resolvedValue === undefined) {
+    return { statement: `${field} = NONE`, bindingEntries: {} }
+  }
+
+  return buildRequiredSurrealSetClause(field, resolvedBindingName, resolvedValue)
+}
+
+export function combineSurrealSetClauses(...clauses: SurrealSetClause[]): {
+  bindings: Record<string, unknown>
+  statement: string
+} {
+  const bindings: Record<string, unknown> = {}
+  for (const clause of clauses) {
+    for (const [key, value] of Object.entries(clause.bindingEntries)) {
+      bindings[key] = value
+    }
+  }
+
+  return { bindings, statement: clauses.map((clause) => clause.statement).join(', ') }
+}
+
+export function compactDefinedRecord<T extends Record<string, unknown>>(value: T): Partial<T> {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as Partial<T>
+}

package/src/db/tables.ts

@@ -17,11 +17,18 @@ export const TABLES = {
   PLAN_CHECKPOINT: 'planCheckpoint',
   PLAN_VALIDATION_ISSUE: 'planValidationIssue',
   PLAN_EVENT: 'planEvent',
+  PLAN_SCHEDULE: 'planSchedule',
+  PLAN_TEMPLATE: 'planTemplate',
+  PLAN_CYCLE: 'planCycle',
   ORGANIZATION: 'organization',
   ORGANIZATION_MEMBER: 'organizationMember',
   USER: 'user',
   RECENT_ACTIVITY_EVENT: 'recentActivityEvent',
   RECENT_ACTIVITY: 'recentActivity',
+  PLAYBOOK: 'playbook',
+  PLAYBOOK_VERSION: 'playbookVersion',
+  INSTITUTIONAL_MEMORY: 'institutionalMemory',
+  QUALITY_METRIC: 'qualityMetric',
 } as const
 
 export type DatabaseTable = (typeof TABLES)[keyof typeof TABLES] | (string & {})

package/src/db/workstream-message-row.ts

@@ -0,0 +1,15 @@
+import { recordIdSchema } from '@lota-sdk/shared'
+import { z } from 'zod'
+
+export const WorkstreamMessageRowSchema = z.object({
+  id: recordIdSchema,
+  workstreamId: recordIdSchema,
+  messageId: z.string(),
+  role: z.enum(['system', 'user', 'assistant']),
+  parts: z.array(z.record(z.string(), z.unknown())).optional(),
+  metadata: z.record(z.string(), z.unknown()).nullish(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date().optional(),
+})
+
+export type WorkstreamMessageRow = z.infer<typeof WorkstreamMessageRowSchema>