From e5bf9550a43eccf6e3eda5daadb076d798eb8aed Mon Sep 17 00:00:00 2001 From: Matt Bruce Date: Fri, 16 Jan 2026 16:59:58 -0600 Subject: [PATCH] Signed-off-by: Matt Bruce --- Proposal.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Proposal.md b/Proposal.md index eb515d9..081ec70 100644 --- a/Proposal.md +++ b/Proposal.md @@ -18,6 +18,7 @@ Create a single, typed, discoverable namespace for persisted app data with consi ### Core Components - **StorageKey** protocol - Defines storage configuration for each data type +- **StorageKey.migration** - Optional protocol-based migration attached to a key - **StorageRouter** actor - Main entry point coordinating all storage operations - **StorageProviding** protocol - Abstraction for storage operations - **StorageKeyCatalog** protocol - Catalog of keys for auditing/validation @@ -47,6 +48,10 @@ Each helper is a dedicated actor providing thread-safe access to a specific stor - **AnyStorageKey** - Type-erased storage key for catalogs - **AnyStorageMigration** - Type-erased migration for protocol-based workflows - **AnyCodable** - Type-erased Codable for mixed-type payloads +- **MigrationContext** - Context for conditional migrations (app version, device, system info) +- **MigrationResult** - Migration outcome with errors and metadata +- **MigrationError** - Error types for migration failures +- **DeviceInfo / SystemInfo** - Device and system metrics used by migrations ## Usage Pattern Apps extend StorageKeys with their own key types and use StorageRouter.shared. This follows the Notification.Name pattern for discoverable keys. @@ -62,6 +67,14 @@ The `StorageRouter` provides discovery APIs to retrieve all registered keys for ## Sync Behavior StorageRouter can call WCSession.updateApplicationContext for manual or automaticSmall sync policies when availability allows it. Session activation and receiving data are owned by the app. +### Bootstrapping and Watch Requests +LocalData exposes helper APIs to make watch sync reliable after relaunch or reconnection: + +- `StorageRouter.syncRegisteredKeysIfNeeded()` re-sends stored values for eligible keys. +- `StorageRouter.syncSnapshot()` returns a payload snapshot for replying to watch requests. + +Apps should call `syncRegisteredKeysIfNeeded()` on launch and on WatchConnectivity reachability changes, and reply to watch-initiated requests with `syncSnapshot()` to avoid launch-order issues. + ## Platforms - iOS 17+ - watchOS 10+ @@ -69,5 +82,6 @@ StorageRouter can call WCSession.updateApplicationContext for manual or automati ## Future Ideas (Not Implemented) - Key rotation strategies for encrypted data - Watch-optimized data representations +- Persistent storage for sync policy overrides Any future changes should keep LocalData documentation in sync with code changes.