spine-framework 0.3.125 → 0.3.127

package/.framework/src/lib/utils.ts

@@ -1,59 +1,75 @@
-/**
- * @module src/lib/utils
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * General-purpose frontend utility functions. Pure helpers only — no React,
- * no Supabase, no side effects. Safe to use in any component or hook.
- *
- * **Exports:** `cn`, `formatDate`, `formatTime`, `formatDateTime`,
- * `formatRelativeTime`, `formatFileSize`, `formatCurrency`, `formatNumber`,
- * `truncateText`, `generateSlug`, `capitalize`, `debounce`, `throttle`,
- * `isValidUrl`, `getFileExtension`, `generateId`, `deepClone`
- *
- * @seeAlso src/lib/api.ts (fetch utilities)
- * @seeAlso functions/_shared/schema-utils.ts (server-side field formatters
- *   for storage-layer data; parallel set to the date/currency helpers here)
- */
 
-import { type ClassValue, clsx } from 'clsx'
-import { twMerge } from 'tailwind-merge'
 
-// ─── TAILWIND HELPERS ───────────────────────────────────────────────────────────
 
-/**
- * Merges Tailwind class strings with conflict resolution via `tailwind-merge`
- * and conditional class support via `clsx`. The standard utility for
- * composing class names in all Spine components.
- *
- * @param inputs - Any number of class values (strings, arrays, objects)
- * @returns Merged, deduplicated class string
- * @throws never
- * @example
- * ```ts
- * cn('px-4 py-2', isActive && 'bg-blue-500', 'px-6') // → 'py-2 bg-blue-500 px-6'
- * ```
- */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="utils_imports_1783712804" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import CSS class utilities"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide class merging dependencies"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="clsx, twMerge" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import external CSS utility libraries" 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: utility. Direct callers: 0. Direct calls: 0. Related files: 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"]
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+// CIL[END chunk_id="utils_imports_1783712804"]
+// CIL[BEGIN chunk_id="utils_cn_1783712804" type="function" identity="cn" parent="none"]
+// CIL[DOC-MACRO purpose="Merge CSS class names with Tailwind"]
+// CIL[DOC-RESPONSIBILITY responsibility="Combine and deduplicate CSS classes"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Apply clsx then twMerge for class handling" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx, .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 function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
-
-// ─── DATE FORMATTERS ────────────────────────────────────────────────────────────
-
-/**
- * Formats a date as a locale date string ('Jan 15, 2024').
- * Returns `'N/A'` for null/undefined, `'Invalid Date'` for non-parseable input.
- * @param date - ISO string, Date object, null, or undefined
- * @param options - Optional `Intl.DateTimeFormatOptions` overrides
- * @throws never
- */
+// CIL[END chunk_id="utils_cn_1783712804"]
+// CIL[BEGIN chunk_id="utils_formatdate_1783712804" type="function" identity="formatDate" parent="none"]
+// CIL[DOC-MACRO purpose="Format date to readable string"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert date to localized format"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Handle null/invalid dates, format with options" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 3. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 3. Total affected: 3."]
+// 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 formatDate(date: string | Date | null | undefined, options?: Intl.DateTimeFormatOptions) {
   if (!date) return 'N/A'
   
   const dateObj = typeof date === 'string' ? new Date(date) : date
   
-  // Check if date is invalid
   if (!dateObj || isNaN(dateObj.getTime())) return 'Invalid Date'
   
   return dateObj.toLocaleDateString('en-US', {
@@ -63,18 +79,26 @@ export function formatDate(date: string | Date | null | undefined, options?: Int
     ...options,
   })
 }
-
-/**
- * Formats a date as a locale time string ('02:30 PM').
- * Returns `'N/A'` for null/undefined, `'Invalid Date'` for bad input.
- * @throws never
- */
+// CIL[END chunk_id="utils_formatdate_1783712804"]
+// CIL[BEGIN chunk_id="utils_formattime_1783712804" type="function" identity="formatTime" parent="none"]
+// CIL[DOC-MACRO purpose="Format time to readable string"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert time to localized format"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Handle null/invalid dates, format time with options" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/table-primitives.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 formatTime(date: string | Date | null | undefined, options?: Intl.DateTimeFormatOptions) {
   if (!date) return 'N/A'
   
   const dateObj = typeof date === 'string' ? new Date(date) : date
   
