spine-framework 0.3.124 → 0.3.126

package/.framework/functions/_shared/webhook-registration.ts

@@ -1,80 +1,68 @@
-/**
- * @module webhook-registration
- * @audience custom-developer
- * @layer shared-util
- * @stability stable
- *
- * Helper utilities for custom webhook handlers to self-register.
- * Use this in your custom Netlify functions to register as webhook handlers.
- *
- * **Usage in a custom function:**
- * ```ts
- * import { createHandler } from '../_shared/middleware'
- * import { registerWebhookHandler } from '../_shared/webhook-registration'
- * import { adminDb } from '../_shared/db'
- *
- * export const handler = createHandler(async (event, ctx) => {
- *   // Your webhook logic here
- * })
- *
- * // Self-register on first load (idempotent)
- * registerWebhookHandler({
- *   name: 'my-custom-handler',
- *   functionName: 'custom_my-webhook',
- *   description: 'Handles my custom integration events',
- *   events: ['user.created', 'item.updated'],
- *   db: adminDb
- * }).catch(console.error)
- * ```
- *
- * @seeAlso webhook-registry.ts (core lookup service)
- * @seeAlso 014_webhook_registry.sql (database table)
- */
 
-import { adminDb } from './db'
 
+
+
+// CIL[BEGIN chunk_id="webhookregistration_imports_1784020784" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import database dependency for webhook registration"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import adminDb for database operations"]
+// CIL[DOC-CONTEXT module="webhook-registration" layer="shared" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="adminDb" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import database connection for webhook handler management" 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: shared. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+import { adminDb } from './db'
+// CIL[END chunk_id="webhookregistration_imports_1784020784"]
+// CIL[BEGIN chunk_id="webhookregistration_interface_1784020784" type="interface" identity="WebhookHandlerRegistration" parent="none"]
+// CIL[DOC-MACRO purpose="Define webhook handler registration interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide structure for webhook handler configuration"]
+// CIL[DOC-CONTEXT module="webhook-registration" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="WebhookHandlerRegistration interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with handler metadata, events, and optional database" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/cortex/functions/custom_cil-embeddings.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 interface WebhookHandlerRegistration {
-  /** Unique handler identifier (e.g., 'cortex-handler') */
   name: string
-  
-  /** Netlify function name (e.g., 'custom_cortex-handler') */
   functionName: string
-  
-  /** Human-readable description */
   description?: string
-  
-  /** Events this handler subscribes to */
   events?: string[]
-  
-  /** Account ID (null for system handlers) */
+  appId?: string | null
   accountId?: string | null
-  
-  /** Database client (defaults to adminDb) */
+  isSystem?: boolean
   db?: typeof adminDb
 }
