spine-framework 0.3.124 → 0.3.126

package/.framework/functions/observability.ts

@@ -1,58 +1,59 @@
-/**
- * @module observability
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * Aggregated observability metrics API. All handlers delegate to Postgres
- * analytics RPCs that operate over the `v2.logs` table. Results are
- * read-only; no writes occur in this module.
- *
- * **Routed by:** `GET/POST /.netlify/functions/observability`
- *
- * **Actions (all GET unless noted):**
- * | ?action               | handler                |
- * |-----------------------|------------------------|
- * | event_volume          | getEventVolume         |
- * | error_rate            | getErrorRate           |
- * | latency_percentiles   | getLatencyPercentiles  |
- * | pipeline_stats        | getPipelineStats       |
- * | top_actors            | getTopActors           |
- * | ai_support_metrics    | getAiSupportMetrics    |
- * | cleanup               | cleanupOldLogs (POST)  |
- *
- * **Authorization:** All read endpoints require account context (RLS-scoped
- * via `ctx.db`). `cleanup` additionally requires the `system_admin` role.
- *
- * INVARIANT: Every handler requires both `from` and `to` date params
- *   (except `cleanup`). Requests without them throw immediately.
- *
- * @seeAlso logs.ts (raw log access with filter/search)
- * @seeAlso system-cron.ts (evaluateThresholds calls observability RPCs)
- * @seeAlso pipeline-executions.ts (pipeline_stats RPC aggregates these)
- */
 
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="observability_moduleheader_1783968140" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for observability metrics API"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import handler utilities and database access"]
+// CIL[DOC-CONTEXT module="observability" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules" errors="Import failures" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports createHandler, adminDb" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
+import { isSystemAdmin } from './_shared/principal'
+import { resolveTypeId } from './_shared/resolve-ids'
+// CIL[END chunk_id="observability_moduleheader_1783968140"]
+// CIL[BEGIN chunk_id="observability_geteventvolume_1783968140" type="function" identity="getEventVolume" parent="none"]
+// CIL[DOC-MACRO purpose="Get event volume metrics with time bucketing"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query aggregated event statistics"]
+// CIL[DOC-CONTEXT module="observability" layer="api-handler" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of event volume data" errors="Account context required, dates required, DB errors" side_effects="DB RPC call"]
+// CIL[DOC-MICRO logic_summary="Calls get_event_volume RPC with date range and bucket parameters" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+function floorBucket(date: Date, bucket: string): Date {
+  const d = new Date(date)
+  d.setMilliseconds(0)
+  d.setSeconds(0)
+  if (bucket === 'hour' || bucket === 'day') d.setMinutes(0)
+  if (bucket === 'day') d.setHours(0)
+  return d
+}
 
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-/**
- * Returns time-bucketed event volume counts via the `get_event_volume` RPC.
- *
- * Query params: `from` (required, ISO), `to` (required, ISO),
- * `bucket` ('minute'|'hour'|'day', default 'hour')
- *
- * @returns Array of `{ bucket_time, event_type, count }` rows
- * @throws Error('Account context required')
- * @throws Error('from and to dates are required')
- * @sideEffects DB read: get_event_volume RPC
- * @calledBy handler (?action=event_volume)
- */
 export const getEventVolume = createHandler(async (ctx, body) => {
   const { from, to, bucket = 'hour' } = ctx.query || {}
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
 
-  if (!ctx.accountId) {
+  if (!isSystemAdmin(ctx.principal) && !ctx.accountId) {
     throw new Error('Account context required')
   }
 
@@ -60,37 +61,50 @@ export const getEventVolume = createHandler(async (ctx, body) => {
     throw new Error('from and to dates are required')
   }
 
-  const { data, error: err } = await ctx.db
-    .rpc('get_event_volume', {
-      p_account_id: ctx.accountId,
-      p_event_type: null,
-      p_bucket: bucket,
-      p_from: from,
-      p_to: to,
-    })
+  let query = db
+    .from('logs')
+    .select('created_at')
+    .gte('created_at', from)
+    .lte('created_at', to)
+
+  if (!isSystemAdmin(ctx.principal) && ctx.accountId) {
+    query = query.eq('account_id', ctx.accountId)
+  }
+
+  const { data, error: err } = await query.order('created_at', { ascending: true })
 
   if (err) throw err
-  return data || []
-})
 
-// ── Error Rate ───────────────────────────────────────────
-/**
- * Returns aggregate error rate for the account time window via the
- * `get_error_rate` RPC.
- *
- * Query params: `from` (required, ISO), `to` (required, ISO)
- *
- * @returns `{ total: number, errors: number, rate: number }` (0.0–1.0)
- * @throws Error('Account context required')
- * @throws Error('from and to dates are required')
- * @sideEffects DB read: get_error_rate RPC
- * @calledBy handler (?action=error_rate)
- * @calledBy system-cron.ts evaluateThresholds (metric='error_rate')
- */
+  const counts: Record<string, number> = {}
+  for (const row of data || []) {
+    const key = floorBucket(new Date(row.created_at), bucket).toISOString()
+    counts[key] = (counts[key] || 0) + 1
+  }
+
+  return Object.entries(counts)
+    .map(([bucket, count]) => ({ bucket, count }))
+    .sort((a, b) => new Date(a.bucket).getTime() - new Date(b.bucket).getTime())
+})
+// CIL[END chunk_id="observability_geteventvolume_1783968140"]
+// CIL[BEGIN chunk_id="observability_geterrorrate_1783968140" type="function" identity="getErrorRate" parent="none"]
+// CIL[DOC-MACRO purpose="Get error rate metrics for date range"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query aggregated error statistics"]
+// CIL[DOC-CONTEXT module="observability" layer="api-handler" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Error rate data object" errors="Account context required, dates required, DB errors" side_effects="DB RPC call"]
+// CIL[DOC-MICRO logic_summary="Calls get_error_rate RPC with date range parameters" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const getErrorRate = createHandler(async (ctx, body) => {
   const { from, to } = ctx.query || {}
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
 
