spine-framework 0.3.125 → 0.3.127

package/.framework/functions/logs.ts

@@ -1,63 +1,45 @@
-/**
- * @module logs
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * Read API for the `v2.logs` table plus a write endpoint for external log
- * ingestion. The `logs` table schema uses internal column names
- * (`level`, `source`, `source_type`, `source_id`, `context`) that differ from
- * the stable frontend contract. All reads are mapped through `mapLogRow`.
- *
- * **Routed by:** `GET/POST /.netlify/functions/logs`
- *
- * **Actions:**
- * | method | ?action | handler      |
- * |--------|---------|------------------|
- * | GET    | account | listAccount  |
- * | GET    | target  | listTarget   |
- * | GET    | person  | listPerson   |
- * | GET    | stats   | getStats     |
- * | GET    | search  | search       |
- * | POST   | cleanup | cleanup      |
- * | POST   | (default)| log         |
- *
- * **Authorization:** All operations use `ctx.db` (RLS-scoped, always filtered
- * to `account_id`). No inserts are made by this module — `emitLog` from
- * `_shared/audit.ts` is the canonical write path.
- *
- * **Column mapping (DB → API):**
- * | DB column    | API field   |
- * |--------------|-------------|
- * | level        | event_type  |
- * | person_id    | actor_id    |
- * | source_type  | target_type |
- * | source_id    | target_id   |
- * | source       | action      |
- * | context      | details     |
- *
- * @seeAlso audit.ts (emitLog — canonical write path for all system events)
- * @seeAlso observability.ts (aggregated metrics over logs)
- */
 
-import { createHandler, json, error, parseBody } from './_shared/middleware'
 
