C# V4→V5 API Migration Guide

I need help migrating a Ditto C#/.NET application from v4 to v5. Focus on these critical changes:

INITIALIZATION:
Replace `new Ditto(DittoIdentity, string)` with `Ditto.Open(DittoConfig)` or `await Ditto.OpenAsync(DittoConfig)`.
- Create a `DittoConfig` with the constructor: `new DittoConfig(databaseId, connect, persistenceDirectory?)`
- For server/cloud: `new DittoConfig(databaseId: "id", connect: new DittoConfigConnect.Server(new Uri("https://...")))`
- For offline/P2P: `new DittoConfig(databaseId: "id", connect: new DittoConfigConnect.SmallPeersOnly(privateKey: null))`
- For shared key: `new DittoConfig(databaseId: "id", connect: new DittoConfigConnect.SmallPeersOnly(privateKey: "your-shared-key"))`
- The old identity classes (`DittoOfflinePlayground`, `DittoOnlinePlayground`, `DittoOnlineWithAuthentication`, `DittoSharedKey`, `DittoManual`) are all removed
- `DittoIdentityType` enum is removed entirely
- Remove `UpdateTransportConfig` workaround patterns for adding websocket URLs — `DittoConfig` handles the server URL directly. Note: `UpdateTransportConfig()` still exists but signature changed: v4 takes `Action<DittoTransportConfig>`, v5 takes `Action<DittoTransportConfigBuilder>` (builder pattern)
- Remove `DisableSyncWithV3()` calls — v3 protocol is fully dropped in v5
- Remove `await ditto.Store.ExecuteAsync("ALTER SYSTEM SET DQL_STRICT_MODE = false")` — v5 defaults to `false`
- IMPORTANT: If your v4 app used the default (strict=true), set `DQL_STRICT_MODE=true` BEFORE starting sync to maintain v4 behavior. Objects that were replaced whole in v4 will silently merge at field level in v5 without this.
- Use `using var ditto = Ditto.Open(config);` for IDisposable cleanup
- By default, the Transport Config no longer needed to set websocketUrl for Big Peer as this is automatically set by the SDK from the auth server URL.  

NAMESPACE CHANGES:
v5 reorganizes types into sub-namespaces. You will get compile errors until these are updated.
- `DittoSDK.Auth` — `DittoAuthenticator`, `DittoAuthenticationProvider`, `DittoAuthenticationExpirationHandler`
- `DittoSDK.Exceptions` — `DittoException`
- `DittoSDK.Store` — `DittoStoreObserver`, `DittoQueryResult`, `DittoQueryResultItem`
- `DittoSDK.Sync` — `DittoSyncSubscription`
- `DittoSDK.Transport` — `DittoPeer`, `DittoPresenceGraph`, `DittoPresence`, `DittoConnection`, `DittoConnectionType`
- `DittoSDK.Logging` — `DittoLogLevel`, `DittoLogger`
- `DittoSDK.DiskUsage` — `DittoDiskUsageItem`

SYNC:
The sync API moved from top-level Ditto methods to the `Ditto.Sync` sub-object.
- `ditto.StartSync()` → `ditto.Sync.Start()`
- `ditto.StopSync()` → `ditto.Sync.Stop()`
- `ditto.GetTransportDiagnostics()` → removed in v5 (no replacement)
- `ditto.IsSyncActive` → `ditto.Sync.IsActive`