-  if (!ctx.accountId) {
+  if (!isSystemAdmin(ctx.principal) && !ctx.accountId) {
     throw new Error('Account context required')
   }
 
@@ -98,35 +112,58 @@ export const getErrorRate = createHandler(async (ctx, body) => {
     throw new Error('from and to dates are required')
   }
 
-  const { data, error: err } = await ctx.db
-    .rpc('get_error_rate', {
-      p_account_id: ctx.accountId,
-      p_from: from,
-      p_to: to,
-    })
+  let query = db
+    .from('logs')
+    .select('outcome, level')
+    .gte('created_at', from)
+    .lte('created_at', to)
+
+  if (!isSystemAdmin(ctx.principal) && ctx.accountId) {
+    query = query.eq('account_id', ctx.accountId)
+  }
+
+  const { data, error: err } = await query
 
   if (err) throw err
-  return data?.[0] || { total: 0, errors: 0, rate: 0 }
+
+  const rows = data || []
+  const total = rows.length
+  const errors = rows.filter((r: any) => r.outcome === 'failure' || r.level === 'error').length
+  return {
+    total,
+    errors,
+    rate: total > 0 ? errors / total : 0,
+  }
 })
+// CIL[END chunk_id="observability_geterrorrate_1783968140"]
+// CIL[BEGIN chunk_id="observability_getlatencypercentiles_1783968140" type="function" identity="getLatencyPercentiles" parent="none"]
+// CIL[DOC-MACRO purpose="Get latency percentile metrics for performance monitoring"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query aggregated latency statistics"]
+// CIL[DOC-CONTEXT module="observability" layer="api-handler" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Latency percentile data" errors="Account context required, dates required, DB errors" side_effects="DB RPC call"]
+// CIL[DOC-MICRO logic_summary="Calls get_latency_percentiles RPC with source and date range" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0
+  const idx = (p / 100) * (sorted.length - 1)
+  const lower = Math.floor(idx)
+  const upper = Math.ceil(idx)
+  const weight = idx - lower
+  return sorted[lower] * (1 - weight) + sorted[upper] * weight
+}
 
