# Telemetry Schema Migrations

Phase 72.5.1.9 adds `@v2/telemetry-schema-migrations`, the additive schema
migration tooling used before new telemetry event types or optional payload
fields reach emitters.

## Compatibility Policy

`createTelemetrySchemaMigrationPlan` and `validateTelemetrySchemaMigrationPlan`
enforce the `v2-telemetry-schema-migrations-additive-v1` policy. Minor and patch
updates may add event types, add optional fields, deprecate fields, or document
fields. Breaking changes require a new wire major, and `remove-required-field`
is always rejected.

Plans must keep `minReaderSchemaMajor <= target wire major`. Release gates must
prove `readerSkipsUnknownFields`, `warehouseToleratesUnknownTopics`, ingestion
accepts additive payload fields, and rollback is documented.

## Registry And Batch Applier

`TelemetrySchemaRegistry` registers the standard taxonomy schemas from
`@v2/telemetry-ingestion` and accepts additive event definitions after a plan
passes validation. Duplicate topic and payload schema versions are rejected.

`applyTelemetrySchemaMigrationsToBatch` can add optional payload defaults to a
`TelemetryEventBatch`. By default it preserves the existing reader-compatible
wire version; `emitTargetWireVersion: true` is reserved for deployments where
new readers have already rolled out.

Targeted verification:

```bash
pnpm --filter @v2/telemetry-schema-migrations run typecheck
pnpm --filter @v2/telemetry-schema-migrations run test
python V2/ue/Tools/check-v2-telemetry-schema-migrations.py
```