# CloudKit Schema Guardrails (SwiftData)

Use this checklist before changing any `@Model` used by SwiftData + CloudKit.

## Why

CloudKit-backed SwiftData is additive-first. Breaking schema edits can stop sync or cause migration failures on user devices with existing data.

## Safe Changes

- Add a new model type.
- Add a new property that is optional or has a default value.
- Add a new optional relationship.
- Add new computed properties (no storage impact).
- Add new methods/helpers/extensions.

## Risky / Avoid Changes

- Do not use `@Attribute(.unique)`.
- Do not remove stored properties that have shipped.
- Do not rename stored properties that have shipped.
- Do not change stored property types after shipping.
- Do not make optional relationships non-optional.

## If You Need a Breaking Change

1. Add a new property with a new name (keep old property).
2. Migrate values in app code lazily at runtime.
3. Ship at least one version with both old+new properties.
4. Only consider cleanup after all active users have migrated.

## Model Rules for This App

- Every stored property in `@Model` should be optional or have a default.
- Relationships must stay optional for CloudKit compatibility.
- Keep derived state computed (single source of truth).

## Pre-merge Checklist

- [ ] `xcodebuild ... build` succeeds.
- [ ] Existing sample/create/edit/delete flows still work.
- [ ] At least one device signed into iCloud verifies sync behavior.
- [ ] No schema-breaking edits were introduced.

## Operational Notes

- First sync on a fresh install can take time.
- CloudKit conflicts are generally last-writer-wins.
- Keep mutation methods centralized in state/store types to reduce conflict bugs.