spine-framework 0.3.145 → 0.4.1

package/.framework/functions/eval-harness.ts

@@ -1,3 +1,12 @@
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-MACRO purpose="Eval harness module imports and entry re-export"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import dependencies and expose the main eval handler for serverless function routing"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none at module level" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declares the shared imports and main handler re-export for the evaluation harness" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
 
 
 
@@ -19,21 +28,6 @@
 
 
 
-// CIL[BEGIN chunk_id="eval-harness_moduleheader_1783969696" type="module_header" identity="imports" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for eval harness module"]
-// CIL[DOC-RESPONSIBILITY responsibility="Import middleware, database, utilities, and audit functions"]
-// CIL[DOC-CONTEXT module="eval-harness" layer="backend_functions" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imported_modules" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Import required dependencies for evaluation test harness" 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: backend_functions. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, .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'
@@ -41,44 +35,74 @@ import { resolveTypeId } from './_shared/resolve-ids'
 import { create } from './admin-data'
 import { emitLog } from './_shared/audit'
 import { callOpenAIEmbeddings } from './_shared/llm'
-// CIL[END chunk_id="eval-harness_moduleheader_1783969696"]
-// CIL[BEGIN chunk_id="eval-harness_constants_1783969696" type="function" identity="constants" parent="none"]
-// CIL[DOC-MACRO purpose="Define evaluation constants and types"]
-// CIL[DOC-RESPONSIBILITY responsibility="Configure test types and confidence tier thresholds"]
-// CIL[DOC-CONTEXT module="eval-harness" layer="backend_functions" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="constants" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Define test categories and confidence score ranges for evaluation" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/IntegrationsPage.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="context" content="purpose='Eval harness module imports and entry re-export'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/eval-harness.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:TEST_TYPES:constant" type="constant" identity="TEST_TYPES" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-MACRO purpose="Enumeration of supported evaluation test categories"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide the canonical list of test_type values used in eval test cases and coverage"]
+// CIL[DOC-STABILITY stability="internal"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/eval-harness.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="readonly array of test type strings" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Static const array of eval test categories" notable_decisions="[]"]
 const TEST_TYPES = ['easy', 'medium', 'hard', 'security', 'hallucination', 'stale', 'account_gating'] as const
+// CIL[END stable_id="~/.framework/functions/eval-harness.ts:TEST_TYPES:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:TestType:type" type="type" identity="TestType" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-VECTOR type="context" content="purpose='Enumeration of supported evaluation test categories'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[DOC-MACRO purpose="Type union derived from the TEST_TYPES array"]
+// CIL[DOC-RESPONSIBILITY responsibility="Constrain test_type fields to the supported categories"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/eval-harness.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="TestType union type" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Type alias derived from TEST_TYPES" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 type TestType = typeof TEST_TYPES[number]
-
+// CIL[DOC-VECTOR type="context" content="purpose='Type union derived from the TEST_TYPES array'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/eval-harness.ts:TestType:type"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:CONFIDENCE_TIERS:constant" type="constant" identity="CONFIDENCE_TIERS" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-MACRO purpose="Threshold map for categorizing confidence scores"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define min and max score boundaries for high, medium and low tiers"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/eval-harness.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="constant tier threshold object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Object mapping tier names to min and max similarity score ranges" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 const CONFIDENCE_TIERS = {
   high:   { min: 0.85, max: 1.00 },
   medium: { min: 0.60, max: 0.849 },
   low:    { min: 0.00, max: 0.599 },
 }
-// CIL[END chunk_id="eval-harness_constants_1783969696"]
-// CIL[BEGIN chunk_id="eval-harness_createtestcase_1783969696" type="function" identity="createTestCase" parent="none"]
-// CIL[DOC-MACRO purpose="Create evaluation test case"]
-// CIL[DOC-RESPONSIBILITY responsibility="Create test case with question and expected outcomes"]
-// CIL[DOC-CONTEXT module="eval-harness" layer="backend_functions" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="created_test_case" errors="validation_errors,db_errors" side_effects="db_write"]
-// CIL[DOC-MICRO logic_summary="Validate input, resolve type ID, create test case item" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 2."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Threshold map for categorizing confidence scores'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/eval-harness.ts:CONFIDENCE_TIERS:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:createTestCase:constant" type="constant" identity="createTestCase" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-MACRO purpose="Create a new eval test case record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Validate input, resolve the eval_test_case type, and persist the test case item"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/eval-harness.ts"]
+// CIL[DOC-CONTRACT inputs="question, expected_tier, expected_escalate, expected_source_ids, excluded_source_ids, test_type" outputs="created item record" errors="throws if question missing or eval_test_case type not found" side_effects="inserts a new active item into the items table"]
+// CIL[DOC-MICRO logic_summary="Resolves the eval_test_case type and inserts an item with the provided test parameters" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const createTestCase = createHandler(async (ctx, body) => {
   const {
     question, expected_tier = 'medium', expected_escalate = false,
@@ -107,21 +131,21 @@ export const createTestCase = createHandler(async (ctx, body) => {
     },
   })
 })
