Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/rules/data-sync-storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ paths:
This path holds user data. A silent wrong answer here looks exactly like an empty database, so prove late-completion and cancellation behavior with a test.

- **A synced CKRecord type or field reaches CloudKit Production before anything writes it.** Both apps pin the container to Production, where nothing is auto-created, and CloudKit rejects a whole record that carries an undeclared field. Write fields only through `record.fields(SomeSyncField.self)`, never `record["..."]`. To ship one: add it in Development, deploy to Production in the Console, run `apple/scripts/export-cloudkit-schema.sh`, commit `apple/CloudKit/production-schema.ckdb`, then add it to the matching `verifiedInProduction`. `ProductionSchemaParityTests` checks code against the snapshot in both directions, not against the server, so never edit the snapshot by hand: `apple/scripts/export-cloudkit-schema.sh --check` compares it with Production. A tag's `app` job runs `--check-deployed` instead, which fails only on a record type, field, field type, index, role or grant the tag's snapshot has and Production lacks.
- **A storage format stays readable by the previous stable.** Sparkle never downgrades, and a beta user can turn betas off (`apple/RELEASING.md`, Storage check). The one exception is a value the previous stable has no field for, such as a theme color in a slot added after it: that file is written at the oldest schema that holds it, and everything else keeps the old format (`.claude/rules/theme.md`, Model).
- **A storage format stays readable by the previous stable.** Sparkle never downgrades, and a beta user can turn betas off (`apple/RELEASING.md`, Storage check). The one exception is a value the previous stable has no field for, such as a theme color in a slot added after it: that file is written at the oldest schema that holds it, everything else keeps the old format, and its synced record still holds the old format (`.claude/rules/theme.md`, Model and Sync).
- **Persist, then notify.** `SyncChangeTracker.markDeleted()` runs after the storage write, because its notification can start a sync that re-uploads the record from the stale file.
- **Concurrent schema loads await the one in-flight `loadTask`** in `SQLSchemaProvider`; never guard with a flag that returns without data.
- **Every metadata read goes through `DatabaseManager.withMetadataDriver`**, never `MetadataConnectionPool.shared` directly, so an embedded engine with `supportsConnectionPooling = false` (DuckDB, PGlite) stays on its session driver; a second connection to it is a different, empty database.
Expand Down
3 changes: 2 additions & 1 deletion .claude/rules/theme.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@ paths:

## Sync

- **Each user theme syncs as the `AppSettings` record `theme.<id>`** holding `ThemeFileFormat.encode(_:)` bytes. A user edit marks it dirty, a trash marks it deleted once the trash lands, and a load or migration marks nothing. Built-ins never sync.
- **Each user theme syncs as the `AppSettings` record `theme.<id>`**, holding only its schema 3 keys, encoded at schema 3, so the previous stable reads and edits it. A theme that sets a key schema N introduced also syncs `themeSchema<N>.<id>`, holding the whole theme at schema N. An older Mac skips a record it cannot read but keeps it as the merge base, so a single record at the newer schema would be overwritten by its next edit.
- **Each record owns its keys.** Applying `theme.<id>` keeps the local theme's keys newer than 3, and applying `themeSchema<N>.<id>` changes only the keys schema N introduced. A user edit marks both dirty, a trash marks both deleted once the trash lands, and a load or migration marks nothing. Built-ins never sync.
- **A synced theme is untrusted.** `ThemeCatalog.applyRemote(category:data:)` checks the category id (never a built-in), a 64 KB cap, nesting depth, a full decode and the file id, and never writes over bytes it has not read. A validation failure is a logged skip; only a disk failure returns `.failed`, which withholds the change token so the pull replays. A remote delete trashes the file through `removeWithoutSync(ids:)`.
- The light and dark theme ids sync. The appearance mode and fonts are device-local, and a received `appearance` record never changes them.
- `SyncCoordinator.themeContentKind` names `ThemeSchema.current`, so a Mac upgraded past a bump refetches the zone once. After the first full pull, only local themes the server lacks are marked dirty, once.
Loading