AUTHENTICATION:
The `IDittoAuthenticationDelegate` interface is removed. Replace with `DittoAuthenticationExpirationHandler` async delegate.
- Set `ditto.Auth.ExpirationHandler = async (ditto, timeUntilExpiration) => { ... }` after Ditto.Open()
- The delegate signature is: `Task DittoAuthenticationExpirationHandler(Ditto ditto, TimeSpan timeUntilExpiration)`
- First param is the `Ditto` instance. Access auth via `ditto.Auth.LoginAsync()`
- Second param is `TimeSpan` (not seconds as a number). Check `timeUntilExpiration == TimeSpan.Zero` for initial auth.
- Use `DittoAuthenticationProvider.Development` for playground/dev tokens
- The handler is called when `timeUntilExpiration == TimeSpan.Zero` (initial auth or expired) and when `timeUntilExpiration > TimeSpan.Zero` (token expiring soon). Handle both cases.
- `authenticator.LoginWithToken(token, provider)` → removed, use `ditto.Auth.LoginAsync(token, provider)` instead
- `authenticator.Login(token, provider)` → removed (sync overload gone), use `ditto.Auth.LoginAsync(token, provider)`
- `authenticator.LoginWithCredentials(username, password, provider)` → removed
- `IDittoAuthenticationDelegate.AuthenticationStatusDidChange()` → removed, use `DittoAuthenticator.ObserveStatus()` for cancellable observation
- New: `ditto.Auth.Logout()` — explicit logout support
- New: `DittoAuthenticator.ObserveStatus()` — returns `IDisposable` observer for auth status changes

OBSERVERS — `DittoLiveQuery` → `DittoStoreObserver`:
The legacy `DittoLiveQuery` from collection `.ObserveLocal()` is replaced by `DittoStoreObserver` from `Store.RegisterObserver()`.
- `DittoLiveQuery` type → `DittoStoreObserver`
- `collection.Find("...").ObserveLocal((docs, event) => { ... })` → `store.RegisterObserver("SELECT ...", args, (DittoQueryResult result) => { ... })`
- The callback receives `DittoQueryResult` with `.Items` property (list of `DittoQueryResultItem`)
- `observer.Cancel()` for cleanup (replaces `liveQuery.Stop()`)

BACK PRESSURE (RegisterObserver with signalNext):
Use the `Action<DittoQueryResult, Action>` overload for manual back-pressure control.
- Standard observer: `store.RegisterObserver(query, result => { ... })` — auto-signals after handler returns
- Async observer: `store.RegisterObserver(query, async result => { ... })` — auto-signals after Task completes
- Back-pressure: `store.RegisterObserver(query, args, async (result, signalNext) => { await ...; signalNext(); })` — must call `signalNext()` when ready for next update
- Changes during processing are coalesced — you get the latest state, not every intermediate change

COLLECTION API → DQL:
The entire Collection/Document API is removed. Replace all collection operations with DQL via `Store.ExecuteAsync()`.
- `store.Collection("cars")` → removed. Use `store.ExecuteAsync("SELECT * FROM cars")`
- `collection.FindAll().Exec()` → `await store.ExecuteAsync("SELECT * FROM cars")`
- `collection.Find("color == 'blue'").Exec()` → `await store.ExecuteAsync("SELECT * FROM cars WHERE color = :color", new Dictionary<string, object> { ["color"] = "blue" })`
- `collection.FindById(id).Exec()` → `await store.ExecuteAsync("SELECT * FROM cars WHERE _id = :id", new Dictionary<string, object> { ["id"] = "car-1" })`
- `collection.Upsert(value)` → `await store.ExecuteAsync("INSERT INTO cars DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE", new Dictionary<string, object> { ["doc"] = value })`
- `collection.FindById(id).Update(doc => { doc["color"].Set("green"); })` → `await store.ExecuteAsync("UPDATE cars SET color = :color WHERE _id = :id", new Dictionary<string, object> { ["color"] = "green", ["id"] = "car-1" })`
- `collection.FindById(id).Remove()` → `await store.ExecuteAsync("DELETE FROM cars WHERE _id = :id", new Dictionary<string, object> { ["id"] = "car-1" })`
- `collection.FindById(id).Evict()` → `await store.ExecuteAsync("EVICT FROM cars WHERE _id = :id", new Dictionary<string, object> { ["id"] = "car-1" })`
- `collection.FindAll().Sort("color", DittoSortDirection.Ascending).Limit(20).Offset(40).Exec()` → `await store.ExecuteAsync("SELECT * FROM cars ORDER BY color ASC LIMIT 20 OFFSET 40")`
- `DittoSortDirection` enum is removed — use `ASC`/`DESC` in DQL
- IMPORTANT: `ExecuteAsync` takes `Dictionary<string, object>` for arguments — NOT anonymous objects. `RegisterObserver` and `RegisterSubscription` DO accept anonymous `object` arguments.
- Always use parameterized queries with `:paramName` — NEVER use string interpolation

