spine-framework 0.3.144 → 0.4.0

package/.framework/functions/observability.ts

@@ -1,3 +1,12 @@
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Observability and analytics function entry point"]
+// CIL[DOC-RESPONSIBILITY responsibility="Exports handler-driven analytics endpoints for event volume, error rate, latency, pipeline stats, top actors, AI support metrics, and log cleanup"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports shared middleware, database, auth, and id resolution utilities" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="internal"]
 
 
 
@@ -6,40 +15,25 @@
 
 
 
-// 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="context" content="purpose='Observability and analytics function entry point'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:floorBucket:function" type="function" identity="floorBucket" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Bucket a date to a chosen granularity"]
+// CIL[DOC-RESPONSIBILITY responsibility="Normalize a Date to the start of the requested hour or day bucket"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="date: Date, bucket: string" outputs="Date" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Zeroes seconds and milliseconds; zeroes minutes for hour/day and hours for day" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function floorBucket(date: Date, bucket: string): Date {
   const d = new Date(date)
   d.setMilliseconds(0)
@@ -48,7 +42,22 @@ function floorBucket(date: Date, bucket: string): Date {
   if (bucket === 'day') d.setHours(0)
   return d
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Bucket a date to a chosen granularity'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:floorBucket:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:getEventVolume:constant" type="constant" identity="getEventVolume" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Return event counts grouped by time bucket"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query logs for a date range and aggregate counts by ISO bucket"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.from, ctx.query.to, ctx.query.bucket" outputs="array of { bucket, count }" errors="Account context required; from/to required; database error" side_effects="reads logs table"]
+// CIL[DOC-MICRO logic_summary="Selects adminDb or ctx.db based on role; filters by account_id; groups with floorBucket; sorts ascending" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getEventVolume = createHandler(async (ctx, body) => {
   const { from, to, bucket = 'hour' } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -85,21 +94,21 @@ export const getEventVolume = createHandler(async (ctx, body) => {
     .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="context" content="purpose='Return event counts grouped by time bucket'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:getEventVolume:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:getErrorRate:constant" type="constant" identity="getErrorRate" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Compute error rate over a date range"]
+// CIL[DOC-RESPONSIBILITY responsibility="Count total log rows and failures to derive an error rate"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.from, ctx.query.to" outputs="{ total, errors, rate }" errors="Account context required; from/to required; database error" side_effects="reads logs table"]
+// CIL[DOC-MICRO logic_summary="Queries logs for outcome/level; counts rows where outcome is failure or level is error" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getErrorRate = createHandler(async (ctx, body) => {
   const { from, to } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -135,21 +144,21 @@ export const getErrorRate = createHandler(async (ctx, body) => {
     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="context" content="purpose='Compute error rate over a date range'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:getErrorRate:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:percentile:function" type="function" identity="percentile" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Compute a percentile of a sorted numeric array"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return weighted percentile value using linear interpolation"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="sorted: number[], p: number" outputs="number" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Calculates index from p and length-1; blends lower and upper sorted values" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function percentile(sorted: number[], p: number): number {
   if (sorted.length === 0) return 0
   const idx = (p / 100) * (sorted.length - 1)
@@ -158,7 +167,22 @@ function percentile(sorted: number[], p: number): number {
   const weight = idx - lower
   return sorted[lower] * (1 - weight) + sorted[upper] * weight
 }
-
+// CIL[DOC-VECTOR type="context" content="purpose='Compute a percentile of a sorted numeric array'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:percentile:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:getLatencyPercentiles:constant" type="constant" identity="getLatencyPercentiles" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Return duration latency percentiles"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query positive non-null duration_ms values and compute p50/p90/p95/p99"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.from, ctx.query.to, ctx.query.source" outputs="{ p50, p90, p95, p99 }" errors="Account context required; from/to required; database error" side_effects="reads logs table"]
+// CIL[DOC-MICRO logic_summary="Filters by span_name when source provided; converts and filters duration values; sorts and delegates to percentile" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getLatencyPercentiles = createHandler(async (ctx, body) => {
   const { from, to, source = 'request' } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -199,21 +223,21 @@ export const getLatencyPercentiles = createHandler(async (ctx, body) => {
     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="context" content="purpose='Return duration latency percentiles'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:getLatencyPercentiles:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:getPipelineStats:constant" type="constant" identity="getPipelineStats" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Aggregate pipeline execution statistics"]
+// CIL[DOC-RESPONSIBILITY responsibility="Group pipeline_executions by pipeline_id and count successes/failures/durations"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.from, ctx.query.to" outputs="array of { pipeline_id, success_count, failure_count, avg_duration_ms }" errors="Account context required; from/to required; database error" side_effects="reads pipeline_executions table"]
+// CIL[DOC-MICRO logic_summary="Iterates rows to update per-pipeline counters and compute average duration where both timestamps exist" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getPipelineStats = createHandler(async (ctx, body) => {
   const { from, to } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -262,21 +286,21 @@ export const getPipelineStats = createHandler(async (ctx, body) => {
     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="context" content="purpose='Aggregate pipeline execution statistics'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:getPipelineStats:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:getTopActors:constant" type="constant" identity="getTopActors" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Rank principals by event volume"]
+// CIL[DOC-RESPONSIBILITY responsibility="Count log rows per created_by and return the top N"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.from, ctx.query.to, ctx.query.limit" outputs="array of { principal_id, event_count }" errors="Account context required; from/to required; database error" side_effects="reads logs table"]
+// CIL[DOC-MICRO logic_summary="Tallies created_by occurrences; sorts descending and limits to parsed limit defaulting to 5" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getTopActors = createHandler(async (ctx, body) => {
   const { from, to, limit = 5 } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -314,21 +338,21 @@ export const getTopActors = createHandler(async (ctx, body) => {
     .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="context" content="purpose='Rank principals by event volume'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:getTopActors:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:cleanupOldLogs:constant" type="constant" identity="cleanupOldLogs" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Delete old logs via retention policy"]
+// CIL[DOC-RESPONSIBILITY responsibility="Invoke a stored function to purge logs older than the requested retention"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.days" outputs="{ deleted_count }" errors="System admin required; database error" side_effects="calls cleanup_old_logs RPC; deletes records"]
+// CIL[DOC-MICRO logic_summary="Restricts to system_admin; parses days defaulting to 90; runs cleanup_old_logs RPC" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const cleanupOldLogs = createHandler(async (ctx, body) => {
   const { days = 90 } = ctx.query || {}
 
@@ -344,21 +368,21 @@ export const cleanupOldLogs = createHandler(async (ctx, body) => {
   if (err) throw err
   return { deleted_count: data?.[0]?.deleted_count || 0 }
 })
-// 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="context" content="purpose='Delete old logs via retention policy'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:cleanupOldLogs:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:getAiSupportMetrics:constant" type="constant" identity="getAiSupportMetrics" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Compute AI support KPIs for the account"]
+// CIL[DOC-RESPONSIBILITY responsibility="Aggregate AI feedback, resolved items, and escalated items over a period"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.from, ctx.query.to" outputs="{ period, ai_attempted, ai_resolved, human_escalations, thumbs_down_rate, kb_articles_created, kb_reuse_count, knowledge_gaps }" errors="Account context required; database error" side_effects="reads items table via adminDb"]
+// CIL[DOC-MICRO logic_summary="Resolves ai_feedback_record type id; runs three parallel queries; computes rates and counts from feedback data" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getAiSupportMetrics = createHandler(async (ctx, _body) => {
   if (!ctx.accountId) throw new Error('Account context required')
 
@@ -429,21 +453,21 @@ export const getAiSupportMetrics = createHandler(async (ctx, _body) => {
     knowledge_gaps:     knowledgeGaps,
   }
 })
-// 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="context" content="purpose='Compute AI support KPIs for the account'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:getAiSupportMetrics:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/observability.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/observability.ts"]
+// CIL[DOC-MACRO purpose="Route observability action requests"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch the requested analytics action to the appropriate function"]
+// CIL[DOC-CONTEXT module="observability" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/observability.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.action" outputs="action-specific result" errors="Unknown action" side_effects="delegates to analytics functions"]
+// CIL[DOC-MICRO logic_summary="Switch on action and awaits the matching handler; returns default error for unknown actions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
 
@@ -466,4 +490,10 @@ 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"]
+// CIL[DOC-VECTOR type="context" content="purpose='Route observability action requests'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:handler:constant"]