@chipmobilesdk/rn-local-db 0.1.0 → 0.1.2

package/README.md

@@ -354,7 +354,7 @@ Every one returns a `DeletionOutcome` rather than a bare success — what was re
 
 If a deletion is interrupted — a force-quit, a battery death — the next open reports `SCOPE_DELETED` rather than presenting the scope as healthy. Call `deleteScopeData` again to finish it.
 
-A handle whose scope is deleted beneath it reports `SCOPE_DELETED` on its next use. The deletion does not wait for it.
+A handle whose scope is deleted beneath it reports `SCOPE_DELETED` on its next use. The deletion does not wait for it, and nothing revives it: open a new handle and rebuild whatever was built on the old one. An app that retries through the dead handle gets the same error every time, which reaches the user as a screen that only relaunching can fix.
 
 ---
 

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@chipmobilesdk/rn-local-db",
-	"version": "0.1.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
+	"version": "0.1.2",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"exports": {
 		".": {
@@ -31,6 +31,7 @@
 		"src/scope",
 		"src/sqlite",
 		"src/testing",
+		"skills",
 		"README.md",
 		"CHANGELOG.md"
 	],
@@ -54,8 +55,8 @@
 	"engines": {
 		"node": ">=22.11.0"
 	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/skills/sdk-rn-local-db/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: sdk-rn-local-db
+description: "Offline SQLite storage via @chipmobilesdk/rn-local-db: schemas, scoped data, queries, transactions, migrations, attachments, encryption. Use when persisting data locally, writing a migration, deleting a user's data, or handling sign-out data retention."
+metadata:
+  package: "@chipmobilesdk/rn-local-db"
+  packageVersion: "0.1.0"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-local-db
+
+Local-first SQLite persistence with a scope model, declarative schemas, typed queries,
+migrations, attachments and optional encryption.
+
+## Use this when
+
+- Persisting any app data on device
+- Declaring or changing a schema, or writing a migration
+- Deciding what happens to data at sign-out
+- Storing files/attachments alongside records
+- Enabling encryption or answering a backup/privacy question
+
+## Read before writing any code
+
+Two concepts cause most of the bugs in this package. Do not skip them:
+
+1. **The scope model** — data belongs to a scope, and getting the scope wrong leaks
+   data between users or loses it on sign-out.
+2. **The four value conditions** — this package distinguishes more record states than
+   "set" vs "null". Handling only two of them produces silent data loss.
+
+Read `## The scope model` and `## Records and the four value conditions` in the README
+before designing a schema.
+
+## Deletion, sign-out, and dead handles
+
+The README has a dedicated section (`## Deletion, and why sign-out is not deletion`).
+Treat any "clear data on logout" requirement as a design question answered by that
+section, not by deleting the database file.
+
+`deleteScopeData` and `deleteDatabase` are module-level and do not wait for open
+handles. **After either, open a NEW handle and rebuild everything derived from the
+old one** — repositories, providers, the screen behind a retry button. The old handle
+raises `SCOPE_DELETED` (or `CLOSED_HANDLE` if the app closed it first) on every call,
+so a Retry wired to it can never succeed: the app stays broken until the process
+restarts. An interrupted deletion instead reports `SCOPE_DELETED` from the next
+`openDatabase` — call `deleteScopeData` again to finish it, then open.
+
+## Public API
+
+`setDiagnosticLogger`, `Budgets`, and types `DiagnosticLogger`, `DiagnosticCode` are
+exported from the root. The schema, query, migration, scope, crypto and attachment
+surfaces are large — enumerate them from
+`node_modules/@chipmobilesdk/rn-local-db/src/index.ts` when needed rather than guessing.
+
+## Where the detail lives
+
+`node_modules/@chipmobilesdk/rn-local-db/README.md` is ~700 lines. Read one section:
+
+| Need | Section |
+|---|---|
+| Install and native setup | `## Install` |
+| Data ownership / sign-out / deleting it all | `## The scope model`, `## Deletion, and why sign-out is not deletion` |
+| Defining tables | `## Declaring a schema` |
+| Null vs missing vs unset | `## Records and the four value conditions` |
+| Reading data | `## Queries` |
+| Atomic writes | `## Transactions and batches` |
+| Schema change | `## Migrations` |
+| Files and blobs | `## Attachments` |
+| Encryption at rest | `## Encryption` |
+| iOS/Android backup behaviour | `## Backup posture` |
+
+Start from `## Contents` if you are unsure which section applies.