SUBSCRIPTIONS — `DittoSubscription` → `DittoSyncSubscription`:
- `collection.Find("color == 'red'").Subscribe()` → `ditto.Sync.RegisterSubscription("SELECT * FROM cars WHERE color = :color", new { color = "red" })`
- `DittoSubscription` type → `DittoSyncSubscription`
- `sub.Cancel()` for cleanup
- Note: `RegisterSubscription` accepts anonymous `object` arguments

TRANSACTIONS — `Write()` → `TransactionAsync()`:
- `ditto.Store.Write(tx => { tx.Scoped("cars").Upsert(value); })` → `await ditto.Store.TransactionAsync(async tx => { await tx.ExecuteAsync("INSERT INTO ...", args); })`
- The callback now receives `DittoTransaction` (not `DittoWriteTransaction`) and uses async DQL
- `DittoWriteStrategy.UpdateDifferentValues` is removed — use `ON ID CONFLICT DO MERGE` in DQL

PRESENCE:
- `peer.PeerKeyString` → `peer.PeerKey`
- `peer.Os` (string) → `peer.Os` (DittoPeerOS? — type changed from string to nullable enum)
- `peer.IsDittoCloudConnected` → `peer.IsConnectedToDittoServer`
- `connection.PeerKeyString1` / `PeerKeyString2` → `connection.PeerKey1` / `PeerKey2`
- `connection.ApproximateDistanceInMeters` → **removed, no replacement**
- `DittoPresenceGraph`, `DittoPeer`, `DittoConnection`, `DittoConnectionType` moved to `DittoSDK.Transport` namespace

DITTO CLASS:
- `new Ditto(identity, path)` → `Ditto.Open(config)` or `await Ditto.OpenAsync(config)`
- `ditto.SiteId` → removed (use peer identity from presence graph)
- `ditto.SDKVersion` → use static `Ditto.Version` property
- `ditto.DisableSyncWithV3()` → removed
- `ditto.StartSync()` / `StopSync()` → `ditto.Sync.Start()` / `Stop()`
- `ditto.GetTransportDiagnostics()` → removed

DISK USAGE:
- `ditto.DiskUsage.Exec()` → `ditto.DiskUsage.Item` (property, not method)
- `DittoDiskUsageChild` → `DittoDiskUsageItem` (type renamed)
- Types moved to `DittoSDK.DiskUsage` namespace

LOGGING:
- `DittoLogger.SetLoggingEnabled(true)` → `DittoLogger.IsEnabled = true`

ERRORS:
- `DittoException` moved to `DittoSDK.Exceptions` namespace
- Add `using DittoSDK.Exceptions;` where exceptions are caught

REMOVED APIS (no replacement):
- `DittoLiveQueryEvent.Hash()` — document change hashing removed
- `DittoLiveQueryEvent.HashMnemonic()` — human-readable hash removed
- `DittoWriteStrategy.UpdateDifferentValues` — use `ON ID CONFLICT DO MERGE` in DQL
- `IDittoAuthenticationDelegate.AuthenticationStatusDidChange()` — use `DittoAuthenticator.ObserveStatus()`
- `DittoUpdateResult` (and `Set`, `Removed`, `Incremented` subclasses) — DQL returns row counts only
- `DittoPendingCursorOperation.ObserveLocalWithNextSignal()` — use `RegisterObserver` with `signalNext` overload
- `DittoSmallPeerInfoSyncScope` enum — use `ALTER SYSTEM SET smallPeerInfoSyncScope = '...'`
- `DittoSortDirection` enum — use `ASC`/`DESC` in DQL
- `DittoStore.FetchAttachment(DittoAttachmentFetchDelegate)` — use async `Func`/Task overload
- `DittoIdentityType` enum — replaced by `DittoConfig` constructor with `DittoConfigConnect` types
- `Ditto.DisableSyncWithV3()` — v3 sync dropped
- `Ditto.GetTransportDiagnostics()` — transport diagnostics removed
- `Ditto.SiteId` — use peer identity from presence graph
- `connection.ApproximateDistanceInMeters` — peer distance estimation removed

