From b4559921673b776bb2ecc30bb507b1e6392a4921 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Wed, 11 Nov 2026 19:28:51 +0700 Subject: [PATCH] docs(theme): sync a theme's newer keys in a record of their own --- .claude/rules/data-sync-storage.md | 2 +- .claude/rules/theme.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.claude/rules/data-sync-storage.md b/.claude/rules/data-sync-storage.md index b26e10e85f..e49dd41663 100644 --- a/.claude/rules/data-sync-storage.md +++ b/.claude/rules/data-sync-storage.md @@ -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. diff --git a/.claude/rules/theme.md b/.claude/rules/theme.md index 6c4975a2dd..593c071b66 100644 --- a/.claude/rules/theme.md +++ b/.claude/rules/theme.md @@ -55,7 +55,8 @@ paths: ## Sync -- **Each user theme syncs as the `AppSettings` record `theme.`** 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.`**, 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.`, 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.` keeps the local theme's keys newer than 3, and applying `themeSchema.` 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.