# AEDB Migration System
## Purpose
Migrations are for structural engine changes that require AEDB action, not for every schema edit in application code.
## Core rule
With tagged-field serialization, adding/removing state/event fields is schema evolution handled by the format:
- unknown tags are ignored
- missing tags deserialize to defaults
- no startup rewrite required
Because of that, **field add/remove does not require a migration entry**.
## What requires a migration entry
- Create or drop state
- Create or drop event
- Create or drop processor
- Add or drop index
- Field type changes that require transform logic
- Field renames (tag/name alias mapping)
## Tagged-field rules
- Tags are never reused.
- Dropped fields retire their tag permanently.
- New fields must have a sensible default (or use `Option<T>`).
- Derive macros must reject duplicate tag definitions at compile time.
## Startup behavior
AEDB executes unapplied migrations in version order before serving traffic.
Applied metadata is tracked internally (`version`, `name`, timestamp/checkpoint metadata).
## Background migration tasks
Some migrations can complete asynchronously:
- Index backfill: index is marked building; writes maintain it immediately; queries can fail as not-ready until complete.
- Optional rewrite sweep for expensive type transforms on cold data.
## WAL replay compatibility
WAL replay must remain valid across migration versions:
- each WAL entry includes the schema version active at write time
- replay resolves the versioned schema chain and applies forward transforms when needed
If schema changes are additive-only (new tagged fields), replay works without special migration transforms.