Make things 'betterer' across the board (#23)

* Make things 'betterer' across the board

* fix: reorganize struct fields and config parameters for consistency

- [x] Reorder Config struct fields alphabetically and by related functionality
- [x] Reorganize Observation model fields with archival fields grouped together
- [x] Reorder ObservationStore fields to group related members
- [x] Reorder Store struct fields with health check caching grouped
- [x] Reorganize HealthInfo and PoolMetrics struct field order
- [x] Reorder maintenance Service struct fields logically
- [x] Reorganize MCP server handler parameter structs alphabetically
- [x] Reorder pattern detector candidate tracking fields
- [x] Reorganize search Manager struct fields by functionality
- [x] Reorder vector Client struct fields with mutex protections grouped
- [x] Reorganize handler request/response struct fields
- [x] Update handlers_test.go to expect wrapped response format
- [x] Reorder middleware TokenAuth and rate limiter fields
- [x] Reorganize Service struct fields with grouped functionality
- [x] Fix RateLimiter field ordering for clarity
- [x] Reorder CircuitBreaker metrics fields

* fix(security): improve JSON output safety and path traversal protection

- [x] Replace unsafe JSON string formatting with proper json.Marshal in export handler
- [x] Remove escapeJSONString helper function in favor of standard JSON marshaling
- [x] Add safeResolvePath function to validate paths and prevent directory traversal
- [x] Apply path traversal validation in captureFileMtimes operations
- [x] Cap result slice capacity in getRecentSearchQueries to prevent DoS via excessive allocation

* fix(sdk): improve path traversal protection and allocation safety

- [x] Enhance safeResolvePath with stricter validation using filepath.Rel
- [x] Reject paths containing ".." after cleaning to prevent traversal
- [x] Validate absolute paths are within cwd when cwd is specified
- [x] Apply safeResolvePath validation to GetFileContent for consistency
- [x] Add comprehensive test coverage for path traversal protection
- [x] Fix allocation safety in getRecentSearchQueries by using constant capacity

internal/worker/handlers_test.go

@@ -66,6 +66,7 @@ func testService(t *testing.T) (*Service, func()) {
 		cancel:           cancel,
 		startTime:        time.Now(),
 		retrievalStats:   make(map[string]*RetrievalStats),
+		cachedObsCounts:  make(map[string]cachedCount),
 	}
 
 	svc.setupRoutes()
@@ -345,11 +346,13 @@ func TestHandleGetObservations_Limit(t *testing.T) {
 
 	assert.Equal(t, http.StatusOK, rec.Code)
 
-	// Parse as generic JSON array since the model uses custom marshaling
-	var observations []map[string]interface{}
-	err := json.Unmarshal(rec.Body.Bytes(), &observations)
+	// Parse as object with observations key (API returns wrapped response)
+	var response map[string]interface{}
+	err := json.Unmarshal(rec.Body.Bytes(), &response)
 	require.NoError(t, err)
 
+	observations, ok := response["observations"].([]interface{})
+	require.True(t, ok, "expected observations array in response")
 	assert.Len(t, observations, 10)
 }
 
@@ -1135,10 +1138,13 @@ func TestHandleGetObservations_DefaultLimit(t *testing.T) {
 
 	assert.Equal(t, http.StatusOK, rec.Code)
 
-	var observations []map[string]interface{}
-	err := json.Unmarshal(rec.Body.Bytes(), &observations)
+	var response map[string]interface{}
+	err := json.Unmarshal(rec.Body.Bytes(), &response)
 	require.NoError(t, err)
 
+	observations, ok := response["observations"].([]interface{})
+	require.True(t, ok, "expected observations array in response")
+
 	// Should return default limit (100)
 	assert.LessOrEqual(t, len(observations), DefaultObservationsLimit)
 }
@@ -1159,10 +1165,12 @@ func TestHandleGetObservations_FilterByProject(t *testing.T) {
 
 	assert.Equal(t, http.StatusOK, rec.Code)
 
-	var observations []map[string]interface{}
-	err := json.Unmarshal(rec.Body.Bytes(), &observations)
+	var response map[string]interface{}
+	err := json.Unmarshal(rec.Body.Bytes(), &response)
 	require.NoError(t, err)
 
+	observations, ok := response["observations"].([]interface{})
+	require.True(t, ok, "expected observations array in response")
 	assert.Len(t, observations, 2)
 }
 
@@ -1412,10 +1420,12 @@ func TestHandleGetObservations(t *testing.T) {
 
 	assert.Equal(t, http.StatusOK, rec.Code)
 
-	var observations []map[string]interface{}
-	err := json.Unmarshal(rec.Body.Bytes(), &observations)
+	var response map[string]interface{}
+	err := json.Unmarshal(rec.Body.Bytes(), &response)
 	require.NoError(t, err)
 
+	observations, ok := response["observations"].([]interface{})
+	require.True(t, ok, "expected observations array in response")
 	assert.GreaterOrEqual(t, len(observations), 2)
 }
 
@@ -2697,10 +2707,13 @@ func TestHandleGetObservations_EmptyResult(t *testing.T) {
 
 	assert.Equal(t, http.StatusOK, rec.Code)
 
-	// Should return empty array, not null
-	var obs []interface{}
-	err := json.Unmarshal(rec.Body.Bytes(), &obs)
+	// Should return empty array within observations key, not null
+	var response map[string]interface{}
+	err := json.Unmarshal(rec.Body.Bytes(), &response)
 	require.NoError(t, err)
+
+	obs, ok := response["observations"].([]interface{})
+	require.True(t, ok, "expected observations array in response")
 	assert.NotNil(t, obs)
 }