Label addition docs: the auto_migrate trap, the migrate_updates contract, the ordering caveat

[0x054]

Parent

Spec: #329.

What to build

The documentation that makes the remaining sharp edge a known edge instead of a production surprise. The auto-migrate docs state loudly that plain auto_migrate never evolves existing objects — enum types included — and that this particular gap is structurally invisible to tests, because fresh schemas always get the complete label set (#328's core finding). migrate_updates=True is documented as the answer, with the label-addition contract spelled out: append-only, warn-never-act for removals, the reviewed-migration exit, and the end-of-order caveat for ORDER BY on enum columns. The Alembic page documents the comparator's behavior.

Examples follow house rules: every field declaration shown in both Assignment and Annotated styles; queries use lambda predicates.

Acceptance criteria

• Auto-migrate docs carry the enum-drift trap prominently, with the fresh-schema/test-invisibility explanation
• Label addition contract documented: gating, append-only scope, warnings, ordering caveat, Alembic exit for removals
• Alembic bridge docs cover the comparator (additions, autocommit wrapping, extra-label comments)
• Examples show both declaration styles and lambda predicates, and pass the docs-examples test seam

Blocked by

• Label addition tracer: missing labels appended under migrate_updates, new member round-trips #330
• Label addition warnings: extra live labels warn-never-act; create pass stays silent #331
• Label addition edges: shared types, default-in-same-run, append ordering, idempotence #332
• Alembic comparator: autogenerate emits label additions from the shared diff, with parity pins #333