-// ─── HELPERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: LOGS_MAP_ROW ──────────────────────────────────────────────
-/**
- * @chunk-id    LOGS_MAP_ROW_1_0_0
- * @version     1.0.0
- * @hash        52289a18616b71c05c908c27f2fd5d09837e7b861d30b9307bb6bdf265dd4845
- * @macro       Log Row Mapper
- * @micro       Maps raw DB log rows to stable frontend API contract
- * @inputs      row: any — Raw database log row from v2.logs table
- * @outputs     object — Mapped log row with API field names
- * @depends-on  [none]
- * @depended-by [listAccount, listTarget, listPerson, search]
- * @side-effects [none]
- * @tags        logs, mapping, helper, api-contract
- */
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="logs_moduleheader_1783968140" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import middleware dependencies for log API handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import shared handler utilities"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Imported middleware functions" errors="Import failures" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports createHandler, json, error, parseBody from shared middleware" 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: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/migrations/015_simplify_apps_table.sql, \."]
+// 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, json, error, parseBody } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+import { isSystemAdmin } from './_shared/principal'
+// CIL[END chunk_id="logs_moduleheader_1783968140"]
+// CIL[BEGIN chunk_id="logs_maplogrow_1783968140" type="function" identity="mapLogRow" parent="none"]
+// CIL[DOC-MACRO purpose="Transform raw DB log row to stable frontend API contract"]
+// CIL[DOC-RESPONSIBILITY responsibility="Map internal log fields to public API fields"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Mapped log row with API field names" errors="Invalid row structure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Maps DB columns (level, person_id, source_type, etc.) to API fields (event_type, actor_id, target_type, etc.)" 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: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/components/ui/dialog.tsx, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, \."]
+// 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"]
 function mapLogRow(row: any) {
   return {
     id: row.id,
@@ -66,75 +48,120 @@ function mapLogRow(row: any) {
     target_type: row.source_type,
     target_id: row.source_id,
     action: row.source,
+    span_name: row.span_name,
+    trace_id: row.trace_id,
+    span_id: row.span_id,
+    parent_span_id: row.parent_span_id,
+    duration_ms: row.duration_ms,
+    outcome: row.outcome,
+    event_category: row.event_category,
+    kind: row.kind,
     message: row.message,
     details: row.context,
     metadata: row.metadata,
     created_at: row.created_at,
   }
 }
-// ─── CHUNK_END: LOGS_MAP_ROW ────────────────────────────────────────────────
-
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: LOGS_LIST_ACCOUNT ──────────────────────────────────────────────
-/**
- * @chunk-id    LOGS_LIST_ACCOUNT_1_0_0
- * @version     1.0.0
- * @hash        d512e35890e479c88f4e6130567b16b1143a164705fca4e887aee643cc76a1e5
- * @macro       Account Logs List Handler
- * @micro       Lists all account log entries with filtering and mapping
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     Array of mapped log rows with API field names
- * @depends-on  [createHandler, mapLogRow]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, row mapping]
- * @tags        logs, list, account, pagination
- */
+// CIL[END chunk_id="logs_maplogrow_1783968140"]
+// CIL[BEGIN chunk_id="logs_listaccount_1783968140" type="function" identity="listAccount" parent="none"]
+// CIL[DOC-MACRO purpose="List all account log entries with filtering and pagination"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query and return paginated account logs"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of mapped log rows" errors="Account context required, DB errors" side_effects="DB read operations"]
+// CIL[DOC-MICRO logic_summary="Builds filtered query on logs table, applies date/type filters, returns mapped results" 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: .framework/src/components/ui/dialog.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/RolesPage.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"]
 export const listAccount = createHandler(async (ctx, body) => {
-  const { event_type, target_type, date_from, date_to, limit = 100, offset = 0 } = ctx.query || {}
+  const { event, event_type, target_type, source, source_id, actor_id, query: searchQuery, date_from, date_to, trace_id, limit = 100, offset = 0 } = 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')
   }
 
-  let query = ctx.db
+  if (event === 'threshold.breached') {
+    let q = db
+      .from('logs')
+      .select('id, span_name, metadata, created_at', { count: 'exact' })
+      .eq('span_name', 'threshold.breached')
+      .order('created_at', { ascending: false })
+
+    if (!isSystemAdmin(ctx.principal) && ctx.accountId) {
+      q = q.eq('account_id', ctx.accountId)
+    }
+    if (date_from) q = q.gte('created_at', date_from)
+    if (date_to) q = q.lte('created_at', date_to)
+
+    const { data, error: err, count } = await q.range(
+      parseInt(offset.toString()),
+      parseInt(offset.toString()) + parseInt(limit.toString()) - 1
+    )
+
+    if (err) throw err
+
+    const alerts = (data || []).map((row: any) => ({
+      id: row.id,
+      metric: row.metadata?.metric || row.span_name,
+      threshold_value: row.metadata?.threshold_value ?? 0,
+      actual_value: row.metadata?.actual_value ?? 0,
+      created_at: row.created_at,
+    }))
+
+    return { data: alerts, total: count || alerts.length }
+  }
+
+  let query = db
     .from('logs')
-    .select('*')
-    .eq('account_id', ctx.accountId)
+    .select('*', { count: 'exact' })
     .order('created_at', { ascending: false })
 
+  if (!isSystemAdmin(ctx.principal) && ctx.accountId) {
+    query = query.eq('account_id', ctx.accountId)
+  }
   if (event_type) query = query.eq('level', event_type)
+  if (event) query = query.eq('span_name', event)
   if (target_type) query = query.eq('source_type', target_type)
+  if (source) query = query.eq('source', source)
+  if (source_id) query = query.eq('source_id', source_id)
+  if (actor_id) query = query.eq('created_by', actor_id)
+  if (searchQuery) query = query.ilike('message', `%${searchQuery}%`)
   if (date_from) query = query.gte('created_at', date_from)
   if (date_to) query = query.lte('created_at', date_to)
+  if (trace_id) query = query.eq('trace_id', trace_id)
 
-  const { data, error: err } = await query.range(
+  const { data, error: err, count } = await query.range(
     parseInt(offset.toString()),
     parseInt(offset.toString()) + parseInt(limit.toString()) - 1
   )
 
   if (err) throw err
 
-  return (data || []).map(mapLogRow)
+  return {
+    data: (data || []).map(mapLogRow),
+    total: count || 0
+  }
 })
-// ─── CHUNK_END: LOGS_LIST_ACCOUNT ────────────────────────────────────────────────
-
-// ─── CHUNK_START: LOGS_LIST_TARGET ──────────────────────────────────────────────
-/**
- * @chunk-id    LOGS_LIST_TARGET_1_0_0
- * @version     1.0.0
- * @hash        7ea27876f183b59057284ca9007aed6e0e65050b196f00756b8ad5715073e745
- * @macro       Target Logs List Handler
- * @micro       Lists log entries for specific target entity with filtering
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     Array of mapped log rows for target entity
- * @depends-on  [createHandler, mapLogRow]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, row mapping]
- * @tags        logs, list, target, entity-specific
- */
+// CIL[END chunk_id="logs_listaccount_1783968140"]
+// CIL[BEGIN chunk_id="logs_listtarget_1783968140" type="function" identity="listTarget" parent="none"]
+// CIL[DOC-MACRO purpose="List log entries for specific target entity with filtering"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query logs by target type and ID with pagination"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of mapped log rows for target" errors="Missing target params, DB errors" side_effects="DB read operations"]
+// CIL[DOC-MICRO logic_summary="Filters logs by source_type and source_id, applies optional event_type filter" 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: .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/schema-utils.ts, \."]
+// 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 listTarget = createHandler(async (ctx, body) => {
   const { target_type, target_id, event_type, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -165,23 +192,21 @@ export const listTarget = createHandler(async (ctx, body) => {
 
   return (data || []).map(mapLogRow)
 })
-// ─── CHUNK_END: LOGS_LIST_TARGET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: LOGS_LIST_PERSON ──────────────────────────────────────────────
-/**
- * @chunk-id    LOGS_LIST_PERSON_1_0_0
- * @version     1.0.0
- * @hash        1c502ddeac8766153f1cc9ff6ffc8a7804dd83519d3c2e8b11dcf610fc6d6dfe
- * @macro       Person Activity Feed Handler
- * @micro       Returns activity feed for person with system event filtering
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     Array of mapped log rows for person activity
- * @depends-on  [createHandler, mapLogRow]
- * @depended-by [Netlify function routing]
- * @side-effects [DB queries, row mapping]
- * @tags        logs, list, person, activity-feed
- */
+// CIL[END chunk_id="logs_listtarget_1783968140"]
+// CIL[BEGIN chunk_id="logs_listperson_1783968140" type="function" identity="listPerson" parent="none"]
+// CIL[DOC-MACRO purpose="Returns activity feed for person with system event filtering"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query person's activity logs with optional system filtering"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of mapped log rows for person" errors="Person ID required, DB errors" side_effects="DB read operations"]
+// CIL[DOC-MICRO logic_summary="Filters by person_id, optionally excludes system events, returns mapped results" 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: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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"]
 export const listPerson = createHandler(async (ctx, body) => {
   const { person_id, include_system, limit = 50, offset = 0 } = ctx.query || {}
 
@@ -215,67 +240,67 @@ export const listPerson = createHandler(async (ctx, body) => {
 
   return (data || []).map(mapLogRow)
 })
-// ─── CHUNK_END: LOGS_LIST_PERSON ────────────────────────────────────────────────
-
-// ─── CHUNK_START: LOGS_GET_STATS ──────────────────────────────────────────────
-/**
- * @chunk-id    LOGS_GET_STATS_1_0_0
- * @version     1.0.0
- * @hash        a25e065d770b9658aa1a7d1db325e044febbac498c06cad735e18167442a2674
- * @macro       Logs Statistics Handler
- * @micro       Returns log counts by event type with date range filtering
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     {total: number, by_type: Record<string, number>} — Log statistics
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing]
- * @side-effects [DB count query, aggregation]
- * @tags        logs, stats, analytics, monitoring
- */
+// CIL[END chunk_id="logs_listperson_1783968140"]
+// CIL[BEGIN chunk_id="logs_getstats_1783968140" type="function" identity="getStats" parent="none"]
+// CIL[DOC-MACRO purpose="Returns log counts by event type with date range filtering"]
+// CIL[DOC-RESPONSIBILITY responsibility="Aggregate log statistics by event type"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{total: number, by_type: Record<string, number>}" errors="Account context required, DB errors" side_effects="DB read operations"]
+// CIL[DOC-MICRO logic_summary="Counts logs by level field, aggregates into by_type object" 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 getStats = createHandler(async (ctx, body) => {
-  const { date_from, date_to } = ctx.query || {}
+  const { event_type, target_type, source, source_id, actor_id, query: searchQuery, date_from, date_to } = ctx.query || {}
 
   if (!ctx.accountId) {
     throw new Error('Account context required')
   }
 
-  let query = ctx.db
-    .from('logs')
-    .select('id, level')
-    .eq('account_id', ctx.accountId)
-
-  if (date_from) query = query.gte('created_at', date_from)
-  if (date_to) query = query.lte('created_at', date_to)
-
-  const { data, error: err } = await query
+  const { data, error: err } = await ctx.db.rpc('get_log_stats', {
+    p_account_id: ctx.accountId,
+    p_level: event_type || null,
+    p_source: source || null,
+    p_source_type: target_type || null,
+    p_source_id: source_id || null,
+    p_person_id: actor_id || null,
+    p_query: searchQuery || null,
+    p_date_from: date_from || null,
+    p_date_to: date_to || null,
+  })
 
   if (err) throw err
 
-  const rows = data || []
-  const by_type: Record<string, number> = {}
-  for (const row of rows) {
-    by_type[row.level] = (by_type[row.level] || 0) + 1
+  return data?.[0] || {
+    total: 0,
+    error_count: 0,
+    user_action_count: 0,
+    event_type_count: 0,
+    levels: [],
+    sources: [],
+    source_types: []
   }
-
-  return { total: rows.length, by_type }
 })
-// ─── CHUNK_END: LOGS_GET_STATS ────────────────────────────────────────────────
-
-// ─── CHUNK_START: LOGS_SEARCH ──────────────────────────────────────────────
-/**
- * @chunk-id    LOGS_SEARCH_1_0_0
- * @version     1.0.0
- * @hash        25f4552cc8b604e280e77c9180dea6435c99f864f8d1578af44ea68793c4c67d
- * @macro       Logs Text Search Handler
- * @micro       Performs full-text search on log messages with filtering
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     Array of mapped log rows matching search query
- * @depends-on  [createHandler, mapLogRow]
- * @depended-by [Netlify function routing]
- * @side-effects [DB ILIKE search, row mapping]
- * @tags        logs, search, text-search, ilike
- */
+// CIL[END chunk_id="logs_getstats_1783968140"]
+// CIL[BEGIN chunk_id="logs_search_1783968140" type="function" identity="search" parent="none"]
+// CIL[DOC-MACRO purpose="Performs full-text search on log messages with filtering"]
+// CIL[DOC-RESPONSIBILITY responsibility="Search log messages and return filtered results"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Array of mapped log rows matching search" errors="Search query required, DB errors" side_effects="DB read operations"]
+// CIL[DOC-MICRO logic_summary="Uses ILIKE to search message field, applies event_type and target_type filters" 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 search = createHandler(async (ctx, body) => {
   const { query: searchQuery, event_type, target_type, limit = 50, offset = 0 } = ctx.query || {}
 
@@ -306,23 +331,21 @@ export const search = createHandler(async (ctx, body) => {
 
   return (data || []).map(mapLogRow)
 })
-// ─── CHUNK_END: LOGS_SEARCH ────────────────────────────────────────────────
-
-// ─── CHUNK_START: LOGS_LOG ──────────────────────────────────────────────
-/**
- * @chunk-id    LOGS_LOG_1_0_0
- * @version     1.0.0
- * @hash        521255a8c1a7e4110e2873050c8b58c8819fa6540bb039d30117946ef741633f
- * @macro       Log Entry Writer
- * @micro       Writes external log entry with field mapping and validation
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — Log data including event_type and optional fields
- * @outputs     {log_id: string} — ID of created log entry
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing]
- * @side-effects [DB insert with field mapping]
- * @tags        logs, create, external, instrumentation
- */
+// CIL[END chunk_id="logs_search_1783968140"]
+// CIL[BEGIN chunk_id="logs_log_1783968140" type="function" identity="log" parent="none"]
+// CIL[DOC-MACRO purpose="Writes external log entry with field mapping and validation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Insert new log entry into database"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{log_id: string}" errors="event_type required, DB errors" side_effects="DB insert operation"]
+// CIL[DOC-MICRO logic_summary="Maps API fields to DB columns, inserts into logs table, returns ID" 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 log = createHandler(async (ctx, body) => {
   const { event_type, target_type, target_id, action, message, details, metadata } = body
 
@@ -354,23 +377,21 @@ export const log = createHandler(async (ctx, body) => {
 
   return { log_id: data?.id }
 })
-// ─── CHUNK_END: LOGS_LOG ────────────────────────────────────────────────
-
-// ─── CHUNK_START: LOGS_CLEANUP ──────────────────────────────────────────────
-/**
- * @chunk-id    LOGS_CLEANUP_1_0_0
- * @version     1.0.0
- * @hash        3790847ac4c98e79285483511dcc23c303dc339b4988ac5715c1f165a1bb29c9
- * @macro       Logs Cleanup Handler
- * @micro       Deletes old log entries beyond retention period
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — days_to_keep (default 90)
- * @outputs     {deleted_count: number} — Number of deleted log entries
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing, system-cron.ts]
- * @side-effects [DB delete by date]
- * @tags        logs, cleanup, retention, maintenance
- */
+// CIL[END chunk_id="logs_log_1783968140"]
+// CIL[BEGIN chunk_id="logs_cleanup_1783968140" type="function" identity="cleanup" parent="none"]
+// CIL[DOC-MACRO purpose="Deletes old log entries beyond retention period"]
+// CIL[DOC-RESPONSIBILITY responsibility="Remove expired log entries from database"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="{deleted_count: number}" errors="DB errors" side_effects="DB delete operation"]
+// CIL[DOC-MICRO logic_summary="Calculates cutoff date from days_to_keep, deletes older logs" 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 cleanup = createHandler(async (ctx, body) => {
   const { days_to_keep = 90 } = body
 
@@ -387,25 +408,21 @@ export const cleanup = createHandler(async (ctx, body) => {
 
   return { deleted_count: (data || []).length }
 })
-// ─── CHUNK_END: LOGS_CLEANUP ────────────────────────────────────────────────
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: LOGS_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    LOGS_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        62e729c4e43a30a85394c5ed66a1c2a12898135b133b8b712f481670d2351b22
- * @macro       Logs Router
- * @micro       Routes HTTP methods and actions to appropriate log handlers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body for POST operations
- * @outputs     Varies — Depends on routed handler (listAccount/listTarget/listPerson/getStats/search/cleanup/log)
- * @depends-on  [createHandler, listAccount, listTarget, listPerson, getStats, search, cleanup, log]
- * @depended-by [Netlify function routing]
- * @side-effects [Delegates to appropriate handler]
- * @tags        logs, router, crud, netlify-function
- */
+// CIL[END chunk_id="logs_cleanup_1783968140"]
+// CIL[BEGIN chunk_id="logs_handler_1783968140" type="function" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Routes HTTP methods and actions to appropriate log handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch requests to correct log handler functions"]
+// CIL[DOC-CONTEXT module="logs" layer="api-handler" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Varies by handler" errors="Invalid action or method" side_effects="Delegates to handlers"]
+// CIL[DOC-MICRO logic_summary="Switch statement routes action+method combinations to appropriate 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 || {}
   const method = ctx.query?.method || 'GET'
@@ -435,4 +452,4 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// ─── CHUNK_END: LOGS_HANDLER ────────────────────────────────────────────────
+// CIL[END chunk_id="logs_handler_1783968140"]