spine-framework 0.3.144 → 0.4.0

package/.framework/functions/admin-funnel.ts

@@ -1,64 +1,62 @@
+// CIL[BEGIN stable_id="~/.framework/functions/admin-funnel.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/admin-funnel.ts"]
+// CIL[DOC-MACRO purpose="Module-level imports for the admin funnel metrics handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import shared middleware and database client used by the handler"]
+// CIL[DOC-CONTEXT module="admin-funnel" layer="function" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Dependency wiring for the admin funnel function" notable_decisions="Uses createHandler and adminDb from _shared"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
+// CIL[DOC-AUDIENCE audience="internal"]
 
-// CIL[BEGIN chunk_id="admin-funnel_module_header_1784019432" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for funnel metrics"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide middleware and admin database access"]
-// CIL[DOC-CONTEXT module="admin-funnel" layer="api-handler" 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="imported_modules" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports required modules for funnel analytics" 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: 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 { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
-// CIL[END chunk_id="admin-funnel_module_header_1784019432"]
-// CIL[BEGIN chunk_id="admin-funnel_metrics_1784019432" type="function" identity="metrics" parent="none"]
-// CIL[DOC-MACRO purpose="Calculate funnel metrics and conversion rates"]
-// CIL[DOC-RESPONSIBILITY responsibility="Aggregate funnel data across visitor journey stages"]
-// CIL[DOC-CONTEXT module="admin-funnel" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="funnel_metrics_object" errors="types_not_found" side_effects="database_queries,aggregation_calculations"]
-// CIL[DOC-MICRO logic_summary="Queries signals, sessions, instances; calculates conversion rates and stage distribution" 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: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.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='Module-level imports for the admin funnel metrics handler'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.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/admin-funnel.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-funnel.ts:metrics:constant" type="constant" identity="metrics" parent="~/.framework/functions/admin-funnel.ts"]
+// CIL[DOC-MACRO purpose="Compute admin funnel metrics for the last 30 days"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query item type registry and items table to calculate visitor, user, install, and stage distribution metrics"]
+// CIL[DOC-CONTEXT module="admin-funnel" layer="function" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/admin-funnel.ts"]
+// CIL[DOC-CONTRACT inputs="ctx: RequestContext, body: request payload" outputs="anonymous_visitors, identified_users, installed_instances, conversion_rates, stage_distribution" errors="none — missing signal types degrade to zeroed metrics" side_effects="Reads from adminDb; no writes"]
+// CIL[DOC-MICRO logic_summary="Resolve funnel_signal, anonymous_session, and spine_instance type IDs from types (kind='item'); count signals, anonymous sessions, identified accounts, and installed instances; return conversion rates and stage distribution" notable_decisions="Signal types are app-seeded, so absent types produce zeroed sections rather than errors; ignores signal items without account_id for stage counts; uses 30-day window; guards division with zero checks"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 export const metrics = createHandler(async (ctx, body) => {
-  const { data: signalType } = await adminDb
-    .from('item_type_registry')
-    .select('id')
-    .eq('slug', 'funnel_signal')
-    .single()
-  
-  const { data: sessionType } = await adminDb
-    .from('item_type_registry')
-    .select('id')
-    .eq('slug', 'anonymous_session')
-    .single()
-  
-  const { data: instanceType } = await adminDb
-    .from('item_type_registry')
-    .select('id')
-    .eq('slug', 'spine_instance')
-    .single()
+  const { data: typeRows } = await adminDb
+    .from('types')
+    .select('id, slug')
+    .eq('kind', 'item')
+    .in('slug', ['funnel_signal', 'anonymous_session', 'spine_instance'])
 