-/**
- * Returns request latency percentiles (p50/p90/p99) via the
- * `get_latency_percentiles` RPC.
- *
- * Query params: `from` (required, ISO), `to` (required, ISO),
- * `source` (log source filter, default 'request')
- *
- * @returns `{ p50: number, p90: number, p99: number }` (milliseconds)
- * @throws Error('Account context required')
- * @throws Error('from and to dates are required')
- * @sideEffects DB read: get_latency_percentiles RPC
- * @calledBy handler (?action=latency_percentiles)
- * @calledBy system-cron.ts evaluateThresholds (metric='latency_p95')
- */
 export const getLatencyPercentiles = createHandler(async (ctx, body) => {
   const { from, to, source = 'request' } = ctx.query || {}
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
 
-  if (!ctx.accountId) {
+  if (!isSystemAdmin(ctx.principal) && !ctx.accountId) {
     throw new Error('Account context required')
   }
 
@@ -134,35 +171,54 @@ export const getLatencyPercentiles = createHandler(async (ctx, body) => {
     throw new Error('from and to dates are required')
   }
 
-  const { data, error: err } = await ctx.db
-    .rpc('get_latency_percentiles', {
-      p_account_id: ctx.accountId,
-      p_source: source,
-      p_from: from,
-      p_to: to,
-    })
+  let query = db
+    .from('logs')
+    .select('duration_ms')
+    .not('duration_ms', 'is', null)
+    .gte('created_at', from)
+    .lte('created_at', to)
+
+  if (source) query = query.eq('span_name', source)
+  if (!isSystemAdmin(ctx.principal) && ctx.accountId) {
+    query = query.eq('account_id', ctx.accountId)
+  }
+
+  const { data, error: err } = await query
 
   if (err) throw err
-  return data?.[0] || { p50: 0, p90: 0, p99: 0 }
-})
 
-/**
- * Returns per-pipeline execution statistics (success/failure counts,
- * average duration) via the `get_pipeline_stats` RPC.
- *
- * Query params: `from` (required, ISO), `to` (required, ISO)
- *
- * @returns Array of `{ pipeline_id, name, success_count, failure_count, avg_duration_ms }`
- * @throws Error('Account context required')
- * @throws Error('from and to dates are required')
- * @sideEffects DB read: get_pipeline_stats RPC
- * @calledBy handler (?action=pipeline_stats)
- * @calledBy system-cron.ts evaluateThresholds (metric='pipeline_failure_rate')
- */
+  const values = (data || [])
+    .map((r: any) => Number(r.duration_ms))
+    .filter((v: number) => !isNaN(v) && v > 0)
+    .sort((a: number, b: number) => a - b)
+
+  return {
+    p50: percentile(values, 50),
+    p90: percentile(values, 90),
+    p95: percentile(values, 95),
+    p99: percentile(values, 99),
+  }
+})
+// CIL[END chunk_id="observability_getlatencypercentiles_1783968140"]
+// CIL[BEGIN chunk_id="observability_getpipelinestats_1783968140" type="function" identity="getPipelineStats" parent="none"]
+// CIL[DOC-MACRO purpose="Get pipeline execution statistics for monitoring"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query aggregated pipeline metrics"]
+// CIL[DOC-CONTEXT module="observability" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of pipeline statistics" errors="Account context required, dates required, DB errors" side_effects="DB RPC call"]
+// CIL[DOC-MICRO logic_summary="Calls get_pipeline_stats RPC with date range parameters" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const getPipelineStats = createHandler(async (ctx, body) => {
   const { from, to } = ctx.query || {}
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
 
-  if (!ctx.accountId) {
+  if (!isSystemAdmin(ctx.principal) && !ctx.accountId) {
     throw new Error('Account context required')
   }
 
@@ -170,34 +226,62 @@ export const getPipelineStats = createHandler(async (ctx, body) => {
     throw new Error('from and to dates are required')
   }
 
-  const { data, error: err } = await ctx.db
-    .rpc('get_pipeline_stats', {
-      p_account_id: ctx.accountId,
-      p_from: from,
-      p_to: to,
-    })
+  let query = db
+    .from('pipeline_executions')
+    .select('pipeline_id, status, started_at, completed_at')
+    .gte('created_at', from)
+    .lte('created_at', to)
+
+  if (!isSystemAdmin(ctx.principal) && ctx.accountId) {
+    query = query.eq('account_id', ctx.accountId)
+  }
+
+  const { data, error: err } = await query
 
   if (err) throw err
-  return data || []
-})
 
