[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C5845MAD3AEBNSN3BT61WH":3,"skill-same:01M6C5845MAD3AEBNSN3BT61WH":64},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":22,"linkOnly":23,"markdownContent":24,"markdownBody":25,"frontMatter":26,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":14,"repositoryHtmlUrl":30,"repositoryHomepageUrl":31,"ownerHtmlUrl":32,"ownerBlogUrl":33,"ownerDescription":34,"updatedAt":35,"install":36,"resources":49},"01M6C5845MAD3AEBNSN3BT61WH","sdk-setup",null,"Ditto SDK setup, lifecycle, and production security (Flutter, JavaScript, Kotlin, Swift): DittoConfig, the authentication expiration handler, system parameters, sync start and stop, close, transports, presence, keys, permissions, revocation. Use when initializing Ditto, writing Ditto login, startup, shutdown, or background code, configuring Ditto transports, reviewing Ditto security, or when Ditto sync never starts or devices do not connect.","ditto-examples\u002Fditto-cookbook","ditto-examples","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F192611150?v=4","01M6C57F0Y1W6S5D9RD8GHE3YB","Ditto Examples","01M6C57F52Z11DDMBC0ZJ7FJPG",0,"MIT","https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Fsdk-setup\u002FSKILL.md",[],[19,20,21],"sdk","setup","sdk setup","2026-11-10 10:12:30",false,"---\nname: sdk-setup\ndescription: \"Ditto SDK setup, lifecycle, and production security (Flutter, JavaScript, Kotlin, Swift): DittoConfig, the authentication expiration handler, system parameters, sync start and stop, close, transports, presence, keys, permissions, revocation. Use when initializing Ditto, writing Ditto login, startup, shutdown, or background code, configuring Ditto transports, reviewing Ditto security, or when Ditto sync never starts or devices do not connect.\"\n---\n\n# Ditto SDK Setup, Lifecycle, and Security\n\nOpening Ditto, authenticating, starting and stopping sync, shutting down, transports and presence, and securing a production deployment. Targets Ditto SDK 5.2.0 in every SDK; the code for each SDK is on its page.\n\n## Before You Apply\n\n- Identify the project's SDK and version: Flutter (`ditto_live` in `pubspec.yaml` \u002F `pubspec.lock`), JavaScript (`@dittolive\u002Fditto` in `package.json`), Kotlin (`com.ditto:ditto-kotlin` in Gradle files), or Swift (`DittoSwift` in `Package.swift`, `Package.resolved`, or the Xcode project). These rules target SDK 5.2.0; for devices that still run 5.1.0, also apply `§ Known Issues in SDK 5.1.0`. **Note (SDK 5.1.0 and 5.2.0)** and **Note (SDK 5.1.0)** mark easy-to-miss behavior seen on those releases, with the safe pattern; **(SDK 5.1+)** \u002F **(SDK 5.2+)** mark features introduced in that release.\n- For API calls, Grep the outline of that SDK's page, `${CLAUDE_SKILL_DIR}\u002F..\u002Fguide\u002Freference\u002Fbest-practices\u002Fplatforms\u002F\u003Csdk>.md` (`flutter`, `javascript`, `kotlin`, `swift`), with `^#{1,3} ` and read only the section you need, not the whole page; sections are named `\u003CTopic> in \u003CSDK>`.\n- `§ \u003CHeading>` cites the full guide: Grep the heading as a fixed string in `best-practices\u002F` and `knowledge\u002F` under `${CLAUDE_SKILL_DIR}\u002F..\u002Fguide\u002Freference\u002F`, then read that section.\n- Report each finding at the severity of its item in `§ Anti-Pattern Checklist` (the checklist decides; Grep a phrase of the item there). The labels below rank the rules, not each item in them.\n\n## Prevents\n\n- A second open of an open persistence directory; a Swift instance released while in use\n- Small-peers-only without a private key; hardcoded keys or tokens; the development token in a release build\n- Errors escaping the authentication expiration handler; unchecked login results\n- System parameters assumed to persist, set with `ALTER SYSTEM` after open, or changed after sync has started\n- Closing Ditto in the background; a transport configuration built from scratch; TCP hubs with more than six clients\n- Secrets or personal data in peer metadata; presence recorded in documents on every callback\n- Access control via mutable fields, `syncGroup`, or client checks; revocation checking disabled\n\n## Workflow\n\nApp startup order (`§ Complete app startup`; the service for each SDK: *App startup in \u003CSDK>* on the SDK page):\n\n```\nStartup:\n- [ ] 1. Configure the logger before opening (Flutter: await Ditto.init() first)\n- [ ] 2. Open the single shared instance with DittoConfig(..., system parameters); share it\n- [ ] 3. Server: set the expiration handler | Small peers: setOfflineOnlyLicenseToken(token)\n- [ ] 4. CREATE INDEX IF NOT EXISTS ... (skip on in-memory stores)\n- [ ] 5. Long-lived ditto.sync.registerSubscription(...)\n- [ ] 6. ditto.sync.start()\n- [ ] If a step after 2 fails: close the instance, then report the error\n- [ ] SDK 5.1: ALTER SYSTEM SET ... after step 3, before step 6\n```\n\n| | Flutter | JavaScript | Kotlin | Swift |\n|---|---|---|---|---|\n| Open | `await Ditto.open(DittoConfig(...))` | `await Ditto.open(config)` (Web: `await init()` first) | `DittoFactory.create(config)` | `try await Ditto.open(config:)` |\n| Start sync | `ditto.sync.start()` (`void`; throws) | `ditto.sync.start()` | `ditto.sync.start()` (throws) | `try ditto.sync.start()` |\n| Login failure | `AuthResponse.exception`; does not throw | Result `error`; does not throw | **Throws** | Completion handler `error` |\n\nMore: `§ Platform Differences`.\n\n## Rules\n\n### 1. Open Ditto once and share the instance (CRITICAL)\n\nOnly one `Ditto` instance can use a persistence directory at a time. What a second open of an open directory does differs by SDK; never rely on it to fail.\n> **Note (SDK 5.1.0):** In Flutter, `Ditto.open()` on a directory that is already open may never complete instead of throwing.\n\n**✅ DO**: open at app start and pass the instance through DI or a service; let concurrent callers wait for one pending open (reset it on failure); where a tool restarts your code without ending the process (Flutter hot restart), use a new `persistenceDirectory` per start in debug builds, and a fixed one in release.\n**❌ DON'T**: open per screen or request; reopen before closing has completed; touch, partly delete, or copy the persistence directory (sync silently diverges); in Swift, hold only `ditto.store` or `ditto.sync` (they reference `Ditto` weakly; without a strong reference the instance shuts down at once).\n\nFlutter: `Ditto.open()` initializes the SDK (SDK 5.1+); call `await Ditto.init()` first only before `Ditto.openSync()`, `DittoLogger`, or `Ditto.defaultRootDirectory`, or for custom Web asset URLs.\n\n`§ One instance per persistence directory`, `§ Opening Ditto in Flutter`, `§ Opening Ditto in Swift` · Example: *One shared instance in \u003CSDK>* on the SDK page\n\n### 2. Choose the connection mode deliberately (CRITICAL)\n\n| Connection (Flutter name) | Use for | Peer authentication |\n|---|---|---|\n| Server URL (`DittoConfigConnectServer(url: ...)`) | Production with real users | Webhook login; TLS |\n| Small peers with a key (`DittoConfigConnectSmallPeersOnly(privateKey: key)`) | Small peers only (closed networks) | Shared key; TLS 1.3 |\n| Small peers without a key (the default) | Local store tests, development | **None**; documented as unencrypted |\n\n**✅ DO**: copy the Server URL from the Ditto Portal exactly; check no placeholder `databaseID` remains (`open()` may not reject it); in small-peers mode pass a base64 P-256 PKCS#8 DER `privateKey` from secure provisioning (MDM) and call `setOfflineOnlyLicenseToken(token)` before you start sync; roll out a new key to all devices together.\n**❌ DON'T**: ship the keyless mode; hardcode keys, tokens, or API keys (binaries can be decompiled); use a shared key when you need per-user permissions or single-device revocation.\n\n`§ DittoConfig`, `§ Small-Peers-Only Deployments` · Code: *DittoConfig in \u003CSDK>* · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#small-peers-only-deployments)\n\n### 3. Set a non-throwing expiration handler before sync starts (CRITICAL)\n\nWith a server connection, starting sync fails until a handler is set. It runs before the first login and when credentials near or pass expiry. How `login` reports failure differs by SDK (*Login failure* above): Kotlin **throws**.\n\n**✅ DO**: set the handler before you start sync; fetch a fresh token inside it; check the login result the way your SDK reports it; catch your own errors.\n**❌ DON'T**: let an error escape from the handler (Ditto does not receive it, and it becomes unhandled); cache one token for the app's lifetime; ship the development provider or the Portal development token.\n\n`auth.logout()` **stops sync**; start it again after the next login. Logout with a cleanup callback (SDK 5.2+) runs after sync stops and may only `EVICT`; it swallows exceptions, so verify the result.\n\n`§ Authentication`, `§ Authentication in Production` · Code: *Authentication in \u003CSDK>* · Details: [reference\u002Fstartup-and-lifecycle.md](reference\u002Fstartup-and-lifecycle.md#authentication)\n\n### 4. Pass system parameters in DittoConfig on every open (CRITICAL)\n\nSystem parameters are in memory only and reset on restart or reopen. The system parameters of `DittoConfig` (SDK 5.2+) are applied before Ditto starts, so startup-only parameters take effect, and an unknown name or a wrong type makes opening fail. Startup-only parameters set later with `ALTER SYSTEM` have no effect.\n\n**✅ DO**: pass the app's settings in one map on every open; use `ALTER SYSTEM` only to change a value while the app runs; confirm with `SHOW \u003Cparameter>`. On SDK 5.1: `ALTER SYSTEM` after opening and before sync starts, queries, or observers (subscriptions may come first).\n**❌ DON'T**: run `ALTER SYSTEM` once in a migration; change `DQL_STRICT_MODE` (default `false`) after sync, queries, or observers have run.\n\n`§ Applying System Parameters`, `§ System Parameters Reference`, `§ Strict Mode` · Code: *DittoConfig in \u003CSDK>* on the SDK page\n\n### 5. Start sync after its prerequisites; never close on background (CRITICAL)\n\nStarting sync fails without the expiration handler or license token; it does nothing if already active (`sync.isActive`). After `sync.stop()` the local store stays usable, connections close, subscriptions stay registered, and changes sync after `start()`. Flutter's `start()` and `stop()` return `void` (do not await).\n\n**✅ DO**: keep Ditto open in the background; if the app must not sync there, stop sync when the app goes to the background and restart on return only the sync you paused.\n**❌ DON'T**: close Ditto when the app goes to the background: closing is final, later calls fail, and every subscription and observer must be re-created.\n\nBackground sync: iOS is best-effort and needs the Bluetooth central and peripheral background modes; Android needs Ditto's foreground service in `AndroidManifest.xml`.\n\n`§ Starting and Stopping Sync` · Code: *Sync and the App Lifecycle in \u003CSDK>* on the SDK page\n\n### 6. Change transports with updateTransportConfig (CRITICAL)\n\nA new, empty transport configuration has **every transport disabled**, including the peer-to-peer transports a default instance enables. The Server URL is used automatically.\n\n**✅ DO**: `ditto.updateTransportConfig`, changing only what you need (all peer-to-peer transports, `peerToPeer.bluetoothLE`, `listen.tcp`, `connect.tcpServers`).\n**❌ DON'T**: assign a fresh transport configuration (Flutter: `TransportConfig()`); treat `global.syncGroup` as a security boundary.\n\nInvalid values do not throw; they only log. WebSocket sync between Small Peers is off by default; enable it only with TLS. Use Multicast (Beta) (SDK 5.1+) only with Ditto support.\n\n`§ Transport Configuration`, `§ Multicast (Beta) (SDK 5.1+)` · Code: *Transports and Presence in \u003CSDK>* · Details: [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md)\n\n### 7. Raise the TCP connection limit on hubs with more than six clients (CRITICAL)\n\n> **Note (SDK 5.1.0 and 5.2.0):** A device accepts 6 TCP connections by default (`MESH_CHOOSER_MAX_WLAN_CONNECTIONS`). In testing, extra clients got no data and no API error; only a `WARN` log `... at capacity for this transport`. On 5.2.0, connections it opened itself also count when it accepts one, so a hub that also dials out admits fewer.\n\n**✅ DO**: on the hub, pass `MESH_CHOOSER_MAX_WLAN_CONNECTIONS` (for example 12) in the system parameters of `DittoConfig` on every open (SDK 5.2+); on SDK 5.1, `ALTER SYSTEM` after opening and **before** sync starts.\n**❌ DON'T**: raise it after sync started (rejected clients stayed out in testing).\n\n`§ Transport Configuration` · Details: [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md#transport-configuration)\n\n### 8. Keep metadata non-sensitive; record presence sparingly (CRITICAL)\n\n`ditto.presence.peerMetadata` and the webhook's `identityServiceMetadata` reach every peer in the mesh.\n\n**✅ DO**: keep peer metadata small (max 4096 bytes encoded; larger throws), set once at startup; `stop()` presence observers when their screen goes away.\n**❌ DON'T**: put secrets, tokens, or personal data in either; treat self-set `peerMetadata` as a security check.\n**Recording presence (HIGH)**: write a peer only when its stored time is older than the needed precision, in one transaction, not per callback; keep writers of one peer from writing at once (e.g. random timers); never write from the observer that reads the record.\n\n`§ Presence`, `§ Recording presence in documents`, `§ Identity metadata is visible to the mesh` · Code: *Transports and Presence in \u003CSDK>* · Details: [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md#presence)\n\n### 9. Enforce access with webhook permissions scoped by _id (CRITICAL)\n\nThe webhook returns per-collection `read` and `write` rules (each with `everything` and `queriesByCollection`) that can reference only `_id`, in legacy syntax (`_id.storeId == 'store-1'`; `\"true\"` matches all), not DQL.\n\n**✅ DO**: encode access boundaries (user, store, organization) in a structured `_id` before shipping; grant the narrowest rules per role; reject unknown users with `{\"authenticated\": false}`; keep `expirationSeconds` moderate so permission changes arrive on re-authentication; account for relaying: peer-to-peer data needs mutual write permission, so read-only roles cannot relay it.\n**❌ DON'T**: rely on mutable fields, `syncGroup`, sync scopes, or client checks; embed long-lived secrets to mint tokens on the device.\n\n`§ Permissions`, ``§ Design `_id` for permission scoping``, `§ Write authority and peer-to-peer relaying` · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#permissions)\n\n### 10. Revoke by rejecting in the webhook first (CRITICAL)\n\nCertificate revocation (SDK 5.1+) covers server-authenticated identities only and certificates issued before it; it is permanent.\n\n**✅ DO**: reject the identity in the webhook, then revoke via the Ditto Server HTTP API; keep `PEER_CERTIFICATE_REVOCATION_CHECK_ENABLED` enabled (default).\n**❌ DON'T**: disable revocation checking in production; expect revocation with a shared key.\n\n`§ Certificate Revocation (SDK 5.1+)` · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#certificate-revocation-sdk-51)\n\n### 11. Validate input, protect data at rest, secure the webhook (CRITICAL)\n\nOnly Swift and Kotlin can encrypt the local store at rest (SDK 5.2+): a 32-byte key in `DittoConfig.encryptionKey` on every open, kept in the Keychain or Android Keystore; switching an existing store means deleting it (`deleteStore`) and syncing again.\n\n**✅ DO**: validate before writes and pass values as `:parameters`; treat peer documents as untrusted; without Ditto encryption, rely on OS protection and encrypt sensitive fields in the app (keys in secure storage); serve the webhook over HTTPS, validate tokens, and verify the `ditto-signature` header.\n**❌ DON'T**: interpolate input into DQL; store tokens or keys in documents.\n\n`§ Input Validation and Query Parameters`, `§ Data at Rest`, `§ Webhook Security` · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#data-at-rest)\n\n### 12. Shut down in order, only when the app is done with Ditto (HIGH; CRITICAL in Flutter)\n\nRelease observers, subscriptions, presence and transport-condition observers, fetchers, and the connection request handler explicitly. Closing is final, stops sync, and releases resources, but **does not** wait for unsent changes. In-flight work: Flutter fails pending `execute()` calls, and stops the isolate if a transaction is open (on 5.2.0, reopening in the same process can also stop: `§ Changes in SDK 5.2.0`); JavaScript and Kotlin wait; Swift has no `close()` (5.1.0, 5.2.0): releasing the last reference shuts Ditto down and waits for an open transaction. Flutter's `close()` also does not end `changes` streams and **resets** `DittoLogger.customLogCallback`.\n\n**✅ DO**: await pending work (if data must reach a peer, its confirmed commit ID), release observers, then close. A growing count in `ditto.store.observers` across screens reveals observers never released.\n**❌ DON'T**: rely on garbage collection; send the Flutter `Ditto` or `Store` to another isolate.\n\n`§ Resource Cleanup and Shutdown`, `§ Forwarding logs to your own pipeline` · Code: *Closing Ditto in \u003CSDK>* on the SDK page\n\n### 13. Filter connections with a fast, non-throwing handler (MEDIUM; CRITICAL in Kotlin)\n\n`ditto.presence.connectionRequestHandler` returns `allow` or `deny` within 10 s, or the peer is rejected; catch every error (a throw ends a Kotlin app).\n\n**✅ DO**: catch errors and return `deny` at once; keep permissions as the primary control.\n\n`§ Controlling Incoming Connections` · Code: *Transports and Presence in \u003CSDK>* · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#controlling-incoming-connections)\n\n### 14. Plan for platform requirements and Web limits (MEDIUM)\n\nPin the exact SDK version; request Bluetooth, Wi-Fi, local network, and nearby-device permissions before sync. Android, SDK 5.2+: multicast permissions are requested separately. Flutter 5.2: the root is application support, also for a relative `persistenceDirectory`, so pass the absolute 5.1 path or 5.1 data is not found. Flutter Web and the JavaScript SDK in browsers: in-memory store, no indexes; Flutter Web syncs only over WebSocket with Ditto Server.\n\n`§ Requirements`, `§ DittoConfig`, `§ Upgrading from SDK 5.1` · Code: *Installing the \u003CSDK> SDK* · Details: [reference\u002Fstartup-and-lifecycle.md](reference\u002Fstartup-and-lifecycle.md#requirements)\n\n## Diagnose: Sync Never Starts or Devices Do Not Connect\n\n| Symptom | Cause |\n|---|---|\n| Opening fails with system parameters | Unknown name or wrong type (rule 4) |\n| `start()`: \"an authentication expiration handler has not yet been set\" | No handler (rule 3) |\n| `start()`: \"...not yet activated\" | No offline license token (small peers) |\n| \"The license failed verification\" | `setOfflineOnlyLicenseToken` fails: invalid token; a peer without a valid token is invisible |\n| Server login fails silently | Unchecked login result (rule 3) |\n| Sync stopped after sign-out | `logout()` stops sync |\n| `WARN` `BadSignature` \u002F `DecryptError` | Mismatched shared keys |\n| `WARN` `at capacity for this transport` | Hub TCP limit (rule 7) |\n| No peers, no error | Fresh transport configuration, missing permissions, radios off: observe transport conditions; check Android permissions (SDK 5.1+) |\n| `TRANSPORTS_DISCOVERED_PEERS` connects nothing | LAN transport disabled; use `connect.tcpServers` |\n| No relay through a middle device | It lacks write permission |\n\n`§ Diagnosing transport problems (SDK 5.1+)`, `§ When Data Does Not Sync` · Details: [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md#diagnosing-transport-problems-sdk-51)\n\n## Checklist\n\n- [ ] One shared instance (Swift: a strong reference to `Ditto` itself); failed startup closes it\n- [ ] Server + webhook, or small peers with provisioned `privateKey` and license token\n- [ ] No keys, tokens, or development provider in release builds\n- [ ] Expiration handler set before `sync.start()`; checks the login result the way the SDK reports it (*Login failure* above); never throws\n- [ ] System parameters in `DittoConfig.systemParameters` on every open (5.1: `ALTER SYSTEM` before sync)\n- [ ] Sync started after its prerequisites (Flutter: `start()` not awaited); no `close()` when the app goes to the background\n- [ ] Pending work awaited and observers cancelled before `close()`\n- [ ] Transports via `updateTransportConfig()`; hub TCP limit raised before sync\n- [ ] No secrets in peer or identity metadata\n- [ ] Permissions scoped by `_id`, narrowest per role; revocation checking on\n- [ ] Inputs parameterized; sensitive data encrypted (store key on Swift\u002FKotlin, or fields); webhook signatures verified\n\n## More\n\n- Reference: [reference\u002Fstartup-and-lifecycle.md](reference\u002Fstartup-and-lifecycle.md) (requirements, `DittoConfig`, startup, auth, system parameters, shutdown), [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md) (transports, TCP hubs, diagnostics, presence), [reference\u002Fsecurity.md](reference\u002Fsecurity.md) (keys, webhook, `_id` design, revocation, data at rest)\n- Related skills: `query-sync` (subscriptions), `performance-observability` (logging, diagnostics), `storage-lifecycle` (tombstone parameters), `testing` (local store tests), `audit` (whole-app review)\n","# Ditto SDK Setup, Lifecycle, and Security\n\nOpening Ditto, authenticating, starting and stopping sync, shutting down, transports and presence, and securing a production deployment. Targets Ditto SDK 5.2.0 in every SDK; the code for each SDK is on its page.\n\n## Before You Apply\n\n- Identify the project's SDK and version: Flutter (`ditto_live` in `pubspec.yaml` \u002F `pubspec.lock`), JavaScript (`@dittolive\u002Fditto` in `package.json`), Kotlin (`com.ditto:ditto-kotlin` in Gradle files), or Swift (`DittoSwift` in `Package.swift`, `Package.resolved`, or the Xcode project). These rules target SDK 5.2.0; for devices that still run 5.1.0, also apply `§ Known Issues in SDK 5.1.0`. **Note (SDK 5.1.0 and 5.2.0)** and **Note (SDK 5.1.0)** mark easy-to-miss behavior seen on those releases, with the safe pattern; **(SDK 5.1+)** \u002F **(SDK 5.2+)** mark features introduced in that release.\n- For API calls, Grep the outline of that SDK's page, `${CLAUDE_SKILL_DIR}\u002F..\u002Fguide\u002Freference\u002Fbest-practices\u002Fplatforms\u002F\u003Csdk>.md` (`flutter`, `javascript`, `kotlin`, `swift`), with `^#{1,3} ` and read only the section you need, not the whole page; sections are named `\u003CTopic> in \u003CSDK>`.\n- `§ \u003CHeading>` cites the full guide: Grep the heading as a fixed string in `best-practices\u002F` and `knowledge\u002F` under `${CLAUDE_SKILL_DIR}\u002F..\u002Fguide\u002Freference\u002F`, then read that section.\n- Report each finding at the severity of its item in `§ Anti-Pattern Checklist` (the checklist decides; Grep a phrase of the item there). The labels below rank the rules, not each item in them.\n\n## Prevents\n\n- A second open of an open persistence directory; a Swift instance released while in use\n- Small-peers-only without a private key; hardcoded keys or tokens; the development token in a release build\n- Errors escaping the authentication expiration handler; unchecked login results\n- System parameters assumed to persist, set with `ALTER SYSTEM` after open, or changed after sync has started\n- Closing Ditto in the background; a transport configuration built from scratch; TCP hubs with more than six clients\n- Secrets or personal data in peer metadata; presence recorded in documents on every callback\n- Access control via mutable fields, `syncGroup`, or client checks; revocation checking disabled\n\n## Workflow\n\nApp startup order (`§ Complete app startup`; the service for each SDK: *App startup in \u003CSDK>* on the SDK page):\n\n```\nStartup:\n- [ ] 1. Configure the logger before opening (Flutter: await Ditto.init() first)\n- [ ] 2. Open the single shared instance with DittoConfig(..., system parameters); share it\n- [ ] 3. Server: set the expiration handler | Small peers: setOfflineOnlyLicenseToken(token)\n- [ ] 4. CREATE INDEX IF NOT EXISTS ... (skip on in-memory stores)\n- [ ] 5. Long-lived ditto.sync.registerSubscription(...)\n- [ ] 6. ditto.sync.start()\n- [ ] If a step after 2 fails: close the instance, then report the error\n- [ ] SDK 5.1: ALTER SYSTEM SET ... after step 3, before step 6\n```\n\n| | Flutter | JavaScript | Kotlin | Swift |\n|---|---|---|---|---|\n| Open | `await Ditto.open(DittoConfig(...))` | `await Ditto.open(config)` (Web: `await init()` first) | `DittoFactory.create(config)` | `try await Ditto.open(config:)` |\n| Start sync | `ditto.sync.start()` (`void`; throws) | `ditto.sync.start()` | `ditto.sync.start()` (throws) | `try ditto.sync.start()` |\n| Login failure | `AuthResponse.exception`; does not throw | Result `error`; does not throw | **Throws** | Completion handler `error` |\n\nMore: `§ Platform Differences`.\n\n## Rules\n\n### 1. Open Ditto once and share the instance (CRITICAL)\n\nOnly one `Ditto` instance can use a persistence directory at a time. What a second open of an open directory does differs by SDK; never rely on it to fail.\n> **Note (SDK 5.1.0):** In Flutter, `Ditto.open()` on a directory that is already open may never complete instead of throwing.\n\n**✅ DO**: open at app start and pass the instance through DI or a service; let concurrent callers wait for one pending open (reset it on failure); where a tool restarts your code without ending the process (Flutter hot restart), use a new `persistenceDirectory` per start in debug builds, and a fixed one in release.\n**❌ DON'T**: open per screen or request; reopen before closing has completed; touch, partly delete, or copy the persistence directory (sync silently diverges); in Swift, hold only `ditto.store` or `ditto.sync` (they reference `Ditto` weakly; without a strong reference the instance shuts down at once).\n\nFlutter: `Ditto.open()` initializes the SDK (SDK 5.1+); call `await Ditto.init()` first only before `Ditto.openSync()`, `DittoLogger`, or `Ditto.defaultRootDirectory`, or for custom Web asset URLs.\n\n`§ One instance per persistence directory`, `§ Opening Ditto in Flutter`, `§ Opening Ditto in Swift` · Example: *One shared instance in \u003CSDK>* on the SDK page\n\n### 2. Choose the connection mode deliberately (CRITICAL)\n\n| Connection (Flutter name) | Use for | Peer authentication |\n|---|---|---|\n| Server URL (`DittoConfigConnectServer(url: ...)`) | Production with real users | Webhook login; TLS |\n| Small peers with a key (`DittoConfigConnectSmallPeersOnly(privateKey: key)`) | Small peers only (closed networks) | Shared key; TLS 1.3 |\n| Small peers without a key (the default) | Local store tests, development | **None**; documented as unencrypted |\n\n**✅ DO**: copy the Server URL from the Ditto Portal exactly; check no placeholder `databaseID` remains (`open()` may not reject it); in small-peers mode pass a base64 P-256 PKCS#8 DER `privateKey` from secure provisioning (MDM) and call `setOfflineOnlyLicenseToken(token)` before you start sync; roll out a new key to all devices together.\n**❌ DON'T**: ship the keyless mode; hardcode keys, tokens, or API keys (binaries can be decompiled); use a shared key when you need per-user permissions or single-device revocation.\n\n`§ DittoConfig`, `§ Small-Peers-Only Deployments` · Code: *DittoConfig in \u003CSDK>* · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#small-peers-only-deployments)\n\n### 3. Set a non-throwing expiration handler before sync starts (CRITICAL)\n\nWith a server connection, starting sync fails until a handler is set. It runs before the first login and when credentials near or pass expiry. How `login` reports failure differs by SDK (*Login failure* above): Kotlin **throws**.\n\n**✅ DO**: set the handler before you start sync; fetch a fresh token inside it; check the login result the way your SDK reports it; catch your own errors.\n**❌ DON'T**: let an error escape from the handler (Ditto does not receive it, and it becomes unhandled); cache one token for the app's lifetime; ship the development provider or the Portal development token.\n\n`auth.logout()` **stops sync**; start it again after the next login. Logout with a cleanup callback (SDK 5.2+) runs after sync stops and may only `EVICT`; it swallows exceptions, so verify the result.\n\n`§ Authentication`, `§ Authentication in Production` · Code: *Authentication in \u003CSDK>* · Details: [reference\u002Fstartup-and-lifecycle.md](reference\u002Fstartup-and-lifecycle.md#authentication)\n\n### 4. Pass system parameters in DittoConfig on every open (CRITICAL)\n\nSystem parameters are in memory only and reset on restart or reopen. The system parameters of `DittoConfig` (SDK 5.2+) are applied before Ditto starts, so startup-only parameters take effect, and an unknown name or a wrong type makes opening fail. Startup-only parameters set later with `ALTER SYSTEM` have no effect.\n\n**✅ DO**: pass the app's settings in one map on every open; use `ALTER SYSTEM` only to change a value while the app runs; confirm with `SHOW \u003Cparameter>`. On SDK 5.1: `ALTER SYSTEM` after opening and before sync starts, queries, or observers (subscriptions may come first).\n**❌ DON'T**: run `ALTER SYSTEM` once in a migration; change `DQL_STRICT_MODE` (default `false`) after sync, queries, or observers have run.\n\n`§ Applying System Parameters`, `§ System Parameters Reference`, `§ Strict Mode` · Code: *DittoConfig in \u003CSDK>* on the SDK page\n\n### 5. Start sync after its prerequisites; never close on background (CRITICAL)\n\nStarting sync fails without the expiration handler or license token; it does nothing if already active (`sync.isActive`). After `sync.stop()` the local store stays usable, connections close, subscriptions stay registered, and changes sync after `start()`. Flutter's `start()` and `stop()` return `void` (do not await).\n\n**✅ DO**: keep Ditto open in the background; if the app must not sync there, stop sync when the app goes to the background and restart on return only the sync you paused.\n**❌ DON'T**: close Ditto when the app goes to the background: closing is final, later calls fail, and every subscription and observer must be re-created.\n\nBackground sync: iOS is best-effort and needs the Bluetooth central and peripheral background modes; Android needs Ditto's foreground service in `AndroidManifest.xml`.\n\n`§ Starting and Stopping Sync` · Code: *Sync and the App Lifecycle in \u003CSDK>* on the SDK page\n\n### 6. Change transports with updateTransportConfig (CRITICAL)\n\nA new, empty transport configuration has **every transport disabled**, including the peer-to-peer transports a default instance enables. The Server URL is used automatically.\n\n**✅ DO**: `ditto.updateTransportConfig`, changing only what you need (all peer-to-peer transports, `peerToPeer.bluetoothLE`, `listen.tcp`, `connect.tcpServers`).\n**❌ DON'T**: assign a fresh transport configuration (Flutter: `TransportConfig()`); treat `global.syncGroup` as a security boundary.\n\nInvalid values do not throw; they only log. WebSocket sync between Small Peers is off by default; enable it only with TLS. Use Multicast (Beta) (SDK 5.1+) only with Ditto support.\n\n`§ Transport Configuration`, `§ Multicast (Beta) (SDK 5.1+)` · Code: *Transports and Presence in \u003CSDK>* · Details: [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md)\n\n### 7. Raise the TCP connection limit on hubs with more than six clients (CRITICAL)\n\n> **Note (SDK 5.1.0 and 5.2.0):** A device accepts 6 TCP connections by default (`MESH_CHOOSER_MAX_WLAN_CONNECTIONS`). In testing, extra clients got no data and no API error; only a `WARN` log `... at capacity for this transport`. On 5.2.0, connections it opened itself also count when it accepts one, so a hub that also dials out admits fewer.\n\n**✅ DO**: on the hub, pass `MESH_CHOOSER_MAX_WLAN_CONNECTIONS` (for example 12) in the system parameters of `DittoConfig` on every open (SDK 5.2+); on SDK 5.1, `ALTER SYSTEM` after opening and **before** sync starts.\n**❌ DON'T**: raise it after sync started (rejected clients stayed out in testing).\n\n`§ Transport Configuration` · Details: [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md#transport-configuration)\n\n### 8. Keep metadata non-sensitive; record presence sparingly (CRITICAL)\n\n`ditto.presence.peerMetadata` and the webhook's `identityServiceMetadata` reach every peer in the mesh.\n\n**✅ DO**: keep peer metadata small (max 4096 bytes encoded; larger throws), set once at startup; `stop()` presence observers when their screen goes away.\n**❌ DON'T**: put secrets, tokens, or personal data in either; treat self-set `peerMetadata` as a security check.\n**Recording presence (HIGH)**: write a peer only when its stored time is older than the needed precision, in one transaction, not per callback; keep writers of one peer from writing at once (e.g. random timers); never write from the observer that reads the record.\n\n`§ Presence`, `§ Recording presence in documents`, `§ Identity metadata is visible to the mesh` · Code: *Transports and Presence in \u003CSDK>* · Details: [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md#presence)\n\n### 9. Enforce access with webhook permissions scoped by _id (CRITICAL)\n\nThe webhook returns per-collection `read` and `write` rules (each with `everything` and `queriesByCollection`) that can reference only `_id`, in legacy syntax (`_id.storeId == 'store-1'`; `\"true\"` matches all), not DQL.\n\n**✅ DO**: encode access boundaries (user, store, organization) in a structured `_id` before shipping; grant the narrowest rules per role; reject unknown users with `{\"authenticated\": false}`; keep `expirationSeconds` moderate so permission changes arrive on re-authentication; account for relaying: peer-to-peer data needs mutual write permission, so read-only roles cannot relay it.\n**❌ DON'T**: rely on mutable fields, `syncGroup`, sync scopes, or client checks; embed long-lived secrets to mint tokens on the device.\n\n`§ Permissions`, ``§ Design `_id` for permission scoping``, `§ Write authority and peer-to-peer relaying` · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#permissions)\n\n### 10. Revoke by rejecting in the webhook first (CRITICAL)\n\nCertificate revocation (SDK 5.1+) covers server-authenticated identities only and certificates issued before it; it is permanent.\n\n**✅ DO**: reject the identity in the webhook, then revoke via the Ditto Server HTTP API; keep `PEER_CERTIFICATE_REVOCATION_CHECK_ENABLED` enabled (default).\n**❌ DON'T**: disable revocation checking in production; expect revocation with a shared key.\n\n`§ Certificate Revocation (SDK 5.1+)` · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#certificate-revocation-sdk-51)\n\n### 11. Validate input, protect data at rest, secure the webhook (CRITICAL)\n\nOnly Swift and Kotlin can encrypt the local store at rest (SDK 5.2+): a 32-byte key in `DittoConfig.encryptionKey` on every open, kept in the Keychain or Android Keystore; switching an existing store means deleting it (`deleteStore`) and syncing again.\n\n**✅ DO**: validate before writes and pass values as `:parameters`; treat peer documents as untrusted; without Ditto encryption, rely on OS protection and encrypt sensitive fields in the app (keys in secure storage); serve the webhook over HTTPS, validate tokens, and verify the `ditto-signature` header.\n**❌ DON'T**: interpolate input into DQL; store tokens or keys in documents.\n\n`§ Input Validation and Query Parameters`, `§ Data at Rest`, `§ Webhook Security` · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#data-at-rest)\n\n### 12. Shut down in order, only when the app is done with Ditto (HIGH; CRITICAL in Flutter)\n\nRelease observers, subscriptions, presence and transport-condition observers, fetchers, and the connection request handler explicitly. Closing is final, stops sync, and releases resources, but **does not** wait for unsent changes. In-flight work: Flutter fails pending `execute()` calls, and stops the isolate if a transaction is open (on 5.2.0, reopening in the same process can also stop: `§ Changes in SDK 5.2.0`); JavaScript and Kotlin wait; Swift has no `close()` (5.1.0, 5.2.0): releasing the last reference shuts Ditto down and waits for an open transaction. Flutter's `close()` also does not end `changes` streams and **resets** `DittoLogger.customLogCallback`.\n\n**✅ DO**: await pending work (if data must reach a peer, its confirmed commit ID), release observers, then close. A growing count in `ditto.store.observers` across screens reveals observers never released.\n**❌ DON'T**: rely on garbage collection; send the Flutter `Ditto` or `Store` to another isolate.\n\n`§ Resource Cleanup and Shutdown`, `§ Forwarding logs to your own pipeline` · Code: *Closing Ditto in \u003CSDK>* on the SDK page\n\n### 13. Filter connections with a fast, non-throwing handler (MEDIUM; CRITICAL in Kotlin)\n\n`ditto.presence.connectionRequestHandler` returns `allow` or `deny` within 10 s, or the peer is rejected; catch every error (a throw ends a Kotlin app).\n\n**✅ DO**: catch errors and return `deny` at once; keep permissions as the primary control.\n\n`§ Controlling Incoming Connections` · Code: *Transports and Presence in \u003CSDK>* · Details: [reference\u002Fsecurity.md](reference\u002Fsecurity.md#controlling-incoming-connections)\n\n### 14. Plan for platform requirements and Web limits (MEDIUM)\n\nPin the exact SDK version; request Bluetooth, Wi-Fi, local network, and nearby-device permissions before sync. Android, SDK 5.2+: multicast permissions are requested separately. Flutter 5.2: the root is application support, also for a relative `persistenceDirectory`, so pass the absolute 5.1 path or 5.1 data is not found. Flutter Web and the JavaScript SDK in browsers: in-memory store, no indexes; Flutter Web syncs only over WebSocket with Ditto Server.\n\n`§ Requirements`, `§ DittoConfig`, `§ Upgrading from SDK 5.1` · Code: *Installing the \u003CSDK> SDK* · Details: [reference\u002Fstartup-and-lifecycle.md](reference\u002Fstartup-and-lifecycle.md#requirements)\n\n## Diagnose: Sync Never Starts or Devices Do Not Connect\n\n| Symptom | Cause |\n|---|---|\n| Opening fails with system parameters | Unknown name or wrong type (rule 4) |\n| `start()`: \"an authentication expiration handler has not yet been set\" | No handler (rule 3) |\n| `start()`: \"...not yet activated\" | No offline license token (small peers) |\n| \"The license failed verification\" | `setOfflineOnlyLicenseToken` fails: invalid token; a peer without a valid token is invisible |\n| Server login fails silently | Unchecked login result (rule 3) |\n| Sync stopped after sign-out | `logout()` stops sync |\n| `WARN` `BadSignature` \u002F `DecryptError` | Mismatched shared keys |\n| `WARN` `at capacity for this transport` | Hub TCP limit (rule 7) |\n| No peers, no error | Fresh transport configuration, missing permissions, radios off: observe transport conditions; check Android permissions (SDK 5.1+) |\n| `TRANSPORTS_DISCOVERED_PEERS` connects nothing | LAN transport disabled; use `connect.tcpServers` |\n| No relay through a middle device | It lacks write permission |\n\n`§ Diagnosing transport problems (SDK 5.1+)`, `§ When Data Does Not Sync` · Details: [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md#diagnosing-transport-problems-sdk-51)\n\n## Checklist\n\n- [ ] One shared instance (Swift: a strong reference to `Ditto` itself); failed startup closes it\n- [ ] Server + webhook, or small peers with provisioned `privateKey` and license token\n- [ ] No keys, tokens, or development provider in release builds\n- [ ] Expiration handler set before `sync.start()`; checks the login result the way the SDK reports it (*Login failure* above); never throws\n- [ ] System parameters in `DittoConfig.systemParameters` on every open (5.1: `ALTER SYSTEM` before sync)\n- [ ] Sync started after its prerequisites (Flutter: `start()` not awaited); no `close()` when the app goes to the background\n- [ ] Pending work awaited and observers cancelled before `close()`\n- [ ] Transports via `updateTransportConfig()`; hub TCP limit raised before sync\n- [ ] No secrets in peer or identity metadata\n- [ ] Permissions scoped by `_id`, narrowest per role; revocation checking on\n- [ ] Inputs parameterized; sensitive data encrypted (store key on Swift\u002FKotlin, or fields); webhook signatures verified\n\n## More\n\n- Reference: [reference\u002Fstartup-and-lifecycle.md](reference\u002Fstartup-and-lifecycle.md) (requirements, `DittoConfig`, startup, auth, system parameters, shutdown), [reference\u002Ftransports-and-presence.md](reference\u002Ftransports-and-presence.md) (transports, TCP hubs, diagnostics, presence), [reference\u002Fsecurity.md](reference\u002Fsecurity.md) (keys, webhook, `_id` design, revocation, data at rest)\n- Related skills: `query-sync` (subscriptions), `performance-observability` (logging, diagnostics), `storage-lifecycle` (tombstone parameters), `testing` (local store tests), `audit` (whole-app review)\n",{"name":5,"description":7},"main","b67d1a0bc891c9b2a952f8beb0a6dce7d449717c","plugins\u002Fditto\u002Fskills\u002Fsdk-setup","https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook","https:\u002F\u002Fdocs.ditto.live\u002Fhome\u002Fintroduction","https:\u002F\u002Fgithub.com\u002Fditto-examples","https:\u002F\u002Fdocs.ditto.live","Example Apps and Information for Ditto","2026-11-13 17:08:48",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add ditto-examples\u002Fditto-cookbook --skill sdk-setup",{"tool":42,"command":43},"bunx","bunx skills add ditto-examples\u002Fditto-cookbook --skill sdk-setup",{"tool":45,"command":46},"pnpm","pnpm dlx skills add ditto-examples\u002Fditto-cookbook --skill sdk-setup","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Fsdk-setup\u002FSKILL.md",true,[50,56,60],{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"reference\u002Fsecurity.md","REFERENCE","参考文档",24817,"https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Fsdk-setup\u002Freference\u002Fsecurity.md",{"path":57,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":58,"sourceHtmlUrl":59},"reference\u002Fstartup-and-lifecycle.md",50904,"https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Fsdk-setup\u002Freference\u002Fstartup-and-lifecycle.md",{"path":61,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":62,"sourceHtmlUrl":63},"reference\u002Ftransports-and-presence.md",32856,"https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Fsdk-setup\u002Freference\u002Ftransports-and-presence.md",[65,75,106,126,135,145],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":22},"01M6C58EAD92WQKNE74549PXEW","transactions-attachments","Ditto SDK transactions and attachments (Flutter, JavaScript, Kotlin, Swift): ditto.store.transaction with tx.execute only, no nesting, short scopes, rollback, close(); newAttachment, ATTACHMENT declarations, lazy fetchAttachment with a stall timeout, immutability, thumbnails, and blob availability. Use when writing or reviewing ditto.store.transaction, newAttachment, or fetchAttachment code, or when displaying photos or files stored in Ditto.","https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Ftransactions-attachments\u002FSKILL.md",[],[72,73,74],"transactions attachments","attachments","transactions",{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":86,"publishedAt":22},"01M6C58B0PQHV5WXMQRP9DEPX1","testing","Ditto SDK testing strategies in Flutter, JavaScript, Kotlin, or Swift: local-store test helper, tests for DQL statements, MISSING\u002FNULL filters, merge-sensitive writes, soft delete, observer lifecycle, subscription rules, and multi-peer sync tests in one process. Use when writing or reviewing tests for code that uses Ditto, setting up a Ditto test harness, or reproducing a Ditto sync or merge bug.","https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Ftesting\u002FSKILL.md",[81],{"categoryNo":82,"categoryName":83,"taxonomyType":84,"taxonomyTypeDesc":85},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",[77,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105],"swift","harness","lifecycle","up","for","strategies","test harness","when","testing strategies","tests","missing","bug","writing","filters","code","delete","merge","sync","local",{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":112,"publishedAt":22},"01M6C587HJC1SVAPYEZHJBV1C7","storage-lifecycle","Ditto SDK data removal and local storage management covering DELETE vs soft delete vs EVICT, tombstones and their TTL, husk documents, eviction with complementary subscriptions, retention cleanup, and storage monitoring. Use when writing Ditto DELETE or EVICT statements, soft-delete flags or retention cleanup for Ditto documents, or TOMBSTONE_TTL_HOURS, or when deleted Ditto data came back or evicted documents sync back.","https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Fstorage-lifecycle\u002FSKILL.md",[],[89,113,114,105,115,116,94,117,118,119,120,102,19,104,121,99,122,123,124,125],"storage","storage lifecycle","with","subscriptions","ttl","use","ditto","retention","cleanup","documents","monitoring","back","evict",{"skillNo":127,"name":128,"nameZh":6,"description":129,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":22},"01M6C580SCSJK0E5Z54AJTV242","query-sync","Ditto SDK DQL reads and writes, subscriptions, and store observers (Flutter, JavaScript, Kotlin, Swift): query parameters, MISSING vs NULL, membership filters, subscription and observer lifecycle, ON ID CONFLICT upserts, JOIN, RETURNING. Use when writing or reviewing ditto.store.execute, ditto.sync.registerSubscription, registerObserver, or DQL in an app that uses Ditto, or when Ditto data does not sync or a Ditto query returns nothing.","https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Fquery-sync\u002FSKILL.md",[],[133,134,104],"query","query sync",{"skillNo":136,"name":137,"nameZh":6,"description":138,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":139,"categories":140,"keywords":141,"publishedAt":22},"01M6C57X4C3TQSWZJC882ECQV2","performance-observability","Ditto SDK store observer performance and diagnostics (Flutter, JavaScript, Kotlin, Swift): observer lifecycle, backpressure (registerObserverV2, signalNext, suspending handlers), narrow UI updates, differs, redundant writes, indexes, ADVISE, EXPLAIN, PROFILE, logging, and system: collections. Use when a Ditto query is slow, a screen showing Ditto data janks, Ditto observers grow memory, Ditto upserts repeat, or when setting up Ditto logging.","https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Fperformance-observability\u002FSKILL.md",[],[142,143,144],"performance observability","performance","observability",{"skillNo":146,"name":147,"nameZh":6,"description":148,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":149,"categories":150,"keywords":151,"publishedAt":22},"01M6C57V1EZKA9B5W1G4F00HAH","guide","Searches the complete Ditto SDK best practices guide (SDK 5.2.0, Flutter, JavaScript, Kotlin, Swift) bundled with this plugin, for answers the focused ditto skills do not cover. Use to look up a Ditto API, DQL keyword or function, system parameter, error message, an SDK's API or behavior, or the reasoning behind a rule, or when a Ditto question spans several topics.","https:\u002F\u002Fgithub.com\u002Fditto-examples\u002Fditto-cookbook\u002Fblob\u002Fmain\u002Fplugins\u002Fditto\u002Fskills\u002Fguide\u002FSKILL.md",[],[147,152,153,154,90,155,118,156,157,115,158,159,160,161,91,119,162,94,163,164],"kotlin","plugin","system","question","best practices","api","error","do","message","complete","flutter","javascript","topics"]