spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/functions/observability.ts

@@ -1,12 +1,27 @@
 // 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"]
+/**
+ * @module   observability
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module provides observability functions for the application, facilitating monitoring and logging of system behavior. It serves as a middleware handler that integrates with the database and user permissions to ensure that only authorized users can access certain functionalities. INVARIANT: All requests must be authenticated as system administrators to proceed with observability actions.
+ *
+ * @seeAlso middleware.ts (provides the handler for observability functions).
+ * @seeAlso db.ts (handles database interactions necessary for observability).
+ * @seeAlso principal.ts (manages user permissions and roles).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
 
 
 
@@ -19,21 +34,34 @@ import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { isSystemAdmin } from './_shared/principal'
 import { resolveTypeId } from './_shared/resolve-ids'
-// 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"]
+/**
+ * The floorBucket function normalizes a given date to the start of a specified time bucket, such as an hour or day, facilitating data aggregation based on time intervals.
+ *
+ * @inputSpec
+ *   - date: Date (required) — the date to be normalized.
+ *   - bucket: string (required) — the time bucket to normalize to, can be 'hour' or 'day'.
+ * @outputSpec  Date — the normalized date object.
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 function floorBucket(date: Date, bucket: string): Date {
   const d = new Date(date)
   d.setMilliseconds(0)
@@ -42,22 +70,33 @@ 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"]
+/**
+ * Retrieves the volume of events logged within a specified date range, grouped by time buckets. This function is essential for analyzing event frequency over time.
+ *
+ * @throws      Error — Account context required, Error — from and to dates are required.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       adminDb.from('logs'), db.from('logs'), floorBucket
+ * @cil-generated
+ */
 export const getEventVolume = createHandler(async (ctx, body) => {
   const { from, to, bucket = 'hour' } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -94,21 +133,32 @@ 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[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"]
+/**
+ * Calculates the error rate of logs within a specified date range, returning the total number of logs, the number of errors, and the error rate. This function is essential for monitoring and observability purposes.
+ *
+ * @throws      Error — Account context required, or from and to dates are required.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       adminDb.from('logs'), adminDb.select, adminDb.gte, adminDb.lte, adminDb.eq
+ * @cil-generated
+ */
 export const getErrorRate = createHandler(async (ctx, body) => {
   const { from, to } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -144,21 +194,34 @@ export const getErrorRate = createHandler(async (ctx, body) => {
     rate: total > 0 ? errors / total : 0,
   }
 })
-// 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"]
+/**
+ * Calculates the p-th percentile of a sorted array of numbers for statistical analysis and data observability. This function is essential for deriving insights from numerical datasets.
+ *
+ * @inputSpec
+ *   - sorted: number[] (required) — a sorted array of numbers to calculate the percentile from.
+ *   - p: number (required) — the desired percentile value (0-100).
+ * @outputSpec  number — the calculated percentile value.
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 function percentile(sorted: number[], p: number): number {
   if (sorted.length === 0) return 0
   const idx = (p / 100) * (sorted.length - 1)
@@ -167,22 +230,33 @@ 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"]
+/**
+ * Calculates latency percentiles for logs within a specified date range while ensuring that only authorized users can access the data. It also handles errors related to missing parameters.
+ *
+ * @throws      Error — Account context required, Error — from and to dates are required.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       adminDb.from('logs'), db.from('logs')
+ * @cil-generated
+ */
 export const getLatencyPercentiles = createHandler(async (ctx, body) => {
   const { from, to, source = 'request' } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -223,21 +297,33 @@ export const getLatencyPercentiles = createHandler(async (ctx, body) => {
     p99: percentile(values, 99),
   }
 })
-// 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"]
+/**
+ * Fetches pipeline execution statistics based on a date range and account context, aggregating success and failure counts along with average execution duration for each pipeline.
+ *
+ * @throws      Error — Account context required, or from and to dates are required, or database query error.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       adminDb.from('pipeline_executions'), adminDb.select, adminDb.gte, adminDb.lte, adminDb.eq
+ * @errorHandling none
+ * @cil-generated
+ */
 export const getPipelineStats = createHandler(async (ctx, body) => {
   const { from, to } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -286,21 +372,32 @@ 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[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"]
+/**
+ * Retrieves the top actors based on event counts within a specified date range while ensuring the user has the necessary account context and permissions. This function is essential for monitoring user activity in the system.
+ *
+ * @throws      Error — Account context required, Error — from and to dates are required
+ * @sideEffects none
+ * @stability   internal
+ * @calls       adminDb.from('logs'), adminDb.select, adminDb.gte, adminDb.lte, adminDb.eq
+ * @cil-generated
+ */
 export const getTopActors = createHandler(async (ctx, body) => {
   const { from, to, limit = 5 } = ctx.query || {}
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
@@ -338,23 +435,34 @@ export const getTopActors = createHandler(async (ctx, body) => {
     .sort((a, b) => b.event_count - a.event_count)
     .slice(0, parseInt(limit.toString()) || 5)
 })
-// 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"]
+/**
+ * Cleans up old logs from the database based on a specified retention period. It ensures that only system administrators can perform this action.
+ *
+ * @throws      Error — System admin required, Error — if database RPC fails
+ * @sideEffects Database RPC call to 'cleanup_old_logs'
+ * @stability   internal
+ * @calls       ctx.db.rpc('cleanup_old_logs')
+ * @cil-generated
+ */
 export const cleanupOldLogs = createHandler(async (ctx, body) => {
-  const { days = 90 } = ctx.query || {}
+  const { days = 30 } = ctx.query || {}
 
   if (!ctx.principal?.roles?.includes('system_admin')) {
     throw new Error('System admin required')
@@ -362,27 +470,38 @@ export const cleanupOldLogs = createHandler(async (ctx, body) => {
 
   const { data, error: err } = await ctx.db
     .rpc('cleanup_old_logs', {
-      p_retention_days: parseInt(days.toString()) || 90,
+      p_retention_days: parseInt(days.toString()) || 30,
     })
 
   if (err) throw err
   return { deleted_count: data?.[0]?.deleted_count || 0 }
 })
-// 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"]
+/**
+ * Retrieves AI support metrics for a specific account over a defined time period, aggregating feedback and resolution data to provide insights into AI performance and user satisfaction.
+ *
+ * @throws      Error — Account context required
+ * @sideEffects Database reads from 'items' table for metrics aggregation.
+ * @stability   internal
+ * @calls       adminDb.from('items'), resolveTypeId
+ * @cil-generated
+ */
 export const getAiSupportMetrics = createHandler(async (ctx, _body) => {
   if (!ctx.accountId) throw new Error('Account context required')
 
@@ -453,21 +572,32 @@ export const getAiSupportMetrics = createHandler(async (ctx, _body) => {
     knowledge_gaps:     knowledgeGaps,
   }
 })
-// 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"]
+/**
+ * The handler processes incoming requests based on the specified action in the query parameters, executing the corresponding function for each action. It provides a centralized point for handling various observability metrics and actions.
+ *
+ * @throws      Error — Unknown action: if the action is not recognized.
+ * @sideEffects none
+ * @stability   internal
+ * @calls       getEventVolume, getErrorRate, getLatencyPercentiles, getPipelineStats, getTopActors, getAiSupportMetrics, cleanupOldLogs
+ * @cil-generated
+ */
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
 
@@ -490,10 +620,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[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"]
+// CIL[END stable_id="~/.framework/functions/observability.ts:handler:constant"]
+
+
+
+
+
+

package/.framework/functions/pipeline-executions.ts

@@ -127,7 +127,7 @@ export const create = createHandler(async (ctx, body) => {
       pipeline_id,
       status: 'pending',
       trigger_data: trigger_data || {},
-      created_by: ctx.principal?.id || null,
+      created_by: ctx.principal?.type === 'human' ? ctx.principal.id : null,
       account_id: ctx.accountId,
     })
     .select('id')