-// CIL[END chunk_id="eval-harness_createtestcase_1783969696"]
-// CIL[BEGIN chunk_id="eval-harness_listtestcases_1783969696" type="function" identity="listTestCases" parent="none"]
-// CIL[DOC-MACRO purpose="List evaluation test cases"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve test cases with optional filtering"]
-// CIL[DOC-CONTEXT module="eval-harness" layer="backend_functions" related_files="[\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="test_cases" errors="db_errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Query test cases by type and test type, return paginated results" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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="context" content="purpose='Create a new eval test case record'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/eval-harness.ts:createTestCase:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:listTestCases:constant" type="constant" identity="listTestCases" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-MACRO purpose="List active eval test case records"]
+// CIL[DOC-RESPONSIBILITY responsibility="Query active items for the eval_test_case type with optional test_type filter"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/eval-harness.ts"]
+// CIL[DOC-CONTRACT inputs="query: test_type, limit, offset" outputs="array of test case records" errors="throws on database error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Builds a query against items filtered by status, type and optional test_type" notable_decisions="[]"]
+// CIL[DOC-STABILITY stability="internal"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 export const listTestCases = createHandler(async (ctx, _body) => {
   const { test_type, limit = '200', offset = '0' } = ctx.query || {}
 
@@ -142,21 +166,21 @@ export const listTestCases = createHandler(async (ctx, _body) => {
   if (error) throw error
   return data || []
 })
-// CIL[END chunk_id="eval-harness_listtestcases_1783969696"]
-// CIL[BEGIN chunk_id="eval-harness_runeval_1783969696" type="function" identity="runEval" parent="none"]
-// CIL[DOC-MACRO purpose="Run evaluation test suite"]
-// CIL[DOC-RESPONSIBILITY responsibility="Execute test cases and measure retrieval performance"]
-// CIL[DOC-CONTEXT module="eval-harness" layer="backend_functions" related_files="[\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="eval_results" errors="api_errors,db_errors" side_effects="api_calls,db_write,audit_log"]
-// CIL[DOC-MICRO logic_summary="Run embeddings search, evaluate recall and boundary violations, store results" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="complex_logic,external_api"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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[END stable_id="~/.framework/functions/eval-harness.ts:listTestCases:constant"]
+// CIL[DOC-VECTOR type="context" content="purpose='List active eval test case records'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:runEval:constant" type="constant" identity="runEval" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-MACRO purpose="Run an evaluation pass over active test cases and store results"]
+// CIL[DOC-RESPONSIBILITY responsibility="Embed questions, retrieve similar documents, score recall, boundaries, tier correctness and record the execution"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/eval-harness.ts"]
+// CIL[DOC-CONTRACT inputs="body: test_type, similarity_threshold, match_count; requires account context" outputs="run summary and per-case results" errors="throws if account missing or database errors; skips cases on embed failure" side_effects="inserts a pipeline_executions row and emits an audit log"]
+// CIL[DOC-MICRO logic_summary="For each test case, computes embeddings, calls match_embeddings, checks recall, boundaries, tier correctness, and writes the execution result" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const runEval = createHandler(async (ctx, body) => {
   const { test_type, similarity_threshold = 0.15, match_count = 8 } = body || {}
   if (!ctx.accountId) throw new Error('Account context required')
