spine-framework 0.3.125 → 0.3.127

package/.framework/functions/cil-doc.ts

@@ -0,0 +1,1752 @@
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_module_header_1784235266" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Module header and top-level exports for cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own module-level imports, exports, and configuration for cortex.functions.custom_cil-doc"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="module exports and side effects" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares module scope, imports dependencies, and exports public surface of cortex.functions.custom_cil-doc" 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: function. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .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"]
+
+
+
+
+
+import { createHandler } from './_shared/middleware'
+import { adminDb } from './_shared/db'
+import { update as adminUpdate } from './admin-data'
+import { callOpenAIChat } from './_shared/llm'
+import { FileStatus, FileTreeNode, isSelectedPath, getFileStatus, updateTreeNodeStatus, saveProjectTree } from './_shared/cil'
+import * as fs from 'fs'
+import * as path from 'path'
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_module_header_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_default_model_1784235266" type="variable" identity="default_model" parent="none"]
+// CIL[DOC-MACRO purpose="Defines default_model configuration or state in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value and default configuration for default_model"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="value of default_model" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares default_model with initial value or constant binding used by cortex.functions.custom_cil-doc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/TypeDetailPage.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"]
+const DEFAULT_MODEL = 'gpt-4o-mini'
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_default_model_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_model_prices_1784235266" type="variable" identity="model_prices" parent="none"]
+// CIL[DOC-MACRO purpose="Defines model_prices configuration or state in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value and default configuration for model_prices"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="value of model_prices" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares model_prices with initial value or constant binding used by cortex.functions.custom_cil-doc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/TypeDetailPage.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"]
+const MODEL_PRICES: Record<string, { input_per_1m: number; output_per_1m: number }> = {
+  'gpt-4o-mini':   { input_per_1m: 0.15,  output_per_1m: 0.60  },
+  'gpt-4o':        { input_per_1m: 2.50,  output_per_1m: 10.00 },
+  'gpt-4-turbo':   { input_per_1m: 10.00, output_per_1m: 30.00 },
+  'gpt-3.5-turbo': { input_per_1m: 0.50,  output_per_1m: 1.50  },
+}
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_model_prices_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_estimated_output_tokens_per_chunk_1784235266" type="variable" identity="estimated_output_tokens_per_chunk" parent="none"]
+// CIL[DOC-MACRO purpose="Defines estimated_output_tokens_per_chunk configuration or state in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value and default configuration for estimated_output_tokens_per_chunk"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="value of estimated_output_tokens_per_chunk" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares estimated_output_tokens_per_chunk with initial value or constant binding used by cortex.functions.custom_cil-doc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/TypeDetailPage.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"]
+const ESTIMATED_OUTPUT_TOKENS_PER_CHUNK = 200
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_estimated_output_tokens_per_chunk_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_system_prompt_overhead_tokens_1784235266" type="variable" identity="system_prompt_overhead_tokens" parent="none"]
+// CIL[DOC-MACRO purpose="Defines system_prompt_overhead_tokens configuration or state in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value and default configuration for system_prompt_overhead_tokens"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="value of system_prompt_overhead_tokens" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares system_prompt_overhead_tokens with initial value or constant binding used by cortex.functions.custom_cil-doc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/TypeDetailPage.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"]
+const SYSTEM_PROMPT_OVERHEAD_TOKENS = 350
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_system_prompt_overhead_tokens_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_estimatetokens_1784235266" type="function" identity="estimatetokens" parent="none"]
+// CIL[DOC-MACRO purpose="Implements estimatetokens logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute estimatetokens and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides estimatetokens with estimateTokens(text: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4)
+}
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_estimatetokens_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_needsdocumentation_1784235266" type="function" identity="needsdocumentation" parent="none"]
+// CIL[DOC-MACRO purpose="Implements needsdocumentation logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute needsdocumentation and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides needsdocumentation with needsDocumentation(chunk: any inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function needsDocumentation(chunk: any): boolean {
+  const d = chunk.data || {}
+  
+  if (d.doc_validation_errors && d.doc_validation_errors.length > 0) return true
+  
+  
+  
+  const required = d.chunk_type === 'module_header'
+    ? REQUIRED_MODULE_FIELDS
+    : REQUIRED_CHUNK_FIELDS
+  return required.some(f => !d[f] || String(d[f]).trim() === '')
+}
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_needsdocumentation_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_loadallchunks_1784235266" type="function" identity="loadallchunks" parent="none"]
+// CIL[DOC-MACRO purpose="Implements loadallchunks logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute loadallchunks and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides loadallchunks with loadAllChunks(projectId: string, filePath?: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+async function loadAllChunks(projectId: string, filePath?: string): Promise<any[]> {
+  const PAGE = 1000
+  const all: any[] = []
+  for (let offset = 0; ; offset += PAGE) {
+    let q = adminDb
+      .from('items')
+      .select('id, title, data')
+      .filter('data->>kb_type', 'eq', 'cil_chunk')
+      .filter('data->>project_id', 'eq', projectId)
+      .eq('is_active', true)
+      .order('id')
+      .range(offset, offset + PAGE - 1)
+    if (filePath) q = q.filter('data->>file_path', 'eq', filePath)
+    const { data, error } = await q
+    if (error) throw new Error(`Failed to load chunks: ${error.message}`)
+    if (!data || data.length === 0) break
+    all.push(...data)
+    if (data.length < PAGE) break
+  }
+  return all
+}
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_loadallchunks_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_loadpendingchunks_1784235266" type="function" identity="loadpendingchunks" parent="none"]
+// CIL[DOC-MACRO purpose="Implements loadpendingchunks logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute loadpendingchunks and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides loadpendingchunks with loadPendingChunks(projectId: string, selectedPaths: string[], requiredStatus: FileStatus inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+async function loadPendingChunks(projectId: string, selectedPaths: string[], requiredStatus: FileStatus): Promise<any[]> {
+  const { data: fileItems } = await adminDb
+    .from('items')
+    .select('id, data')
+    .filter('data->>kb_type', 'eq', 'cil_file')
+    .filter('data->>project_id', 'eq', projectId)
+    .eq('is_active', true)
+
+  const selectedFileIds = (fileItems || [])
+    .filter((f: any) => getFileStatus(f) === requiredStatus && isSelectedPath(f.data?.file_path || f.title, selectedPaths))
+    .map((f: any) => f.id)
+
+  if (selectedFileIds.length === 0) return []
+
+  const { data: allChunks } = await adminDb
+    .from('items')
+    .select('id, title, data')
+    .filter('data->>kb_type', 'eq', 'cil_chunk')
+    .filter('data->>project_id', 'eq', projectId)
+    .eq('is_active', true)
+
+  return (allChunks || []).filter((c: any) => selectedFileIds.includes(c.data?.file_id))
+}
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_loadpendingchunks_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_maybeadvancefiletopass3_1784235266" type="function" identity="maybeadvancefiletopass3" parent="none"]
+// CIL[DOC-MACRO purpose="Implements maybeadvancefiletopass3 logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute maybeadvancefiletopass3 and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides maybeadvancefiletopass3 with maybeAdvanceFileToPass3(ctx: any, fileId: string, tree: FileTreeNode | null inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+async function maybeAdvanceFileToPass3(ctx: any, fileId: string, tree: FileTreeNode | null): Promise<void> {
+  const { data: fileChunks } = await adminDb
+    .from('items')
+    .select('id, title, data')
+    .filter('data->>kb_type', 'eq', 'cil_chunk')
+    .filter('data->>file_id', 'eq', fileId)
+    .eq('is_active', true)
+
+  const allDocumented = (fileChunks || []).every(c => !needsDocumentation(c))
+  if (!allDocumented) return
+
+  const { data: fileItem } = await adminDb
+    .from('items')
+    .select('id, data')
+    .eq('id', fileId)
+    .maybeSingle()
+
+  if (!fileItem) return
+
+  const updateCtx = { ...ctx, query: { ...(ctx.query || {}), entity: 'items', id: fileId } }
+  await adminUpdate(updateCtx, {
+    data: {
+      ...fileItem.data,
+      status: 'pass3_complete',
+      last_status_at: new Date().toISOString(),
+    },
+  }).catch((e: any) => console.error('advance to pass3 failed:', e.message))
+
+  if (tree) updateTreeNodeStatus(tree, fileId, 'pass3_complete')
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_maybeadvancefiletopass3_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_required_module_fields_1784235266" type="variable" identity="required_module_fields" parent="none"]
+// CIL[DOC-MACRO purpose="Defines required_module_fields configuration or state in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value and default configuration for required_module_fields"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="value of required_module_fields" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares required_module_fields with initial value or constant binding used by cortex.functions.custom_cil-doc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+const REQUIRED_MODULE_FIELDS = ['module', 'audience', 'layer', 'stability', 'description']
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_required_module_fields_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_required_chunk_fields_1784235266" type="variable" identity="required_chunk_fields" parent="none"]
+// CIL[DOC-MACRO purpose="Defines required_chunk_fields configuration or state in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value and default configuration for required_chunk_fields"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="value of required_chunk_fields" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares required_chunk_fields with initial value or constant binding used by cortex.functions.custom_cil-doc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+const REQUIRED_CHUNK_FIELDS = ['description', 'input_spec', 'output_spec', 'side_effects', 'stability']
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_required_chunk_fields_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_modulenamefrompath_1784235266" type="function" identity="modulenamefrompath" parent="none"]
+// CIL[DOC-MACRO purpose="Implements modulenamefrompath logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute modulenamefrompath and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides modulenamefrompath with moduleNameFromPath(relPath: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function moduleNameFromPath(relPath: string): string {
+  return path.basename(relPath, path.extname(relPath))
+}
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_modulenamefrompath_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_buildjsdoc_1784235266" type="function" identity="buildjsdoc" parent="none"]
+// CIL[DOC-MACRO purpose="Implements buildjsdoc logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute buildjsdoc and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides buildjsdoc with buildJsDoc(chunk: any inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function buildJsDoc(chunk: any): string {
+  const d = chunk.data || {}
+  const isModuleHeader = d.chunk_type === 'module_header'
+  const description = (d.description || d.macro || '').trim()
+  if (!description) return ''
+
+  
+  if (isModuleHeader) {
+    const body: string[] = []
+    if (d.module)   body.push(`@module   ${d.module}`)
+    if (d.audience) body.push(`@audience ${d.audience}`)
+    if (d.layer)    body.push(`@layer    ${d.layer}`)
+    if (d.stability)body.push(`@stability ${d.stability}`)
+
+    
+    
+    const descLines = description.split('\n')
+
+    
+    const seeAlsoRefs = d.see_also
+      ? d.see_also.split(/\n/).map((s: string) => s.trim()).filter(Boolean)
+      : []
+
+    const docLines = [
+      '/**',
+      ...body.map(l => ` * ${l}`),
+      ' *',
+      ...descLines.map(l => ` * ${l}`),
+      ...(seeAlsoRefs.length > 0 ? [' *'] : []),
+      ...seeAlsoRefs.map(ref => ` * @seeAlso ${ref}`),
+      ' *',
+      ' * @cil-generated',
+      ' */',
+    ]
+    return docLines.join('\n')
+  }
+
+  
+  const body: string[] = []
+
+  const chunkKind = d.chunk_type || ''
+  const isTypeDecl = ['interface', 'type', 'enum'].includes(chunkKind)
+  const isConstant = chunkKind === 'constant'
+  const isCallableChunk = !isTypeDecl && !isConstant
+
+  
+  
+  
+  const macro = (d.macro || '').trim()
+  const micro = (d.micro || '').trim()
+  if (!isTypeDecl && !isConstant) {
+    const descNorm = description.toLowerCase().replace(/\s+/g, ' ')
+    const macroNorm = macro.toLowerCase().replace(/\s+/g, ' ')
+    const macroDistinct = macro && macroNorm !== descNorm && !descNorm.includes(macroNorm.slice(0, 40))
+    const microDistinct = micro && micro !== description && micro !== macro
+    if (macroDistinct) body.push(`@macro       ${macro}`)
+    if (macroDistinct && microDistinct) body.push(`@micro       ${micro}`)
+  }
+
+  
+  if (isCallableChunk && d.input_spec) {
+    const entries = d.input_spec.split(/\n/).map((s: string) => s.trim()).filter(Boolean)
+    if (entries.length === 1 && entries[0].toLowerCase() === 'none') {
+    } else {
+      body.push('@inputSpec')
+      for (const entry of entries) body.push(`  ${entry}`)
+    }
+  }
+
+  
+  
+  if (isCallableChunk && d.output_spec) body.push(`@outputSpec  ${d.output_spec}`)
+
+  
+  const throwsVal = (d.throws || '').trim()
+  if (throwsVal && throwsVal.toLowerCase() !== 'none') body.push(`@throws      ${throwsVal}`)
+
+  
+  if (d.side_effects) body.push(`@sideEffects ${d.side_effects}`)
+
+  
+  if (d.stability) body.push(`@stability   ${d.stability}`)
+
+  
+  
+  const callsVal = (d.calls || '').trim()
+  if (callsVal && callsVal.toLowerCase() !== 'unknown' && callsVal.toLowerCase() !== 'none') {
+    body.push(`@calls       ${callsVal}`)
+  }
+
+  
+  
+  
+  const ehVal = (d.error_handling || '').trim()
+  const ehNoise = /^throws( on (unhandled|unexpected) errors?)?$/i.test(ehVal)
+  if (ehVal && !ehNoise) body.push(`@errorHandling ${ehVal}`)
+
+  
+  
+
+  body.push('@cil-generated')
+
+  const docLines = [
+    '/**',
+    ` * ${description}`,
+    ...(body.length > 0 ? [' *'] : []),
+    ...body.map(l => ` * ${l}`),
+    ' */',
+  ]
+  return docLines.join('\n')
+}
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_buildjsdoc_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_validatechunkdocs_1784235266" type="function" identity="validatechunkdocs" parent="none"]
+// CIL[DOC-MACRO purpose="Implements validatechunkdocs logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute validatechunkdocs and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides validatechunkdocs with validateChunkDocs(chunk: any inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function validateChunkDocs(chunk: any): string[] {
+  const d = chunk.data || {}
+  const errors: string[] = []
+  const isModuleHeader = d.chunk_type === 'module_header'
+
+  const required = isModuleHeader ? REQUIRED_MODULE_FIELDS : REQUIRED_CHUNK_FIELDS
+  for (const field of required) {
+    if (!d[field] || String(d[field]).trim() === '') {
+      errors.push(`missing ${field}`)
+    }
+  }
+
+  if (!isModuleHeader && d.input_spec && d.input_spec !== 'none') {
+    const params = d.input_spec.split(/\n/).map((s: string) => s.trim()).filter(Boolean)
+    const paramNames = params.map(p => {
+      const m = p.match(/^[-\s]*([a-zA-Z0-9_]+)/)
+      return m ? m[1] : ''
+    }).filter(Boolean)
+
+    const code = d.code_content || ''
+    const signatureMatch = code.match(/(?:function|const|let|var)\s+\w+\s*\(([^)]*)\)/)
+    if (signatureMatch) {
+      const rawParams = signatureMatch[1]
+      const declaredNames = rawParams
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => s)
+        .map(s => s.split(/[:=]/)[0].trim().replace(/\?/, ''))
+        .filter(Boolean)
+      for (const declared of declaredNames) {
+        if (!paramNames.includes(declared)) {
+          errors.push(`undocumented parameter: ${declared}`)
+        }
+      }
+    }
+  }
+
+  return errors
+}
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_validatechunkdocs_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_findexistingciljsdoc_1784235266" type="function" identity="findexistingciljsdoc" parent="none"]
+// CIL[DOC-MACRO purpose="Implements findexistingciljsdoc logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute findexistingciljsdoc and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides findexistingciljsdoc with findExistingCilJsDoc(lines: string[], markerIdx: number inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function findExistingCilJsDoc(lines: string[], markerIdx: number): { start: number; end: number } | null {
+  let startIdx = -1
+  for (let i = markerIdx + 1; i < lines.length; i++) {
+    const trimmed = lines[i].trim()
+    if (trimmed === '') continue
+    if (trimmed.startsWith('/**')) { startIdx = i; break }
+    break
+  }
+  if (startIdx === -1) return null
+
+  let endIdx = -1
+  let hasCilTag = false
+  for (let i = startIdx; i < lines.length; i++) {
+    const trimmed = lines[i].trim()
+    if (trimmed.includes('@cil-generated')) hasCilTag = true
+    if (trimmed === '*/' || trimmed.endsWith('*/')) { endIdx = i; break }
+  }
+  if (endIdx === -1 || !hasCilTag) return null
+  return { start: startIdx, end: endIdx }
+}
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_findexistingciljsdoc_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_findlegacyciljsdocabove_1784235266" type="function" identity="findlegacyciljsdocabove" parent="none"]
+// CIL[DOC-MACRO purpose="Implements findlegacyciljsdocabove logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute findlegacyciljsdocabove and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides findlegacyciljsdocabove with findLegacyCilJsDocAbove(lines: string[], markerIdx: number inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function findLegacyCilJsDocAbove(lines: string[], markerIdx: number): { start: number; end: number } | null {
+  let endIdx = -1
+  for (let i = markerIdx - 1; i >= 0; i--) {
+    const trimmed = lines[i].trim()
+    if (trimmed === '') continue
+    if (trimmed === '*/' || trimmed.endsWith('*/')) { endIdx = i; break }
+    break
+  }
+  if (endIdx === -1) return null
+
+  let startIdx = -1
+  let hasCilTag = false
+  for (let i = endIdx; i >= 0; i--) {
+    const trimmed = lines[i].trim()
+    if (trimmed.includes('@cil-generated')) hasCilTag = true
+    if (trimmed.startsWith('/**')) { startIdx = i; break }
+  }
+  if (startIdx === -1 || !hasCilTag) return null
+
+  return { start: startIdx, end: endIdx }
+}
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_findlegacyciljsdocabove_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_writejsdoctosource_1784235266" type="function" identity="writejsdoctosource" parent="none"]
+// CIL[DOC-MACRO purpose="Implements writejsdoctosource logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute writejsdoctosource and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides writejsdoctosource with writeJsDocToSource(chunk: any, repoPath: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function writeJsDocToSource(chunk: any, repoPath: string): void {
+  const d = chunk.data || {}
+  const relPath = d.file_path
+  if (!repoPath || !relPath) return
+
+  const ext = path.extname(relPath).toLowerCase()
+  if (!['.ts', '.tsx', '.js', '.jsx'].includes(ext)) return
+
+  const jsDoc = buildJsDoc(chunk)
+  if (!jsDoc) return
+
+  const absPath = path.join(repoPath, relPath)
+  if (!fs.existsSync(absPath)) return
+
+  const content = fs.readFileSync(absPath, 'utf-8')
+  const lines = content.split('\n')
+
+  const markerMap = findChunkStartMarkers(lines)
+  let markerIdx = markerMap.get((d.chunk_name || chunk.title).trim().toLowerCase())
+  if (markerIdx === undefined) return
+
+  const newLines = [...lines]
+
+  
+  const legacyAbove = findLegacyCilJsDocAbove(newLines, markerIdx)
+  if (legacyAbove) {
+    newLines.splice(legacyAbove.start, legacyAbove.end - legacyAbove.start + 1)
+    
+    markerIdx -= (legacyAbove.end - legacyAbove.start + 1)
+  }
+
+  const existing = findExistingCilJsDoc(newLines, markerIdx)
+  if (existing) {
+    newLines.splice(existing.start, existing.end - existing.start + 1, jsDoc)
+  } else {
+    newLines.splice(markerIdx + 1, 0, jsDoc)
+  }
+
+  fs.writeFileSync(absPath, newLines.join('\n'), 'utf-8')
+}
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_writejsdoctosource_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_escaperegexp_1784235266" type="function" identity="escaperegexp" parent="none"]
+// CIL[DOC-MACRO purpose="Implements escaperegexp logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute escaperegexp and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides escaperegexp with escapeRegExp(s: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_escaperegexp_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_chunk_start_marker_re_1784235266" type="variable" identity="chunk_start_marker_re" parent="none"]
+// CIL[DOC-MACRO purpose="Defines chunk_start_marker_re configuration or state in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value and default configuration for chunk_start_marker_re"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="value of chunk_start_marker_re" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares chunk_start_marker_re with initial value or constant binding used by cortex.functions.custom_cil-doc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+const CHUNK_START_MARKER_RE = /^\s*\/\*\*\s*[─\-]+\s*CHUNK_START:\s*(?:PROPOSAL\s+|REJECTED\s+)?(.+?)\s*[─\-]*\s*\*\/\s*$/
+
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_chunk_start_marker_re_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_findchunkstartmarkers_1784235266" type="function" identity="findchunkstartmarkers" parent="none"]
+// CIL[DOC-MACRO purpose="Implements findchunkstartmarkers logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute findchunkstartmarkers and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides findchunkstartmarkers with findChunkStartMarkers(lines: string[] inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function findChunkStartMarkers(lines: string[]): Map<string, number> {
+  const map = new Map<string, number>()
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(CHUNK_START_MARKER_RE)
+    if (m) {
+      const name = m[1].trim().toLowerCase()
+      if (!map.has(name)) map.set(name, i)
+    }
+  }
+  return map
+}
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_findchunkstartmarkers_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_builddocprompt_1784235266" type="function" identity="builddocprompt" parent="none"]
+// CIL[DOC-MACRO purpose="Implements builddocprompt logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute builddocprompt and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides builddocprompt with buildDocPrompt(chunk: any inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function buildDocPrompt(chunk: any): string {
+  const d = chunk.data || {}
+  const code = (d.code_content || '').slice(0, 3000)
+  const isModuleHeader = d.chunk_type === 'module_header'
+  return isModuleHeader ? buildModuleHeaderPrompt(d, code) : buildChunkPrompt(d, code)
+}
+
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_builddocprompt_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_buildmoduleheaderprompt_1784235266" type="function" identity="buildmoduleheaderprompt" parent="none"]
+// CIL[DOC-MACRO purpose="Implements buildmoduleheaderprompt logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute buildmoduleheaderprompt and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides buildmoduleheaderprompt with buildModuleHeaderPrompt(d: any, code: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function buildModuleHeaderPrompt(d: any, code: string): string {
+  const filePath = d.file_path || 'unknown'
+  return `You are documenting the MODULE HEADER for file: ${filePath}
+
+This is the top of the file — imports, constants, and module-level setup.
+
+\`\`\`typescript
+${code}
+\`\`\`
+
+Generate a file-level JSDoc block. Your job is to orient a developer to this module
+in 10 seconds — what it does, how it is entered, and what depends on it.
+
+Rules:
+- description: 2–4 sentences covering what the module does, its role in the system,
+  and any key architectural constraints. If this is an API handler, include the
+  route pattern(s). If it has a multi-step pipeline (auth → validate → execute),
+  number the steps. If there are non-obvious invariants (things that must always be
+  true for callers), prefix them with INVARIANT:.
+- seeAlso: 2–4 direct dependencies a reader needs to understand this module.
+  Format each as: filename (reason it matters). Omit obvious/trivial imports.
+- Do NOT list every import. Do NOT describe individual functions (those get their own docs).
+
+Respond ONLY with a JSON object (no markdown, no commentary):
+{
+  "description": "<2-4 sentences + optional route table + optional numbered flow + optional INVARIANT lines, all as a single string with \\n between paragraphs>",
+  "module": "<filename without extension>",
+  "audience": "<internal | external | both>",
+  "layer": "<shared-core | app-specific | infrastructure | test>",
+  "stability": "<stable | experimental | deprecated>",
+  "seeAlso": "<newline-separated list: filename (reason). 2-4 entries max. Empty string if no meaningful cross-references.>",
+  "tags": "<comma-separated relevant tags>"
+}`
+}
+
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_buildmoduleheaderprompt_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_buildchunkprompt_1784235266" type="function" identity="buildchunkprompt" parent="none"]
+// CIL[DOC-MACRO purpose="Implements buildchunkprompt logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute buildchunkprompt and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides buildchunkprompt with buildChunkPrompt(d: any, code: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function buildChunkPrompt(d: any, code: string): string {
+  const chunkType = d.chunk_type || 'function'
+  const chunkName = d.chunk_name || 'unknown'
+  const location = `${d.file_path || 'unknown'}:${d.line_start || 0}-${d.line_end || 0}`
+
+  return `You are documenting a ${chunkType} named "${chunkName}" at ${location}.
+
+\`\`\`typescript
+${code}
+\`\`\`
+
+Rules:
+- description: 1–2 sentences — what it does and why it exists in this module.
+  Do NOT start with "It achieves this by". Write it as a direct statement.
+- macro: one sentence classifying WHAT this chunk IS and its primary responsibility.
+  Only write this if it adds information that description does not already convey.
+  Example: "Async resolver that maps an HTTP request to a typed Principal object."
+  If it would be the same sentence as description, return "".
+- micro: one sentence on the SPECIFIC implementation mechanism — the algorithm,
+  branching strategy, data structure, or key external call pattern used.
+  Must be distinct from macro. If not meaningfully distinct, return "".
+  Example: "Checks headers in priority order (API key → cron → trigger → JWT),
+  delegating to a type-specific sub-resolver for each."
+- inputSpec: one line per parameter: - name: Type (required|optional[|nullable]) — description.
+  Be precise about types (string, UUID, timestamp, not just "string").
+  Note enums if the field has a fixed value set.
+  Write "none" if the function takes no parameters.
+- outputSpec: exact return type including Promise<T> if async. Add a brief shape
+  description if the return value is non-obvious.
+- throws: only list errors the function explicitly throws that callers must handle.
+  Write "none" if the function never throws.
+- side_effects: concrete observable effects (DB writes, RPC calls, file I/O,
+  external API calls). Write "none" if the function is pure.
+- stability: stable | experimental | deprecated
+- calls: comma-separated list of KEY named functions or external services this chunk
+  calls. Write the function name or service name only — not method chains.
+  BAD: "adminDb.from, adminDb.select, adminDb.eq, adminDb.single" (these are chained
+       builder methods on one call — write "adminDb.from('schedules')" instead)
+  GOOD: "adminDb.rpc('validate_machine_principal'), getClientIp"
+  GOOD: "supabase.auth.getUser, adminDb.from('people')"
+  Omit: String methods, Array methods, standard library, trivial getters.
+  Write "none" if no significant external callees.
+- errorHandling: only write this if the error handling strategy is non-obvious —
+  e.g. "returns ANONYMOUS_PRINCIPAL on auth failure rather than throwing".
+  Write "" if it simply throws or returns null on error.
+- calledBy: your best guess at likely callers or entry points. For RAG use only.
+- complexity: simple | moderate | complex
+- tags: comma-separated relevant tags
+
+Respond ONLY with a JSON object (no markdown, no commentary):
+{
+  "description": "<1-2 direct sentences>",
+  "macro": "<classification sentence, or empty string>",
+  "micro": "<mechanism sentence distinct from macro, or empty string>",
+  "inputSpec": "<newline-separated param lines, or 'none'>",
+  "outputSpec": "<return type and shape>",
+  "throws": "<ErrorType — condition, or 'none'>",
+  "side_effects": "<effects or 'none'>",
+  "stability": "<stable | experimental | deprecated>",
+  "calls": "<key callees or 'none'>",
+  "errorHandling": "<non-obvious strategy or empty string>",
+  "calledBy": "<likely callers or 'unknown'>",
+  "complexity": "<simple | moderate | complex>",
+  "tags": "<comma-separated tags>"
+}`
+}
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_buildchunkprompt_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_callllm_1784235266" type="function" identity="callllm" parent="none"]
+// CIL[DOC-MACRO purpose="Implements callllm logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute callllm and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides callllm with callLLM(prompt: string, model: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+async function callLLM(prompt: string, model: string): Promise<string> {
+  const j = await callOpenAIChat(undefined, [
+    {
+      role: 'system',
+      content: 'You are a code documentation assistant. You extract structured contracts from source code. Always respond with valid JSON only.',
+    },
+    { role: 'user', content: prompt },
+  ], model, {
+    temperature: 0.2,
+    max_tokens: 800,
+    response_format: { type: 'json_object' }
+  })
+  return j.choices?.[0]?.message?.content?.trim() || '{}'
+}
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_callllm_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_parsedocresponse_1784235266" type="function" identity="parsedocresponse" parent="none"]
+// CIL[DOC-MACRO purpose="Implements parsedocresponse logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute parsedocresponse and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides parsedocresponse with parseDocResponse(raw: string inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function parseDocResponse(raw: string): Record<string, string> {
+  try {
+    
+    let cleaned = raw.trim()
+    if (cleaned.startsWith('```')) {
+      cleaned = cleaned.replace(/^```[a-zA-Z0-9]*\n?/, '').replace(/\n?```$/, '').trim()
+    }
+    const parsed = JSON.parse(cleaned)
+    return {
+      description: String(parsed.description || parsed.macro || '').slice(0, 1000),
+      macro:       String(parsed.macro       || '').slice(0, 500),
+      micro:       String(parsed.micro       || '').slice(0, 500),
+      input_spec:  String(parsed.inputSpec   || parsed.input_spec  || '').slice(0, 2000),
+      output_spec: String(parsed.outputSpec  || parsed.output_spec || '').slice(0, 500),
+      throws:      String(parsed.throws      || '').slice(0, 500),
+      side_effects:String(parsed.sideEffects || parsed.side_effects|| '').slice(0, 500),
+      stability:   ['stable', 'internal', 'experimental', 'deprecated'].includes(parsed.stability)
+        ? parsed.stability : 'internal',
+      called_by:   String(parsed.calledBy    || parsed.called_by  || '').slice(0, 500),
+      calls:       String(parsed.calls        || '').slice(0, 500),
+      tags:        String(parsed.tags          || '').slice(0, 500),
+      complexity:  ['simple', 'moderate', 'complex'].includes(parsed.complexity)
+        ? parsed.complexity : 'moderate',
+      error_handling: String(parsed.errorHandling || parsed.error_handling || '').slice(0, 500),
+      module:      String(parsed.module        || '').slice(0, 100),
+      audience:    ['internal', 'external', 'both'].includes(parsed.audience)
+        ? parsed.audience : 'both',
+      layer:       ['shared-core', 'app-specific', 'infrastructure', 'test'].includes(parsed.layer)
+        ? parsed.layer : 'app-specific',
+      see_also:    String(parsed.seeAlso       || parsed.see_also    || '').slice(0, 1000),
+    }
+  } catch {
+    return {}
+  }
+}
+
+
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_parsedocresponse_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_hasmeaningfulllmfields_1784235266" type="function" identity="hasmeaningfulllmfields" parent="none"]
+// CIL[DOC-MACRO purpose="Implements hasmeaningfulllmfields logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute hasmeaningfulllmfields and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides hasmeaningfulllmfields with hasMeaningfulLlmFields(fields: Record<string, string> inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function hasMeaningfulLlmFields(fields: Record<string, string>): boolean {
+  const meaningfulKeys = ['description', 'macro', 'micro', 'input_spec', 'output_spec']
+  return meaningfulKeys.some(k => (fields[k] || '').trim() !== '')
+}
+
+
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_hasmeaningfulllmfields_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_normalizedocfields_1784235266" type="function" identity="normalizedocfields" parent="none"]
+// CIL[DOC-MACRO purpose="Implements normalizedocfields logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute normalizedocfields and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides normalizedocfields with normalizeDocFields(fields: Record<string, string>, chunk: any inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+function normalizeDocFields(fields: Record<string, string>, chunk: any): Record<string, string> {
+  const d = chunk.data || {}
+  const isModuleHeader = d.chunk_type === 'module_header'
+  const code = d.code_content || ''
+  const chunkName = d.chunk_name || chunk.title || ''
+  const layer = d.layer || (isModuleHeader ? 'shared-core' : 'app-specific')
+
+  const normalized = { ...fields }
+
+  if (isModuleHeader) {
+    if (!normalized.module) normalized.module = moduleNameFromPath(d.file_path || chunkName)
+    if (!normalized.audience) normalized.audience = 'both'
+    if (!normalized.layer) normalized.layer = layer
+    if (!normalized.description) normalized.description = normalized.macro || `${chunkName} module setup and imports.`
+    if (!normalized.stability) normalized.stability = 'stable'
+    if (!normalized.see_also) normalized.see_also = ''
+  } else {
+    const chunkType = d.chunk_type || 'symbol'
+    const isCallable = !['interface', 'type', 'enum', 'constant'].includes(chunkType)
+
+    if (!normalized.description) normalized.description = normalized.macro || `${chunkName} ${chunkType}.`
+
+    
+    
+    
+    const macroFromLlm = fields.macro  
+    const microFromLlm = fields.micro
+    if (macroFromLlm === undefined || macroFromLlm === null) {
+      normalized.macro = normalized.description.split(/(?<=[.!?])\s+/)[0] || normalized.description
+    }
+    if (microFromLlm === undefined || microFromLlm === null) {
+      normalized.micro = ''  
+    }
+
+    
+    
+    if (!normalized.input_spec) {
+      if (isCallable) {
+        const sigMatch = code.match(/(?:function|const|let|var)\s+\w+\s*\(([^)]*)\)|(?:async\s+)?function\s*\(([^)]*)\)/)
+        const paramStr = sigMatch?.[1] || sigMatch?.[2] || ''
+        const params = paramStr.split(',').map(s => s.trim()).filter(Boolean).map(p => {
+          const [name, type] = p.split(/[:=]/).map(s => s.trim())
+          const optional = p.includes('?')
+          return `- ${name.replace(/\?$/, '')}: ${type || 'any'} (${optional ? 'optional' : 'required'})`
+        })
+        normalized.input_spec = params.length ? params.join('\n') : 'none'
+      } else {
+        normalized.input_spec = 'none'
+      }
+    }
+
+    
+    if (!normalized.output_spec) {
+      if (!isCallable) {
+        normalized.output_spec = chunkName  
+      } else {
+        
+        const returnMatch = code.match(/\)\s*:\s*(Promise<[^>]+>|[A-Za-z0-9_<>|[\]{}?\s]+)\s*(?:\{|=>)/)
+        normalized.output_spec = returnMatch ? returnMatch[1].trim() : 'void'
+      }
+    }
+
+    if (!normalized.side_effects) normalized.side_effects = 'none'
+    if (!normalized.stability) normalized.stability = 'stable'
+    if (!normalized.tags) normalized.tags = chunkType
+    if (!normalized.complexity) normalized.complexity = 'moderate'
+    if (!normalized.error_handling) normalized.error_handling = ''
+    if (!normalized.called_by) normalized.called_by = 'unknown'
+    if (!normalized.calls) normalized.calls = 'unknown'
+  }
+
+  return normalized
+}
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_normalizedocfields_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_documentchunk_1784235266" type="function" identity="documentchunk" parent="none"]
+// CIL[DOC-MACRO purpose="Implements documentchunk logic in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute documentchunk and return its computed result"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return value from function execution" errors="throws on invalid input or runtime failure" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Provides documentchunk with documentChunk( inputs, handling internal flow and returning a result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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"]
+async function documentChunk(
+  ctx: any,
+  chunk: any,
+  model: string,
+  force: boolean,
+  repoPath?: string
+): Promise<{ success: boolean; fields_set: string[]; error?: string; skipped?: boolean; updatedChunk?: any; validation_errors?: string[] }> {
+  if (!force && !needsDocumentation(chunk)) {
+    return { success: true, fields_set: [], skipped: true, updatedChunk: chunk }
+  }
+
+  const d = chunk.data || {}
+  if (!d.code_content && !d.chunk_name) {
+    return { success: false, fields_set: [], error: 'No code content to document' }
+  }
+
+  const prompt = buildDocPrompt(chunk)
+
+  let raw: string
+  try {
+    raw = await callLLM(prompt, model)
+  } catch (err) {
+    return { success: false, fields_set: [], error: err instanceof Error ? err.message : String(err) }
+  }
+
+  const rawFields = parseDocResponse(raw)
+  const hadLlmFields = hasMeaningfulLlmFields(rawFields)
+
+  
+  
+  
+  const fields = normalizeDocFields(rawFields, chunk)
+
+  
+  const toWrite: Record<string, string> = {}
+  for (const [k, v] of Object.entries(fields)) {
+    if (force || !d[k]) toWrite[k] = v
+  }
+
+  if (!Object.keys(toWrite).length) {
+    return { success: true, fields_set: [], skipped: true, updatedChunk: chunk }
+  }
+
+  const updatedData = { ...d, ...toWrite, doc_confidence: 'ai_generated', doc_fallback: !hadLlmFields }
+  const updatedChunk = { ...chunk, data: updatedData }
+
+  
+  const validationErrors = validateChunkDocs(updatedChunk)
+  if (validationErrors.length > 0) {
+    return { success: false, fields_set: [], error: `Validation failed: ${validationErrors.join(', ')}`, validation_errors: validationErrors, updatedChunk }
+  }
+
+  const updateCtx = { ...ctx, query: { ...ctx.query, entity: 'items', id: chunk.id } }
+  try {
+    await adminUpdate(updateCtx, { data: updatedData })
+  } catch (updateError: any) {
+    return { success: false, fields_set: [], error: updateError.message }
+  }
+
+  
+  if (repoPath) {
+    writeJsDocToSource(updatedChunk, repoPath)
+  }
+
+  return { success: true, fields_set: Object.keys(toWrite), updatedChunk }
+}
+
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_documentchunk_1784235266"]
+// CIL[BEGIN chunk_id="custom_apps_cortex_functions_custom_cil_doc_handler_1784235266" type="variable" identity="handler" parent="none"]
+// CIL[DOC-MACRO purpose="Defines handler configuration or state in cortex.functions.custom_cil-doc"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hold the value and default configuration for handler"]
+// CIL[DOC-CONTEXT module="cortex.functions.custom_cil-doc" layer="function" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="value of handler" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares handler with initial value or constant binding used by cortex.functions.custom_cil-doc" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: function. 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 const handler = createHandler(async (ctx, body) => {
+  const action = ctx.query?.action
+
+  
+  if (action === 'gap_report') {
+    const projectId = ctx.query?.project_id || body?.project_id
+    if (!projectId) throw new Error('project_id is required')
+
+    const chunks = await loadAllChunks(projectId)
+
+    const undocumented = chunks.filter(needsDocumentation)
+    const documented   = chunks.filter(c => !needsDocumentation(c))
+    const aiGenerated  = documented.filter(c => c.data?.doc_confidence === 'ai_generated')
+    const humanVerified= documented.filter(c => c.data?.doc_confidence === 'human_verified')
+
+    return {
+      project_id: projectId,
+      total_chunks: chunks.length,
+      undocumented_count: undocumented.length,
+      documented_count: documented.length,
+      ai_generated_count: aiGenerated.length,
+      human_verified_count: humanVerified.length,
+      coverage_pct: chunks.length
+        ? Math.round((documented.length / chunks.length) * 100) : 0,
+      undocumented: undocumented.slice(0, 100).map(c => ({
+        id: c.id,
+        chunk_name: c.data?.chunk_name || c.title,
+        file_path: c.data?.file_path || '',
+        chunk_type: c.data?.chunk_type || '',
+        line_count: (c.data?.line_end || 0) - (c.data?.line_start || 0) + 1,
+        token_count: c.data?.token_count || 0,
+      })),
+    }
+  }
+
+  
+  if (action === 'estimate') {
+    const projectId = ctx.query?.project_id || body?.project_id
+    const model = ctx.query?.model || body?.model || DEFAULT_MODEL
+    const modelPrices = body?.model_prices || MODEL_PRICES[model] || MODEL_PRICES[DEFAULT_MODEL]
+    const filePath = ctx.query?.file_path || body?.file_path
+
+    if (!projectId) throw new Error('project_id is required')
+
+    const chunks = await loadAllChunks(projectId, filePath)
+    const toDocument = chunks.filter(needsDocumentation)
+
+    let totalInputTokens = 0
+    const breakdown: any[] = []
+
+    for (const chunk of toDocument) {
+      const prompt = buildDocPrompt(chunk)
+      const inputTokens = estimateTokens(prompt) + SYSTEM_PROMPT_OVERHEAD_TOKENS
+      totalInputTokens += inputTokens
+      breakdown.push({
+        chunk_name: chunk.data?.chunk_name || chunk.title,
+        file_path: chunk.data?.file_path || '',
+        input_tokens: inputTokens,
+      })
+    }
+
+    const totalOutputTokens = toDocument.length * ESTIMATED_OUTPUT_TOKENS_PER_CHUNK
+    const totalTokens = totalInputTokens + totalOutputTokens
+
+    const inputCostUsd  = (totalInputTokens  / 1_000_000) * modelPrices.input_per_1m
+    const outputCostUsd = (totalOutputTokens / 1_000_000) * modelPrices.output_per_1m
+    const totalCostUsd  = inputCostUsd + outputCostUsd
+
+    return {
+      project_id: projectId,
+      model,
+      file_path: filePath || null,
+      model_prices: modelPrices,
+      chunks_to_document: toDocument.length,
+      total_chunks: chunks.length,
+      already_documented: chunks.length - toDocument.length,
+      estimated_input_tokens: totalInputTokens,
+      estimated_output_tokens: totalOutputTokens,
+      estimated_total_tokens: totalTokens,
+      estimated_cost_usd: parseFloat(totalCostUsd.toFixed(4)),
+      estimated_cost_usd_breakdown: {
+        input:  parseFloat(inputCostUsd.toFixed(4)),
+        output: parseFloat(outputCostUsd.toFixed(4)),
+      },
+      
+      top_chunks_by_cost: breakdown
+        .sort((a, b) => b.input_tokens - a.input_tokens)
+        .slice(0, 20),
+    }
+  }
+
+  
+  if (action === 'doc_chunk') {
+    const chunkId = body?.chunk_id || ctx.query?.chunk_id
+    const model = body?.model || ctx.query?.model || DEFAULT_MODEL
+    const force = body?.force ?? false
+    if (!chunkId) throw new Error('chunk_id is required')
+
+    const { data: chunk, error } = await adminDb
+      .from('items')
+      .select('id, title, data')
+      .eq('id', chunkId)
+      .maybeSingle()
+
+    if (error || !chunk) throw new Error(`Chunk not found: ${chunkId}`)
+
+    const projectId = chunk.data?.project_id
+    let repoPath = ''
+    if (projectId) {
+      const { data: projectItem } = await adminDb.from('items').select('data').eq('id', projectId).maybeSingle()
+      repoPath = projectItem?.data?.repo_path || ''
+    }
+
+    const result = await documentChunk(ctx, chunk, model, force, repoPath)
+    return { chunk_id: chunkId, chunk_name: chunk.data?.chunk_name || chunk.title, ...result }
+  }
+
+  
+  
+  
+  if (action === 'validate') {
+    const projectId = ctx.query?.project_id || body?.project_id
+    const filePath = ctx.query?.file_path || body?.file_path
+    if (!projectId) throw new Error('project_id is required')
+
+    const chunks = await loadAllChunks(projectId, filePath)
+    const invalid: any[] = []
+    for (const chunk of chunks) {
+      const errors = validateChunkDocs(chunk)
+      if (errors.length > 0) {
+        invalid.push({
+          chunk_id: chunk.id,
+          chunk_name: chunk.data?.chunk_name || chunk.title,
+          file_path: chunk.data?.file_path || '',
+          chunk_type: chunk.data?.chunk_type || '',
+          errors,
+        })
+      }
+    }
+
+    return {
+      project_id: projectId,
+      file_path: filePath || null,
+      total_chunks: chunks.length,
+      valid_chunks: chunks.length - invalid.length,
+      invalid_chunks: invalid.length,
+      invalid,
+    }
+  }
+
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  if (action === 'document') {
+    const projectId = body?.project_id
+    if (!projectId) throw new Error('project_id is required')
+
+    const model     = body?.model     || DEFAULT_MODEL
+    const dryRun    = body?.dry_run   ?? false
+    const force     = body?.force     ?? false
+    const chunkIds: string[] | undefined = body?.chunk_ids
+    const filePath: string | undefined = body?.file_path
+    const pageLimit = Math.min(parseInt(body?.limit || '5', 10), 100) 
+    const pageOffset= parseInt(body?.offset || '0', 10)
+    const concurrency = Math.min(parseInt(body?.concurrency || '20', 10), 30)
+
+    
+    const { data: projectItem } = await adminDb.from('items').select('id, data').eq('id', projectId).maybeSingle()
+    const selectedPaths: string[] = body?.selected_paths || projectItem?.data?.selected_paths || []
+    const fileTree = (projectItem?.data?.file_tree as FileTreeNode) || null
+
+    
+    
+    let stableList: any[]
+    if (chunkIds?.length) {
+      let q = adminDb
+        .from('items')
+        .select('id, title, data')
+        .filter('data->>kb_type', 'eq', 'cil_chunk')
+        .filter('data->>project_id', 'eq', projectId)
+        .eq('is_active', true)
+        .in('id', chunkIds)
+        .order('id')
+      if (filePath) q = q.filter('data->>file_path', 'eq', filePath)
+      const { data, error } = await q
+      if (error) throw new Error(`Failed to load chunks: ${error.message}`)
+      stableList = data || []
+    } else if (selectedPaths.length > 0 && !filePath) {
+      
+      stableList = await loadPendingChunks(projectId, selectedPaths, 'pass2_complete')
+    } else {
+      stableList = await loadAllChunks(projectId, filePath)
+    }
+
+    const totalChunks = stableList.length
+    const pageChunks  = stableList.slice(pageOffset, pageOffset + pageLimit)
+
+    
+    const allToDocument = force ? pageChunks : pageChunks.filter(needsDocumentation)
+    
+    const totalToDocument = force
+      ? stableList.length
+      : stableList.filter(needsDocumentation).length
+
+    if (dryRun) {
+      return {
+        dry_run: true,
+        project_id: projectId,
+        model,
+        total_to_document: totalToDocument,
+        page_offset: pageOffset,
+        page_limit: pageLimit,
+        page_chunks: pageChunks.length,
+        chunk_names: pageChunks.map(c => c.data?.chunk_name || c.title),
+      }
+    }
+
+    
+    
+    const results: Array<{ chunk: any; fields: Record<string, string> | null; is_fallback?: boolean; error?: string }> = []
+
+    for (let i = 0; i < allToDocument.length; i += concurrency) {
+      const subBatch = allToDocument.slice(i, i + concurrency)
+      const subResults = await Promise.all(subBatch.map(async chunk => {
+        const d = chunk.data || {}
+        if (!d.code_content && !d.chunk_name) {
+          return { chunk, fields: null, error: 'No code content' }
+        }
+        const prompt = buildDocPrompt(chunk)
+        try {
+          const raw = await callLLM(prompt, model)
+          const rawFields = parseDocResponse(raw)
+          const hadLlmFields = hasMeaningfulLlmFields(rawFields)
+          
+          
+          const fields = normalizeDocFields(rawFields, chunk)
+          return { chunk, fields, is_fallback: !hadLlmFields, error: undefined }
+        } catch (err) {
+          
+          const fields = normalizeDocFields({}, chunk)
+          return { chunk, fields, is_fallback: true, error: undefined }
+        }
+      }))
+      results.push(...subResults)
+    }
+
+    
+    let documented = 0, validated = 0, skipped = 0, failed = 0
+    const errors: string[] = []
+    const updatedChunks: any[] = []
+
+    await Promise.all(results.map(async ({ chunk, fields, is_fallback, error: llmError }) => {
+      if (!fields) {
+        if (llmError) { failed++; errors.push(`${chunk.data?.chunk_name || chunk.id}: ${llmError}`) }
+        else skipped++
+        return
+      }
+      const d = chunk.data || {}
+      const toWrite: Record<string, string> = {}
+      for (const [k, v] of Object.entries(fields)) {
+        if (force || !d[k]) toWrite[k] = v
+      }
+      if (!Object.keys(toWrite).length) { skipped++; return }
+
+      const updatedData = { ...d, ...toWrite, doc_confidence: 'ai_generated', doc_fallback: !!is_fallback }
+      const updatedChunk = { ...chunk, data: updatedData }
+
+      
+      const validationErrors = validateChunkDocs(updatedChunk)
+      const chunkUpdateCtx = { ...ctx, query: { ...ctx.query, entity: 'items', id: chunk.id } }
+      if (validationErrors.length > 0) {
+        failed++
+        errors.push(`${chunk.data?.chunk_name || chunk.id}: ${validationErrors.join(', ')}`)
+        await adminUpdate(chunkUpdateCtx, { data: { ...updatedData, doc_validation_errors: validationErrors } })
+          .catch(() => { /* non-fatal — don't mask original validation error */ })
+        return
+      }
+
+      try {
+        await adminUpdate(chunkUpdateCtx, { data: updatedData })
+      } catch (updateError: any) {
+        failed++; errors.push(`${chunk.data?.chunk_name || chunk.id}: ${updateError.message}`)
+        return
+      }
+      {
+        documented++; validated++; updatedChunks.push(updatedChunk)
+      }
+    }))
+
+    
+    
+    if (updatedChunks.length > 0) {
+      const { data: projectItem } = await adminDb.from('items').select('id, data').eq('id', projectId).maybeSingle()
+      const repoPath = projectItem?.data?.repo_path || ''
+      if (repoPath) {
+        const byFile = new Map<string, any[]>()
+        for (const chunk of updatedChunks) {
+          const relPath = chunk.data?.file_path
+          if (!relPath) continue
+          if (!byFile.has(relPath)) byFile.set(relPath, [])
+          byFile.get(relPath)!.push(chunk)
+        }
+        for (const [relPath, chunks] of byFile) {
+          const absPath = path.join(repoPath, relPath)
+          if (!fs.existsSync(absPath)) continue
+          const content = fs.readFileSync(absPath, 'utf-8')
+          const fileLines = content.split('\n')
+          const newLines = [...fileLines]
+          
+          
+          
+          const markerMap = findChunkStartMarkers(newLines)
+          
+          
+          const sorted = [...chunks]
+            .map(c => ({ chunk: c, markerIdx: markerMap.get((c.data?.chunk_name || c.title).trim().toLowerCase()) }))
+            .filter((item): item is { chunk: any; markerIdx: number } => item.markerIdx !== undefined)
+            .sort((a, b) => b.markerIdx - a.markerIdx)
+          const missed = chunks
+            .filter(c => markerMap.get((c.data?.chunk_name || c.title).trim().toLowerCase()) === undefined)
+            .map(c => c.data?.chunk_name || c.title)
+          if (missed.length > 0) {
+            errors.push(`Write-back: could not find markers for ${missed.join(', ')} in ${relPath}`)
+          }
+          for (const { chunk, markerIdx } of sorted) {
+            const jsDoc = buildJsDoc(chunk)
+            if (!jsDoc) {
+              errors.push(`Write-back: no JSDoc built for ${chunk.data?.chunk_name || chunk.title}`)
+              continue
+            }
+            const existing = findExistingCilJsDoc(newLines, markerIdx)
+            if (existing) {
+              newLines.splice(existing.start, existing.end - existing.start + 1, jsDoc)
+            } else {
+              
+              newLines.splice(markerIdx + 1, 0, jsDoc)
+            }
+          }
+          fs.writeFileSync(absPath, newLines.join('\n'), 'utf-8')
+        }
+      }
+    }
+
+    
+    const affectedFileIds = [...new Set((force ? pageChunks : allToDocument).map(c => c.data?.file_id).filter(Boolean))]
+    for (const fileId of affectedFileIds) {
+      await maybeAdvanceFileToPass3(ctx, fileId, fileTree)
+    }
+    if (fileTree) {
+      await saveProjectTree(ctx, projectId, fileTree, { last_ingested_at: new Date().toISOString() })
+    }
+
+    
+    const nextOffset = pageOffset + pageLimit
+    const isLastPage = nextOffset >= totalChunks
+    if (isLastPage && documented > 0) {
+      const { data: projectItem } = await adminDb.from('items').select('id, data').eq('id', projectId).maybeSingle()
+      if (projectItem) {
+        const prices = MODEL_PRICES[model] || MODEL_PRICES[DEFAULT_MODEL]
+        const approxCost = (documented * (ESTIMATED_OUTPUT_TOKENS_PER_CHUNK + 800) / 1_000_000) * ((prices.input_per_1m + prices.output_per_1m) / 2)
+        const projUpdateCtx = { ...ctx, query: { ...ctx.query, entity: 'items', id: projectId } }
+        await adminUpdate(projUpdateCtx, {
+          data: { ...projectItem.data, total_ingestion_cost_usd: (projectItem.data?.total_ingestion_cost_usd || 0) + approxCost, last_ingested_at: new Date().toISOString() },
+        }).catch(() => { /* non-fatal */ })
+      }
+    }
+
+    return {
+      project_id: projectId,
+      model,
+      total_to_document: totalToDocument,
+      total_chunks: totalChunks,
+      page_offset: pageOffset,
+      page_limit: pageLimit,
+      documented,
+      validated,
+      skipped,
+      failed,
+      errors: errors.slice(0, 20),
+      
+      has_more: nextOffset < totalChunks,
+      next_offset: nextOffset < totalChunks ? nextOffset : null,
+      done_total: pageOffset + pageChunks.length,
+    }
+  }
+
+  throw new Error(`Unknown action: ${action}. Valid: estimate, gap_report, document, doc_chunk, validate`)
+})
+
+
+
+
+// CIL[END chunk_id="custom_apps_cortex_functions_custom_cil_doc_handler_1784235266"]