spine-framework 0.3.125 → 0.3.127

package/.framework/functions/_shared/kb.ts

@@ -0,0 +1,319 @@
+import { adminDb } from './db'
+import type { CoreContext } from './middleware'
+import { sanitizeRecordData } from './permissions'
+import { callOpenAIEmbeddings } from './llm'
+
+const EMBEDDING_MODEL = 'text-embedding-3-small'
+const DEFAULT_CHUNK_SIZE = 800
+const DEFAULT_CHUNK_OVERLAP = 100
+const SIMILARITY_THRESHOLD = 0.15
+const DEFAULT_MATCH_COUNT = 10
+const SECURITY_LEVELS: Record<string, string> = {
+  'kb-spine-admin': 'restricted',
+  'kb-spine-internal': 'internal',
+  'kb-spine-public': 'external',
+  'kb-account': 'external',
+}
+
+async function generateEmbedding(text: string, ctx?: CoreContext): Promise<number[]> {
+  const json = await callOpenAIEmbeddings(ctx, [text], EMBEDDING_MODEL)
+  return json.data?.[0]?.embedding || []
+}
+
+function chunkText(text: string, chunkSize: number, overlap: number): string[] {
+  if (!text) return []
+  if (text.length <= chunkSize) return [text]
+
+  const chunks: string[] = []
+  let start = 0
+  while (start < text.length) {
+    const end = Math.min(start + chunkSize, text.length)
+    const chunk = text.slice(start, end)
+    chunks.push(chunk)
+    start += chunkSize - overlap
+    if (start >= end) break
+  }
+  return chunks
+}
+
+function getFieldValue(record: any, field: string): string {
+  if (record[field] !== undefined && record[field] !== null) {
+    const value = record[field]
+    if (Array.isArray(value)) return value.join(' ')
+    return String(value)
+  }
+  const data = record.data || {}
+  if (data[field] !== undefined && data[field] !== null) {
+    const value = data[field]
+    if (Array.isArray(value)) return value.join(' ')
+    return String(value)
+  }
+  return ''
+}
+
+function getRawFieldValue(record: any, field: string): any {
+  if (record[field] !== undefined && record[field] !== null) return record[field]
+  const data = record.data || {}
+  if (data[field] !== undefined && data[field] !== null) return data[field]
+  return undefined
+}
+
+function matchesFilters(record: any, filters: Record<string, any>): boolean {
+  if (!filters || Object.keys(filters).length === 0) return true
+
+  for (const [field, expected] of Object.entries(filters)) {
+    const raw = getRawFieldValue(record, field)
+    const actual = Array.isArray(raw) ? raw : (raw !== undefined ? [raw] : [])
+    const expectedArr = Array.isArray(expected) ? expected : (expected !== undefined ? [expected] : [])
+    if (expectedArr.length === 0) continue
+
+    const hasOverlap = expectedArr.some((ev: any) => actual.includes(ev))
+    if (!hasOverlap) return false
+  }
+
+  return true
+}
+
+async function ensurePlatformAccountId(): Promise<string | null> {
+  const { data } = await adminDb
+    .from('accounts')
+    .select('id')
+    .eq('slug', 'spine-system')
+    .maybeSingle()
+  return data?.id ?? null
+}
+
+export async function kbIngest(ctx: CoreContext, body: { id: string }): Promise<{ ok: boolean; message: string; count?: number }> {
+  const { id } = body
+  if (!id) throw new Error('id is required')
+
+  const { data: record, error } = await adminDb
+    .from('items')
+    .select('*')
+    .eq('id', id)
+    .eq('account_id', ctx.accountId)
+    .maybeSingle()
+
+  if (error) throw error
+  if (!record) throw new Error('record not found')
+
+  if (record.status !== 'published') {
+    await kbRevoke(ctx, { id })
+    return { ok: true, message: 'record is not published; embeddings revoked if any' }
+  }
+
+  const designSchema = record.design_schema || {}
+  const kbConfig = designSchema.functionality?.kb || {}
+  const vectorFields = kbConfig.vector_fields || ['title', 'content']
+  const chunkField = kbConfig.chunk_field || 'content'
+  const chunkSize = kbConfig.chunk_size || DEFAULT_CHUNK_SIZE
+  const chunkOverlap = kbConfig.chunk_overlap || DEFAULT_CHUNK_OVERLAP
+
+  const { data: typeRecord, error: typeSlugError } = await adminDb
+    .from('types')
+    .select('slug, app_id')
+    .eq('id', record.type_id)
+    .single()
+  if (typeSlugError) throw typeSlugError
+
+  const typeSlug = typeRecord?.slug || ''
+  const appId = record.app_id || typeRecord?.app_id || null
+  const securityLevel = SECURITY_LEVELS[typeSlug] || 'internal'
+
+  await kbRevoke(ctx, { id })
+
+  const embeddingsToInsert: any[] = []
+  let chunkIndex = 0
+
+  for (const field of vectorFields) {
+    const raw = getFieldValue(record, field)
+    if (!raw.trim()) continue
+
+    const isChunked = field === chunkField && raw.length > chunkSize
+    const chunks = isChunked ? chunkText(raw, chunkSize, chunkOverlap) : [raw]
+
+    for (const chunk of chunks) {
+      if (!chunk.trim()) continue
+      const embedding = await generateEmbedding(chunk, ctx)
+      if (!embedding.length) continue
+
+      embeddingsToInsert.push({
+        account_id: record.account_id,
+        model_id: EMBEDDING_MODEL,
+        document_id: id,
+        chunk_index: chunkIndex++,
+        content: chunk,
+        embedding: JSON.stringify(embedding),
+        metadata: {
+          type_slug: typeSlug,
+          item_type: typeSlug,
+          app_id: appId,
+          vector_type: field,
+          security_level: securityLevel,
+          status: record.status,
+        },
+        approved_at: new Date().toISOString(),
+        revoked_at: null,
+      })
+    }
+  }
+
+  if (embeddingsToInsert.length === 0) {
+    return { ok: true, message: 'no content to embed', count: 0 }
+  }
+
+  const { error: insertError } = await adminDb.from('embeddings').insert(embeddingsToInsert)
+  if (insertError) throw insertError
+
+  return { ok: true, message: 'embeddings generated', count: embeddingsToInsert.length }
+}
+
+export async function kbRevoke(ctx: CoreContext, body: { id: string }): Promise<{ ok: boolean; message: string; count?: number }> {
+  const { id } = body
+  if (!id) throw new Error('id is required')
+
+  const { data, error } = await adminDb.rpc('revoke_embeddings_for_item', { p_item_id: id })
+  if (error) throw error
+
+  const { error: deleteError } = await adminDb
+    .from('embeddings')
+    .delete()
+    .eq('document_id', id)
+
+  if (deleteError) throw deleteError
+
+  return { ok: true, message: 'embeddings revoked', count: data || 0 }
+}
+
+export async function kbReindex(ctx: CoreContext, body: { type_slug: string; app_id?: string }): Promise<{ ok: boolean; count: number }> {
+  const { type_slug } = body
+  if (!type_slug) throw new Error('type_slug is required')
+
+  const { data: typeRecord } = await adminDb
+    .from('types')
+    .select('id')
+    .eq('slug', type_slug)
+    .maybeSingle()
+
+  if (!typeRecord) throw new Error(`type not found: ${type_slug}`)
+
+  let query = adminDb.from('items').select('id').eq('type_id', typeRecord.id).eq('status', 'published')
+  if (body.app_id) query = query.eq('app_id', body.app_id)
+
+  const { data: records, error } = await query
+  if (error) throw error
+
+  let count = 0
+  for (const record of records || []) {
+    await kbIngest(ctx, { id: record.id })
+    count++
+  }
+
+  return { ok: true, count }
+}
+
+export async function kbSearch(ctx: CoreContext, body: any): Promise<{ results: any[]; count: number }> {
+  const query = body.query
+  const typeSlugs = body.type_slugs || []
+  const sources = body.sources || ['kb']
+  const appId = body.app_id || null
+  const vectorFields = body.vector_fields || []
+  const limit = body.limit || DEFAULT_MATCH_COUNT
+  const offset = body.offset || 0
+  const filters = body.filters || {}
+  const threshold = typeof body.similarity_threshold === 'number' ? body.similarity_threshold : SIMILARITY_THRESHOLD
+
+  if (!query) throw new Error('query is required')
+
+  const accountIds = [ctx.accountId]
+  const platformAccountId = await ensurePlatformAccountId()
+  if (platformAccountId && platformAccountId !== ctx.accountId) {
+    accountIds.push(platformAccountId)
+  }
+
+  const queryEmbedding = await generateEmbedding(query, ctx)
+  if (!queryEmbedding.length) return { results: [], count: 0 }
+
+  const allowedVectorTypes = new Set(vectorFields)
+  const allowedTypeSlugs = new Set(typeSlugs)
+  const includeKb = sources.includes('kb')
+  const includeCode = sources.includes('code')
+
+  const allMatches: any[] = []
+  const vectorTypesToSearch = vectorFields.length ? vectorFields : [null]
+  const matchCount = Math.max(offset + limit, 50)
+
+  for (const vt of vectorTypesToSearch) {
+    const { data: matches, error: rpcError } = await adminDb.rpc('match_embeddings', {
+      query_embedding: queryEmbedding,
+      match_count: matchCount,
+      filter_account_ids: accountIds,
+      filter_vector_type: vt,
+      similarity_threshold: threshold,
+      filter_item_types: null,
+    })
+
+    if (rpcError) throw new Error(`rpc_${rpcError.message}`)
+    allMatches.push(...(matches || []))
+  }
+
+  const filtered = allMatches.filter((m: any) => {
+    if (m.similarity < threshold) return false
+    const meta = m.metadata || {}
+    const vectorType = meta.vector_type || ''
+    const matchAppId = meta.app_id || null
+
+    if (vectorFields.length && !allowedVectorTypes.has(vectorType)) return false
+
+    if (appId && matchAppId !== appId) return false
+
+    return true
+  })
+
+  const bestByDoc = new Map<string, any>()
+  for (const m of filtered) {
+    const existing = bestByDoc.get(m.document_id)
+    if (!existing || m.similarity > existing.similarity) bestByDoc.set(m.document_id, m)
+  }
+
+  const documentIds = Array.from(bestByDoc.keys()).slice(offset, offset + limit)
+  if (documentIds.length === 0) return { results: [], count: 0 }
+
+  const { data: records, error: recordsError } = await (ctx.db || adminDb)
+    .from('items')
+    .select('*, types!inner(slug)')
+    .in('id', documentIds)
+    .in('account_id', accountIds)
+
+  if (recordsError) throw recordsError
+
+  const results: any[] = []
+  for (const match of documentIds.map((id) => bestByDoc.get(id))) {
+    const record = (records || []).find((r: any) => r.id === match.document_id)
+    if (!record) continue
+    if (record.status !== 'published') continue
+    if (!matchesFilters(record, filters)) continue
+
+    const sanitized = await sanitizeRecordData(ctx, record, 'items')
+    if (!sanitized.data || Object.keys(sanitized.data).length === 0) continue
+    const recordTypeSlug = (record as any).types?.slug || sanitized.type_slug || record.type_slug
+    if (typeSlugs.length > 0 && !allowedTypeSlugs.has(recordTypeSlug || '')) continue
+
+    const source = match.metadata?.item_type === 'cil_chunk' ? 'code' : 'kb'
+    results.push({
+      id: record.id,
+      type_slug: recordTypeSlug,
+      title: sanitized.title || record.title,
+      snippet: match.content,
+      app_id: record.app_id || match.metadata?.app_id || null,
+      similarity: match.similarity,
+      status: record.status,
+      created_at: record.created_at,
+      source,
+      data: sanitized.data,
+    })
+  }
+
+  return { results: results.sort((a, b) => b.similarity - a.similarity), count: results.length }
+}
+

