Telemetry correctness contract

Make observability code behave like a correctness-critical contract—not “best effort.”

Apply these rules:

• Use typed, policy-compliant helpers for telemetry event names and payload shapes (never free-form event strings). Keep payloads stable and bounded; never emit raw prompt/text when counts/sanitized fields suffice.
• Respect lifecycle ordering: if an integration/span observation may end before an error is reported, propagate/record the error early enough so terminal spans get the right status.
• Attribute per correct scope: initialize/reset “reason”/failure metadata at the right granularity (e.g., per turn, not inherited from a previous turn). Wrong causes are worse than missing ones—add tests that fail on stale attribution.
• Classify with truthful reason codes: reason enums must match the actual failure condition (don’t label all “ask” errors as timeouts/hangs).
• Avoid double-counting: instrument in one centralized place; don’t add parallel capture paths that both count the same action.
• Don’t mutate semantic core state via telemetry wiring: telemetry configuration should attach hooks/transport only; it must not change bootstrap/session semantics (e.g., sessionId/resume detection).
• Test the telemetry contract: assert event name constants, payload shape, opt-out behavior, and (where applicable) span/terminal status.

Example pattern (typed helper + bounded payload + opt-out safe):

// core-events.ts
export function capturePendingPromptsDiscarded(
  telemetry: ITelemetryService | undefined,
  details: { sessionId: string; count: number; reason: "queue_abort" | "session_teardown" },
): void {
  emit(telemetry, CORE_TELEMETRY_EVENTS.SESSION.PENDING_PROMPTS_DISCARDED, details);
}