@@ -182,6 +206,14 @@ export const runEval = createHandler(async (ctx, body) => {
   let passed = 0; let failed = 0; let skipped = 0
 
   for (const tc of testCases) {
+    // Cases created from a live ticket carry observed (diagnostic) sources but
+    // no human-approved expected_source_ids yet — exclude them from scoring
+    // until review promotes them to golden cases.
+    if (tc.data?.needs_source_review) {
+      skipped++
+      results.push({ id: tc.id, status: 'skipped', reason: 'needs_source_review' })
+      continue
+    }
     const question     = tc.data?.question || tc.title
     const expectedSrcs = tc.data?.expected_source_ids || []
     const excludedSrcs = tc.data?.excluded_source_ids || []
@@ -285,21 +317,21 @@ export const runEval = createHandler(async (ctx, body) => {
 
   return { run_id: execRow?.id || null, summary, results }
 })
-// CIL[END chunk_id="eval-harness_runeval_1783969696"]
-// CIL[BEGIN chunk_id="eval-harness_getresults_1783969696" type="function" identity="getResults" parent="none"]
-// CIL[DOC-MACRO purpose="Get evaluation run results"]
-// CIL[DOC-RESPONSIBILITY responsibility="Retrieve recent evaluation execution results"]
-// CIL[DOC-CONTEXT module="eval-harness" layer="backend_functions" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="eval_results" errors="auth_errors,db_errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Query pipeline executions for eval runs, return summary and results" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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[END stable_id="~/.framework/functions/eval-harness.ts:runEval:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:getResults:constant" type="constant" identity="getResults" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-MACRO purpose="Fetch recent eval run results"]
+// CIL[DOC-VECTOR type="context" content="purpose='Run an evaluation pass over active test cases and store results'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[DOC-RESPONSIBILITY responsibility="Return the latest pipeline_executions rows triggered by eval runs for the current account"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/eval-harness.ts"]
+// CIL[DOC-CONTRACT inputs="query limit" outputs="array of execution records" errors="throws on db error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Queries pipeline_executions for eval_run trigger data and returns recent records" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getResults = createHandler(async (ctx, _body) => {
   if (!ctx.accountId) throw new Error('Account context required')
 
@@ -316,21 +348,21 @@ export const getResults = createHandler(async (ctx, _body) => {
   if (error) throw error
   return data || []
 })
-// CIL[END chunk_id="eval-harness_getresults_1783969696"]
-// CIL[BEGIN chunk_id="eval-harness_getcoverage_1783969696" type="function" identity="getCoverage" parent="none"]
-// CIL[DOC-MACRO purpose="Get test case coverage analysis"]
-// CIL[DOC-RESPONSIBILITY responsibility="Analyze test case distribution across types"]
-// CIL[DOC-CONTEXT module="eval-harness" layer="backend_functions" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="coverage_report" errors="db_errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Count test cases by type, identify coverage gaps" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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="context" content="purpose='Fetch recent eval run results'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/eval-harness.ts:getResults:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:getCoverage:constant" type="constant" identity="getCoverage" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-MACRO purpose="Report how many test cases exist per test category"]
+// CIL[DOC-RESPONSIBILITY responsibility="Count active eval test cases by test_type and list missing categories"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/eval-harness.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="coverage summary and recommendations" errors="throws on db error" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Counts cases per TEST_TYPES and returns totals and recommendations" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const getCoverage = createHandler(async (ctx, _body) => {
   const { data: typeRow } = await adminDb
     .from('types').select('id').eq('slug', 'eval_test_case').eq('kind', 'item').maybeSingle()
@@ -361,21 +393,21 @@ export const getCoverage = createHandler(async (ctx, _body) => {
     recommendation: coverage.filter(c => !c.has_cases).map(c => c.test_type),
   }
 })
-// CIL[END chunk_id="eval-harness_getcoverage_1783969696"]
-// CIL[BEGIN chunk_id="eval-harness_handler_1783969696" type="function" identity="handler" parent="none"]
-// CIL[DOC-MACRO purpose="Route eval harness HTTP methods"]
-// CIL[DOC-RESPONSIBILITY responsibility="Dispatch requests to evaluation operations"]
-// CIL[DOC-CONTEXT module="eval-harness" layer="backend_functions" related_files="[]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="function_responses" errors="method_errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Route based on action and method to specific eval functions" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: backend_functions. 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="context" content="purpose='Report how many test cases exist per test category'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/eval-harness.ts:getCoverage:constant"]
+// CIL[BEGIN stable_id="~/.framework/functions/eval-harness.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/eval-harness.ts"]
+// CIL[DOC-MACRO purpose="Route incoming eval harness requests to the correct action"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch based on action and method to create, list, run, or get eval operations"]
+// CIL[DOC-CONTEXT module="eval-harness" layer="function" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/resolve-ids.ts,.framework/functions/admin-data.ts,.framework/functions/eval-harness.ts"]
+// CIL[DOC-CONTRACT inputs="ctx.query.action and method; body for POST actions" outputs="result of the chosen action or throws" errors="throws Invalid action or method for unsupported combinations" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Switch on action, guard by method, and dispatch to internal handlers" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -402,4 +434,10 @@ export const handler = createHandler(async (ctx, body) => {
 
   throw new Error('Invalid action or method')
 })
-// CIL[END chunk_id="eval-harness_handler_1783969696"]
+// CIL[DOC-VECTOR type="context" content="purpose='Route incoming eval harness requests to the correct action'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/resolve-ids.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/functions/eval-harness.ts:handler:constant"]