NEW APIS:
- `Ditto.Open(DittoConfig)` / `Ditto.OpenAsync(DittoConfig)` — factory methods replacing constructor
- `DittoConfig(databaseId, connect, persistenceDirectory?)` — constructor replaces identity classes
- `DittoConfigConnect.Server` / `DittoConfigConnect.SmallPeersOnly` — connect mode types
- `Ditto.Sync.Start()` / `Stop()` — replaces `StartSync()` / `StopSync()`
- `Ditto.Version` (static property) — replaces `Ditto.SDKVersion`
- `Ditto.DeviceName` — custom peer device name (get/set)
- `DittoAuthenticationExpirationHandler` — async delegate replacing `IDittoAuthenticationDelegate`
- `DittoAuthenticator.LoginAsync()` — replaces `LoginWithToken()` / `Login()`
- `DittoAuthenticator.ObserveStatus()` — returns `IDisposable` auth status observer
- `DittoAuthenticator.Logout()` — explicit logout
- `DittoStore.TransactionAsync()` — async DQL transaction replacing `Write()`; uses `DittoTransaction`
- `DittoStoreObserver` — replaces `DittoLiveQuery`
- `DittoQueryResultItem` — single DQL result row with `.Value` property
- `DittoSyncSubscription` — replaces `DittoSubscription`, exposes `QueryString`, `QueryArguments`, `Cancel()`
- `WifiAwareConfig` / `WifiAwareConfigBuilder` — Android Wi-Fi Aware transport config (MAUI)
- `DittoSyncPermissions.RequestPermissionsAsync()` — Bluetooth/Wi-Fi permission requests (MAUI)
- `DittoDiskUsageItem` — replaces `DittoDiskUsageChild`
- `DittoDiskUsage.Item` (property) — replaces `Exec()` method
- `DittoSDK.Auth`, `DittoSDK.Exceptions`, `DittoSDK.Store`, `DittoSDK.Sync`, `DittoSDK.Transport`, `DittoSDK.Logging`, `DittoSDK.DiskUsage` — new sub-namespaces

BEFORE (v4):
```csharp
using DittoSDK;

var ditto = new Ditto(
    identity: DittoIdentity.OnlinePlayground(
        appId: "your-app-id",
        token: "your-token",
        enableDittoCloudSync: false,
        customAuthUrl: "https://your-server.ditto.live"
    )
);

ditto.UpdateTransportConfig(config =>
{
    config.Connect.WebSocketUrls.Add("wss://...");
});
await ditto.Store.ExecuteAsync("ALTER SYSTEM SET DQL_STRICT_MODE = false");
ditto.DisableSyncWithV3();
ditto.StartSync();

// Collection-based CRUD
var collection = ditto.Store.Collection("cars");
collection.Upsert(new Dictionary<string, object>
{
    { "_id", "car-1" }, { "color", "red" }, { "make", "Toyota" }
});
var docs = collection.FindAll().Exec();
collection.FindById(new DittoDocumentId("car-1")).Update(doc =>
{
    doc["color"].Set("blue");
});
collection.FindById(new DittoDocumentId("car-1")).Remove();

// Live query
DittoLiveQuery liveQuery = collection.FindAll()
    .ObserveLocal((docs, dittoCollectionEvent) =>
    {
        UpdateUI(docs);
    });

// Subscription
DittoSubscription sub = collection.Find("color == 'red'").Subscribe();

// Write transaction
ditto.Store.Write(tx =>
{
    tx.Scoped("cars").Upsert(new Dictionary<string, object>
    {
        { "_id", "car-2" }, { "color", "green" }
    });
});

// Cleanup
liveQuery.Stop();
sub.Cancel();
ditto.StopSync();
ditto.Dispose();
```