package/.framework/functions/_shared/llm.ts

@@ -0,0 +1,92 @@
+// CIL[BEGIN chunk_id="llm_module_header_1784700002" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Broker-backed LLM helpers for core functions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Route OpenAI chat and embedding calls through integration-outbound"]
+// CIL[DOC-CONTEXT module="llm" layer="infrastructure" related_files="[".framework/functions/_shared/agent-runner.ts",".framework/functions/_shared/kb.ts",".framework/functions/embeddings.ts",".framework/functions/integration-outbound.ts",".framework/migrations/051_integration_broker.sql"]"]
+// CIL[DOC-CONTRACT inputs="optional ctx, endpoint, body" outputs="parsed API response" errors="throws on missing key or HTTP failure" side_effects="Calls integration-outbound, writes webhook_deliveries"]
+// CIL[DOC-MICRO logic_summary="Provides callOpenAI, callOpenAIEmbeddings, and callOpenAIChat. Falls back to a system CoreContext when none is provided." notable_decisions="["All OpenAI calls now create an outbound delivery record for audit/retry.","A default system context lets non-handler call sites reuse the helper."]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/agent-runner.ts, .framework/functions/_shared/kb.ts, .framework/functions/embeddings.ts, .framework/functions/integration-outbound.ts, .framework/migrations/051_integration_broker.sql."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="Requires the system 'openai' integration to be seeded."]
+// CIL[DOC-VECTOR type="constraint" content="Non-200 responses throw."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="Replaces direct process.env OPENAI_API_KEY fetches in core."]
+// CIL[DOC-VECTOR type="user_journey" content="AI agents and embedding pipelines use the broker."]
+
+import { execute as executeOutbound } from '../integration-outbound'
+import { adminDb } from './db'
+import { SYSTEM_PRINCIPAL } from './principal'
+
+export interface LlmContext {
+  db?: any
+  principal?: any
+  accountId?: string | null
+  requestId?: string
+  integration?: any
+}
+
+function buildCoreContext(ctx?: LlmContext): any {
+  return ctx || {
+    db: adminDb,
+    principal: SYSTEM_PRINCIPAL,
+    accountId: null,
+    requestId: crypto.randomUUID()
+  }
+}
+
+export async function callOpenAI(ctx: LlmContext | undefined, endpoint: string, body: any): Promise<any> {
+  const coreCtx = buildCoreContext(ctx)
+  const result = await executeOutbound(coreCtx, {
+    integration_slug: 'openai',
+    action_config: { endpoint, body, credential_field: 'api_token' }
+  })
+  return result.response_body
+}
+
+export async function callOpenAIEmbeddings(
+  ctx: LlmContext | undefined,
+  inputs: string[],
+  model = 'text-embedding-3-small'
+): Promise<any> {
+  const integration = ctx?.integration
+  const resolvedModel = integration?.config?.models?.embedding || model
+  return callOpenAI(ctx, '/embeddings', {
+    model: resolvedModel,
+    input: inputs
+  })
+}
+
+export async function callOpenAIChat(
+  ctx: LlmContext | undefined,
+  messages: any[],
+  model = 'gpt-4o-mini',
+  options: { temperature?: number; max_tokens?: number; tools?: any[]; tool_choice?: any; response_format?: any } = {}
+): Promise<any> {
+  const integration = ctx?.integration
+  const resolvedModel = integration?.config?.models?.chat || model
+  const body: any = {
+    model: resolvedModel,
+    messages,
+    temperature: options.temperature ?? 0.7,
+    max_tokens: options.max_tokens ?? 4000
+  }
+  if (options.tools?.length) {
+    body.tools = options.tools
+    body.tool_choice = options.tool_choice ?? 'auto'
+  }
+  if (options.response_format) {
+    body.response_format = options.response_format
+  }
+  return callOpenAI(ctx, '/chat/completions', body)
+}
+
+export async function callEmbeddingApi(inputs: string[], model = 'text-embedding-3-small'): Promise<number[][]> {
+  if (!inputs.length) throw new Error('No inputs provided')
+  const j = await callOpenAIEmbeddings(undefined, inputs, model)
+  return (j.data || [])
+    .sort((a: any, b: any) => a.index - b.index)
+    .map((d: any) => d.embedding)
+}
+
+// CIL[END chunk_id="llm_module_header_1784700002"]

