# V3 Telemetry Schema

Canonical source: `libs/oshun/analytics/src/v3-telemetry-schema.ts`

Published schema: `schema-v3`

Publication status: `published`

The V3 telemetry schema is versioned inside `@oshun/analytics` beside the V1
analytics taxonomies and launch-readiness manifests. Contract changes must pass
the analytics library tests, typecheck, lint, and build before a V3 release gate
can consume the events.

## V1 Analytics Linkage

The schema publication references the following V1 analytics sources:

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/analytics/src/validation.ts`
- `libs/oshun/analytics/src/customer-taxonomy.ts`
- `libs/oshun/analytics/src/admin-taxonomy.ts`
- `libs/oshun/analytics/src/assistant-taxonomy.ts`
- `libs/oshun/analytics/src/flows-taxonomy.ts`
- `libs/oshun/analytics/src/release-taxonomy.ts`
- `libs/oshun/analytics/src/v1-launch-readiness-manifest.ts`
- `libs/oshun/analytics/src/v1-release-and-exit-criteria-manifest.ts`

## Published Events

The first `schema-v3` publication defines these V3 events:

- `oshun.session.started`
- `oshun.tier_router.decision_recorded`
- `tara.practice.engagement_recorded`
- `oshun.accessibility.mode_changed`
- `oshun.localization.locale_selected`
- `oshun.safety.report_submitted`
- `oshun.release_gate.evaluation_recorded`
- `saraswati.music_sync.drift_measured`

Each event declares owner, surface, consent mode, release-gate metric, non-PII
property definitions, and required payload fields.

## First Captured Events

The launch-readiness fixture captures one first event for every published event
definition. Every captured event carries:

- `schemaVersion: "schema-v3"`
- stable `evt_v3_` event ids
- non-PII tenant and session fixture ids
- an ISO-8601 `capturedAtIso`
- a surface matching the published event definition
- all required properties for the event definition

The fixture covers V3 session start, tier-router decisioning, Tara engagement
telemetry, accessibility mode changes, launch locale selection, safety report
routing, release-gate evaluation, and Saraswati music-sync drift.