spine-framework 0.3.145 → 0.4.0

package/.framework/functions/ai-interactions.ts

@@ -1,45 +1,54 @@
+// CIL[BEGIN stable_id="~/.framework/functions/ai-interactions.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/ai-interactions.ts"]
+// CIL[DOC-MACRO purpose="Defines the ai-interactions Netlify function handlers for AI feedback and CIL learning proposals."]
+// CIL[DOC-RESPONSIBILITY responsibility="Initialize the module, register handler exports, and provide shared imports for the AI interaction function."]
+// CIL[DOC-CONTEXT module="ai-interactions" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/funnel.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports shared middleware, database, ID resolution, admin-data helpers, audit logging, and typed signal emission." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="internal"]
 
 
 
 
 
-// CIL[BEGIN chunk_id="ai-interactions_module_header_1784019432" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for AI interaction management"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide middleware, database, type resolution, CRUD, and audit logging"]
-// CIL[DOC-CONTEXT module="ai-interactions" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imported_modules" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports required modules for AI feedback and interaction tracking" 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/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
 import { resolveTypeId } from './_shared/resolve-ids'
 import { create, update } from './admin-data'
 import { emitLog } from './_shared/audit'
-// CIL[END chunk_id="ai-interactions_module_header_1784019432"]
-// CIL[BEGIN chunk_id="ai-interactions_submitfeedback_1784019432" type="function" identity="submitFeedback" parent="none"]
-// CIL[DOC-MACRO purpose="Record customer feedback on AI messages"]
-// CIL[DOC-RESPONSIBILITY responsibility="Stamp feedback, escalate tickets, update interaction records"]
-// CIL[DOC-CONTEXT module="ai-interactions" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="feedback_confirmation" errors="message_id_required,ticket_id_required,invalid_feedback" side_effects="database_updates,ticket_escalation,audit_logging"]
-// CIL[DOC-MICRO logic_summary="Stamps feedback on message, escalates not_helpful to human, updates interaction record" 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/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, custom/apps/portal/pages/ContentPage.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."]
+import { emitSignal } from './_shared/funnel'
+// CIL[DOC-VECTOR type="context" content="purpose='Defines the ai-interactions Netlify function handlers for AI feedback and CIL learning proposals.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/ai-interactions.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/functions/ai-interactions.ts:submitFeedback:constant" type="constant" identity="submitFeedback" parent="~/.framework/functions/ai-interactions.ts"]
+// CIL[DOC-MACRO purpose="Record customer thumbs-up/thumbs-down feedback for an AI message and escalate to human if needed."]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate inputs, persist feedback on the message row, update the ticket status on thumbs-down, attach feedback to the ai_interaction record, and emit an audit log."]
+// CIL[DOC-CONTEXT module="ai-interactions" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/ai-interactions.ts"]
+// CIL[DOC-CONTRACT inputs="message_id, ticket_id, feedback, reason, msgData" outputs="{message_id, ticket_id, feedback, escalated}" errors="missing fields, invalid feedback value" side_effects="updates messages.data, items status/data, and emits an audit log"]
+// CIL[DOC-MICRO logic_summary="Validate required fields, update the message with feedback, on not_helpful assign the ticket to human (reopening resolved tickets via reopened_at/reopen_reason), on helpful resolve a pending_resolution ticket as ai_confirmed, find the linked ai_interaction and record customer_feedback, then emit a structured log." notable_decisions="thumbs are lifecycle accelerators — thumbs-up confirms a pending AI answer, thumbs-down escalates; resolved_via stamps make the outcome auditable"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// Classify why a thumbs-down happened from the message's own evidence trail.
+// Retrieval failure (no usable sources), reasoning failure (sources existed
+// but weren't cited or were ignored), or missing knowledge (nothing to
+// retrieve) each route to a different improvement path downstream.
+function diagnoseFeedback(msgData: any): string {
+  const sources = msgData?.retrieved_sources || []
+  const cited = msgData?.cited_sources || []
+  const meanSim = msgData?.mean_similarity ?? msgData?.retrieval_confidence ?? 0
+  if (!sources.length) return 'missing_knowledge'
+  if (meanSim < 0.35) return 'retrieval_miss'
+  if (!cited.length) return 'reasoning_error'
+  return 'wrong_answer'
+}
+
 export const submitFeedback = createHandler(async (ctx, body) => {
-  const { message_id, ticket_id, feedback } = body || {}
+  const { message_id, ticket_id, feedback, reason } = body || {}
   if (!message_id) throw new Error('message_id is required')
   if (!ticket_id)  throw new Error('ticket_id is required')
   if (!['helpful', 'not_helpful'].includes(feedback)) {
@@ -48,25 +57,70 @@ export const submitFeedback = createHandler(async (ctx, body) => {
 
   const { data: msg } = await adminDb
     .from('messages').select('data').eq('id', message_id).single()
+  const diagnosis = feedback === 'not_helpful' ? diagnoseFeedback(msg?.data) : null
   if (msg) {
     await adminDb
       .from('messages')
-      .update({ data: { ...(msg.data || {}), feedback } })
+      .update({ data: {
+        ...(msg.data || {}),
+        feedback,
+        ...(reason ? { feedback_reason: String(reason).slice(0, 2000) } : {}),
+        ...(diagnosis ? { feedback_diagnosis: diagnosis, needs_review: true } : {}),
+      } })
       .eq('id', message_id)
   }
 
-  if (feedback === 'not_helpful' && ticket_id) {
+  {
     const { data: ticket } = await adminDb
       .from('items').select('status, data').eq('id', ticket_id).single()
-    if (ticket && ticket.status !== 'human_assigned' && ticket.status !== 'resolved') {
-      await adminDb
-        .from('items')
-        .update({
-          status: 'human_assigned',
-          data: { ...(ticket.data || {}), aim_escalation_reason: 'thumbs_down' },
-          updated_at: new Date().toISOString(),
-        })
-        .eq('id', ticket_id)
+    if (ticket) {
+      const now = new Date().toISOString()
+      // Thumbs-down is a definitive negative signal: escalate to a human from
+      // any state, and reopen when the ticket was already resolved/closed.
+      if (feedback === 'not_helpful' && ticket.status !== 'human_assigned' && ticket.status !== 'in_progress') {
+        const wasResolved = ticket.status === 'resolved' || ticket.status === 'closed'
+        await adminDb
+          .from('items')
+          .update({
+            status: 'human_assigned',
+            data: {
+              ...(ticket.data || {}),
+              aim_escalation_reason: 'thumbs_down',
+              last_activity_at: now,
+              ...(wasResolved ? {
+                reopened_at: now,
+                reopen_reason: 'thumbs_down',
+                resolved_at: null,
+                resolved_via: null,
+                aim_resolved_by_ai: false,
+              } : {
+                pending_proposed_by: null,
+                resolve_pending_since: null,
+              }),
+            },
+            updated_at: now,
+          })
+          .eq('id', ticket_id)
+      }
+      // Thumbs-up on a pending-resolution ticket is the explicit customer
+      // confirm: close it, attributing the resolution to whoever proposed it.
+      if (feedback === 'helpful' && ticket.status === 'pending_resolution') {
+        const via = ticket.data?.pending_proposed_by === 'human' ? 'human_confirmed' : 'ai_confirmed'
+        await adminDb
+          .from('items')
+          .update({
+            status: 'resolved',
+            data: {
+              ...(ticket.data || {}),
+              resolved_at: now,
+              resolved_via: via,
+              aim_resolved_by_ai: via === 'ai_confirmed',
+              last_activity_at: now,
+            },
+            updated_at: now,
+          })
+          .eq('id', ticket_id)
+      }
     }
   }
 
@@ -79,32 +133,44 @@ export const submitFeedback = createHandler(async (ctx, body) => {
     const interaction = interactionRows[0]
     await adminDb
       .from('items')
-      .update({ data: { ...(interaction.data || {}), customer_feedback: feedback } })
+      .update({ data: {
+        ...(interaction.data || {}),
+        customer_feedback: feedback,
+        ...(reason ? { feedback_reason: String(reason).slice(0, 2000) } : {}),
+        ...(diagnosis ? { feedback_diagnosis: diagnosis, needs_review: true } : {}),
+      } })
       .eq('id', interaction.id)
   }
 
   await emitLog(ctx, 'ai_interaction.feedback_submitted',
     { type: 'message', id: message_id },
-    { after: { feedback, ticket_id, escalated: feedback === 'not_helpful' } }
+    { after: { feedback, ticket_id, escalated: feedback === 'not_helpful', diagnosis } }
   )
 
+  // Journey event: a customer submitted feedback through the calling app.
+  emitSignal(ctx, {
+    type_slug: 'funnel_signal',
+    action: 'feedback_submitted',
+    data: { ticket_id, feedback, diagnosis, source: ctx.appId ?? 'core' },
+  }).catch(() => {})
+
   return { message_id, ticket_id, feedback, escalated: feedback === 'not_helpful' }
 })
-// CIL[END chunk_id="ai-interactions_submitfeedback_1784019432"]
-// CIL[BEGIN chunk_id="ai-interactions_createinteraction_1784019432" type="function" identity="createInteraction" parent="none"]
-// CIL[DOC-MACRO purpose="Create AI interaction feedback record"]
-// CIL[DOC-RESPONSIBILITY responsibility="Create structured record of AI-human exchange"]
-// CIL[DOC-CONTEXT module="ai-interactions" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="created_record_or_skip" errors="thread_or_message_required,type_not_found" side_effects="database_record_creation,type_resolution"]
-// CIL[DOC-MICRO logic_summary="Resolves type, creates record with interaction metadata, handles missing type gracefully" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
-// 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/src/components/ui/dialog.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .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='Record customer thumbs-up/thumbs-down feedback for an AI message and escalate to human if needed.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/ai-interactions.ts:submitFeedback:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/ai-interactions.ts:createInteraction:constant" type="constant" identity="createInteraction" parent="~/.framework/functions/ai-interactions.ts"]
+// CIL[DOC-MACRO purpose="Create a new interaction-feedback item (default ai_feedback_record, overridable via type_slug) that captures per-message interaction metadata."]
+// CIL[DOC-RESPONSIBILITY responsibility="Resolve the caller-declared type_slug (default ai_feedback_record), validate required identifiers, and insert a typed record."]
+// CIL[DOC-CONTEXT module="ai-interactions" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/ai-interactions.ts"]
+// CIL[DOC-CONTRACT inputs="thread_id or ai_message_id plus optional metadata and optional type_slug" outputs="record or skipped object" errors="none thrown; returns skipped if type not found" side_effects="creates a row in items"]
+// CIL[DOC-MICRO logic_summary="Require thread_id or ai_message_id, resolve body.type_slug (default ai_feedback_record) via resolveTypeId, call create with default/null fields, and return the record." notable_decisions="type_slug lets app-specific demos record interactions under their own item type without forking this function"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const createInteraction = createHandler(async (ctx, body) => {
   const {
     thread_id, ai_message_id, retrieved_sources = [],
@@ -112,20 +178,22 @@ export const createInteraction = createHandler(async (ctx, body) => {
     ai_confidence, retrieval_confidence, kb_candidate,
     answer_quality, assistance_outcome,
     eval_case_id, cil_learning_proposal_id,
-    review_notes, reviewed_by, reviewed_at
+    review_notes, reviewed_by, reviewed_at,
+    type_slug
   } = body || {}
 
   if (!thread_id && !ai_message_id) {
     throw new Error('thread_id or ai_message_id is required')
   }
 
+  const resolvedSlug = type_slug || 'ai_feedback_record'
   let typeId: string | null = null
   try {
-    typeId = await resolveTypeId('item', 'ai_feedback_record')
+    typeId = await resolveTypeId('item', resolvedSlug)
   } catch {
-    return { skipped: true, reason: 'ai_feedback_record type not found' }
+    return { skipped: true, reason: `${resolvedSlug} type not found` }
   }
-  if (!typeId) return { skipped: true, reason: 'ai_feedback_record type not found' }
+  if (!typeId) return { skipped: true, reason: `${resolvedSlug} type not found` }
 
   const record = await create(ctx, {
     entity: 'items',
@@ -157,21 +225,21 @@ export const createInteraction = createHandler(async (ctx, body) => {
 
   return record
 })
-// CIL[END chunk_id="ai-interactions_createinteraction_1784019432"]
-// CIL[BEGIN chunk_id="ai-interactions_updateinteraction_1784019432" type="function" identity="updateInteraction" parent="none"]
-// CIL[DOC-MACRO purpose="Update AI interaction feedback record"]
-// CIL[DOC-RESPONSIBILITY responsibility="Patch allowed fields on interaction record"]
-// CIL[DOC-CONTEXT module="ai-interactions" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="updated_record" errors="id_required,no_updatable_fields,record_not_found" side_effects="database_update,data_merging"]
-// CIL[DOC-MICRO logic_summary="Filters allowed fields, merges with existing data, updates record" 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, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .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='Create a new interaction-feedback item under a caller-declared type_slug (default ai_feedback_record).'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/ai-interactions.ts:createInteraction:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/ai-interactions.ts:updateInteraction:constant" type="constant" identity="updateInteraction" parent="~/.framework/functions/ai-interactions.ts"]
+// CIL[DOC-MACRO purpose="Update an existing ai_interaction record with allowed fields."]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate id and allowed field list, merge patch into existing data, and delegate to the generic update helper."]
+// CIL[DOC-CONTEXT module="ai-interactions" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/ai-interactions.ts"]
+// CIL[DOC-CONTRACT inputs="id and one or more allowed fields" outputs="update result" errors="missing id, no updatable fields, record not found" side_effects="updates items.data"]
+// CIL[DOC-MICRO logic_summary="Validate id, build a patch from the allow-list, fetch existing record data, and call update with merged data." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const updateInteraction = createHandler(async (ctx, body) => {
   const { id, ...fields } = body || {}
   if (!id) throw new Error('id is required')
@@ -197,21 +265,21 @@ export const updateInteraction = createHandler(async (ctx, body) => {
     { data: { ...(existing.data || {}), ...patch } }
   )
 })
-// CIL[END chunk_id="ai-interactions_updateinteraction_1784019432"]
-// CIL[BEGIN chunk_id="ai-interactions_createcilproposal_1784019432" type="function" identity="createCilLearningProposal" parent="none"]
-// CIL[DOC-MACRO purpose="Queue a CIL learning proposal for developer review"]
-// CIL[DOC-RESPONSIBILITY responsibility="Create a cil_learning_proposal item from support case evidence"]
-// CIL[DOC-CONTEXT module="ai-interactions" layer="api-handler" related_files="["custom/apps/cortex/seed/types.json", ".framework/functions/admin-data.ts", ".framework/functions/_shared/schema-utils.ts", "\\\"]"]
-// CIL[DOC-CONTRACT inputs="ticket_id, thread_id, ai_message_id, proposed_summary, source_*" outputs="created_proposal" errors="missing_summary_or_ticket, type_not_found" side_effects="database_record_creation"]
-// CIL[DOC-MICRO logic_summary="Resolves cil_learning_proposal type and creates a draft proposal from support case context" notable_decisions=["Cortex may only create and update proposals; applying them is reserved for the developer workbench."]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
-// CIL[DOC-STABILITY stability="experimental"]
-// CIL[DOC-VECTOR type="context" content="Layer: api-handler. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/seed/types.json, .framework/functions/admin-data.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='Update an existing ai_interaction record with allowed fields.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/ai-interactions.ts:updateInteraction:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/ai-interactions.ts:createCilLearningProposal:constant" type="constant" identity="createCilLearningProposal" parent="~/.framework/functions/ai-interactions.ts"]
+// CIL[DOC-MACRO purpose="Create a draft CIL learning proposal from ticket context and source references."]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate ticket_id and proposed_summary, resolve the cil_learning_proposal type, and insert a draft record."]
+// CIL[DOC-CONTEXT module="ai-interactions" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/ai-interactions.ts"]
+// CIL[DOC-CONTRACT inputs="ticket_id, proposed_summary, optional thread/message/tags" outputs="record or skipped object" errors="missing ticket_id or summary; returns skipped if type not found" side_effects="creates a draft proposal row in items"]
+// CIL[DOC-MICRO logic_summary="Validate required inputs, resolve the proposal type, build data payload with source references, and create the record." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const createCilLearningProposal = createHandler(async (ctx, body) => {
   const {
     ticket_id, thread_id, ai_message_id, proposed_summary,
@@ -252,21 +320,21 @@ export const createCilLearningProposal = createHandler(async (ctx, body) => {
 
   return record
 })
-// CIL[END chunk_id="ai-interactions_createcilproposal_1784019432"]
-// CIL[BEGIN chunk_id="ai-interactions_list_1784019432" type="function" identity="list" parent="none"]
-// CIL[DOC-MACRO purpose="List AI interaction records for account"]
-// CIL[DOC-RESPONSIBILITY responsibility="Query and filter interaction records with pagination"]
-// CIL[DOC-CONTEXT module="ai-interactions" layer="api-handler" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/portal/pages/ContentPage.tsx\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="interaction_records[]" errors="database_error" side_effects="database_query,rls_filtering"]
-// CIL[DOC-MICRO logic_summary="Builds filtered query for ai_feedback_record type with pagination" 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, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, custom/apps/portal/pages/ContentPage.tsx."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Create a draft CIL learning proposal from ticket context and source references.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/ai-interactions.ts:createCilLearningProposal:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/ai-interactions.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/ai-interactions.ts"]
+// CIL[DOC-MACRO purpose="List AI interaction records filtered by feedback and kb_candidate."]
+// CIL[DOC-RESPONSIBILITY responsibility="Build a paged query scoped to the account, apply optional filters, and return matching rows."]
+// CIL[DOC-CONTEXT module="ai-interactions" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/ai-interactions.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query { feedback?, kb_candidate?, limit?, offset? }" outputs="array of records" errors="throws query error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Parse query parameters, select from items with account filter and optional data filters, then return data." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const list = createHandler(async (ctx, _body) => {
   const { feedback, kb_candidate, limit = '50', offset = '0' } = ctx.query || {}
 
@@ -288,21 +356,21 @@ export const list = createHandler(async (ctx, _body) => {
   if (error) throw error
   return data || []
 })
-// CIL[END chunk_id="ai-interactions_list_1784019432"]
-// CIL[BEGIN chunk_id="ai-interactions_handler_1784019432" type="function" identity="handler" parent="none"]
-// CIL[DOC-MACRO purpose="Route AI interaction requests"]
-// CIL[DOC-RESPONSIBILITY responsibility="Dispatch requests to appropriate interaction handlers"]
-// CIL[DOC-CONTEXT module="ai-interactions" layer="api-handler" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="handler_response" errors="invalid_action_or_method" side_effects="delegates_to_interaction_handlers"]
-// CIL[DOC-MICRO logic_summary="Routes actions to submit_feedback, create_interaction, update_interaction, list" 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 AI interaction records filtered by feedback and kb_candidate.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/ai-interactions.ts:list:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/ai-interactions.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/ai-interactions.ts"]
+// CIL[DOC-MACRO purpose="Main request router for the ai-interactions Netlify function."]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch incoming requests to the correct action handler based on action and HTTP method."]
+// CIL[DOC-CONTEXT module="ai-interactions" layer="functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/ai-interactions.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query { action, method } and body" outputs="handler result" errors="invalid action or method" side_effects="delegates to other handlers"]
+// CIL[DOC-MICRO logic_summary="Switch on action and method, call the appropriate sub-handler, and throw an error for unsupported combinations." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -327,4 +395,10 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// CIL[END chunk_id="ai-interactions_handler_1784019432"]
+// CIL[DOC-VECTOR type="context" content="purpose='Main request router for the ai-interactions Netlify function.'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.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/ai-interactions.ts:handler:constant"]