Add annotated trace discovery and export APIs

[johnnygreco]

Summary

Adds annotation-aware dataset discovery and export APIs:

• GET /api/annotations/traces lists annotated sessions with annotation counts and validated target summaries.
• GET /api/annotations/export returns dataset-ready JSON with session metadata, ordered event context, complete paginated annotation records, schema markers, and truncation warnings.
• Extends shared annotation filtering for target type, session/event ID, label, author/source/category/outcome, follow-up state, deleted inclusion, and existing Beacon scope filters.
• Documents the dataset collection endpoints in the README.

Closes #305

Example Output

Discovery response shape:

{
  "schema": "beacon.annotated_traces.index.v1",
  "include_deleted": false,
  "items": [
    {
      "session": {"id": "session-1", "title": "..."},
      "counts": {"annotation_count": 2, "session_annotation_count": 1, "message_annotation_count": 1, "event_annotation_count": 0, "needs_followup_count": 0},
      "targets": [{"target_type": "message", "event_uid": "message-1", "annotation_count": 1}]
    }
  ]
}

Export response shape:

{
  "schema": "beacon.annotated_traces.export.v1",
  "traces": [
    {
      "session": {"id": "session-1", "title": "..."},
      "annotations": [{"annotation_id": "ann-session", "target_type": "session", "note": "..."}],
      "events": [{"event_uid": "message-1", "event_kind": "message", "text_preview": "..."}],
      "event_truncated": false
    }
  ]
}

Validation

• generation: make generate-check -> passed
• formatting: make fmt-check -> passed
• go tests: make test -> passed
• build: make build -> passed
• lint: make lint -> passed
• frontend contracts/unit/lint: npm run test:frontend -> passed
• targeted export/API: go test ./internal/web -run 'TestAnnotationAPIAnnotatedTraces|TestAnnotationAPIExportAnnotatedTraces|TestAPIContractsMatchGoStructTags' -> passed
• whitespace: git diff --check -> passed

Risks

The export endpoint returns bounded event context per trace. event_limit defaults to 1000 and clamps at 5000; responses include event_truncated and warnings when a session has more events than the requested limit.

Candidate discovery scans annotation session summaries in bounded batches and revalidates each annotation target before counting or exporting it, so out-of-scope event/message annotations are skipped rather than exposed through counts or metadata.

Reviewer Notes

Focus on internal/web/api_annotation_exports.go and the extended annotation filters in internal/store/annotations.go. The tests deliberately cover hidden out-of-scope message annotations, deleted annotations, empty exports, API contracts, event truncation, and annotation pagination beyond the store page cap. No UI controls were added in this PR, so no screenshots are included. Backward compatibility was explicitly not required and no legacy export format was added.

[johnnygreco]

Review Record

Frozen target: feature/trace-annotations 65c3ff9d335ac504896cb9a84eac5d1453dfbc13..issue-305-annotation-export bee86e610518bc3c7400f10b4ce3f734bf6b0120
Diff command: git diff 65c3ff9d335ac504896cb9a84eac5d1453dfbc13..bee86e610518bc3c7400f10b4ce3f734bf6b0120

Panel:

• API Scope Safety: security/privacy, robustness/correctness, API contracts -> findings, rerun clean
• Data Export Contract: data/export contract, robustness/correctness, performance/resource limits -> findings, rerun clean
• Tests And Maintainability: tests/coverage, maintainability, complexity discipline -> findings, rerun clean
• Docs And Adoption: user/agent experience, documentation/adoption, API ergonomics -> findings, rerun clean
  Skipped Review-Standard lenses: dependency/supply-chain - no dependency or lockfile changes; UI accessibility/visual layout - no UI controls changed in this PR.

Accepted findings fixed:

• Scope-visible ordering/pagination: annotated trace pagination was originally based on unscoped candidate summaries before target validation, so hidden targets could influence ordering/pages. Fixed by scanning candidate pages, validating annotation targets against the requested/auth scope, building visible groups, sorting by visible lastAnnotationAt DESC, session.ID ASC, then applying offset/limit. Added TestAnnotationAPIAnnotatedTracesOrdersByVisibleScopedAnnotations.
• Scan cap completeness: discovery/export could stop after 5,000 candidate sessions and report has_more=false while more annotated traces existed. Removed the fixed scan cap and compute has_more from the full visible set.
• Large offset overflow: annotated trace offset had no cap. Added maxAnnotatedTracesOffset and TestAnnotationAPIAnnotatedTracesCapsOffset.
• Dataset export docs: README did not explain pagination or event truncation signals. Added limit/offset/has_more guidance, a curl/jq page loop, and event_truncated/warnings notes.

Rejected findings:

• none

Validation after fixes:

• make generate-check -> passed
• make fmt-check -> passed
• go test ./internal/store ./internal/web -> passed
• go test ./internal/web -run 'TestAnnotationAPIAnnotatedTraces|TestAnnotationAPIExportAnnotatedTraces|TestAPIContractsMatchGoStructTags' -> passed
• make test -> passed
• make build -> passed
• make lint -> passed
• npm run test:frontend -> passed
• git diff --check -> passed
• GitHub CI at bee86e610518bc3c7400f10b4ce3f734bf6b0120 -> all checks passed: format, generated, govulncheck, npm-audit, frontend, dependency-review, test, lint, build, playwright-dashboard, playwright-accessibility

Final status: all rerun reviewers clean; no unresolved blockers.