-/**
- * Returns the most active principals (persons) by event count via the
- * `get_top_actors` RPC.
- *
- * Query params: `from` (required, ISO), `to` (required, ISO),
- * `limit` (default 5)
- *
- * @returns Array of `{ person_id, full_name, event_count }` ordered by count desc
- * @throws Error('Account context required')
- * @throws Error('from and to dates are required')
- * @sideEffects DB read: get_top_actors RPC
- * @calledBy handler (?action=top_actors)
- */
+  const stats: Record<string, any> = {}
+  for (const row of data || []) {
+    const s = stats[row.pipeline_id] || { pipeline_id: row.pipeline_id, success_count: 0, failure_count: 0, total_duration_ms: 0, duration_count: 0 }
+    if (row.status === 'completed') s.success_count++
+    if (row.status === 'failed') s.failure_count++
+    if (row.started_at && row.completed_at) {
+      const duration = new Date(row.completed_at).getTime() - new Date(row.started_at).getTime()
+      if (duration > 0) {
+        s.total_duration_ms += duration
+        s.duration_count++
+      }
+    }
+    stats[row.pipeline_id] = s
+  }
+
+  return Object.values(stats).map((s: any) => ({
+    pipeline_id: s.pipeline_id,
+    success_count: s.success_count,
+    failure_count: s.failure_count,
+    avg_duration_ms: s.duration_count > 0 ? Math.round(s.total_duration_ms / s.duration_count) : 0,
+  }))
+})
+// CIL[END chunk_id="observability_getpipelinestats_1783968140"]
+// CIL[BEGIN chunk_id="observability_gettopactors_1783968140" type="function" identity="getTopActors" parent="none"]
+// CIL[DOC-MACRO purpose="Get top actors by activity volume for monitoring"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query most active users/system actors"]
+// CIL[DOC-CONTEXT module="observability" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of actor activity data" errors="Account context required, dates required, DB errors" side_effects="DB RPC call"]
+// CIL[DOC-MICRO logic_summary="Calls get_top_actors RPC with date range and limit parameters" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const getTopActors = createHandler(async (ctx, body) => {
   const { from, to, limit = 5 } = ctx.query || {}
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
 
-  if (!ctx.accountId) {
+  if (!isSystemAdmin(ctx.principal) && !ctx.accountId) {
     throw new Error('Account context required')
   }
 
@@ -205,35 +289,49 @@ export const getTopActors = createHandler(async (ctx, body) => {
     throw new Error('from and to dates are required')
   }
 
-  const { data, error: err } = await ctx.db
-    .rpc('get_top_actors', {
-      p_account_id: ctx.accountId,
-      p_from: from,
-      p_to: to,
-      p_limit: parseInt(limit.toString()) || 5,
-    })
+  let query = db
+    .from('logs')
+    .select('created_by')
+    .gte('created_at', from)
+    .lte('created_at', to)
+
+  if (!isSystemAdmin(ctx.principal) && ctx.accountId) {
+    query = query.eq('account_id', ctx.accountId)
+  }
+
+  const { data, error: err } = await query
 
   if (err) throw err
-  return data || []
-})
 
-// ── Cleanup Old Logs (manual trigger) ────────────────────
-/**
- * Manually triggers cross-account log cleanup via the `cleanup_old_logs`
- * RPC. Requires `system_admin` role — not available to regular users.
- *
- * Query params: `days` (optional, default 90)
- *
- * @returns `{ deleted_count: number }`
- * @throws Error('System admin required') if principal lacks system_admin role
- * @sideEffects DB write: cleanup_old_logs RPC (cross-account DELETE)
- * @calledBy handler (?action=cleanup)
- * @calledBy system-cron.ts cleanupOldLogs (automated daily rotation)
- */
+  const counts: Record<string, number> = {}
+  for (const row of data || []) {
+    const key = row.created_by || 'anonymous'
+    counts[key] = (counts[key] || 0) + 1
+  }
+
+  return Object.entries(counts)
+    .map(([principal_id, event_count]) => ({ principal_id, event_count }))
+    .sort((a, b) => b.event_count - a.event_count)
+    .slice(0, parseInt(limit.toString()) || 5)
+})
+// CIL[END chunk_id="observability_gettopactors_1783968140"]
+// CIL[BEGIN chunk_id="observability_cleanupoldlogs_1783968140" type="function" identity="cleanupOldLogs" parent="none"]
+// CIL[DOC-MACRO purpose="Delete old log entries for storage management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Perform log retention cleanup"]
+// CIL[DOC-CONTEXT module="observability" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{deleted_count: number}" errors="System admin required, DB errors" side_effects="DB RPC call, data deletion"]
+// CIL[DOC-MICRO logic_summary="Calls cleanup_old_logs RPC with retention days parameter" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const cleanupOldLogs = createHandler(async (ctx, body) => {
   const { days = 90 } = ctx.query || {}
 
