spine-framework 0.3.124 → 0.3.126

package/.framework/functions/_shared/app-manifest.ts

@@ -1,21 +1,23 @@
-/**
- * @module app-manifest
- * @audience core-contributor
- * @layer shared-util
- * @stability evolving
- *
- * Utility for loading and merging app manifests with database records.
- * Enables file-first app configuration with database tracking installations.
- *
- * **Pattern:**
- * 1. Manifest files in custom/apps/{slug}/manifest.json are source of truth
- * 2. Database tracks which tenant has which app installed/enabled
- * 3. This utility merges both sources for the API response
- *
- * @seeAlso apps.ts (uses this for manifest-driven responses)
- * @seeAlso 015_simplify_apps_table.sql (database structure)
- */
 
+
+
+
+
+// CIL[BEGIN chunk_id="app-manifest_moduleheader_1784066609" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="App manifest loading and management"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load and merge app configuration manifests"]
+// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="manifest utilities" errors="none" side_effects="file system access"]
+// CIL[DOC-MICRO logic_summary="Defines AppManifest, NavItem interfaces and manifest cache" 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { readFileSync } from 'fs'
 import { resolve } from 'path'
 
@@ -24,7 +26,7 @@ export interface AppManifest {
   slug: string
   description?: string
   version?: string
-  required_roles: string[]  // Migrated from min_role (string) to array
+  required_roles: string[]
   route_prefix?: string
   renderer?: 'generic' | 'custom' | 'none'
   routes: string[]
@@ -46,41 +48,44 @@ export interface NavItem {
   children?: NavItem[]
 }
 
-// Cache for manifest content (development mode - no caching in production)
 const manifestCache = new Map<string, AppManifest>()
 
-/**
- * Loads a manifest.json file from the filesystem.
- * 
- * @param manifestPath - Relative path to manifest (e.g., 'custom/apps/cortex/manifest.json')
- * @returns Parsed manifest or null if not found
- */
+// CIL[END chunk_id="app-manifest_moduleheader_1784066609"]
+// CIL[BEGIN chunk_id="app-manifest_loadmanifest_1784066609" type="function" identity="loadManifest" parent="none"]
+// CIL[DOC-MACRO purpose="Load app manifest from file"]
+// CIL[DOC-RESPONSIBILITY responsibility="Read and parse manifest JSON with caching"]
+// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AppManifest or null" errors="file system errors" side_effects="file reads"]
+// CIL[DOC-MICRO logic_summary="Loads manifest from disk with validation and caching" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, 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 function loadManifest(manifestPath: string): AppManifest | null {
-  // Check cache first (dev only)
   if (manifestCache.has(manifestPath)) {
     return manifestCache.get(manifestPath)!
   }
 
   try {
-    // Resolve from project root (functions are at .assembled/netlify/functions/)
     const projectRoot = resolve(__dirname, '../../../..')
     const fullPath = resolve(projectRoot, manifestPath)
     
     const content = readFileSync(fullPath, 'utf-8')
     const manifest: AppManifest = JSON.parse(content)
     
-    // Validate required fields
     if (!manifest.slug || !manifest.name) {
       console.error(`[app-manifest] Invalid manifest at ${manifestPath}: missing slug or name`)
       return null
     }
     
-    // Ensure required_roles is array (backward compat)
     if (!manifest.required_roles) {
       manifest.required_roles = []
     }
     
-    // Cache for development (dev server restarts clear cache)
     manifestCache.set(manifestPath, manifest)
     
     return manifest
@@ -89,27 +94,43 @@ export function loadManifest(manifestPath: string): AppManifest | null {
     return null
   }
 }
-
-/**
- * Clears the manifest cache. Useful for testing.
- */
+// CIL[END chunk_id="app-manifest_loadmanifest_1784066609"]
+// CIL[BEGIN chunk_id="app-manifest_clearmanifestcache_1784066609" type="function" identity="clearManifestCache" parent="none"]
+// CIL[DOC-MACRO purpose="Clear manifest cache"]
+// CIL[DOC-RESPONSIBILITY responsibility="Reset cached manifest data"]
+// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="none" side_effects="cache clearing"]
+// CIL[DOC-MICRO logic_summary="Clears all cached manifest entries" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. 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 function clearManifestCache(): void {
   manifestCache.clear()
 }
