spine-framework 0.3.145 → 0.4.0

package/.framework/functions/logs.ts

@@ -1,3 +1,12 @@
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-AUDIENCE audience="runtime,developers,operators"]
+// CIL[DOC-MACRO purpose="Module imports and shared setup for the logs Netlify function"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import dependencies and establish module context for log query and write handlers"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports createHandler, json, error, parseBody, adminDb, and isSystemAdmin for use by route handlers" notable_decisions="none"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 
 
 
@@ -7,39 +16,24 @@
 
 
 
-// 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="context" content="purpose='Module imports and shared setup for the logs Netlify function'; 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/logs.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:mapLogRow:function" type="function" identity="mapLogRow" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-MACRO purpose="Map a raw database log row into a normalized log event object"]
+// CIL[DOC-RESPONSIBILITY responsibility="Transform Supabase logs table fields into the external log event schema"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/logs.ts"]
+// CIL[DOC-CONTRACT inputs="row: any (raw log record)" outputs="normalized log event object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Rename and expose log fields such as level to event_type, source to action, and context to details" notable_decisions="none"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 function mapLogRow(row: any) {
   return {
     id: row.id,
@@ -62,21 +56,21 @@ function mapLogRow(row: any) {
     created_at: row.created_at,
   }
 }
-// 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="context" content="purpose='Map a raw database log row into a normalized log event object'; 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/logs.ts:mapLogRow:function"]
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:listAccount:constant" type="constant" identity="listAccount" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-MACRO purpose="List or filter account-wide log events and threshold breach alerts"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return paginated log rows for the current account, applying filters and a special threshold breach view"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/logs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query fields: event, event_type, target_type, source, source_id, actor_id, query, date_from, date_to, trace_id, limit, offset" outputs="{ data, total }" errors="Account context required, database query errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Build a Supabase query against logs, apply account scoping, filters, pagination, and map results through mapLogRow" notable_decisions="Uses isSystemAdmin to allow admin cross-account access and supports threshold.breached span"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const listAccount = createHandler(async (ctx, body) => {
   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
@@ -147,21 +141,21 @@ export const listAccount = createHandler(async (ctx, body) => {
     total: count || 0
   }
 })
-// 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="context" content="purpose='List or filter account-wide log events and threshold breach alerts'; 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/logs.ts:listAccount:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:listTarget:constant" type="constant" identity="listTarget" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-MACRO purpose="List log events for a specific target entity"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return paginated logs scoped to a target_type and target_id within an account"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/logs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query: target_type, target_id, event_type, limit, offset" outputs="log event array" errors="target_type and target_id required, Account context required" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Query logs filtered by account_id, source_type, source_id and optional event_type, paginate and map results" notable_decisions="Requires both target_type and target_id"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const listTarget = createHandler(async (ctx, body) => {
   const { target_type, target_id, event_type, limit = 100, offset = 0 } = ctx.query || {}
 
@@ -192,21 +186,21 @@ export const listTarget = createHandler(async (ctx, body) => {
 
   return (data || []).map(mapLogRow)
 })
-// 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="context" content="purpose='List log events for a specific target entity'; 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/logs.ts:listTarget:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:listPerson:constant" type="constant" identity="listPerson" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-MACRO purpose="List log events for a person or the current principal"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return paginated logs where actor matches a person_id, optionally including system logs"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/logs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query: person_id, include_system, limit, offset" outputs="log event array" errors="Person ID is required, Account context required" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Use ctx.principal.id as fallback, filter by account and person, optionally exclude level='system'" notable_decisions="Defaults principal to current user and hides system events unless requested"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const listPerson = createHandler(async (ctx, body) => {
   const { person_id, include_system, limit = 50, offset = 0 } = ctx.query || {}
 
@@ -240,21 +234,21 @@ export const listPerson = createHandler(async (ctx, body) => {
 
   return (data || []).map(mapLogRow)
 })
-// 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="context" content="purpose='List log events for a person or the current principal'; 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/logs.ts:listPerson:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:getStats:constant" type="constant" identity="getStats" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-MACRO purpose="Return aggregated log statistics for an account"]
+// CIL[DOC-RESPONSIBILITY responsibility="Call the get_log_stats RPC to return summary counts and breakdowns"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/logs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query: event_type, target_type, source, source_id, actor_id, query, date_from, date_to" outputs="stats object with totals and arrays" errors="Account context required, RPC errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Invoke Supabase RPC get_log_stats with account-scoped parameters and return first result or a default zeroed object" notable_decisions="Requires account context and uses ctx.db"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const getStats = createHandler(async (ctx, body) => {
   const { event_type, target_type, source, source_id, actor_id, query: searchQuery, date_from, date_to } = ctx.query || {}
 