-  if (!signalType || !sessionType || !instanceType) {
-    throw new Error('Required types not found')
+  const typeIdFor = (slug: string) => typeRows?.find((t: any) => t.slug === slug)?.id || null
+  const signalTypeId = typeIdFor('funnel_signal')
+  const sessionTypeId = typeIdFor('anonymous_session')
+  const instanceTypeId = typeIdFor('spine_instance')
+
+  // Signal types are seeded by installed apps — a clean framework install
+  // legitimately has none, so degrade to zeroed metrics instead of 500s.
+  if (!signalTypeId && !sessionTypeId && !instanceTypeId) {
+    return {
+      anonymous_visitors: 0,
+      identified_users: 0,
+      installed_instances: 0,
+      conversion_rates: {
+        anonymous_to_identified: 0,
+        identified_to_installed: 0
+      },
+      stage_distribution: []
+    }
   }
 
-  const { data: stageData } = await adminDb
+  const { data: stageData } = signalTypeId ? await adminDb
     .from('items')
     .select('data->>stage, account_id')
-    .eq('type_id', signalType.id)
-    .gte('created_at', new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString())
+    .eq('type_id', signalTypeId)
+    .gte('created_at', new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString()) : { data: [] }
 
   const stageCounts = stageData?.reduce((acc, item) => {
     const stage = item.data?.stage || 'unknown'
@@ -70,27 +68,27 @@ export const metrics = createHandler(async (ctx, body) => {
 
   const totalStageSignals = Object.values(stageCounts).reduce((sum, count) => sum + count, 0)
 
-  const { count: anonymousSessions } = await adminDb
+  const { count: anonymousSessions } = sessionTypeId ? await adminDb
     .from('items')
     .select('*', { count: 'exact', head: true })
-    .eq('type_id', sessionType.id)
+    .eq('type_id', sessionTypeId)
     .is('data->lifecycle->>stitched_to_account_id', null)
-    .gte('created_at', new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString())
+    .gte('created_at', new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString()) : { count: 0 }
 
-  const { data: accountData } = await adminDb
+  const { data: accountData } = signalTypeId ? await adminDb
     .from('items')
     .select('account_id')
-    .eq('type_id', signalType.id)
+    .eq('type_id', signalTypeId)
     .gte('created_at', new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString())
-    .not('account_id', 'is', null)
+    .not('account_id', 'is', null) : { data: [] }
 
   const uniqueAccounts = new Set(accountData?.map(item => item.account_id)).size
 
-  const { count: installedInstances } = await adminDb
+  const { count: installedInstances } = instanceTypeId ? await adminDb
     .from('items')
     .select('*', { count: 'exact', head: true })
-    .eq('type_id', instanceType.id)
-    .not('data->>claimed_by_person_id', 'is', null)
+    .eq('type_id', instanceTypeId)
+    .not('data->>claimed_by_person_id', 'is', null) : { count: 0 }
 
   const stageDistribution = Object.entries(stageCounts).map(([stage, count]) => ({
     stage,
@@ -112,4 +110,10 @@ export const metrics = createHandler(async (ctx, body) => {
     stage_distribution: stageDistribution
   }
 })
-// CIL[END chunk_id="admin-funnel_metrics_1784019432"]
+// CIL[DOC-VECTOR type="context" content="purpose='Compute admin funnel metrics for the last 30 days'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.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/admin-funnel.ts:metrics:constant"]

package/.framework/functions/admin-install-funnel.ts

@@ -1,59 +1,66 @@
+// CIL[BEGIN stable_id="~/.framework/functions/admin-install-funnel.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/admin-install-funnel.ts"]
+// CIL[DOC-MACRO purpose="Netlify function entrypoint for install funnel admin metrics and export handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define admin metrics and exportData handler exports for the install-funnel function"]
+// CIL[DOC-CONTEXT module="admin" layer="function" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports shared middleware and database client for the install funnel admin endpoints" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="admin-api consumer"]
 
 
-// CIL[BEGIN chunk_id="admin-install-funnel_module_header_1784019432" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for install funnel analytics"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide middleware and admin database access"]
-// CIL[DOC-CONTEXT module="admin-install-funnel" layer="api-handler" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/layout/Sidebar.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imported_modules" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports required modules for install funnel processing" 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: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/layout/Sidebar.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="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'
-// CIL[END chunk_id="admin-install-funnel_module_header_1784019432"]
-// CIL[BEGIN chunk_id="admin-install-funnel_metrics_1784019432" type="function" identity="metrics" parent="none"]
-// CIL[DOC-MACRO purpose="Calculate install funnel metrics and trends"]
-// CIL[DOC-RESPONSIBILITY responsibility="Aggregate install data with conversion rates and version analytics"]
-// CIL[DOC-CONTEXT module="admin-install-funnel" layer="api-handler" 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="install_metrics_object" errors="funnel_signal_type_not_found" side_effects="database_queries,aggregation_calculations,trend_analysis"]
-// CIL[DOC-MICRO logic_summary="Counts downloads/installs, calculates conversion rates, analyzes versions, tracks trends" 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: 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="context" content="purpose='Netlify function entrypoint for install funnel admin metrics and export handlers'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.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/admin-install-funnel.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-install-funnel.ts:metrics:constant" type="constant" identity="metrics" parent="~/.framework/functions/admin-install-funnel.ts"]
+// CIL[DOC-MACRO purpose="Serve install funnel metrics including downloads, installs, first use, claimed, trends and version breakdown"]
+// CIL[DOC-RESPONSIBILITY responsibility="Compute and return install funnel analytics from the item registry"]
+// CIL[DOC-CONTEXT module="admin" layer="function" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/admin-install-funnel.ts"]
+// CIL[DOC-CONTRACT inputs="admin request context and body" outputs="JSON metrics object with funnel counts, trends, recent installs and top versions" errors="none — missing signal types degrade to zeroed metrics" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Resolves the funnel_signal and spine_instance types, aggregates counts, formats recent installs and computes 30-day daily trends" notable_decisions="Signal types are app-seeded, so absent types produce zeroed sections rather than errors"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const metrics = createHandler(async (ctx, body) => {
-  const { data: signalType } = await adminDb
-    .from('item_type_registry')
-    .select('id')
-    .eq('slug', 'funnel_signal')
-    .single()
-  
-  if (!signalType) {
-    throw new Error('funnel_signal type not found')
+  const { data: typeRows } = await adminDb
+    .from('types')
+    .select('id, slug')
+    .eq('kind', 'item')
+    .in('slug', ['funnel_signal', 'spine_instance'])
+
+  const signalTypeId = typeRows?.find((t: any) => t.slug === 'funnel_signal')?.id || null
+  const instanceTypeId = typeRows?.find((t: any) => t.slug === 'spine_instance')?.id || null
+
+  // Signal types are seeded by installed apps — a clean framework install
+  // legitimately has none, so degrade to zeroed metrics instead of 500s.
+  if (!signalTypeId) {
+    return {
+      total_downloads: 0,
+      unique_installers: 0,
+      active_instances: 0,
+      conversion_funnel: { downloads: 0, installations: 0, first_use: 0, claimed: 0 },
+      install_trends: [],
+      recent_installs: [],
+      top_versions: []
+    }
   }
 
   const { count: totalDownloads } = await adminDb
     .from('items')
     .select('*', { count: 'exact', head: true })
-    .eq('type_id', signalType.id)
+    .eq('type_id', signalTypeId)
     .eq('data->>source', 'inst')
     .eq('data->>action_type', 'download')
 
   const { data: installerData } = await adminDb
     .from('items')
     .select('data->>serial')
-    .eq('type_id', signalType.id)
+    .eq('type_id', signalTypeId)
     .eq('data->>source', 'inst')
     .not('data->>serial', 'is', null)
 
@@ -63,7 +70,7 @@ export const metrics = createHandler(async (ctx, body) => {
   const { count: activeInstances } = await adminDb
     .from('items')
     .select('*', { count: 'exact', head: true })
-    .eq('type_id', signalType.id)
+    .eq('type_id', signalTypeId)
     .eq('data->>source', 'inst')
     .not('data->>serial', 'is', null)
     .gte('created_at', sevenDaysAgo)
@@ -71,21 +78,21 @@ export const metrics = createHandler(async (ctx, body) => {
   const { count: installations } = await adminDb
     .from('items')
     .select('*', { count: 'exact', head: true })
-    .eq('type_id', signalType.id)
+    .eq('type_id', signalTypeId)
     .eq('data->>source', 'inst')
     .eq('data->>action_type', 'install')
 
   const { count: firstUse } = await adminDb
     .from('items')
     .select('*', { count: 'exact', head: true })
-    .eq('type_id', signalType.id)
+    .eq('type_id', signalTypeId)
     .eq('data->>source', 'inst')
     .eq('data->>action_type', 'first_command')
 
   const { count: claimed } = await adminDb
     .from('items')
     .select('*', { count: 'exact', head: true })
-    .eq('type_id', signalType.id)
+    .eq('type_id', signalTypeId)
     .eq('data->>source', 'inst')
     .not('data->>claimed_by_person_id', 'is', null)
 
@@ -101,10 +108,10 @@ export const metrics = createHandler(async (ctx, body) => {
       data->>claimed_by_person_id,
       data->>claimed_at,
       account_id,
-      people(email),
+      people!fk_items_created_by(email),
       accounts(name)
     `)
-    .eq('type_id', signalType.id)
+    .eq('type_id', signalTypeId)
     .eq('data->>source', 'inst')
     .not('data->>serial', 'is', null)
     .order('created_at', { ascending: false })
@@ -123,10 +130,10 @@ export const metrics = createHandler(async (ctx, body) => {
     person_email: instance.people?.email
   }))
 
-  const { data: versionData } = await adminDb
+  const { data: versionData } = instanceTypeId ? await adminDb
     .from('items')
     .select('data->>version')
-    .eq('type_id', instanceType.id)
+    .eq('type_id', instanceTypeId) : { data: [] }
 
   const versionCounts = versionData?.reduce((acc, item) => {
     const version = item.data?.version || 'unknown'
@@ -156,7 +163,7 @@ export const metrics = createHandler(async (ctx, body) => {
     const { count: dailyDownloads } = await adminDb
       .from('items')
       .select('*', { count: 'exact', head: true })
-      .eq('type_id', signalType.id)
+      .eq('type_id', signalTypeId)
       .eq('data->>source', 'inst')
       .eq('data->>action_type', 'download')
       .gte('created_at', dateStr)
@@ -165,7 +172,7 @@ export const metrics = createHandler(async (ctx, body) => {
     const { count: dailyInstalls } = await adminDb
       .from('items')
       .select('*', { count: 'exact', head: true })
-      .eq('type_id', signalType.id)
+      .eq('type_id', signalTypeId)
       .eq('data->>source', 'inst')
       .eq('data->>action_type', 'install')
       .gte('created_at', dateStr)
@@ -193,30 +200,35 @@ export const metrics = createHandler(async (ctx, body) => {
     top_versions: topVersions
   }
 })
-// CIL[END chunk_id="admin-install-funnel_metrics_1784019432"]
-// CIL[BEGIN chunk_id="admin-install-funnel_exportdata_1784019432" type="function" identity="exportData" parent="none"]
-// CIL[DOC-MACRO purpose="Export all install instances with full details"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide complete install data for analysis and reporting"]
-// CIL[DOC-CONTEXT module="admin-install-funnel" layer="api-handler" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/layout/Sidebar.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="export_data_object" errors="funnel_signal_type_not_found" side_effects="database_query,data_export"]
-// CIL[DOC-MICRO logic_summary="Queries all install instances with full details and metadata" 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/layout/Sidebar.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="context" content="purpose='Serve install funnel metrics including downloads, installs, first use, claimed, trends and version breakdown'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.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/admin-install-funnel.ts:metrics:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-install-funnel.ts:exportData:constant" type="constant" identity="exportData" parent="~/.framework/functions/admin-install-funnel.ts"]
+// CIL[DOC-MACRO purpose="Export raw install funnel instance records with contact and account details"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return all funnel_signal instances with source 'inst' and a non-null serial"]
+// CIL[DOC-CONTEXT module="admin" layer="function" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/admin-install-funnel.ts"]
+// CIL[DOC-CONTRACT inputs="admin request context and body" outputs="JSON object with instances array, exported_at and total_count" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Selects instances with joined people and accounts, ordered by created_at descending" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const exportData = createHandler(async (ctx, body) => {
   const { data: signalType } = await adminDb
-    .from('item_type_registry')
+    .from('types')
     .select('id')
+    .eq('kind', 'item')
     .eq('slug', 'funnel_signal')
-    .single()
+    .maybeSingle()
 
   if (!signalType) {
-    throw new Error('funnel_signal type not found')
+    return {
+      instances: [],
+      exported_at: new Date().toISOString(),
+      total_count: 0
+    }
   }
 
   const { data: instances } = await adminDb
@@ -227,7 +239,7 @@ export const exportData = createHandler(async (ctx, body) => {
       updated_at,
       data,
       account_id,
-      people(email),
+      people!fk_items_created_by(email),
       accounts(name)
     `)
     .eq('type_id', signalType.id)
@@ -241,4 +253,10 @@ export const exportData = createHandler(async (ctx, body) => {
     total_count: instances?.length || 0
   }
 })
-// CIL[END chunk_id="admin-install-funnel_exportdata_1784019432"]
+// CIL[DOC-VECTOR type="context" content="purpose='Export raw install funnel instance records with contact and account details'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.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/admin-install-funnel.ts:exportData:constant"]

package/.framework/functions/admin-signals.ts

@@ -1,50 +1,54 @@
+// CIL[BEGIN stable_id="~/.framework/functions/admin-signals.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/admin-signals.ts"]
+// CIL[DOC-MACRO purpose="Declares the admin-signals function module and its imports"]
+// CIL[DOC-RESPONSIBILITY responsibility="Set up module context and shared dependencies"]
+// CIL[DOC-CONTEXT module=".framework/functions/admin-signals.ts" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="module scope" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Module header that imports shared middleware and database client for admin signal handlers." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="system-admin, developer"]
 
 
-// CIL[BEGIN chunk_id="admin-signals_module_header_1784019432" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for signal analytics"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide middleware and admin database access"]
-// CIL[DOC-CONTEXT module="admin-signals" layer="api-handler" 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="imported_modules" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports required modules for signal processing" 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: 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 { createHandler } from './_shared/middleware'
 import { adminDb } from './_shared/db'
-// CIL[END chunk_id="admin-signals_module_header_1784019432"]
-// CIL[BEGIN chunk_id="admin-signals_metrics_1784019432" type="function" identity="metrics" parent="none"]
-// CIL[DOC-MACRO purpose="Calculate signal metrics and analytics"]
-// CIL[DOC-RESPONSIBILITY responsibility="Aggregate signal data with conversion rates and trends"]
-// CIL[DOC-CONTEXT module="admin-signals" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="signal_metrics_object" errors="funnel_signal_type_not_found" side_effects="database_queries,aggregation_calculations"]
-// CIL[DOC-MICRO logic_summary="Counts signals by time periods, calculates sources, formats recent signals, computes conversion rates" 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: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/principal.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='Declares the admin-signals function module and its imports'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.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/admin-signals.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-signals.ts:metrics:constant" type="constant" identity="metrics" parent="~/.framework/functions/admin-signals.ts"]
+// CIL[DOC-MACRO purpose="Aggregate funnel signal metrics for the admin dashboard"]
+// CIL[DOC-RESPONSIBILITY responsibility="Compute and return totals, daily and weekly counts, conversion rate, top sources, and recent signals"]
+// CIL[DOC-CONTEXT module=".framework/functions/admin-signals.ts" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/admin-signals.ts"]
+// CIL[DOC-CONTRACT inputs="ctx, body" outputs="JSON metrics object" errors="none — missing signal types degrade to zeroed metrics" side_effects="Queries adminDb"]
+// CIL[DOC-MICRO logic_summary="Resolves funnel_signal item type, runs count and select queries over items, aggregates source distribution over the past week, computes conversion rate, and formats the most recent signals." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const metrics = createHandler(async (ctx, body) => {
   const now = new Date()
   const today = now.toISOString().split('T')[0]
   const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString()
   
   const { data: signalType } = await adminDb
-    .from('item_type_registry')
+    .from('types')
     .select('id')
+    .eq('kind', 'item')
     .eq('slug', 'funnel_signal')
-    .single()
-  
+    .maybeSingle()
+
+  // Signal types are seeded by installed apps — a clean framework install
+  // legitimately has none, so degrade to zeroed metrics instead of 500s.
   if (!signalType) {
-    throw new Error('funnel_signal type not found')
+    return {
+      total_signals: 0,
+      signals_today: 0,
+      signals_this_week: 0,
+      conversion_rate: 0,
+      top_sources: [],
+      recent_signals: []
+    }
   }
 
   const { count: totalSignals } = await adminDb
@@ -125,21 +129,21 @@ export const metrics = createHandler(async (ctx, body) => {
     recent_signals: formattedSignals || []
   }
 })
-// CIL[END chunk_id="admin-signals_metrics_1784019432"]
-// CIL[BEGIN chunk_id="admin-signals_audit_1784019432" type="function" identity="audit" parent="none"]
-// CIL[DOC-MACRO purpose="Audit and export signal data with filtering"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide searchable, filterable signal audit trail"]
-// CIL[DOC-CONTEXT module="admin-signals" layer="api-handler" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/db.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="paginated_signals_or_export_data" errors="funnel_signal_type_not_found" side_effects="database_queries,data_formatting"]
-// CIL[DOC-MICRO logic_summary="Builds filtered query, applies pagination, formats signal data for audit/export" 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: custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/db.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, 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='Aggregate funnel signal metrics for the admin dashboard'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.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/admin-signals.ts:metrics:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-signals.ts:audit:constant" type="constant" identity="audit" parent="~/.framework/functions/admin-signals.ts"]
+// CIL[DOC-MACRO purpose="List and optionally export funnel signal audit records"]
+// CIL[DOC-RESPONSIBILITY responsibility="Fetch paginated signal records, apply query filters, and support CSV-like export"]
+// CIL[DOC-CONTEXT module=".framework/functions/admin-signals.ts" layer="functions" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/admin-signals.ts"]
+// CIL[DOC-CONTRACT inputs="ctx, body and ctx.query filter parameters" outputs="Object with signals array, total, page, limit or formatted array for export" errors="query failure throws; missing signal type degrades to an empty page" side_effects="Queries adminDb"]
+// CIL[DOC-MICRO logic_summary="Resolves funnel_signal item type, builds a filtered query over items including related accounts and people, optionally paginates, returns full data for export, and formats each row." notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const audit = createHandler(async (ctx, body) => {
   const {
     page = '1',
@@ -156,13 +160,21 @@ export const audit = createHandler(async (ctx, body) => {
   } = ctx.query || {}
 
   const { data: signalType } = await adminDb
-    .from('item_type_registry')
+    .from('types')
     .select('id')
+    .eq('kind', 'item')
     .eq('slug', 'funnel_signal')
-    .single()
-  
+    .maybeSingle()
+
+  // Signal types are seeded by installed apps — degrade to an empty page.
   if (!signalType) {
-    throw new Error('funnel_signal type not found')
+    if (exportData) return []
+    return {
+      signals: [],
+      total: 0,
+      page: parseInt(page),
+      limit: parseInt(limit)
+    }
   }
 
   let query = adminDb
@@ -183,7 +195,7 @@ export const audit = createHandler(async (ctx, body) => {
       data->attribution->>utm_medium,
       data->attribution->>utm_campaign,
       account_id,
-      people(email),
+      people!fk_items_created_by(email),
       accounts(name)
     `, { count: 'exact' })
     .eq('type_id', signalType.id)
@@ -256,4 +268,10 @@ export const audit = createHandler(async (ctx, body) => {
     limit: parseInt(limit)
   }
 })
-// CIL[END chunk_id="admin-signals_audit_1784019432"]
+// CIL[DOC-VECTOR type="context" content="purpose='List and optionally export funnel signal audit records'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.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/admin-signals.ts:audit:constant"]