.agents/memory/2026-02-24-embedding-health-check-feature-plan.md

2026-02-24 Session Notes

Embedding Health Check Feature Plan

A coding session focused on planning a unified embedding health check system for the Signet daemon. The feature addresses scattered health signals across multiple endpoints (/api/embeddings/status, /api/repair/embedding-gaps, diagnostics.ts) by introducing a single aggregated endpoint and dashboard UI.

Architecture

The plan creates a new read-only module packages/daemon/src/embedding-health.ts (~200 LOC) following the existing diagnostics.ts pattern. It exports buildEmbeddingHealth() which synchronously evaluates embedding system health via seven database checks and provider status.

Seven Health Checks

Each check is a small function with weighted scoring (provider-available: 0.30, coverage: 0.25, dimension-mismatch: 0.15, model-drift: 0.10, null-vectors: 0.08, vec-table-sync: 0.07, orphaned-embeddings: 0.05). Thresholds match diagnostics patterns: ≥0.8 healthy, ≥0.5 degraded, <0.5 unhealthy.

Implementation Tasks

1. Create embedding-health.ts with type definitions and check functions
2. Register GET /api/embeddings/health endpoint in daemon.ts
3. Add orphan cleanup function to repair-actions.ts
4. Add API client function to dashboard/api.ts
5. Build floating health indicator UI in EmbeddingsTab.svelte (collapsed pill + expanded panel)

Dashboard Integration

A floating health indicator in the top-right corner of the embeddings canvas showing status with color-coded dots (green/amber/red). Expands on click to show all checks with fix hints for failed items. Fetches every 60s using lightweight read-only queries.

Key Decisions

• Synchronous DB reads only; provider status pre-resolved by caller
• Duplicate small helper functions locally rather than exposing from diagnostics.ts
• No external dependencies; follows existing daemon patterns
• All checks are actionable with clear fix hints for failed states