@@ -286,21 +280,21 @@ export const getStats = createHandler(async (ctx, body) => {
     source_types: []
   }
 })
-// 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="context" content="purpose='Return aggregated log statistics for an 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/logs.ts:getStats:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:search:constant" type="constant" identity="search" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-MACRO purpose="Search log messages by text within an account"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return paginated log events matching a case-insensitive message substring"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/logs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query: query, event_type, target_type, limit, offset" outputs="log event array" errors="Search query is required, Account context required" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Filter logs by account and message ilike pattern, optionally by level and source_type, then paginate and map" notable_decisions="Performs substring match with SQL ILIKE"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const search = createHandler(async (ctx, body) => {
   const { query: searchQuery, event_type, target_type, limit = 50, offset = 0 } = ctx.query || {}
 
@@ -331,21 +325,21 @@ export const search = createHandler(async (ctx, body) => {
 
   return (data || []).map(mapLogRow)
 })
-// 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="context" content="purpose='Search log messages by text within an 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/logs.ts:search:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:log:constant" type="constant" identity="log" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-MACRO purpose="Create a new log entry from an incoming event"]
+// CIL[DOC-RESPONSIBILITY responsibility="Insert a log record into the logs table using the request body fields"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/logs.ts"]
+// CIL[DOC-CONTRACT inputs="body: event_type, target_type, target_id, action, message, details, metadata" outputs="{ log_id }" errors="event_type is required, Account context required, database insert errors" side_effects="Writes a row to the logs table"]
+// CIL[DOC-MICRO logic_summary="Build an insert from body and principal, default missing fields, and return the created id" notable_decisions="message falls back to action or event_type"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const log = createHandler(async (ctx, body) => {
   const { event_type, target_type, target_id, action, message, details, metadata } = body
 
@@ -377,21 +371,21 @@ export const log = createHandler(async (ctx, body) => {
 
   return { log_id: data?.id }
 })
-// 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="context" content="purpose='Create a new log entry from an incoming event'; 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/logs.ts:log:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:cleanup:constant" type="constant" identity="cleanup" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-MACRO purpose="Delete log records older than a retention period"]
+// CIL[DOC-RESPONSIBILITY responsibility="Remove logs created before the configured days-to-keep cutoff"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/logs.ts"]
+// CIL[DOC-CONTRACT inputs="body: days_to_keep" outputs="{ deleted_count }" errors="Database delete errors" side_effects="Deletes rows from the logs table"]
+// CIL[DOC-MICRO logic_summary="Calculate a cutoff date from days_to_keep and delete logs with created_at before it" notable_decisions="Defaults retention to 90 days"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const cleanup = createHandler(async (ctx, body) => {
   const { days_to_keep = 90 } = body
 
@@ -408,21 +402,21 @@ export const cleanup = createHandler(async (ctx, body) => {
 
   return { deleted_count: (data || []).length }
 })
-// 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="context" content="purpose='Delete log records older than a retention period'; 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/logs.ts:cleanup:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/logs.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/logs.ts"]
+// CIL[DOC-MACRO purpose="Route incoming log function requests to the correct action handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch GET/POST requests based on action query parameter to list, search, stats, cleanup or write operations"]
+// CIL[DOC-CONTEXT module="logs" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/principal.ts,.framework/functions/logs.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query: action, method" outputs="result from selected handler" errors="Invalid action or method" side_effects="Delegates to other handlers, may write or delete logs"]
+// CIL[DOC-MICRO logic_summary="Switch on action and method, calling listAccount, listTarget, listPerson, getStats, search, cleanup, or log; reject unsupported combinations" notable_decisions="Default POST falls through to the log writer; unsupported method/action throws"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -452,4 +446,10 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// CIL[END chunk_id="logs_handler_1783968140"]
+// CIL[DOC-VECTOR type="context" content="purpose='Route incoming log function requests to the correct action handler'; 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/logs.ts:handler:constant"]