@anodb/core 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 show-ritz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,197 @@
+# anoDB wire protocol — version 2 (draft)
+
+Status: **draft**. Kind numbers and the tag name are provisional until checked against the NIP
+registry. Implementations MUST drop anything they cannot validate. Version 1 (anoDB 0.1) is
+obsolete and not supported.
+
+## 1. Keys
+
+| key | holder | used for |
+|---|---|---|
+| **identity** (secp256k1) | the user (key store, recovery key, or a NIP-07/46/55 signer) | delegations, revocations, key packages, public Nostr events |
+| **device** (secp256k1) | one installation | signing every inner message |
+| **epoch key** (32 random bytes) | every active device of every member of a space | encrypting a space stream for one epoch |
+
+### 1.1 Delegation (kind 7304)
+
+```jsonc
+{ "kind": 7304, "pubkey": "<identity>", "tags": [["device", "<device pubkey>"]], "content": "{\"name\":\"phone\"}" }
+```
+
+A revocation is the same kind with `["revoke", "<device pubkey>"]`. Delegations are not published
+on their own; they travel inside encrypted messages (and in key packages, §6).
+
+## 2. Envelope (kind 7303)
+
+```jsonc
+{
+  "kind": 7303,
+  "pubkey": "<throwaway key>",        // device key if metadataProtection = 'none'
+  "created_at": <unix seconds>,
+  "tags": [["n", "<routing tag>"]],
+  "content": "<NIP-44 v2 ciphertext of the inner message JSON>"
+}
+```
+
+| routing | tag | NIP-44 conversation key |
+|---|---|---|
+| space stream | `hex(sha256("anodb/v2/space/" + hex(epochKey)))[0:32]` | the epoch key itself |
+| device inbox | `hex(sha256("anodb/v2/inbox/" + devicePubkey))[0:32]` | ECDH(envelope key, device key) |
+| invite / pairing secret | `hex(sha256("anodb/v2/secret-tag/" + secret))[0:32]` | `sha256("anodb/v2/secret-key/" + secret)` |
+
+`keyId(epochKey) = hex(sha256("anodb/v2/key-id/" + hex(epochKey)))[0:16]`.
+
+Relays therefore see only: a random pubkey, a tag that changes every epoch, time and size.
+
+## 3. Inner message (kind 7305)
+
+A NIP-01 event signed by the **device** key, never published unencrypted. `content` is the payload:
+
+```jsonc
+{ "v": 2, "t": "<type>", "sp": "<space id, 32 hex>", "ep": "<keyId>", "seq": <n>, "dlg": <delegation event>, ...body }
+```
+
+- `seq` starts at 1 and increases by one per (space, device). Gaps reveal missing messages.
+- A receiver MUST check: inner signature; `dlg` delegates to the inner pubkey; `sp`/`ep` match
+  the key that decrypted the envelope; payload shape.
+
+| `t` | body | meaning |
+|---|---|---|
+| `ch` | `c: [[table, rowId, column, value, hlc], …]` | cell changes |
+| `op` | `op: {…}, par: [msgId…]` | membership operation (§5) |
+| `snap` | `sid, i, n, body` | part `i` of `n` of a snapshot |
+
+## 4. Cells and merge
+
+State is `(space, table, rowId, column) → (value, hlc)`; a change wins iff its HLC is greater.
+`hlc = base36(ms, 10) + base36(counter, 5) + "-" + nodeId(16 hex)`; string order = causal order.
+System columns: `$deleted` (`true` = tombstone), `$createdAt` (ms). Changes are applied only if the
+signing identity is authorized (§5) for that device and sequence number; unauthorized messages are
+kept and re-evaluated whenever membership changes.
+
+## 5. Spaces and membership
+
+Every row belongs to a space; a user's personal data is a space whose only member is the user.
+`spaceId = hex(sha256("anodb/v2/space-id/" + owner + "/" + nonce))[0:32]`, so only the owner can
+produce the valid `create` op.
+
+### 5.1 Ops (`t: "op"`)
+
+`par` lists the ids of the ops the author had seen (DAG heads). An op is evaluated only once all its
+ancestors are known; it is **valid iff its author was permitted to perform it in the state formed
+by its valid ancestors**.
+
+| op | fields | who may |
+|---|---|---|
+| `create` | `owner, nonce, name` | the owner (no parents; id must match) |
+| `add` | `identity, role` | owner: any role; admin: writer/reader |
+| `role` | `identity, role, cut?` | owner: any non-owner; admin: writer/reader of non-admins |
+| `remove` | `identity, cut` | owner: anyone but itself; admin: writers/readers |
+| `leave` | `cut` | any non-owner member, for itself |
+| `transfer` | `identity` | the owner, to a member (old owner becomes admin) |
+| `revoke` | `revocation` (kind 7304 event), `cut` | any member, relaying a valid revocation |
+
+Roles: `owner` (exactly one) > `admin` > `writer` > `reader`.
+
+Conflict rules:
+
+- a `remove` of X overrides every `add`/`role` for X that is not its descendant;
+- `cut` maps device → highest accepted `seq`. Concurrent cut-offs for one device combine to the
+  **minimum**. A message from a device with a cut-off is applied only if `seq ≤ cut`;
+- a later (descendant) `add` lifts the identity's cut-offs.
+
+A `ch` or `snap` message is applied iff its author may write under the final membership state
+(including cut-offs). Unauthorized messages are stored and re-evaluated on every membership change.
+
+### 5.2 Keys and rotation
+
+The current epoch key is the one with the highest `num` (ties: lowest key id). Owners/admins
+rotate on removal, device revocation, member addition and every 30 days, by sending the new key to
+every active device of every member through their inboxes, then posting a snapshot in the new
+epoch.
+
+### 5.3 Inbox messages (inner kind 7305, payload `{ v: 2, t, dlg, … }`)
+
+| `t` | fields | accepted when |
+|---|---|---|
+| `key` | `sp, name, personal, num, key, ops[]` | sender is admin+ of `sp` (or the same identity) under the carried + known ops, and the receiver is a member |
+| `invite` | as `key` + `role`, optional `req` | as above; stored until the user accepts (`req = sha256(link secret)` → auto-accept for own join requests) |
+
+`ops` are complete signed inner op events, verifiable without the old epoch keys.
+
+### 5.4 Snapshots (`t: "snap"`)
+
+Parts `i/n` with `body: { ops?: [inner…], cells?: [change…] }`. Rows that are deleted carry only their
+`$deleted` cell. A complete snapshot from an authorized writer is merged like ordinary changes.
+New members and newly paired devices receive keys for the **new** epoch only and catch up from
+snapshots.
+
+### 5.5 Invite links and pairing (secret routing)
+
+- Invite link: `anodb://join?app=<appId>&s=<secret>`. The requester sends `{ t: "joinreq", devices: [delegations], name }`
+  to the secret tag. An admin must approve; the link is single-use and expires.
+- Pairing: `anodb://pair?app=<appId>&d=<new device pubkey>&s=<secret>`; both devices display
+  `sha256("anodb/v2/pair-code/" + d + "/" + s)` as a 6-digit code. The approving device sends
+  `{ t: "pair", delegation, spaces: [grant…] }` to the secret tag. The identity key is never sent.
+
+### 5.6 Key package (kind 10304, public, replaceable)
+
+`content = {"v":2,"delegations":[…]}` signed by the identity, listing current device delegations so
+others can invite by npub.
+
+## 6. Sync (informative)
+
+1. **NIP-77**: `NEG-OPEN` with `{"kinds":[7303],"#n":[tags…]}` over the local envelope set; fetch
+   `need` ids (repeat until complete — relays cap id lookups too), re-publish `have` envelopes.
+   A relay answering `NEG-ERR`, a `NOTICE`, or nothing is treated as unsupported.
+2. **Time-based**: `{"kinds":[7303],"#n":[tags…],"since":cursor−600}` per relay; after `EOSE`, page
+   with `until` until nothing new; advance per-(relay, tag) cursors.
+3. **Gaps**: per (space, device), every `seq` above the coverage of complete snapshots
+   (`heads` in part 0) must be present; missing ones trigger a deep re-fetch.
+4. **Snapshots**: new members/devices start from them.
+
+Outbox: retry until `minAcks` relays acknowledge; envelopes older than 300 s are re-signed (new
+throwaway key, fresh `created_at`, same content).
+
+Optional pruning: envelope key = `sha256("anodb/v2/prune/" + hex(deviceSk) + "/" + salt)`; after a
+snapshot the author publishes NIP-09 kind 5 `["e", id], ["k", "7303"]` for its older envelopes.
+
+## 7. Public tables
+
+Standard events, unencrypted, signed by the identity key:
+
+| preset | kind | row id | replace rule |
+|---|---|---|---|
+| note | 1 | event id | none (delete = kind 5) |
+| profile | 0 | author | newest per author |
+| follows | 3 | `author:target` | newest list per author |
+| reaction | 7 | event id | none |
+| longForm | 30023 | `author:d` | newest per address |
+
+A client publishing a new version of a replaceable event MUST use a `created_at` greater than the
+version it replaces.
+
+## 8. Blob references (Blossom)
+
+Files are stored on Blossom servers (BUD-01/02/11/12), encrypted with AES-256-GCM
+(`blob = iv(12) || ciphertext || tag`). The reference stored in a `json` column:
+
+```jsonc
+{ "v": 1, "sha256": "<sha256 of the encrypted blob>", "size": <plaintext bytes>, "type": "<mime>",
+  "key": "<AES key, hex>", "servers": ["https://…"], "salt": "<hex>", "name"?: "…" }
+```
+
+Uploads/deletes carry `Authorization: Nostr <base64url(kind 24242 event)>` with `t`, `x`,
+`expiration` and `server` tags, signed by `sha256("anodb/v2/blob/" + hex(deviceSk) + "/" + salt)`.
+Clients MUST verify the sha256 of downloaded bytes before decrypting.
+
+## 9. Direct delivery (WebRTC, via nostr-p2p)
+
+- Room: `joinRoom("anodb:" + appId, hex(sha256("anodb/v2/p2p/" + hex(epochKey))), { transport: "direct" })`.
+- Channel `anodb` messages:
+  - `{ t: "hi", proof }` — `proof` is an event of kind 27305 signed by the device key with
+    `content = roomId + ":" + <recipient session pubkey>`; only devices of current members are accepted.
+  - `{ t: "e", e: <envelope> }` — a regular envelope (§2), verified exactly like one from a relay.
+  - `{ t: "a", id }` — acknowledgement after successful ingestion.
+- A sender MAY skip relays for an envelope only if every active device of every member of the space
+  acknowledged it; otherwise it MUST publish it to relays (default after 2 s).

