telemetry: schema-first event registry (typed catalog + generated docs)

Inizia leggendo src/instrumentation/CONVENTIONS.md, i file specifici per dominio sotto src/instrumentation/* e src/instrumentation/EVENTS.md. Segui TelemetryService.trace/log/logError, Span e i relativi test per comprendere l'attuale tipizzazione degli eventi e delle proprietà. Il lavoro è completato quando il design del registro scelto è implementato, la strumentazione e i test sono aggiornati e l'EVENTS.md generato supera il relativo controllo di aggiornamento della CI.

Problem

Telemetry events, properties, and value unions are declared per-domain in src/instrumentation/* and documented by hand in src/instrumentation/EVENTS.md. Nothing structurally prevents:

• emitting an event name that isn't cataloged anywhere,
• adding/renaming a property without updating the docs,
• drifting from the conventions in src/instrumentation/CONVENTIONS.md (a recent audit found camelCase keys, kebab-case enum values, and caller-set result that review missed).

Proposal

Adopt a schema-first registry as the single source of truth for the telemetry surface, the way OTel itself defines semantic conventions in a registry and generates code + docs from it (Weaver).

TS-native sketch:

• A central TelemetryEventMap interface declaring every event with its properties and measurements (value unions spelled out).
• TelemetryService.trace/log/logError constrained to keyof TelemetryEventMap; Span becomes generic (Span<E>) so setProperty/setMeasurement keys and values are type-checked per event. An undeclared event or attribute key becomes a compile error.
• EVENTS.md generated from the registry (script walking the interface + JSDoc), with a CI --check mode so the doc can never go stale.

Known costs / open questions

• Every instrumentation class and its tests are touched by the Span<E> generic.
• Phase names compose at runtime (parent.child), so child phases need registry entries or looser typing.
• The registry partially duplicates per-domain unions the instrumentation classes already export; decide whether the registry imports those types or replaces them.

Cheaper interim guards (could land independently)

• Type the event-name parameter of TelemetryService.trace/log as a union of registered names (names are already top-level string literals; near-zero churn).
• ESLint restriction banning raw telemetry.trace(/.log( outside src/instrumentation (the layering rule from CONVENTIONS.md).
• Golden event catalog aggregated from the test suite's sinks, checked like the existing OTLP goldens.