AFTER (v5):
```csharp
using DittoSDK;
using DittoSDK.Auth;
using DittoSDK.Store;
using DittoSDK.Exceptions;

var config = new DittoConfig(
    databaseId: "your-database-id",
    connect: new DittoConfigConnect.Server(new Uri("https://your-server.ditto.live"))
);

using var ditto = await Ditto.OpenAsync(config);

ditto.Auth.ExpirationHandler = async (ditto, timeUntilExpiration) =>
{
    try
    {
        await ditto.Auth.LoginAsync(
            "your-token",
            DittoAuthenticationProvider.Development);
    }
    catch (DittoException error)
    {
        Console.WriteLine($"Auth failed: {error}, time until expiration: {timeUntilExpiration}");
    }
};

// If maintaining v4 behavior, set strict mode BEFORE starting sync
// await ditto.Store.ExecuteAsync("ALTER SYSTEM SET DQL_STRICT_MODE = true");

ditto.Sync.Start();

// DQL-based CRUD
await ditto.Store.ExecuteAsync(
    "INSERT INTO cars DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE",
    new Dictionary<string, object> { ["doc"] = new Dictionary<string, object> { ["_id"] = "car-1", ["color"] = "red", ["make"] = "Toyota" } });

var result = await ditto.Store.ExecuteAsync("SELECT * FROM cars");

await ditto.Store.ExecuteAsync(
    "UPDATE cars SET color = :color WHERE _id = :id",
    new Dictionary<string, object> { ["color"] = "blue", ["id"] = "car-1" });

await ditto.Store.ExecuteAsync(
    "DELETE FROM cars WHERE _id = :id",
    new Dictionary<string, object> { ["id"] = "car-1" });

// Store observer (replaces live query)
DittoStoreObserver observer = ditto.Store.RegisterObserver(
    "SELECT * FROM cars",
    (DittoQueryResult result) =>
    {
        UpdateUI(result.Items);
    });

// Sync subscription (replaces collection subscription)
DittoSyncSubscription sub = ditto.Sync.RegisterSubscription(
    "SELECT * FROM cars WHERE color = :color",
    new { color = "red" });

// DQL transaction (replaces write transaction)
await ditto.Store.TransactionAsync(async tx =>
{
    await tx.ExecuteAsync(
        "INSERT INTO cars DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE",
        new Dictionary<string, object> { ["doc"] = new Dictionary<string, object> { ["_id"] = "car-2", ["color"] = "green" } });
});

// Cleanup
observer.Cancel();
sub.Cancel();
ditto.Sync.Stop();
// ditto.Dispose() handled by 'using' statement
```

CHECKLIST:

Step 1 — Update Package:
- Update `DittoSDK` NuGet package to v5.x

Step 2 — Fix Namespace Imports:
- Add `using DittoSDK.Auth;` where auth types are used
- Add `using DittoSDK.Exceptions;` where `DittoException` is caught
- Add `using DittoSDK.Store;` for `DittoStoreObserver`, `DittoQueryResult`, `DittoQueryResultItem`
- Add `using DittoSDK.Sync;` for `DittoSyncSubscription`
- Add `using DittoSDK.Transport;` for `DittoPeer`, `DittoConnection`, `DittoPresenceGraph`
- Add `using DittoSDK.Logging;` for `DittoLogger`, `DittoLogLevel`
- Add `using DittoSDK.DiskUsage;` for `DittoDiskUsageItem`

Step 3 — Replace Initialization:
- Replace `new Ditto(identity, path)` with `Ditto.Open(config)` or `await Ditto.OpenAsync(config)`
- Replace identity classes with `new DittoConfig(databaseId, connect)` constructor
- Remove `DittoIdentityType` enum references
- Add `using var` for IDisposable cleanup