-  // Check if date is invalid
   if (!dateObj || isNaN(dateObj.getTime())) return 'Invalid Date'
   
   return dateObj.toLocaleTimeString('en-US', {
@@ -83,18 +107,26 @@ export function formatTime(date: string | Date | null | undefined, options?: Int
     ...options,
   })
 }
-
-/**
- * Formats a date as a locale date+time string ('Jan 15, 2024, 02:30 PM').
- * Returns `'N/A'` for null/undefined, `'Invalid Date'` for bad input.
- * @throws never
- */
+// CIL[END chunk_id="utils_formattime_1783712804"]
+// CIL[BEGIN chunk_id="utils_formatdatetime_1783712804" type="function" identity="formatDateTime" parent="none"]
+// CIL[DOC-MACRO purpose="Format date and time to readable string"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert datetime to localized format"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Handle null/invalid dates, format datetime with options" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. 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 formatDateTime(date: string | Date | null | undefined, options?: Intl.DateTimeFormatOptions) {
   if (!date) return 'N/A'
   
   const dateObj = typeof date === 'string' ? new Date(date) : date
   
-  // Check if date is invalid
   if (!dateObj || isNaN(dateObj.getTime())) return 'Invalid Date'
   
   return dateObj.toLocaleString('en-US', {
@@ -106,20 +138,26 @@ export function formatDateTime(date: string | Date | null | undefined, options?:
     ...options,
   })
 }
-
-/**
- * Formats a date as a human-readable relative string
- * ('just now', '5 minutes ago', '3 days ago', or falls back to `formatDate`
- * for dates older than 7 days).
- * Returns `'N/A'` for null/undefined, `'Invalid Date'` for bad input.
- * @throws never
- */
+// CIL[END chunk_id="utils_formatdatetime_1783712804"]
+// CIL[BEGIN chunk_id="utils_formatrelativetime_1783712804" type="function" identity="formatRelativeTime" parent="none"]
+// CIL[DOC-MACRO purpose="Format relative time from now"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert date to human-readable relative time"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Calculate time differences and format with units" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. 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 formatRelativeTime(date: string | Date | null | undefined) {
   if (!date) return 'N/A'
   
   const dateObj = typeof date === 'string' ? new Date(date) : date
   
-  // Check if date is invalid
   if (isNaN(dateObj.getTime())) return 'Invalid Date'
   
   const now = new Date()
@@ -141,16 +179,21 @@ export function formatRelativeTime(date: string | Date | null | undefined) {
     return formatDate(dateObj)
   }
 }
-
-// ─── NUMBER FORMATTERS ───────────────────────────────────────────────────────────
-
-/**
- * Formats bytes as a human-readable size string ('1.23 MB').
- * Returns `'0 Bytes'` for 0.
- * @param bytes - Non-negative byte count
- * @param decimals - Decimal places (default 2)
- * @throws never
- */
+// CIL[END chunk_id="utils_formatrelativetime_1783712804"]
+// CIL[BEGIN chunk_id="utils_formatfilesize_1783712804" type="function" identity="formatFileSize" parent="none"]
+// CIL[DOC-MACRO purpose="Format file size with appropriate units"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert bytes to human-readable size"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Calculate appropriate unit and format with decimals" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx, .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 function formatFileSize(bytes: number, decimals = 2) {
   if (bytes === 0) return '0 Bytes'
 
@@ -162,47 +205,79 @@ export function formatFileSize(bytes: number, decimals = 2) {
 
   return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i]
 }
-
-/**
- * Formats a number as a locale currency string ('$1,234.56').
- * @param amount - Numeric value
- * @param currency - ISO 4217 code (default 'USD')
- * @param locale - BCP 47 locale tag (default 'en-US')
- * @throws never
- */
+// CIL[END chunk_id="utils_formatfilesize_1783712804"]
+// CIL[BEGIN chunk_id="utils_formatcurrency_1783712804" type="function" identity="formatCurrency" parent="none"]
+// CIL[DOC-MACRO purpose="Format number as currency"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert amount to localized currency format"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Use Intl.NumberFormat for currency formatting" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. 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"]
 export function formatCurrency(amount: number, currency = 'USD', locale = 'en-US') {
   return new Intl.NumberFormat(locale, {
     style: 'currency',
     currency,
   }).format(amount)
 }