package/.framework/functions/_shared/logging.ts

@@ -0,0 +1,288 @@
+import { CoreContext } from './middleware'
+import { adminDb } from './db'
+import { formatPrincipalForAudit } from './principal'
+
+export type LogLevel = 'off' | 'timing' | 'warnings' | 'errors' | 'all'
+
+export interface LogContext extends CoreContext {
+  appId?: string | null
+  source?: string
+  logLevel?: string
+}
+
+export interface AdminDataLogPayload {
+  entity: string
+  action: string
+  method?: string
+  durationMs?: number
+  recordId?: string
+  rowCount?: number
+  filters?: Record<string, any>
+  typeSlug?: string
+  error?: any
+  warning?: string
+}
+
+const VALID_LEVELS: LogLevel[] = ['off', 'timing', 'warnings', 'errors', 'all']
+
+function parseLogLevelHeader(value: string | undefined): LogLevel[] {
+  if (!value) return []
+  const parts = value.split(/[,|]/).map(p => p.trim()).filter(Boolean)
+  if (parts.length === 0) {
+    const single = value.trim() as LogLevel
+    return VALID_LEVELS.includes(single) ? [single] : []
+  }
+  const levels = parts.filter(p => VALID_LEVELS.includes(p as LogLevel)) as LogLevel[]
+  return levels
+}
+
+function getCache(ctx: LogContext): Map<string, any> | undefined {
+  return (ctx as any).__loggingCache
+}
+
+function getOrCreateCache(ctx: LogContext): Map<string, any> {
+  if (!(ctx as any).__loggingCache) {
+    ;(ctx as any).__loggingCache = new Map()
+  }
+  return (ctx as any).__loggingCache
+}
+
+function findSetting(
+  rows: any[],
+  scope: string,
+  scopeId?: string | null
+): LogLevel[] | undefined {
+  const row = rows.find(
+    (r) => r.scope === scope && (scopeId === undefined ? r.scope_id == null : r.scope_id === scopeId)
+  )
+  return row?.value?.levels as LogLevel[] | undefined
+}
+
+export async function resolveLogLevels(
+  ctx: LogContext,
+  options?: { entity?: string; action?: string }
+): Promise<LogLevel[]> {
+  const cache = getOrCreateCache(ctx)
+  const cacheKey = `levels:${options?.entity || ''}:${options?.action || ''}`
+  if (cache.has(cacheKey)) {
+    return cache.get(cacheKey)
+  }
+
+  const defaultLevels: LogLevel[] = ['timing', 'errors']
+
+  const { data: rows, error } = await adminDb
+    .from('system_settings')
+    .select('scope, scope_id, value')
+    .eq('key', 'logging')
+
+  if (error || !rows || rows.length === 0) {
+    cache.set(cacheKey, defaultLevels)
+    return defaultLevels
+  }
+
+  const headerLevels = parseLogLevelHeader(ctx.logLevel)
+  if (headerLevels.length > 0) {
+    cache.set(cacheKey, headerLevels)
+    return headerLevels
+  }
+
+  let levels: LogLevel[] = findSetting(rows, 'global') || defaultLevels
+
+  function apply(scope: string, scopeId?: string | null) {
+    const found = findSetting(rows, scope, scopeId)
+    if (found && found.length > 0) {
+      levels = found
+    }
+  }
+
+  const source = ctx.source || ctx.principal?.provenance?.sourceType
+  if (source) apply('source', source)
+
+  if (ctx.principal?.id) apply('principal', ctx.principal.id)
+
+  if (ctx.accountId) apply('account', ctx.accountId)
+
+  if (ctx.appId) apply('app', ctx.appId)
+
+  if (options?.entity && options?.action) {
+    apply('tool', `${options.entity}:${options.action}`)
+  }
+
+  if (options?.entity) {
+    apply('tool', options.entity)
+  }
+
+  cache.set(cacheKey, levels)
+  return levels
+}
+
+function buildMessage(payload: AdminDataLogPayload): string {
+  const { entity, action, method, durationMs, recordId, error, warning } = payload
+  let msg = `admin-data ${action} ${entity}`
+  if (method) msg += ` (${method})`
+  if (recordId) msg += ` id:${recordId}`
+  if (durationMs !== undefined) msg += ` in ${durationMs}ms`
+  if (warning) msg += ` warning: ${warning}`
+  if (error) msg += ` failed: ${error.message || String(error)}`
+  return msg
+}
+
+function buildContext(payload: AdminDataLogPayload): Record<string, any> {
+  const ctx: Record<string, any> = {}
+  if (payload.durationMs !== undefined) ctx.duration_ms = payload.durationMs
+  if (payload.method) ctx.method = payload.method
+  if (payload.rowCount !== undefined) ctx.row_count = payload.rowCount
+  if (payload.filters && Object.keys(payload.filters).length > 0) ctx.filters = payload.filters
+  if (payload.typeSlug) ctx.type_slug = payload.typeSlug
+  if (payload.warning) ctx.warning = payload.warning
+  if (payload.error) ctx.error_message = payload.error.message || String(payload.error)
+  return ctx
+}
+
+function traceLogFields(ctx: LogContext): Record<string, any> {
+  const trace = ctx.trace
+  if (!trace) return {}
+  return {
+    trace_id: trace.traceId,
+    span_id: trace.spanId,
+    parent_span_id: trace.parentSpanId,
+    trace_flags: trace.traceFlags,
+    tracestate: trace.traceState,
+    sampled: trace.sampled
+  }
+}
+
+function buildMetadata(
+  ctx: LogContext,
+  payload: AdminDataLogPayload
+): Record<string, any> {
+  const meta: Record<string, any> = {
+    request_id: ctx.requestId,
+    source: ctx.source || ctx.principal?.provenance?.sourceType,
+    entity: payload.entity,
+    action: payload.action,
+    principal: ctx.principal ? formatPrincipalForAudit(ctx.principal) : null,
+    ...traceLogFields(ctx)
+  }
+  if (payload.recordId) meta.record_id = payload.recordId
+  if (payload.error && payload.error.stack) {
+    meta.error_stack = String(payload.error.stack).split('\n').slice(0, 5).join('\n')
+  }
+  return meta
+}
+
+function extractLogResult(result: any): { recordId?: string; rowCount?: number } {
+  if (!result || typeof result !== 'object') return {}
+
+  if (Array.isArray(result)) {
+    return { rowCount: result.length }
+  }
+
+  if (typeof result.id === 'string') {
+    return { recordId: result.id }
+  }
+
+  if (result.data && Array.isArray(result.data)) {
+    const out: any = { rowCount: result.data.length }
+    if (result.data.length === 1 && result.data[0]?.id) {
+      out.recordId = result.data[0].id
+    }
+    return out
+  }
+
+  if (result.data && typeof result.data === 'object' && typeof result.data.id === 'string') {
+    return { recordId: result.data.id }
+  }
+
+  if (typeof result.count === 'number') {
+    return { rowCount: result.count }
+  }
+
+  return {}
+}
+
+export async function logAdminDataOperation(
+  ctx: LogContext,
+  payload: AdminDataLogPayload
+): Promise<void> {
+  try {
+    if (payload.entity === 'logs' || payload.entity === 'observability') {
+      return
+    }
+
+    const levels = await resolveLogLevels(ctx, payload)
+
+    if (levels.includes('off') || levels.length === 0) {
+      return
+    }
+
+    const isAll = levels.includes('all')
+    const isError = !!payload.error
+    const isWarning = !!payload.warning
+
+    if (isError && !isAll && !levels.includes('errors')) return
+    if (isWarning && !isAll && !levels.includes('warnings')) return
+    if (!isError && !isWarning && !isAll && !levels.includes('timing')) return
+
+    let level: 'info' | 'warn' | 'error' = 'info'
+    if (isError) level = 'error'
+    else if (isWarning) level = 'warn'
+
+    const logRow = {
+      level,
+      source: 'admin-data',
+      source_type: payload.entity,
+      source_id: payload.recordId || null,
+      person_id: ctx.principal?.id || null,
+      created_by: ctx.principal?.id || null,
+      app_id: ctx.appId || null,
+      account_id: ctx.accountId || null,
+      span_name: `admin-data.${payload.action}`,
+      kind: 'event',
+      started_at: new Date().toISOString(),
+      duration_ms: payload.durationMs || null,
+      ...traceLogFields(ctx),
+      message: buildMessage(payload),
+      context: buildContext(payload),
+      metadata: buildMetadata(ctx, payload),
+      created_at: new Date().toISOString()
+    }
+
+    const logDb = ctx.db || adminDb
+    await logDb.from('logs').insert(logRow)
+  } catch (err) {
+    console.error('Failed to write admin-data log:', err)
+  }
+}
+
+export async function withAdminLogging<T>(
+  ctx: LogContext,
+  params: Omit<AdminDataLogPayload, 'durationMs' | 'error' | 'recordId' | 'rowCount'>,
+  operation: () => Promise<T>
+): Promise<T> {
+  const start = Date.now()
+  let result: T
+  let error: any
+  let recordId: string | undefined
+  let rowCount: number | undefined
+
+  try {
+    result = await operation()
+    const extracted = extractLogResult(result)
+    recordId = extracted.recordId
+    rowCount = extracted.rowCount
+    return result
+  } catch (err) {
+    error = err
+    throw err
+  } finally {
+    const durationMs = Date.now() - start
+    logAdminDataOperation(ctx, {
+      ...params,
+      durationMs,
+      error,
+      recordId,
+      rowCount
+    }).catch(console.error)
+  }
+}