# ADR-028: Additive-only for v1, Cast migration when needed

## Status

Accepted

## Context

Graph type schemas will evolve over time. Changes range from adding optional fields (non-breaking) to removing fields or changing types (breaking). The repository layer needs a strategy for handling schema changes.

## Decision

For v1, schema changes should be additive (new optional fields, new types, new enum values). This avoids data migration entirely. When additive-only is insufficient, `Value.Cast` handles common migration cases (adding fields with defaults, type narrowing). Custom migration functions are the consumer's responsibility for breaking changes.

## Consequences

- v1 schemas should only add optional fields and new types
- The `version` field on `graph_types` stays at 1 for additive changes
- Breaking changes require a version bump and migration strategy
- `Value.Cast` is available for common migration cases but is not a migration framework

## References

- [schema-evolution.md](../schema-evolution.md)