Add trace annotation API foundation

[johnnygreco]

Summary

Adds the foundation for first-class trace/session annotations.

Closes #302

This PR adds the canonical annotation model, ClickHouse storage table, store helpers, typed JSON API routes, shared API contract entries, and focused tests for session/event annotation CRUD. Annotation schema is intentionally extensible with structured target, author, source, category, outcome, score, confidence, follow-up, label, note, metadata, status, and schema fields.

Schema decision: this is a real schema change. Beacon schema version is bumped from 9 to 10. There are no compatibility ALTERs, legacy shims, or old-schema upgrade paths.

Validation

• generation: make generate-check -> passed, templ updates=0
• formatting: make fmt-check -> passed
• go tests: make test -> passed
• frontend contracts/unit/lint: npm run test:frontend -> passed
• whitespace: git diff --check -> passed

Risks

Annotation APIs are intentionally target-bound for this foundation PR. Broad annotation discovery/export is left to #305 so the storage/API contract can settle before dataset workflows build on it.

The schema version bump means existing older Beacon schemas are not supported by this build. That is intentional per the goal direction.

Reviewer Notes

Focus on the annotation data contract, validation bounds, target resolution, soft-delete semantics, and whether the API shape is sufficient for #303 UI and #304 MCP without duplicating models. Backward compatibility was explicitly not required and should not be added.

[johnnygreco]

Review Record

Frozen target: feature/trace-annotations 23a5aaee4436dd46bdac4802403ba4fd6be4d602..issue-302-annotation-foundation 102be20bb95d7d352adae5b25a1d3b0e621b6a5e
Diff command: git diff --find-renames 23a5aaee4436dd46bdac4802403ba4fd6be4d602..102be20bb95d7d352adae5b25a1d3b0e621b6a5e

Panel:

• Popper: data model, API correctness, authorization/security, validation -> clean
• Avicenna: maintainability, complexity, tests, integration coverage -> clean
• Cicero: API ergonomics, integration behavior, data replacement semantics, correctness -> clean

Skipped Review-Standard lenses:

• UI/user accessibility: human UI is out of scope for Add annotation storage, domain model, and JSON API foundation #302 and covered by Build human transcript annotation UI #303.
• MCP/agent tool experience: MCP annotation tools are out of scope for Add annotation storage, domain model, and JSON API foundation #302 and covered by Add MCP annotation tools for agents #304.
• Dataset export/adoption docs: export workflows and user-facing docs are out of scope for Add annotation storage, domain model, and JSON API foundation #302 and covered by Add annotated-trace discovery and dataset export workflows #305/Complete annotation QA, docs, and final polish #306.
• Dependency/supply chain: no dependency or lockfile changes.
• Native extensions/FFI: not applicable.

Accepted findings fixed:

• Generic GET /api/annotations?annotation_id=... could bypass source/runtime scope -> list responses now re-resolve every returned annotation target through the active API scope, with a regression test for out-of-scope annotation IDs.
• Author identity length validation was ineffective because normalization silently truncated fields -> author fields are now trimmed without truncation and oversize author values fail validation.
• ReplacingMergeTree(updated_at) could pick nondeterministic rows for same-millisecond update/delete writes -> annotation rows now carry monotonic revision, use ReplacingMergeTree(revision), and update/delete increment revision.
• Real ClickHouse annotation CRUD was not covered -> added skipped-by-default live ClickHouse CRUD coverage for create/list/update/delete, event session resolution, metadata, labels, and deleted filtering.
• CI lint caught a dead increment in the test fake -> cleaned up the fake scope matcher/row parser and reran lint.

Rejected findings:

• None.

Validation after fixes:

• git diff --check -> pass
• make generate-check -> pass, templ updates=0
• make fmt-check -> pass
• make test -> pass
• make lint -> pass
• make build -> pass
• npm run test:frontend -> pass
• GitHub CI on 102be20bb95d7d352adae5b25a1d3b0e621b6a5e -> all checks passed: dependency-review, format, frontend, generated, govulncheck, npm-audit, build, lint, test, playwright-accessibility, playwright-dashboard.

Final status: all rerun reviewers clean; all required local validation and CI passed on the reviewed head.