feat: add deterministic evidence-health assessment core

[harshitethic]

Summary

Adds a dependency-free, versioned evidence-health core for captured agent sessions, plus focused tests and user-facing semantics documentation.

This is a scoped foundation for #240 rather than claiming the entire issue is complete. The PR intentionally implements the deterministic calculation layer first; wiring the result into every CLI/API/dashboard surface can build on this without duplicating health rules.

What the core detects

• missing / duplicate session start and end markers
• events recorded outside the session boundary
• mixed session IDs
• missing / duplicate event IDs
• non-finite timestamps and timestamp regressions
• unpaired tool calls/results
• unpaired LLM requests/responses
• duplicate and out-of-order terminal outcomes
• failed tool/LLM calls represented by parent-linked ERROR terminal events
• observable export failures
• explicitly declared provider blind spots
• active sessions vs finalized sessions with a missing end marker

The result is versioned and machine-readable with healthy, partial, unknown, and invalid states plus stable reason codes.

Trust boundary

A key constraint from #240 is that a clean timeline must not be presented as proof of complete capture. This implementation therefore never guesses provider limitations from absent events. Provider blind spots must be supplied explicitly by the capture adapter / future capture matrix work (#239), and they are kept distinct from observed structural defects.

The empty-evidence path also preserves any observable export failures and declared provider blind spots instead of returning early and discarding those signals; the overall state remains unknown because there is still no event stream to assess.

That keeps the core local and dependency-free, matching the repository's architecture constraints.

Tests

tests/test_evidence_health.py covers the healthy path, empty/active/finalized sessions, malformed boundaries and IDs, timestamp issues, tool and LLM relationship failures, duplicate/out-of-order outcomes, failed calls terminating in ERROR, provider blind spots, export failures, and versioned serialization.

Documentation

docs/evidence-health.md documents statuses, reason semantics, the distinction between observed defects and provider limitations, and what a healthy result does not claim.

Scope / follow-ups

This PR does not claim to close #240 yet. Remaining integration work includes exposing the same result through the CLI/replay/API/dashboard and sourcing provider limitations from the capture matrix rather than ad-hoc callers. Keeping those integrations separate avoids inventing provider metadata before #239 defines it and avoids coupling the calculation engine to the dashboard work in #242.

Validation

Fresh-clone focused validation on PR head 91dbcf5dcac074cb8890b76068d6888fea04cbad:

PYTHONPATH=src python -m unittest discover -s tests -p 'test_evidence_health.py' -v

Result: 17 tests passed.

A full unittest discovery was also started on the available Windows host, but unrelated platform-sensitive tests are not clean there, so I am not claiming full-suite success from that run. Upstream GitHub Actions is still action_required with zero jobs created, so upstream CI itself has not executed yet.

No runtime dependencies or storage-format changes are introduced.

[harshitethic]

Validation update: I reproduced the PR head (91dbcf5dcac074cb8890b76068d6888fea04cbad) from a fresh clone and ran the focused evidence-health suite with the repository's src/ layout on PYTHONPATH:

PYTHONPATH=src python -m unittest discover -s tests -p 'test_evidence_health.py' -v

Result: 17 tests passed.

I also started the full unittest discovery. It exercises many platform-specific tests that are not clean on this Windows host, so I am not treating that run as authoritative full-suite validation. Upstream Actions still shows action_required with zero jobs, so CI itself has not run.

[harshitethic]

@Siddhant-K-code this one is ready for maintainer review. It keeps the scope narrow to the deterministic evidence-health core for #240, and I ran the focused suite on the PR head (17 tests passed). I deliberately left CLI/dashboard wiring and provider-matrix integration out so the core can be reviewed independently. Happy to adjust the API/reason codes if you want a different shape before merge.