-
-/**
- * Merges database app record with manifest data.
- * Manifest takes precedence for metadata fields.
- * 
- * @param dbRecord - App record from app_definitions table
- * @returns Merged app data for API response
- */
+// CIL[END chunk_id="app-manifest_clearmanifestcache_1784066609"]
+// CIL[BEGIN chunk_id="app-manifest_mergewithmanifest_1784066609" type="function" identity="mergeWithManifest" parent="none"]
+// CIL[DOC-MACRO purpose="Merge database record with manifest"]
+// CIL[DOC-RESPONSIBILITY responsibility="Combine DB and manifest configuration"]
+// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="merged record" errors="manifest load errors" side_effects="file reads"]
+// CIL[DOC-MICRO logic_summary="Merges database record with manifest file data" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/IntegrationsPage.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 function mergeWithManifest(dbRecord: any): any {
   if (!dbRecord) return null
   
-  // If no manifest path, return DB record as-is (legacy mode)
   if (!dbRecord.manifest_path || dbRecord.config_source !== 'manifest') {
-    // Convert legacy min_role to required_roles for frontend compatibility
     return {
       ...dbRecord,
       required_roles: dbRecord.min_role ? [dbRecord.min_role] : [],
@@ -117,7 +138,6 @@ export function mergeWithManifest(dbRecord: any): any {
     }
   }
   
-  // Load manifest and merge
   const manifest = loadManifest(dbRecord.manifest_path)
   if (!manifest) {
     console.warn(`[app-manifest] Could not load manifest for ${dbRecord.slug}, falling back to DB`)
@@ -128,54 +148,48 @@ export function mergeWithManifest(dbRecord: any): any {
     }
   }
   
-  // Merge: Manifest metadata + DB state fields
   return {
     id: dbRecord.id,
     slug: manifest.slug,
     name: manifest.name,
     description: manifest.description || dbRecord.description,
-    
-    // Role-based access (new array format)
     required_roles: manifest.required_roles,
-    min_role: manifest.required_roles[0] || null, // Backward compat
-    
-    // Navigation and routing
+    min_role: manifest.required_roles[0] || null,
     routes: manifest.routes,
     nav_items: manifest.nav_items,
-    
-    // Features and metadata
     features: manifest.features || [],
     dependencies: manifest.dependencies || [],
     version: manifest.version,
-    
-    // Database state fields
     is_active: dbRecord.is_active,
     is_system: dbRecord.is_system,
     is_public: manifest.is_public ?? false,
     auth_required: manifest.auth_required ?? true,
-    
-    // Installation tracking
     account_id: dbRecord.account_id,
     pack_id: dbRecord.pack_id,
     ownership: dbRecord.ownership,
-    
-    // Internal
     _source: 'manifest',
     _manifest_path: dbRecord.manifest_path
   }
 }
-
-/**
- * Lists all available manifests from filesystem.
- * Used for initial discovery before database tracking.
- * 
- * @returns Array of discovered app slugs and their paths
- */
+// CIL[END chunk_id="app-manifest_mergewithmanifest_1784066609"]
+// CIL[BEGIN chunk_id="app-manifest_discovermanifests_1784066609" type="function" identity="discoverManifests" parent="none"]
+// CIL[DOC-MACRO purpose="Discover available app manifests"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return list of known manifest paths"]
+// CIL[DOC-CONTEXT module="_shared/app-manifest" layer="infrastructure" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="manifest list" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns hardcoded list of app manifest locations" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: infrastructure. 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 discoverManifests(): Array<{slug: string, path: string}> {
-  // In production, this would scan the filesystem
-  // For now, return known manifests based on the plan
   return [
     { slug: 'cortex', path: 'custom/apps/cortex/manifest.json' },
     { slug: 'customer-portal', path: 'custom/apps/customer-portal/manifest.json' }
   ]
 }
