feat: add durable provider cache

Add a private provider-neutral SQLite WAL cache with transactional migrations, retained raw payloads and tombstones, per-window opaque checkpoints, and reserved outbox/conflict tables.

Verify migrations, permissions, identity invariants, concurrent access, atomic pull-page rollback, and future-schema rejection with deterministic tests. No OAuth, networking, secrets, or Graph synchronization is included yet.

include/nocal/storage/sync_cache.hpp

@@ -0,0 +1,122 @@
+#pragma once
+
+#include <cstdint>
+#include <filesystem>
+#include <memory>
+#include <span>
+#include <string>
+#include <vector>
+
+namespace nocal::storage {
+
+struct CachedAccount {
+    std::string id;
+    std::string provider;
+    std::string remote_subject;
+    std::string display_name;
+
+    bool operator==(const CachedAccount&) const = default;
+};
+
+struct CachedCalendar {
+    std::string id;
+    std::string account_id;
+    std::string remote_id;
+    std::string name;
+    std::string color;
+    bool read_only{false};
+    bool active{true};
+    std::string raw_payload;
+
+    bool operator==(const CachedCalendar&) const = default;
+};
+
+struct CachedEvent {
+    std::string id;
+    std::string calendar_id;
+    std::string remote_id;
+    std::string uid;
+    std::string etag;
+    std::string change_key;
+    std::string raw_payload;
+    bool deleted{false};
+
+    bool operator==(const CachedEvent&) const = default;
+};
+
+struct CachedEventInstance {
+    std::string id;
+    std::string event_id;
+    std::int64_t start_epoch_microseconds{0};
+    std::int64_t end_epoch_microseconds{0};
+    bool all_day{false};
+    std::string title;
+    std::string location;
+    std::string description;
+    std::string time_zone;
+
+    bool operator==(const CachedEventInstance&) const = default;
+};
+
+struct SyncCheckpoint {
+    std::string calendar_id;
+    std::string window_start;
+    std::string window_end;
+    std::string cursor;
+    bool complete{false};
+
+    bool operator==(const SyncCheckpoint&) const = default;
+};
+
+struct PullPage {
+    std::vector<CachedEvent> events;
+    std::vector<CachedEventInstance> instances;
+    SyncCheckpoint checkpoint;
+
+    bool operator==(const PullPage&) const = default;
+};
+
+struct CacheSnapshot {
+    std::vector<CachedAccount> accounts;
+    std::vector<CachedCalendar> calendars;
+    std::vector<CachedEvent> events;
+    std::vector<CachedEventInstance> instances;
+    std::vector<SyncCheckpoint> checkpoints;
+
+    bool operator==(const CacheSnapshot&) const = default;
+};
+
+class SyncCache {
+public:
+    static constexpr int current_schema_version = 1;
+
+    explicit SyncCache(std::filesystem::path path);
+    ~SyncCache();
+
+    SyncCache(const SyncCache&) = delete;
+    SyncCache& operator=(const SyncCache&) = delete;
+    SyncCache(SyncCache&&) noexcept;
+    SyncCache& operator=(SyncCache&&) noexcept;
+
+    [[nodiscard]] const std::filesystem::path& path() const noexcept;
+
+    void upsert_account(const CachedAccount& account);
+
+    // Call only after a provider calendar listing has completed. Calendars
+    // omitted from the completed listing are retained but marked inactive.
+    void replace_calendars_after_complete_listing(
+        std::string account_id, std::span<const CachedCalendar> calendars);
+
+    // Applies one provider page and advances its opaque cursor in the same
+    // transaction. Instances for each changed event are replaced; tombstoned
+    // events retain their last raw payload and have no instances.
+    void apply_pull_page(const PullPage& page);
+
+    [[nodiscard]] CacheSnapshot snapshot() const;
+
+private:
+    struct Impl;
+    std::unique_ptr<Impl> impl_;
+};
+
+} // namespace nocal::storage