-  // Only system admins can trigger manual cleanup
   if (!ctx.principal?.roles?.includes('system_admin')) {
     throw new Error('System admin required')
   }
@@ -246,28 +344,21 @@ export const cleanupOldLogs = createHandler(async (ctx, body) => {
   if (err) throw err
   return { deleted_count: data?.[0]?.deleted_count || 0 }
 })
-
-// ─── AI SUPPORT METRICS ──────────────────────────────────────────────────────
-
-/**
- * Returns the AI support loop health metrics.
- * All values are derived from existing tables — no new table required.
- *
- * Metrics:
- *   - ai_attempted:        AI agent messages sent
- *   - ai_resolved:         Tickets resolved without escalation
- *   - human_escalations:   Tickets assigned to humans
- *   - thumbs_down_rate:    Ratio of not_helpful / total AI messages (0–1)
- *   - medium_confidence:   AI messages with confidence 0.60–0.85
- *   - kb_articles_created: Postmortem KB articles
- *   - kb_reuse_count:      Total reuse_count across ai_feedback_record items
- *   - knowledge_gaps:      Interactions with kb_candidate=false + not_helpful feedback
- *
- * Query params: from, to (ISO dates, optional — defaults to last 30 days)
- *
- * @sideEffects DB reads: items, messages tables
- * @calledBy handler (?action=ai_support_metrics)
- */
+// CIL[END chunk_id="observability_cleanupoldlogs_1783968140"]
+// CIL[BEGIN chunk_id="observability_getaisupportmetrics_1783968140" type="function" identity="getAiSupportMetrics" parent="none"]
+// CIL[DOC-MACRO purpose="Get AI support metrics and knowledge gaps analysis"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query AI performance and coverage statistics"]
+// CIL[DOC-CONTEXT module="observability" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AI metrics object with knowledge gaps" errors="Account context required, DB errors" side_effects="DB queries"]
+// CIL[DOC-MICRO logic_summary="Queries AI metrics and knowledge gaps, returns aggregated analysis" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_dependencies"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const getAiSupportMetrics = createHandler(async (ctx, _body) => {
   if (!ctx.accountId) throw new Error('Account context required')
 