+// CIL[END chunk_id="app-manifest_discovermanifests_1784066609"]

package/.framework/functions/_shared/audit.ts

@@ -1,47 +1,53 @@
-/**
- * @module audit
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * Unified audit logging for all operations in Spine. Every state-changing
- * operation should call `emitAudit` to write a structured row to the `logs`
- * table with full principal provenance. Audit failures never throw — a failed
- * log write must never break the operation that triggered it.
- *
- * INVARIANT: always call `emitAudit` after a successful write, not before.
- *   Pass `result: 'failure'` only when the operation itself failed.
- * INVARIANT: never pass sensitive secrets (API keys, tokens) in metadata.
- *
- * @seeAlso principal.ts (formatPrincipalForAudit — shapes the principal field)
- * @seeAlso middleware.ts (CoreContext — ctx.requestId ties logs to HTTP requests)
- * @seeAlso logs.ts (API handler that queries the logs table)
- * @seeAlso permissions.ts (getPrincipalPermissionSummary — used in metadata)
- */
 
+
+
+// CIL[BEGIN chunk_id="audit_moduleheader_1784068075" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Audit logging system imports"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import dependencies for audit functionality"]
+// CIL[DOC-CONTEXT module="_shared/audit" layer="infrastructure" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imports" errors="none" side_effects="module imports"]
+// CIL[DOC-MICRO logic_summary="Imports CoreContext, database, and principal utilities" 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { CoreContext } from './middleware'
 import { adminDb } from './db'
 import { Principal, formatPrincipalForAudit } from './principal'
+import { Span, TraceContext } from './tracing'
+// CIL[END chunk_id="audit_moduleheader_1784068075"]
+// CIL[BEGIN chunk_id="audit_emitaudit_1784068075" type="function" identity="emitAudit" parent="none"]
+// CIL[DOC-MACRO purpose="Emit audit log entries"]
+// CIL[DOC-RESPONSIBILITY responsibility="Write structured audit logs to database"]
+// CIL[DOC-CONTEXT module="_shared/audit" layer="infrastructure" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/migrations/015_simplify_apps_table.sql\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Promise<void>" errors="database errors" side_effects="database writes"]
+// CIL[DOC-MICRO logic_summary="Inserts audit records with principal context and metadata" 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/migrations/015_simplify_apps_table.sql."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+function traceFields(ctx: CoreContext): Partial<Record<string, any>> {
+  const trace = (ctx as any).trace as TraceContext | undefined
+  if (!trace) return {}
+  return {
+    trace_id: trace.traceId,
+    span_id: trace.spanId,
+    parent_span_id: trace.parentSpanId,
+    trace_flags: trace.traceFlags,
+    tracestate: trace.traceState,
+    sampled: trace.sampled
+  }
+}
 