-
-/**
- * Formats a number using `Intl.NumberFormat` with optional format options.
- * @throws never
- */
+// CIL[END chunk_id="utils_formatcurrency_1783712804"]
+// CIL[BEGIN chunk_id="utils_formatnumber_1783712804" type="function" identity="formatNumber" parent="none"]
+// CIL[DOC-MACRO purpose="Format number with localization"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert number to localized format"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Use Intl.NumberFormat for number formatting" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx, .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 function formatNumber(num: number, options?: Intl.NumberFormatOptions) {
   return new Intl.NumberFormat('en-US', options).format(num)
 }
-
-// ─── STRING UTILITIES ────────────────────────────────────────────────────────────
-
-/**
- * Truncates text to `maxLength` characters, appending `'...'` if truncated.
- * Returns the original string if it fits within `maxLength`.
- * @throws never
- */
+// CIL[END chunk_id="utils_formatnumber_1783712804"]
+// CIL[BEGIN chunk_id="utils_truncatetext_1783712804" type="function" identity="truncateText" parent="none"]
+// CIL[DOC-MACRO purpose="Truncate text to maximum length"]
+// CIL[DOC-RESPONSIBILITY responsibility="Limit text length with ellipsis"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Check length, slice if needed, add ellipsis" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. 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 truncateText(text: string, maxLength: number) {
   if (text.length <= maxLength) return text
   return text.slice(0, maxLength) + '...'
 }
-
-/**
- * Converts text to a URL-friendly slug: lowercased, diacritics stripped,
- * spaces/underscores/hyphens collapsed to single `-`, leading/trailing
- * hyphens removed.
- * @throws never
- */
+// CIL[END chunk_id="utils_truncatetext_1783712804"]
+// CIL[BEGIN chunk_id="utils_generateslug_1783712804" type="function" identity="generateSlug" parent="none"]
+// CIL[DOC-MACRO purpose="Convert text to URL-friendly slug"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create slug from text string"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/table-primitives.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Lowercase, remove special chars, replace spaces, trim" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/table-primitives.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 generateSlug(text: string) {
   return text
     .toLowerCase()
@@ -210,25 +285,39 @@ export function generateSlug(text: string) {
     .replace(/[\s_-]+/g, '-')
     .replace(/^-+|-+$/g, '')
 }
-
-/** Capitalises the first character of a string. @throws never */
+// CIL[END chunk_id="utils_generateslug_1783712804"]
+// CIL[BEGIN chunk_id="utils_capitalize_1783712804" type="function" identity="capitalize" parent="none"]
+// CIL[DOC-MACRO purpose="Capitalize first letter of text"]
+// CIL[DOC-RESPONSIBILITY responsibility="Format text with proper capitalization"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/table-primitives.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Get first char, uppercase, concat with rest" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/table-primitives.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 capitalize(text: string) {
   return text.charAt(0).toUpperCase() + text.slice(1)
 }
-
-// ─── TIMING UTILITIES ────────────────────────────────────────────────────────────
-
-/**
- * Returns a debounced wrapper that delays invoking `func` until `wait` ms
- * after the last call. Resets the timer on each call.
- * @param func - The function to debounce
- * @param wait - Delay in milliseconds
- * @throws never (the wrapper itself never throws; `func` may throw)
- * @example
- * ```ts
- * const search = debounce((q: string) => fetchResults(q), 300)
- * ```
- */
+// CIL[END chunk_id="utils_capitalize_1783712804"]
+// CIL[BEGIN chunk_id="utils_debounce_1783712804" type="function" identity="debounce" parent="none"]
+// CIL[DOC-MACRO purpose="Debounce function calls"]
+// CIL[DOC-RESPONSIBILITY responsibility="Delay function execution until wait period ends"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="(...args: Parameters<T>) => void" errors="none" side_effects="timer_management"]
+// CIL[DOC-MICRO logic_summary="Clear previous timeout, set new timeout for 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: utility. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function debounce<T extends (...args: any[]) => any>(
   func: T,
   wait: number
@@ -239,14 +328,21 @@ export function debounce<T extends (...args: any[]) => any>(
     timeout = setTimeout(() => func(...args), wait)
   }
 }