@@ -276,26 +367,22 @@ export const getAiSupportMetrics = createHandler(async (ctx, _body) => {
   const from = ctx.query?.from || thirtyDaysAgo
   const to   = ctx.query?.to   || now.toISOString()
 
-  // Run all queries in parallel for performance
+  const feedbackTypeId = await resolveTypeId('item', 'ai_feedback_record')
+
   const [
-    aiMessagesResult,
+    feedbackResult,
     resolvedResult,
     escalatedResult,
-    notHelpfulResult,
-    mediumConfResult,
-    kbCreatedResult,
-    feedbackRecordsResult,
   ] = await Promise.allSettled([
-    // AI agent messages
     adminDb
-      .from('messages')
-      .select('id, data', { count: 'exact', head: false })
+      .from('items')
+      .select('data')
       .eq('account_id', ctx.accountId)
-      .eq('data->>sender_type', 'agent')
+      .eq('type_id', feedbackTypeId)
       .gte('created_at', from)
-      .lte('created_at', to),
+      .lte('created_at', to)
+      .limit(5000),
 
-    // Tickets resolved without AI escalation
     adminDb
       .from('items')
       .select('id', { count: 'exact', head: true })
@@ -305,7 +392,6 @@ export const getAiSupportMetrics = createHandler(async (ctx, _body) => {
       .gte('created_at', from)
       .lte('created_at', to),
 
-    // Tickets escalated to humans
     adminDb
       .from('items')
       .select('id', { count: 'exact', head: true })
@@ -313,66 +399,23 @@ export const getAiSupportMetrics = createHandler(async (ctx, _body) => {
       .eq('status', 'human_assigned')
       .gte('created_at', from)
       .lte('created_at', to),
-
-    // Not-helpful AI messages
-    adminDb
-      .from('messages')
-      .select('id', { count: 'exact', head: true })
-      .eq('account_id', ctx.accountId)
-      .eq('data->>sender_type', 'agent')
-      .eq('data->>feedback', 'not_helpful')
-      .gte('created_at', from)
-      .lte('created_at', to),
-
-    // Medium-confidence AI messages
-    adminDb
-      .from('messages')
-      .select('id', { count: 'exact', head: true })
-      .eq('account_id', ctx.accountId)
-      .eq('data->>sender_type', 'agent')
-      .gte('data->>confidence', '0.60')
-      .lte('data->>confidence', '0.85')
-      .gte('created_at', from)
-      .lte('created_at', to),
-
-    // Postmortem KB articles created
-    adminDb
-      .from('items')
-      .select('id', { count: 'exact', head: true })
-      .eq('account_id', ctx.accountId)
-      .eq('data->>kb_type', 'postmortem')
-      .gte('created_at', from)
-      .lte('created_at', to),
-
-    // AI feedback records for reuse + gaps
-    adminDb
-      .from('items')
-      .select('data')
-      .eq('account_id', ctx.accountId)
-      .gte('created_at', from)
-      .lte('created_at', to)
-      .limit(500),
   ])
 
-  // Extract values safely
-  const aiMessages = aiMessagesResult.status === 'fulfilled' ? (aiMessagesResult.value.data || []) : []
-  const aiAttempted = aiMessages.length
-
-  const aiResolved   = resolvedResult.status === 'fulfilled'   ? (resolvedResult.value.count   || 0) : 0
-  const escalated    = escalatedResult.status === 'fulfilled'  ? (escalatedResult.value.count  || 0) : 0
-  const notHelpful   = notHelpfulResult.status === 'fulfilled' ? (notHelpfulResult.value.count || 0) : 0
-  const mediumConf   = mediumConfResult.status === 'fulfilled' ? (mediumConfResult.value.count || 0) : 0
-  const kbCreated    = kbCreatedResult.status === 'fulfilled'  ? (kbCreatedResult.value.count  || 0) : 0
-
-  const feedbackRows = feedbackRecordsResult.status === 'fulfilled'
-    ? (feedbackRecordsResult.value.data || [])
+  const feedbackRows = feedbackResult.status === 'fulfilled'
+    ? (feedbackResult.value.data || [])
     : []
 
+  const aiAttempted = feedbackRows.length
+  const notHelpful  = feedbackRows.filter((r: any) => r.data?.customer_feedback === 'not_helpful').length
+  const kbCreated   = feedbackRows.filter((r: any) => r.data?.kb_article_id).length
   const kbReuseCount = feedbackRows.reduce((sum: number, r: any) => sum + (Number(r.data?.reuse_count) || 0), 0)
   const knowledgeGaps = feedbackRows.filter((r: any) =>
     r.data?.kb_candidate === false && r.data?.customer_feedback === 'not_helpful'
   ).length
 
+  const aiResolved = resolvedResult.status === 'fulfilled' ? (resolvedResult.value.count || 0) : 0
+  const escalated  = escalatedResult.status === 'fulfilled' ? (escalatedResult.value.count || 0) : 0
+
   const thumbsDownRate = aiAttempted > 0 ? notHelpful / aiAttempted : 0
 
   return {
@@ -381,21 +424,26 @@ export const getAiSupportMetrics = createHandler(async (ctx, _body) => {
     ai_resolved:        aiResolved,
     human_escalations:  escalated,
     thumbs_down_rate:   Math.round(thumbsDownRate * 1000) / 1000,
-    medium_confidence:  mediumConf,
     kb_articles_created: kbCreated,
     kb_reuse_count:     kbReuseCount,
     knowledge_gaps:     knowledgeGaps,
   }
 })
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-/**
- * Netlify function entry point. Dispatches to analytics handler by ?action.
- * All valid ?action values are listed in the module dispatch table.
- * @throws Error('Unknown action: <action>. Valid actions: ...') on mismatch
- * @calledBy Netlify function routing
- */
+// CIL[END chunk_id="observability_getaisupportmetrics_1783968140"]
+// CIL[BEGIN chunk_id="observability_handler_1783968140" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Route observability actions to appropriate metric handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch monitoring requests to correct metric functions"]
+// CIL[DOC-CONTEXT module="observability" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Varies by action" errors="Unknown action" side_effects="Delegates to handlers"]
+// CIL[DOC-MICRO logic_summary="Switch statement routes action parameter to appropriate metric handler" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
 
@@ -418,3 +466,4 @@ export const handler = createHandler(async (ctx, body) => {
       throw new Error(`Unknown action: ${action}. Valid actions: event_volume, error_rate, latency_percentiles, pipeline_stats, top_actors, ai_support_metrics, cleanup`)
   }
 })
+// CIL[END chunk_id="observability_handler_1783968140"]