-
-/**
- * Registers a webhook handler in the database registry.
- * Idempotent - safe to call multiple times.
- *
- * @param config - Handler registration configuration
- * @returns Promise that resolves when registration completes
- *
- * @example
- * ```ts
- * await registerWebhookHandler({
- *   name: 'slack-webhook',
- *   functionName: 'custom_slack-integration',
- *   description: 'Posts notifications to Slack',
- *   events: ['item.created', 'item.updated']
- * })
- * ```
- */
+// CIL[END chunk_id="webhookregistration_interface_1784020784"]
+// CIL[BEGIN chunk_id="webhookregistration_registerwebhookhandler_1784020784" type="function" identity="registerWebhookHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Register webhook handler in database"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create or update webhook handler record"]
+// CIL[DOC-CONTEXT module="webhook-registration" layer="shared" related_files="[\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="database errors" side_effects="database update"]
+// CIL[DOC-MICRO logic_summary="Upserts handler record with metadata and activation status" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/cortex/functions/custom_cil-embeddings.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 async function registerWebhookHandler(
   config: WebhookHandlerRegistration
 ): Promise<void> {
   const db = config.db || adminDb
-  
+
   try {
     const { error } = await db
       .from('webhook_handlers')
@@ -83,12 +71,15 @@ export async function registerWebhookHandler(
         function_name: config.functionName,
         description: config.description || `${config.name} webhook handler`,
         events: config.events || [],
+        app_id: config.appId || null,
         account_id: config.accountId || null,
+        is_system: config.isSystem || false,
         is_active: true,
         is_deleted: false,
-        updated_at: new Date().toISOString()
+        updated_at: new Date().toISOString(),
+        created_at: new Date().toISOString()
       }, {
-        onConflict: 'name'
+        onConflict: 'app_id,account_id,name'
       })
 
     if (error) {
@@ -102,19 +93,29 @@ export async function registerWebhookHandler(
     throw err
   }
 }
-
-/**
- * Deregisters a webhook handler (soft delete).
- *
- * @param name - Handler identifier to deregister
- * @param db - Optional database client
- */
+// CIL[END chunk_id="webhookregistration_registerwebhookhandler_1784020784"]
+// CIL[BEGIN chunk_id="webhookregistration_deregisterwebhookhandler_1784020784" type="function" identity="deregisterWebhookHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Deregister webhook handler from database"]
+// CIL[DOC-RESPONSIBILITY responsibility="Soft delete webhook handler record"]
+// CIL[DOC-CONTEXT module="webhook-registration" layer="shared" related_files="[\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="database errors" side_effects="database update"]
+// CIL[DOC-MICRO logic_summary="Updates handler to inactive and deleted status" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: \."]
+// 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 async function deregisterWebhookHandler(
   name: string,
+  appId: string | null = null,
+  accountId: string | null = null,
   db: typeof adminDb = adminDb
 ): Promise<void> {
   try {
-    const { error } = await db
+    let query = db
       .from('webhook_handlers')
       .update({
         is_active: false,
@@ -123,6 +124,11 @@ export async function deregisterWebhookHandler(
       })
       .eq('name', name)
 
+    if (appId !== undefined) query = query.eq('app_id', appId)
+    if (accountId !== undefined) query = query.eq('account_id', accountId)
+
+    const { error } = await query
+
     if (error) {
       console.error(`[webhook-registration] Failed to deregister ${name}:`, error)
       throw error
@@ -134,14 +140,21 @@ export async function deregisterWebhookHandler(
     throw err
   }
 }
-
-/**
- * Checks if a handler is registered.
- *
- * @param name - Handler identifier to check
- * @param db - Optional database client
- * @returns True if handler exists and is active
- */
+// CIL[END chunk_id="webhookregistration_deregisterwebhookhandler_1784020784"]
+// CIL[BEGIN chunk_id="webhookregistration_ishandlerregistered_1784020784" type="function" identity="isHandlerRegistered" parent="none"]
+// CIL[DOC-MACRO purpose="Check if webhook handler is registered and active"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify handler registration status"]
+// CIL[DOC-CONTEXT module="webhook-registration" layer="shared" related_files="[\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="database errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Queries webhook_handlers table for active, non-deleted 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: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/migrations/015_simplify_apps_table.sql, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.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 async function isHandlerRegistered(
   name: string,
   db: typeof adminDb = adminDb
@@ -166,3 +179,4 @@ export async function isHandlerRegistered(
     return false
   }
 }
+// CIL[END chunk_id="webhookregistration_ishandlerregistered_1784020784"]

package/.framework/functions/_shared/webhook-registry.ts

@@ -1,85 +1,129 @@
-/**
- * @module webhook-registry
- * @audience core-contributor
- * @layer shared-service
- * @stability stable
- *
- * Dynamic webhook handler registry for runtime handler resolution.
- * Replaces static imports with database-driven handler lookups.
- *
- * **Pattern:**
- * 1. Custom handlers self-register via `integrations` table or `webhook_handlers` table
- * 2. Core looks up handler by name at runtime
- * 3. Dynamic import loads the handler function
- *
- * **Benefits:**
- * - Core has zero hardcoded dependencies on custom handlers
- * - Handlers can be added/removed without core code changes
- * - Multi-tenancy: different tenants can have different handlers
- *
- * @seeAlso integration-routes.ts (uses this registry)
- * @seeAlso custom_webhook-handlers.ts (legacy static registry - being phased out)
- */
 
+
+
+
+
+// CIL[BEGIN chunk_id="webhookregistry_imports_1784020784" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import database dependency and initialize handler cache"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import adminDb and create handler caching system"]
+// CIL[DOC-CONTEXT module="webhook-registry" layer="shared" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="adminDb, handlerCache" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import database and initialize Map for handler metadata caching" 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: shared. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.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 { adminDb } from './db'
 
-// In-memory cache for handler metadata (not the handlers themselves)
-const handlerCache = new Map<string, { functionName: string; loaded: boolean }>()
-
-/**
- * Looks up a webhook handler in the database registry.
- * Returns the function name to dynamically import.
- *
- * @param handlerName - The handler identifier (e.g., "cortex-handler")
- * @returns Handler metadata or null if not found
- */
-export async function lookupHandler(handlerName: string): Promise<{ functionName: string } | null> {
-  // Check cache first
-  const cached = handlerCache.get(handlerName)
+interface HandlerCacheEntry {
+  functionName: string
+  loaded: boolean
+}
+
+const handlerCache = new Map<string, HandlerCacheEntry>()
+// CIL[END chunk_id="webhookregistry_imports_1784020784"]
+// CIL[BEGIN chunk_id="webhookregistry_lookuphandler_1784020784" type="function" identity="lookupHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Lookup webhook handler metadata with caching"]
+// CIL[DOC-RESPONSIBILITY responsibility="Find handler function name in database with cache optimization"]
+// CIL[DOC-CONTEXT module="webhook-registry" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="function name or null" errors="database errors" side_effects="cache update"]
+// CIL[DOC-MICRO logic_summary="Checks cache first, queries webhook_handlers table, caches result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.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 async function lookupHandler(
+  handlerName: string,
+  appId?: string | null,
+  accountId?: string | null
+): Promise<{ functionName: string } | null> {
+  const cacheKey = `${appId || 'null'}:${accountId || 'null'}:${handlerName}`
+  const cached = handlerCache.get(cacheKey)
   if (cached) {
     return { functionName: cached.functionName }
   }
 
-  // Query database for handler registration
-  const { data, error } = await adminDb
+  let query = adminDb
     .from('webhook_handlers')
-    .select('name, function_name, is_active')
+    .select('name, function_name, is_active, is_deleted')
     .eq('name', handlerName)
     .eq('is_active', true)
-    .single()
+    .eq('is_deleted', false)
+
+  if (appId !== undefined) {
+    query = query.eq('app_id', appId)
+  }
+  if (accountId !== undefined) {
+    query = query.eq('account_id', accountId)
+  }
+
+  const { data, error } = await query.single()
 
+  // Fallback to a global / system handler if no app- or account-scoped one exists.
   if (error || !data) {
-    console.log(`[webhook-registry] Handler not found: ${handlerName}`)
-    return null
+    const { data: fallbackData, error: fallbackError } = await adminDb
+      .from('webhook_handlers')
+      .select('name, function_name, is_active, is_deleted')
+      .eq('name', handlerName)
+      .eq('is_active', true)
+      .eq('is_deleted', false)
+      .is('app_id', null)
+      .is('account_id', null)
+      .single()
+
+    if (fallbackError || !fallbackData) {
+      console.log(`[webhook-registry] Handler not found: ${handlerName} (appId=${appId}, accountId=${accountId})`)
+      return null
+    }
+
+    handlerCache.set(cacheKey, {
+      functionName: fallbackData.function_name,
+      loaded: false
+    })
+
+    return { functionName: fallbackData.function_name }
   }
 
-  // Cache the result
-  handlerCache.set(handlerName, {
+  handlerCache.set(cacheKey, {
     functionName: data.function_name,
     loaded: false
   })
 
   return { functionName: data.function_name }
 }
-
-/**
- * Loads a webhook handler function dynamically.
- * Uses dynamic import to avoid static dependencies.
- *
- * @param functionName - The Netlify function name (e.g., "custom_cortex-handler")
- * @returns The handler function or null if not found
- */
+// CIL[END chunk_id="webhookregistry_lookuphandler_1784020784"]
+// CIL[BEGIN chunk_id="webhookregistry_loadhandler_1784020784" type="function" identity="loadHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Dynamically load webhook handler function from module"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import and validate handler function from file system"]
+// CIL[DOC-CONTEXT module="webhook-registry" layer="shared" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/migrations/025_retype_threads_messages.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Function or null" errors="import errors" side_effects="module loading"]
+// CIL[DOC-MICRO logic_summary="Dynamic import with handler/default export validation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/principal.ts, .framework/migrations/025_retype_threads_messages.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"]
 export async function loadHandler(functionName: string): Promise<Function | null> {
   try {
-    // Dynamic import of the handler function
-    // Functions are in the same directory after assembly
-    const module = await import(`../${functionName}`)
+    const prefix = functionName.startsWith('custom/') ? '../../../' : '../'
+    const module = await import(`${prefix}${functionName}`)
     
-    // Handler should be exported as 'handler' or default
-    const handler = module.handler || module.default
+    const handler = module.adapt || module.handler || module.default
     
     if (typeof handler !== 'function') {
-      console.error(`[webhook-registry] Export 'handler' not found in ${functionName}`)
+      console.error(`[webhook-registry] No 'adapt' or 'handler' export found in ${functionName}`)
       return null
     }
 
@@ -89,31 +133,64 @@ export async function loadHandler(functionName: string): Promise<Function | null
     return null
   }
 }
-
-/**
- * Resolves a webhook handler by name.
- * Combines lookup + load for convenience.
- *
- * @param handlerName - The handler identifier
- * @returns The handler function or null
- */
-export async function resolveHandler(handlerName: string): Promise<Function | null> {
-  const metadata = await lookupHandler(handlerName)
+// CIL[END chunk_id="webhookregistry_loadhandler_1784020784"]
+// CIL[BEGIN chunk_id="webhookregistry_resolvehandler_1784020784" type="function" identity="resolveHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Resolve webhook handler function by name"]
+// CIL[DOC-RESPONSIBILITY responsibility="Combine lookup and loading for complete handler resolution"]
+// CIL[DOC-CONTEXT module="webhook-registry" layer="shared" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\".framework/migrations/025_retype_threads_messages.sql\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Function or null" errors="lookup/load errors" side_effects="cache update"]
+// CIL[DOC-MICRO logic_summary="Looks up metadata then loads and returns handler function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, .framework/migrations/025_retype_threads_messages.sql, .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 async function resolveHandler(
+  handlerName: string,
+  appId?: string | null,
+  accountId?: string | null
+): Promise<Function | null> {
+  const metadata = await lookupHandler(handlerName, appId, accountId)
   if (!metadata) return null
 
   return loadHandler(metadata.functionName)
 }
-
-/**
- * Clears the handler cache. Useful for testing or after deployments.
- */
+// CIL[END chunk_id="webhookregistry_resolvehandler_1784020784"]
+// CIL[BEGIN chunk_id="webhookregistry_clearhandlercache_1784020784" type="function" identity="clearHandlerCache" parent="none"]
+// CIL[DOC-MACRO purpose="Clear webhook handler cache"]
+// CIL[DOC-RESPONSIBILITY responsibility="Reset handler metadata cache for fresh lookups"]
+// CIL[DOC-CONTEXT module="webhook-registry" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="none" side_effects="cache cleared"]
+// CIL[DOC-MICRO logic_summary="Clears Map cache to force fresh database queries" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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 function clearHandlerCache(): void {
   handlerCache.clear()
 }
-
-/**
- * Lists all registered handlers (for debugging/admin).
- */
+// CIL[END chunk_id="webhookregistry_clearhandlercache_1784020784"]
+// CIL[BEGIN chunk_id="webhookregistry_listregisteredhandlers_1784020784" type="function" identity="listRegisteredHandlers" parent="none"]
+// CIL[DOC-MACRO purpose="List all registered webhook handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve names of all active webhook handlers"]
+// CIL[DOC-CONTEXT module="webhook-registry" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string array" errors="database errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Queries webhook_handlers table and returns active handler names" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. 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 async function listRegisteredHandlers(): Promise<string[]> {
   const { data, error } = await adminDb
     .from('webhook_handlers')
@@ -127,3 +204,4 @@ export async function listRegisteredHandlers(): Promise<string[]> {
 
   return data?.map(h => h.name) || []
 }
+// CIL[END chunk_id="webhookregistry_listregisteredhandlers_1784020784"]