-
-/**
- * Returns a throttled wrapper that invokes `func` at most once per `limit` ms.
- * Subsequent calls within the window are dropped.
- * @param func - The function to throttle
- * @param limit - Throttle window in milliseconds
- * @throws never
- */
+// CIL[END chunk_id="utils_debounce_1783712804"]
+// CIL[BEGIN chunk_id="utils_throttle_1783712804" type="function" identity="throttle" parent="none"]
+// CIL[DOC-MACRO purpose="Throttle function calls"]
+// CIL[DOC-RESPONSIBILITY responsibility="Limit function execution frequency"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="(...args: Parameters<T>) => void" errors="none" side_effects="timer_management"]
+// CIL[DOC-MICRO logic_summary="Execute immediately, then ignore until limit expires" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function throttle<T extends (...args: any[]) => any>(
   func: T,
   limit: number
@@ -260,10 +356,21 @@ export function throttle<T extends (...args: any[]) => any>(
     }
   }
 }
-
-// ─── VALIDATION & FILE UTILITIES ────────────────────────────────────────────────────
-
-/** Returns true if `url` is a valid absolute URL (any protocol). @throws never */
+// CIL[END chunk_id="utils_throttle_1783712804"]
+// CIL[BEGIN chunk_id="utils_isvalidurl_1783712804" type="function" identity="isValidUrl" parent="none"]
+// CIL[DOC-MACRO purpose="Validate URL string format"]
+// CIL[DOC-RESPONSIBILITY responsibility="Check if string is valid URL"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/RolesPage.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Try URL constructor, return true/false based on success" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, 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"]
 export function isValidUrl(url: string) {
   try {
     new URL(url)
@@ -272,17 +379,39 @@ export function isValidUrl(url: string) {
     return false
   }
 }
-
-/**
- * Extracts the file extension from a filename. Returns an empty string if
- * there is no extension. Works correctly for dotfiles (e.g. `.gitignore` → `''`).
- * @throws never
- */
+// CIL[END chunk_id="utils_isvalidurl_1783712804"]
+// CIL[BEGIN chunk_id="utils_getfileextension_1783712804" type="function" identity="getFileExtension" parent="none"]
+// CIL[DOC-MACRO purpose="Extract file extension from filename"]
+// CIL[DOC-RESPONSIBILITY responsibility="Parse filename to get extension"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Use lastIndexOf and bit tricks for extraction" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. 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 getFileExtension(filename: string) {
   return filename.slice((filename.lastIndexOf('.') - 1 >>> 0) + 2)
 }
-
-/** Generates a random alphanumeric ID of the given length (default 8). @throws never */
+// CIL[END chunk_id="utils_getfileextension_1783712804"]
+// CIL[BEGIN chunk_id="utils_generateid_1783712804" type="function" identity="generateId" parent="none"]
+// CIL[DOC-MACRO purpose="Generate random alphanumeric ID"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create unique identifier string"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="string" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Loop and append random chars from charset" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, .framework/src/pages/admin/TypeDetailPage.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 generateId(length = 8) {
   const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
   let result = ''
@@ -291,15 +420,21 @@ export function generateId(length = 8) {
   }
   return result
 }
-
-// ─── OBJECT UTILITIES ─────────────────────────────────────────────────────────────
-
-/**
- * Recursively deep-clones an object, array, or Date. Primitives and null
- * are returned by value. Does not handle Maps, Sets, or class instances
- * with custom prototypes.
- * @throws never
- */
+// CIL[END chunk_id="utils_generateid_1783712804"]
+// CIL[BEGIN chunk_id="utils_deepclone_1783712804" type="function" identity="deepClone" parent="none"]
+// CIL[DOC-MACRO purpose="Deep clone object recursively"]
+// CIL[DOC-RESPONSIBILITY responsibility="Create independent copy of complex objects"]
+// CIL[DOC-CONTEXT module="utils" layer="utility" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="T" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Handle primitives, dates, arrays, objects recursively" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: utility. 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 deepClone<T>(obj: T): T {
   if (obj === null || typeof obj !== 'object') return obj
   if (obj instanceof Date) return new Date(obj.getTime()) as unknown as T
@@ -315,3 +450,4 @@ export function deepClone<T>(obj: T): T {
   }
   return obj
 }
+// CIL[END chunk_id="utils_deepclone_1783712804"]