Step 4 — Update Sync API:
- Replace `ditto.StartSync()` → `ditto.Sync.Start()`
- Replace `ditto.StopSync()` → `ditto.Sync.Stop()`
- Remove `GetTransportDiagnostics()` calls (removed in v5)
- Remove `ditto.DisableSyncWithV3()` calls
- Set `DQL_STRICT_MODE=true` BEFORE `Sync.Start()` if maintaining v4 strict behavior

Step 5 — Update Authentication:
- Replace `IDittoAuthenticationDelegate` implementations with `DittoAuthenticationExpirationHandler` async delegate
- Handler signature: `Task DittoAuthenticationExpirationHandler(Ditto ditto, TimeSpan timeUntilExpiration)`
- Replace `LoginWithToken()` / `Login()` / `LoginWithCredentials()` → `LoginAsync()`
- Use `DittoAuthenticationProvider.Development` for playground tokens
- Handle `timeUntilExpiration == TimeSpan.Zero` (initial) vs `> TimeSpan.Zero` (refresh)
- Update status observation to `DittoAuthenticator.ObserveStatus()` (returns `IDisposable`)

Step 6 — Replace Collection API with DQL:
- Search for `ditto.Store.Collection(` and replace all with DQL `ExecuteAsync()`
- Replace `.FindAll()`, `.Find(`, `.FindById(` with DQL `SELECT`
- Replace `.Upsert(` with `INSERT INTO ... DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE`
- Replace `.Update(` closures with `UPDATE SET`
- Replace `.Remove()` with `DELETE FROM`
- Replace `.Evict()` with `EVICT FROM`
- Replace `.Sort("field", DittoSortDirection.Ascending).Limit(n).Offset(n)` with `ORDER BY field ASC LIMIT n OFFSET n` in DQL
- Use `Dictionary<string, object>` for `ExecuteAsync` arguments — NOT anonymous objects
- Use parameterized queries — never string interpolation

Step 7 — Replace Live Queries and Subscriptions:
- Replace `DittoLiveQuery` type → `DittoStoreObserver`
- Replace `.ObserveLocal()` → `ditto.Store.RegisterObserver()` with `DittoQueryResult` callback
- Replace `DittoSubscription` → `DittoSyncSubscription`
- Replace `.Subscribe()` → `ditto.Sync.RegisterSubscription()`

Step 8 — Replace Write Transactions:
- Replace `ditto.Store.Write(tx => { })` → `await ditto.Store.TransactionAsync(async tx => { })`
- Replace `tx.Scoped("collection").Upsert(...)` → `await tx.ExecuteAsync("INSERT ...")`
- Note: Callback now receives `DittoTransaction` (not `DittoWriteTransaction`)

Step 9 — Update Renamed Properties and Types:
- `Ditto.SiteId` → removed (use peer identity from presence graph)
- `Ditto.SDKVersion` → use static `Ditto.Version` property
- `DittoDiskUsageChild` → `DittoDiskUsageItem`
- `DittoDiskUsage.Exec()` → `DittoDiskUsage.Item` (property)
- `peer.PeerKeyString` → `peer.PeerKey`
- `peer.IsDittoCloudConnected` → `peer.IsConnectedToDittoServer`
- `connection.PeerKeyString1` / `PeerKeyString2` → `connection.PeerKey1` / `PeerKey2`
- Remove `connection.ApproximateDistanceInMeters` usage (no replacement)
- `peer.Os` type changed from string to `DittoPeerOS?` (nullable enum)

Step 10 — Verify and Test:
- Build compiles with zero errors
- No deprecated API warnings
- DQL strict mode set correctly for your data model
- Auth handler fires before first sync
- Observers receive initial data
- Subscriptions sync data across peers
- Transactions are atomic
- No memory leaks on navigation

Work through the codebase systematically. Show me each file's changes.