package/README.md

@@ -1,3 +1,293 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/anodb-logo.svg" alt="anoDB — Absolutely No DB" width="720" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">anoDB — Absolutely No DB</h1>
+
+<p align="center"><strong>A decentralized, local-first database.</strong><br />Zero servers to run. Zero servers to trust.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@anodb/core"><img src="https://img.shields.io/npm/v/@anodb/core?label=%40anodb%2Fcore" alt="@anodb/core on npm" /></a>
+  <a href="https://www.npmjs.com/package/@anodb/cli"><img src="https://img.shields.io/npm/v/@anodb/cli?label=%40anodb%2Fcli" alt="@anodb/cli on npm" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" /></a>
+</p>
+
+anoDB is a decentralized, local-first database SDK that treats on-device SQLite as the source of truth and distributes changes as **end-to-end encrypted Nostr events** through existing public relays.
+
+True to its name, it requires **absolutely no developer-operated server**: no API server, no database server, and no project setup. Offline reads and writes, multi-device sync, sharing with other people, and reading/writing public Nostr data are available through a single type-safe, SQL-like API.
+
+> **Status: v0.7 / experimental.** The protocol ([PROTOCOL.md](PROTOCOL.md), v2) may change incompatibly. See [docs/DESIGN.md](docs/DESIGN.md) for design details and limitations, and [docs/DECISIONS.md](docs/DECISIONS.md) for the decision log.
+
+## Features
+
+- 📴 **Offline-first** — Writes commit immediately to local SQLite. The network catches up later.
+- 🧾 **Type-safe SQL** — A [Kysely](https://kysely.dev) query builder with JOINs, plus raw SQL writes (`UPDATE … LIKE`, `INSERT … SELECT`, upserts) that are captured and synced.
+- 👥 **Sharing** — Spaces with owner / admin / writer / reader roles, invitations by npub or one-time links, removal with cut-offs, key rotation.
+- 🔐 **Secure by default** — Writes are signed by per-device keys, keys are stored encrypted, relays see only throwaway pubkeys and rotating tags, and new members never see deleted history.
+- 🔀 **Deterministic merging** — Cell-level Last-Writer-Wins with Hybrid Logical Clocks; tolerant of out-of-order delivery, duplicates and retries.
+- ⚡ **Direct device-to-device sync** — Your devices connect over WebRTC ([nostr-p2p](https://github.com/sho-ritz/nostr-p2p)) and exchange changes in tens of milliseconds; relays remain the store for offline devices.
+- 🔁 **4-layer sync** — NIP-77 Negentropy, time-based fallback, sequence-gap detection, snapshots. A durable outbox retries until `minAcks` relays acknowledge.
+- 🌐 **Nostr tables** — Profiles, notes, follows, reactions and long-form articles as SQL tables, readable and writable by any Nostr client.
+- 📎 **Encrypted files** — Large files go to [Blossom](https://github.com/hzrd149/blossom) servers, encrypted on the device; only a reference is stored in the database.
+- ⚛️ **React hooks** — `useQuery`, `useSyncStatus`.
+
+## Get started
+
+In an existing app (Next.js, Vite, SvelteKit, Tauri, Electron, Expo or Node):
+
+```sh
+npx @anodb/cli init
+```
+
+One interactive command does the whole setup:
+
+1. Asks the language (English / 日本語) and detects your environment and framework
+2. Installs `@anodb/core` (plus `sql.js` for web apps)
+3. Generates `anodb/schema`, `anodb/db` and a React `<DBProvider>`
+4. Web apps: copies the SQLite WASM files to `public/anodb/` and adds `"postinstall": "anodb assets"` to keep them in sync
+5. Wraps your app in `<DBProvider>` (Next.js `app/layout` or Vite `src/main`)
+6. Optionally checks that the relays store and serve events
+
+Then use it from any component:
+
+```tsx
+import { useAnoDB, useQuery } from '@anodb/core/react'
+
+const db = useAnoDB()
+const todos = useQuery((db) => db.selectFrom('todo').selectAll(), [])
+await db.insertInto('todo').values({ title: 'Milk', done: false }).execute()
+```
+
+No bundler configuration, no server, no account. Keys are generated on each user's device on first
+launch. Only one tab per origin opens the database; other tabs get `AnoDBError('tab-locked')`.
+
+### Packages
+
+The product is **anoDB**; on npm it lives under the `@anodb` scope.
+
+| Package | What it is |
+|---|---|
+| [`@anodb/core`](https://www.npmjs.com/package/@anodb/core) | The database: sync, sharing, keys, files, React hooks (`@anodb/core/react`) and Node driver (`@anodb/core/node`) |
+| [`@anodb/cli`](https://www.npmjs.com/package/@anodb/cli) | `npx @anodb/cli init` — the setup wizard (you never import it) |
+| [`nostr-p2p`](https://www.npmjs.com/package/nostr-p2p) | WebRTC over Nostr signaling, used internally by `@anodb/core` |
+
+### Manual setup
+
+```sh
+npm install @anodb/core sql.js   # sql.js only for browsers / Tauri
+npx anodb assets                 # copy the SQLite WASM files to public/anodb/
+```
+
+```ts
+import { browserDriver, createAnoDB } from '@anodb/core'
+const db = await createAnoDB({ appId, schema, driver: await browserDriver({ name: appId }) })
+```
+
+Runs in browsers / Tauri (sql.js persisted to IndexedDB), Electron and Node.js 22.13+ (`node:sqlite`), and React Native / Expo (`expo-sqlite`).
+
+## Usage
+
+```ts
+import { createAnoDB, defineSchema } from '@anodb/core'
+
+const schema = defineSchema({
+  todo: { title: 'text', done: 'boolean', priority: 'integer', meta: 'json' },
+  tag: { name: 'text', todoId: 'text' },
+})
+
+const db = await createAnoDB({ appId: 'com.example.todo', schema, driver })
+
+// SQL-like and type-safe, JOINs included
+await db.insertInto('todo').values({ title: 'Buy groceries', done: false }).execute()
+await db.updateTable('todo').set({ done: true }).where('title', 'like', '%groceries%').execute()
+const rows = await db
+  .selectFrom('todo')
+  .leftJoin('tag', 'tag.todoId', 'todo.id')
+  .select(['todo.title', 'tag.name'])
+  .execute()
+
+// Raw SQL works too; writes are captured by triggers, encrypted and synced
+await db.execute('UPDATE todo SET done = 1 WHERE priority > ?', [2])
+
+// Transactions (atomic locally, one sync unit)
+await db.transaction().execute(async (tx) => {
+  await tx.insertInto('todo').values({ title: 'A' }).execute()
+})
+
+// Live queries: re-run on local or remote changes
+const stop = db.subscribe(db.selectFrom('todo').selectAll(), (rows) => render(rows))
+```
+
+- Every table gets `id`, `space`, `createdAt` and `updatedAt` (`space` defaults to your personal space).
+- Following SQLite semantics, `boolean` reads as `0 | 1` and `json` reads as JSON text.
+
+### Keys (most secure defaults)
+
+| Environment | Default key store |
+|---|---|
+| Browser / Tauri | IndexedDB, sealed with a non-extractable WebCrypto key |
+| Node | Environment variables (`npx @anodb/cli init` writes only the device key and delegation to `.env`, never the identity key) |
+| Electron / Expo | `electronKeyStore(safeStorage)` / `secureStorageKeyStore(expo-secure-store)` |
+
+- Every write is signed by a **device key**; the identity key is used once to register the device.
+- With `identity: 'recovery'`, the identity key is handed to `onRecoveryKey` once and never stored on the device.
+- External signers: `signer: nip07Signer() | nip46Signer(uri) | nip55Signer(bridge)`.
+- Relays see only throwaway pubkeys, per-epoch tags, times and sizes (`metadataProtection: 'none'` turns this off for allow-listed relays).
+
+## Sharing (spaces)
+
+```ts
+const family = await db.createSpace('Family')
+await db.insertInto('todo').values({ title: 'Milk', space: family }).execute()
+
+// Invite by npub (the invitee publishes a key package first: db.publishKeyPackage())
+await db.invite(family, 'npub1alice…', 'writer')        // owner / admin / writer / reader
+// Invitee: nothing syncs until they accept
+alice.onInvitation((i) => …); await alice.acceptInvitation(i.space)
+
+// One-time, expiring invite link; an admin must approve each request
+const link = await db.createInviteLink(family, { role: 'reader', expiresInMs: 86_400_000 })
+db.onJoinRequest((req) => db.approveJoinRequest(req.id))
+
+await db.setRole(family, who, 'reader')
+await db.removeMember(family, who)
+```
+
+- New members receive **only a snapshot of the current state** — no edit history and no deleted content.
+- Group keys rotate on member removal, device revocation, member addition and every 30 days.
+- After removal, writes beyond each device's sequence-number cut-off are rejected (backdating does not help).
+
+### Adding and revoking devices
+
+```ts
+// New device: show a QR code
+const offer = await newDevice.startPairing()   // render offer.uri as QR, show offer.code
+await offer.done; await newDevice.close()      // reopen: it now has the same identity
+// Existing device: scan, compare the code, approve (the identity key is never copied)
+const req = db.parsePairing(uri); /* check req.code */ await req.approve('Laptop')
+
+await db.revokeDevice(lostDevicePubkey)        // lost or stolen device
+```
+
+> ⚠ Group keys are delivered to device keys only. **If you lose every device, your personal space cannot be recovered** (shared spaces can be restored by other members). Register at least two devices.
+
+## Public Nostr data (tables)
+
+```ts
+import { defineSchema, publicTable } from '@anodb/core'
+
+const schema = defineSchema({
+  todo: { title: 'text' },                 // private (encrypted in a space)
+  posts: publicTable('note'),              // kind 1
+  profiles: publicTable('profile'),        // kind 0
+  follows: publicTable('follows'),         // kind 3
+  reactions: publicTable('reaction'),      // kind 7
+  articles: publicTable('longForm'),       // kind 30023
+})
+
+await db.insertInto('posts').values({ content: 'hello nostr', tags: [['t', 'anodb']] }).execute() // signed & published
+await db.syncPublic('posts', { authors: [alice] }, { live: true })                                // fetch & follow
+await db.selectFrom('posts').innerJoin('profiles', 'profiles.author', 'posts.author')
+  .select(['posts.content', 'profiles.name']).execute()                                         // JOIN
+```
+
+Public tables are **not encrypted**. Notes and reactions cannot be edited (deleting publishes a NIP-09 request); profiles, follow lists and articles are replaceable.
+
+## Direct sync over WebRTC
+
+Where WebRTC is available (browsers, or Node with `node-datachannel`), **your own devices connect
+directly** and exchange changes peer-to-peer (signaling goes through the same Nostr relays).
+
+```ts
+createAnoDB({ ..., p2p: { mode: 'own-devices' } })       // default where WebRTC exists
+createAnoDB({ ..., p2p: { mode: 'members' } })           // also connect to other members (they see your IP)
+createAnoDB({ ..., p2p: { mode: 'off' } })               // relays only
+// Node: p2p: { rtc: { RTCPeerConnection } } from 'node-datachannel/polyfill'
+
+db.p2pPeers() // [{ space, device, transport: 'direct' }]
+```
+
+- Rooms are derived from each space's epoch key, so only members can join and removed members drop out when keys rotate.
+- Every peer proves which device it is with a signature; envelopes received directly go through the same verification as relay ones.
+- A change **skips relays entirely when every device of the space acknowledged it**; otherwise it is published to relays after 2 s, so offline devices still get it.
+- `members` mode is opt-in because direct connections reveal IP addresses to other members.
+
+## Files (Blossom)
+
+Values are limited to ~44 KB, so files go to Blossom servers (Nostr's blob storage). They are
+encrypted on the device with a random key; the database only stores a small reference, which is
+synced end-to-end encrypted like any other value — so only members of the space can open the file.
+
+```ts
+const schema = defineSchema({ notes: { text: 'text', photo: 'json' } })
+
+const ref = await db.blobs.put(file, { type: file.type, name: file.name }) // encrypt + upload (mirrored)
+await db.insertInto('notes').values({ text: 'receipt', photo: ref }).execute()
+
+const [row] = await db.selectFrom('notes').select('photo').execute()
+const blob = await db.blobs.getBlob(row.photo)   // download, verify hash, decrypt
+img.src = URL.createObjectURL(blob)
+
+await db.blobs.delete(ref)                        // only from the device that uploaded it
+```
+
+- Servers see only ciphertext, its size, upload time and your IP. Each upload is signed by a throwaway key.
+- Downloads are verified against the sha256, so a server cannot alter a file; other servers are tried on failure.
+- Default servers: `DEFAULT_BLOB_SERVERS` (public servers that accept encrypted uploads). **Most public Blossom servers only accept images/video and reject ciphertext**, and none guarantee retention — use `blobServers` to add your own or paid servers.
+
+## Sync health
+
+```ts
+db.status        // { state: 'offline' | 'syncing' | 'synced', connectedRelays, pendingEvents }
+db.syncHealth()  // { gaps: [{ space, device, missing: [7, 8] }], nip77: { 'wss://…': true } }
+await db.repair() // deep re-fetch from every relay
+```
+
+On NIP-77 relays, reconciliation is exact and lost envelopes are re-uploaded automatically. On other relays, per-device sequence numbers still **detect** anything missing.
+
+## React
+
+```tsx
+import { AnoDBProvider, useQuery, useSyncStatus } from '@anodb/core/react'
+
+<AnoDBProvider db={db}><App /></AnoDBProvider>
+const todos = useQuery((db) => db.selectFrom('todo').selectAll().where('done', '=', 0), [])
+const status = useSyncStatus()
+```
+
+## Column types
+
+| Type | Write (TS) | Read (TS) | SQLite |
+|---|---|---|---|
+| `text` | `string` | `string` | TEXT |
+| `integer` | `number` (safe integer) | `number` | INTEGER |
+| `real` | `number` | `number` | REAL |
+| `boolean` | `boolean \| 0 \| 1` | `0 \| 1` | INTEGER |
+| `json` | any JSON value | `string` (JSON text) | TEXT |
+
+All columns are nullable.
+
+## Limitations
+
+- **Public relays do not guarantee retention.** Multiple relays, `minAcks` and repair improve durability but cannot guarantee it.
+- **Consistency across devices is eventual.** Not suitable for global inventory counts, balances or uniqueness constraints.
+- **SQL queries only cover locally available data.**
+- **Deletion uses tombstones.** Copies held by relays or other people are not erased; removed members keep what they already read.
+- **Losing every device loses your personal space** (by design, for security).
+- With only non-NIP-77 relays, more events in a single second than a relay's result limit can be missed; `syncHealth()` reports the gap.
+- Files depend on Blossom servers' retention policies (none are guaranteed).
+- The local SQLite file itself is not encrypted; rely on disk encryption.
+
+See [docs/DESIGN.md](docs/DESIGN.md) for the threat model and open issues.
+
+## Development
+
+```sh
+npm test              # unit + integration tests against a mock relay (NIP-77, fault injection)
+npm run typecheck
+npm run smoke:public  # checks against real public relays (network required)
+```
+
+## License
+
+MIT

package/dist/anodb.d.ts

@@ -0,0 +1,69 @@
+import type { CapturedCell } from './capture.js';
+import { type AnoDBOptions } from './db.js';
+import { type P2PMode, type PeerInfo, P2PSync } from './p2p.js';
+import { AnoDBSharing } from './sharing.js';
+import type { NostrEvent, SchemaDefinition } from './types.js';
+export interface SyncGap {
+    space: string;
+    device: string;
+    /** Missing sequence numbers (at most 100 listed). */
+    missing: number[];
+}
+export interface PublicSyncFilter {
+    authors?: string[];
+    ids?: string[];
+    since?: number;
+    until?: number;
+    limit?: number;
+    /** Tag filters without the `#`, e.g. `{ t: ['anodb'] }`. */
+    tags?: Record<string, string[]>;
+}
+/** anoDB database handle: SQL-like API, spaces & sharing, NIP-77 sync, public Nostr tables. */
+export declare class AnoDB<S extends SchemaDefinition> extends AnoDBSharing<S> {
+    #private;
+    protected afterInit(): Promise<void>;
+    /** Effective P2P mode: own devices by default where WebRTC exists. */
+    get p2pMode(): P2PMode;
+    protected holdForPeers(space: string): number;
+    protected afterEnvelope(space: string, outer: NostrEvent, held: boolean): void;
+    /** Raw P2P room state (troubleshooting). */
+    p2pDiagnostics(): ReturnType<P2PSync['diagnostics']>;
+    /** Devices currently connected directly (for status UIs). */
+    p2pPeers(): PeerInfo[];
+    protected afterCatchUp(relay: string): Promise<void>;
+    /**
+     * Layer 1: NIP-77 set reconciliation with one relay (fetch what we miss, upload what it misses).
+     * Layer 3: if sequence gaps remain, do a deep re-fetch from all relays (rate limited).
+     * Returns whether the relay supports NIP-77.
+     */
+    reconcile(relay: string): Promise<boolean>;
+    /** Layer 3: messages known to exist (by per-device sequence numbers) but not received. */
+    syncHealth(): {
+        gaps: SyncGap[];
+        nip77: Record<string, boolean>;
+    };
+    /** Deep re-fetch of every stream from every connected relay (ignores cursors). */
+    repair(): Promise<void>;
+    /** Envelope keys are derived from the device key + a random salt so they can sign deletions later. */
+    protected wrap(innerJson: string, tag: string, convKey: Uint8Array, signerSk?: Uint8Array): NostrEvent;
+    protected resignEnvelope(e: NostrEvent): NostrEvent;
+    protected afterSnapshot(space: string, before: number): void;
+    /** Insert/update/delete on a public table → signed standard Nostr events (identity key). */
+    protected commitPublic(cells: CapturedCell[]): Promise<void>;
+    /** Project a verified event into a public table (replaceable semantics per preset). */
+    protected applyPublicEvent(table: string, e: NostrEvent): boolean;
+    /**
+     * Fetch standard events into a public table (verified, cached for offline use). With `live`,
+     * keeps a subscription open; call the returned `stop()` to end it.
+     */
+    syncPublic<T extends Extract<keyof S, string>>(table: T, filter?: PublicSyncFilter, opts?: {
+        live?: boolean;
+        relays?: readonly string[];
+        timeoutMs?: number;
+    }): Promise<{
+        received: number;
+        stop: () => void;
+    }>;
+    close(): Promise<void>;
+}
+export declare function createAnoDB<const S extends SchemaDefinition>(opts: AnoDBOptions<S>): Promise<AnoDB<S>>;