-// ─── PRIMARY AUDIT FUNCTION ───────────────────────────────────────────────────
-
-// ─── CHUNK_START: SHARED_AUDIT_EMIT ──────────────────────────────────────────────
-/**
- * @chunk-id    SHARED_AUDIT_EMIT_1_0_0
- * @version     1.0.0
- * @hash        d9c3dbc103f5f2f0543dc4c154bbad256e59c885643a20bc20ca07198eabd67c
- * @macro       Audit Log Emitter
- * @micro       Writes structured audit logs to logs table with principal provenance
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      action: string — Dot-namespaced action (e.g. 'items.create')
- * @inputs      target: {type, id?, account_id?} — Resource being acted upon
- * @inputs      metadata: {changes?, result?, error?, ...} — Optional context
- * @outputs     void — Always resolves, never rejects
- * @depends-on  [adminDb, formatPrincipalForAudit]
- * @depended-by [All state-changing API functions, pipeline-runner, trigger-engine]
- * @side-effects [DB insert to logs table, console.error on failure]
- * @tags        audit, logging, security, compliance
- */
 export async function emitAudit(
   ctx: CoreContext,
   action: string,
@@ -54,13 +60,21 @@ export async function emitAudit(
   }
 ): Promise<void> {
   try {
-    // Use the RLS-scoped db from context, or fallback to adminDb
     const logDb = ctx.db || adminDb
-    
+    const result = metadata?.result
+    const level = result === 'failure' || result === 'denied' ? 'warning' : 'info'
+
     await logDb.from('logs').insert({
-      level: metadata?.result === 'failure' || metadata?.result === 'denied' ? 'warning' : 'info',
+      level,
       source: 'audit',
+      source_type: 'event',
       message: `${action} by ${ctx.principal?.type || 'unknown'}:${ctx.principal?.id || 'anonymous'}`,
+      span_name: action,
+      kind: 'event',
+      outcome: result === 'failure' ? 'failure' : result === 'denied' ? 'failure' : result === 'success' ? 'success' : null,
+      event_category: result ? 'business_outcome' : 'audit',
+      started_at: new Date().toISOString(),
+      ...traceFields(ctx),
       metadata: {
         principal: ctx.principal ? formatPrincipalForAudit(ctx.principal) : null,
         action,
@@ -76,31 +90,73 @@ export async function emitAudit(
     })
   } catch (err) {
     console.error('Failed to emit audit log:', err)
-    // Don't throw - audit failures shouldn't break operations
   }
 }
-// ─── CHUNK_END: SHARED_AUDIT_EMIT ────────────────────────────────────────────────
 
-// ─── LEGACY EXPORTS ───────────────────────────────────────────────────────────
+export async function emitSpan(
+  ctx: CoreContext,
+  span: Span,
+  options?: {
+    action?: string
+    target?: { type: string; id?: string; account_id?: string }
+    level?: string
+    kind?: string
+    event_category?: string
+    metadata?: Record<string, any>
+  }
+): Promise<void> {
+  try {
+    const logDb = ctx.db || adminDb
+    const level = options?.level || (span.status === 'error' ? 'warning' : 'info')
+    const outcome = span.status === 'error' ? 'failure' : span.status === 'ok' ? 'success' : null
 
-// ─── CHUNK_START: SHARED_AUDIT_EMIT_LOG ──────────────────────────────────────────────
-/**
- * @chunk-id    SHARED_AUDIT_EMIT_LOG_1_0_0
- * @version     1.0.0
- * @hash        148fb1ce7badf1d3df08e2daa38bac4c084c94ba2f262c782c9df092a22890dd
- * @macro       Legacy Audit Log Wrapper
- * @micro       Backward compatibility wrapper around emitAudit
- * @inputs      ctx: CoreContext — Request context
- * @inputs      eventType: string — Action string (maps to emitAudit's action)
- * @inputs      target: {type, id} | undefined — Resource target
- * @inputs      changes: {before?, after?} | undefined — Change data
- * @inputs      metadata: Record<string, any> — Additional context
- * @outputs     void — Always resolves
- * @depends-on  [emitAudit]
- * @depended-by [Legacy code, should not be used in new code]
- * @side-effects [DB insert via emitAudit, console.error on failure]
- * @tags        audit, logging, legacy, wrapper, deprecated
- */
+    await logDb.from('logs').insert({
+      level,
+      source: 'span',
+      source_type: 'span',
+      message: `${span.spanName} ${span.status === 'error' ? 'failed' : 'completed'}`,
+      trace_id: span.traceId,
+      span_id: span.spanId,
+      parent_span_id: span.parentSpanId,
+      trace_flags: span.traceFlags,
+      tracestate: span.traceState,
+      span_name: span.spanName,
+      started_at: span.startedAt,
+      ended_at: span.endedAt,
+      duration_ms: span.durationMs,
+      sampled: span.sampled,
+      kind: options?.kind || 'span',
+      outcome,
+      event_category: options?.event_category,
+      metadata: {
+        principal: ctx.principal ? formatPrincipalForAudit(ctx.principal) : null,
+        action: options?.action || span.spanName,
+        target: options?.target || { type: 'request', account_id: ctx.accountId },
+        request_id: ctx.requestId,
+        ...span.attributes,
+        ...(options?.metadata || {})
+      },
+      account_id: options?.target?.account_id || ctx.accountId || ctx.principal?.accountId || null
+    })
+  } catch (err) {
+    console.error('Failed to emit span log:', err)
+  }
+}
+// CIL[END chunk_id="audit_emitaudit_1784068075"]
+// CIL[BEGIN chunk_id="audit_emitlog_1784068075" type="function" identity="emitLog" parent="none"]
+// CIL[DOC-MACRO purpose="Emit general log entries"]
+// CIL[DOC-RESPONSIBILITY responsibility="Wrapper for audit logging with change tracking"]
+// CIL[DOC-CONTEXT module="_shared/audit" layer="infrastructure" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Promise<void>" errors="audit errors" side_effects="database writes"]
+// CIL[DOC-MICRO logic_summary="Delegates to emitAudit with structured change data" 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/migrations/015_simplify_apps_table.sql, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export async function emitLog(
   ctx: CoreContext,
   eventType: string,
@@ -119,27 +175,23 @@ export async function emitLog(
     })
   } catch (error) {
     console.error('Failed to emit log:', error)
-    // Don't throw - logging failures shouldn't break operations
   }
 }
