Schema evolution

In one line: the schema lives in the database, so changing a component is a real, versioned, migrated operation — not undefined behaviour.

The model from your side is deliberately simple: change the struct (add a field, widen int→long, …), bump the [Component] revision (("Skirmish.Health", 1) → 2), and reopen. The engine compares the persisted schema against the runtime schema and migrates the stored data before your code runs. For changes it can't infer (a field computed from old data) you supply a migration function.

Reopening with a changed struct and no revision bump — or with an older app than wrote the data — is caught, not silently accepted (SchemaValidationException / SchemaDowngradeException). Only Versioned components carry the history migration relies on.

How it relates

• Component — evolution is versioned per component, keyed on its [Component] revision.
• Storage mode — migration is a Versioned-layout operation.
• Archetype — archetype membership is part of the persisted schema.
• DatabaseEngine — migration runs at Open, before the first read.

In the API

• SchemaChangeKind — the classification of a detected schema change.
• SchemaHistoryR1 — the persisted schema-history record.

Learn & use

• Narrative: Guide ch.2 §3 — evolution
• Feature detail: schema · compatible evolution · migration functions