-// ─── CHUNK_END: SHARED_AUDIT_EMIT_LOG ────────────────────────────────────────────────
-
-// ─── CHUNK_START: SHARED_AUDIT_EMIT_ACTIVITY ──────────────────────────────────────────────
-/**
- * @chunk-id    SHARED_AUDIT_EMIT_ACTIVITY_1_0_0
- * @version     1.0.0
- * @hash        58e532a743fdae480ca24d311be66e82612477309270ec7462fd7dfd695d5282
- * @macro       Legacy Activity Logger
- * @micro       Wraps emitLog with activity. prefix for backward compatibility
- * @inputs      ctx: CoreContext — Request context
- * @inputs      type: string — Activity type (prefixed with 'activity.')
- * @inputs      details: Record<string, any> — Metadata context
- * @outputs     void — Always resolves
- * @depends-on  [emitLog]
- * @depended-by [Legacy code, should not be used in new code]
- * @side-effects [DB insert via emitLog → emitAudit, console.error on failure]
- * @tags        audit, logging, legacy, activity, deprecated
- */
+// CIL[END chunk_id="audit_emitlog_1784068075"]
+// CIL[BEGIN chunk_id="audit_emitactivity_1784068075" type="function" identity="emitActivity" parent="none"]
+// CIL[DOC-MACRO purpose="Emit activity log entries"]
+// CIL[DOC-RESPONSIBILITY responsibility="Log user activities with activity prefix"]
+// CIL[DOC-CONTEXT module="_shared/audit" layer="infrastructure" related_files="[\".framework/src/components/ui/dialog.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/migrations/015_simplify_apps_table.sql\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Promise<void>" errors="log errors" side_effects="database writes"]
+// CIL[DOC-MICRO logic_summary="Wraps emitLog with activity. prefix for categorization" 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: infrastructure. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/migrations/015_simplify_apps_table.sql, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export async function emitActivity(
   ctx: CoreContext,
   type: string,
@@ -147,4 +199,4 @@ export async function emitActivity(
 ): Promise<void> {
   await emitLog(ctx, `activity.${type}`, undefined, undefined, details)
 }
-// ─── CHUNK_END: SHARED_AUDIT_EMIT_ACTIVITY ────────────────────────────────────────────────
+// CIL[END chunk_id="audit_emitactivity_1784068075"]