tablinum 0.0.1

package/.context/attachments/pasted_text_2026-03-07_15-48-27.txt

@@ -0,0 +1,498 @@
+# localstr — Product Requirements Document
+
+| | |
+|---|---|
+| **Version** | 0.1 — Draft |
+| **Author** | Kevin Åberg Kultalahti |
+| **Package** | `localstr` |
+| **Status** | Pre-implementation |
+
+---
+
+## 1. Purpose
+
+localstr is a browser-first local-first sync library. It gives developers a simple, typed API for storing and querying structured data that syncs automatically across devices and users via Nostr relays. The Nostr protocol is an implementation detail. Developers who use localstr never interact with keypairs, relay connections, event kinds, or NIPs. They define a schema, write data, query it, and optionally share it. Everything else happens underneath.
+
+The design goal is a library that a developer can integrate into an application in under thirty minutes without reading documentation about distributed systems, cryptography, or peer-to-peer networking.
+
+---
+
+## 2. Problem Statement
+
+Local-first applications — where the local device is the primary source of truth and sync happens in the background — are hard to build today. The options available to developers each carry significant costs.
+
+CRDTs solve the merge problem correctly but require deep understanding of distributed systems to implement, and the leading libraries expose that complexity directly to the developer. PouchDB and CouchDB require developers to operate their own infrastructure. Firestore and similar cloud databases give you sync for free but lock your data to a vendor and require a server round-trip for every read. Building on raw WebSockets means reinventing sync, conflict resolution, and offline queuing from scratch.
+
+The result is that most applications either skip local-first entirely and accept the UX tradeoffs of cloud-only data, or they invest months building sync infrastructure that should be a solved problem.
+
+localstr solves this by using the Nostr protocol as a sync layer. Nostr's signed event model maps naturally onto local-first architecture: each write produces a signed, encrypted, self-contained event that can be stored locally, published to multiple relays, and replicated to other devices without conflict. The local IndexedDB store is a materialized view of the event log. The relays are the backup and transport layer. Nothing is stored on a server that the developer controls.
+
+---
+
+## 3. Goals
+
+### 3.1 In Scope
+
+- A typed schema definition system where the developer defines collections and field types once, and TypeScript types are derived automatically.
+- A Dexie-inspired query builder API covering equality, range, sort, limit, and count operations.
+- Reactive subscriptions that push updates to callbacks whenever matching data changes.
+- Transparent encryption of all data using NIP-44 before it leaves the device.
+- Identity derived entirely from a password using Argon2id key derivation. The developer and user never handle a private key.
+- Multi-device sync via Nostr relays. Writes are published to relays and fetched on demand.
+- A collaboration model where a collection can be shared via an invite URL, allowing another user to join and receive the same encrypted data.
+- A simple key-value API alongside the collection API for unstructured or singleton data.
+- Browser-only target for v1. No Node.js or Bun support in the initial release.
+
+### 3.2 Out of Scope (v1)
+
+- Server-side or Node.js storage adapters (planned for v2 using LMDB).
+- JOIN operations across collections.
+- Full-text search.
+- Transactions spanning multiple writes.
+- Key rotation or member revocation from shared collections.
+- Conflict resolution beyond last-write-wins on replaceable events.
+- Any Nostr social features: profiles, follows, feeds, reactions.
+
+---
+
+## 4. Architecture
+
+### 4.1 Data Flow
+
+Every write follows the same path: the developer calls an API method, the library validates the data against the schema, encrypts the content using NIP-44, constructs a Nostr event, writes it to local IndexedDB, and publishes it to configured relays asynchronously. Reads query IndexedDB directly. The relays are never in the read path for local queries.
+
+On startup, or when sync is triggered manually, the library fetches events from relays that are newer than the latest locally stored event. These are decrypted, validated, and written into IndexedDB, updating the materialized KV and collection stores. This means the local store is always usable even when offline.
+
+### 4.2 Storage Model
+
+IndexedDB holds two logical stores, accessed via the `idb` library:
+
+**events** — the canonical append-only log of all Nostr events. Each row stores the raw event fields: `id`, `kind`, `pubkey`, `created_at`, `content` (encrypted), `tags` (JSON array), and `sig`. This store is the source of truth. If it is intact, all other state can be reconstructed from it.
+
+**kv** — a materialized view derived from the events store. Each row holds a `key`, the decrypted JSON `value`, `updated_at`, and a reference to the source `event_id`. This store exists for query performance. It is always rebuildable.
+
+Indexes on the events store cover: `kind`, `pubkey`, `created_at`, and the `d` tag (the primary identifier for replaceable events). Indexes on the kv store cover the collection prefix on the key and any scalar fields declared in the schema.
+
+### 4.3 Event Mapping
+
+Schema collections map to Nostr kind 30078 replaceable events. The `d` tag is set to a namespaced key combining the collection name and the record identifier. The content field holds the NIP-44 encrypted JSON payload of the record. When a record is updated, a new event with the same `d` tag replaces the previous one both locally and on relays.
+
+Append-only log entries (for collections marked as append-only in the schema) map to regular non-replaceable events, preserving full history.
+
+The key-value API uses the same kind 30078 mapping with a flat key as the `d` tag.
+
+### 4.4 Encryption
+
+All content is encrypted with NIP-44 before leaving the local device. The encryption key is the Nostr private key derived from the user's password via Argon2id. For personal data, the content is encrypted to the user's own public key. For shared collections, content is encrypted to a shared symmetric key that is distributed to members via NIP-59 gift wrap events.
+
+NIP-59 gift wrap adds three layers of indirection: the plaintext payload (rumor), a sealed inner event signed by the real keypair, and an outer gift wrap event signed by a single-use ephemeral keypair. This means relay operators cannot determine who sent data to whom, and cannot correlate events to identities.
+
+### 4.5 Identity
+
+Identity is derived entirely from the user's password. The library passes the password through Argon2id with an application-specific salt to produce 64 bytes. The first 32 bytes become the encryption key. The second 32 bytes become the Nostr private key, from which the public key is derived deterministically.
+
+The developer never stores, serializes, or transmits a private key. Recovery is "back up your password". This is the entire key management story in v1.
+
+An escape hatch `signer` option in `createLocalstr` allows advanced users to supply their own NIP-07 compatible signer if they want to bring an existing Nostr identity. This is optional and not part of the primary UX.
+
+### 4.6 Relay Strategy
+
+The library maintains a pool of relay connections using nostr-tools `SimplePool`. Writes are published to all configured relays. Reads fetch from all relays and deduplicate by event id. The relay pool is managed internally. The developer configures relay URLs at initialization and does not interact with the pool directly.
+
+Sync is manual by default. The developer calls `db.sync()` to trigger a fetch of new events from relays. An `autoSync` option can be set at initialization to enable periodic background sync. The sync status is observable via `db.syncStatus()` and `db.onSync(callback)`.
+
+---
+
+## 5. Schema Definition
+
+### 5.1 Overview
+
+The schema is the single source of truth for the library. It drives TypeScript type inference, IndexedDB index creation, runtime validation, and query planning. It is defined once at initialization using builder functions exported from the library.
+
+### 5.2 Collection Builder
+
+A collection is a named group of records sharing the same field structure. It is declared with the `collection()` function, which takes an object mapping field names to field descriptors.
+
+```typescript
+import { collection, field } from 'localstr'
+
+const exercises = collection({
+  name:     field.string(),
+  sets:     field.number(),
+  reps:     field.number(),
+  weight:   field.number().optional(),
+  loggedAt: field.number(),
+})
+```
+
+### 5.3 Field Types
+
+| Field Declaration | Description |
+|---|---|
+| `field.string()` | A required UTF-8 string. Gets an IndexedDB index. |
+| `field.number()` | A required number (integer or float). Gets an IndexedDB index. |
+| `field.boolean()` | A required boolean. Gets an IndexedDB index. |
+| `field.string().array()` | An array of strings. Gets a multiEntry IndexedDB index. |
+| `field.number().array()` | An array of numbers. Gets a multiEntry IndexedDB index. |
+| `field.json()` | An opaque JSON value. Stored as-is, not indexed, not queryable. |
+| `field.*.optional()` | Any field type marked optional. Indexed but sparse. TypeScript type becomes `T \| undefined`. |
+
+### 5.4 Type Inference
+
+The TypeScript type for a record in a collection is fully inferred from the schema. The developer does not write a separate interface. Required fields are non-optional in the inferred type. Optional fields carry `| undefined`. Array fields produce `T[]`. The `json()` field produces `unknown`.
+
+The inferred types flow through the entire API surface: `add()`, `update()`, `where()`, and `watch()` all receive and return the correct types without any additional annotation from the developer.
+
+### 5.5 Full Schema Example
+
+```typescript
+const schema = {
+  exercises: collection({
+    name:     field.string(),
+    sets:     field.number(),
+    reps:     field.number(),
+    weight:   field.number().optional(),
+    loggedAt: field.number(),
+  }),
+  bodyweight: collection({
+    kg:         field.number(),
+    recordedAt: field.number(),
+  }),
+}
+
+const db = await createLocalstr({ password, relays, schema })
+```
+
+---
+
+## 6. API Reference
+
+### 6.1 Initialization
+
+```typescript
+const db = await createLocalstr({
+  password:      string,
+  relays:        string[],
+  schema:        Schema,
+  autoSync?:     boolean,   // default false
+  syncInterval?: number,    // milliseconds, default off
+  signer?:       NostrSigner,
+})
+```
+
+`createLocalstr` is async. It derives the keypair from the password, opens the IndexedDB database, creates or migrates stores based on the schema, and establishes relay connections. It resolves with the db handle. It rejects if the password is empty, if no relays are provided, or if IndexedDB is unavailable.
+
+### 6.2 Collection API
+
+#### add()
+
+```typescript
+const id = await db.collection('exercises').add({
+  name:     'Squat',
+  sets:     5,
+  reps:     5,
+  weight:   100,
+  loggedAt: Date.now(),
+})
+// returns: string (the generated record id)
+```
+
+Validates the input against the schema at runtime. Generates a unique id. Writes to IndexedDB immediately. Publishes to relays asynchronously. Returns the record id.
+
+#### update()
+
+```typescript
+await db.collection('exercises').update(id, {
+  weight: 105,
+})
+```
+
+Accepts a partial record. Merges with the existing record. Validates the merged result. Writes a new replaceable event to IndexedDB and relays. Throws if the id does not exist.
+
+#### delete()
+
+```typescript
+await db.collection('exercises').delete(id)
+```
+
+Marks the record as deleted locally. Publishes a deletion event to relays. The record is excluded from all subsequent queries.
+
+#### Query Builder
+
+Queries are constructed by chaining methods on the collection handle. The query is not executed until `get()`, `first()`, `count()`, or `watch()` is called.
+
+```typescript
+const results = await db.collection('exercises')
+  .where('loggedAt').above(startOfDay)
+  .sortBy('loggedAt', 'asc')
+  .limit(20)
+  .get()
+```
+
+| Method | Description |
+|---|---|
+| `.where(field)` | Begins a filter clause. Must be followed by a comparator. |
+| `.equals(value)` | Exact match on the current field. |
+| `.above(value)` | Greater than. Numbers and timestamps only. |
+| `.below(value)` | Less than. Numbers and timestamps only. |
+| `.between(lower, upper)` | Inclusive range. Numbers and timestamps only. |
+| `.anyOf(values[])` | Matches any value in the provided array. |
+| `.sortBy(field, 'asc'\|'desc')` | Orders results. Defaults to ascending. |
+| `.limit(n)` | Maximum number of results to return. |
+| `.offset(n)` | Skip the first n results. Used for pagination. |
+| `.get()` | Executes the query. Returns `Promise<T[]>`. |
+| `.first()` | Executes the query. Returns `Promise<T \| undefined>`. |
+| `.count()` | Executes the query. Returns `Promise<number>`. Does not fetch record content. |
+| `.each(cb)` | Executes the query and calls cb for each result. Returns `Promise<void>`. |
+| `.watch(cb)` | Registers a live subscription. Calls cb immediately with current results, then again on any change. Returns an unsubscribe function. |
+
+#### Query Planning
+
+When a query is executed, the library splits it into two plans: a relay filter plan and a local filter plan. Fields that map directly to Nostr filter primitives (tag filters, `since`, `until`, `limit`) are included in the relay REQ filter. All other predicates are applied locally after fetching from IndexedDB. The developer sees neither plan. The split is transparent.
+
+Fields indexed in IndexedDB use index-based cursors for local filtering rather than full table scans. This keeps local queries fast regardless of event log size.
+
+### 6.3 Key-Value API
+
+| Method | Description |
+|---|---|
+| `db.set(key, value)` | Stores any JSON-serializable value at key. Returns `Promise<void>`. |
+| `db.get(key)` | Returns `Promise<unknown \| undefined>`. Returns undefined if key does not exist. |
+| `db.delete(key)` | Removes the key. Returns `Promise<void>`. |
+| `db.has(key)` | Returns `Promise<boolean>`. |
+| `db.subscribe(key, cb)` | Calls cb with the current value, then on every change. Returns unsubscribe function. |
+
+### 6.4 Sync API
+
+| Method | Description |
+|---|---|
+| `db.sync()` | Fetches new events from all relays for all collections. Returns `Promise<void>` that resolves when the fetch is complete. |
+| `db.sync(collectionName)` | Fetches new events for a specific collection only. |
+| `db.syncStatus()` | Returns `'idle' \| 'syncing' \| 'error'`. |
+| `db.onSync(cb)` | Registers a callback invoked on every sync cycle with status and event count. Returns unsubscribe function. |
+
+### 6.5 Collaboration API
+
+#### share()
+
+```typescript
+const url = await db.share('exercises')
+// returns: string — an invite URL with encrypted key material in the fragment
+
+const url = await db.share('exercises', { password: 'optional-extra-password' })
+// password-protected invite — recipient must supply password to join
+```
+
+Generates an invite URL for the specified collection. The URL fragment contains an ephemeral keypair and the collection's shared encryption key, wrapped in a gift wrap event. The fragment is never sent to a server. The `password` option runs the fragment key material through Argon2id before encoding, requiring the recipient to know the password to decrypt.
+
+#### join()
+
+```typescript
+await db.join(inviteUrl)
+await db.join(inviteUrl, { password: 'the-password' })
+```
+
+Parses the invite URL, decrypts the key material from the fragment, derives the shared collection keypair, and begins syncing the collection from relays. After `join()` resolves, the collection is available via the standard query API.
+
+#### members()
+
+```typescript
+const members = await db.members('exercises')
+// returns: Array<{ pubkey: string, joinedAt: number }>
+```
+
+### 6.6 Lifecycle API
+
+| Method | Description |
+|---|---|
+| `db.close()` | Closes relay connections and IndexedDB handle. Returns `Promise<void>`. |
+| `db.destroy()` | Closes connections and deletes all local data. Returns `Promise<void>`. |
+| `db.export()` | Returns a JSON-serializable snapshot of all local events. Useful for backup. |
+| `db.import(data)` | Replays a previously exported snapshot into local storage. Merges with existing data. |
+
+---
+
+## 7. Internal Services
+
+The library is structured as a set of internal services wired together at initialization. Each service has a single responsibility. They communicate through typed interfaces rather than direct imports. This structure makes the codebase testable in isolation and makes it straightforward to swap implementations in future versions.
+
+### 7.1 IdentityService
+
+Responsible for all keypair operations. Takes the password and derives a 64-byte seed using Argon2id with a fixed application-level salt concatenated with an optional user-supplied salt. The first 32 bytes become the private key. The public key is derived from the private key using secp256k1. Exposes `getPrivateKey()`, `getPublicKey()`, and `sign(event)` methods. Holds the keypair in memory only. Never serializes private key material to any storage.
+
+### 7.2 CryptoService
+
+Responsible for encrypting and decrypting event content. Uses NIP-44 for all encryption. Exposes `encrypt(plaintext, recipientPubkey)` and `decrypt(ciphertext, senderPubkey)` methods. Also exposes `giftWrap(event, recipientPubkey)` and `unwrapGift(wrappedEvent)` for the collaboration invite flow. Depends on IdentityService for the local keypair.
+
+### 7.3 LocalStore
+
+Responsible for all IndexedDB operations. Wraps `idb`. Exposes typed methods for writing events, querying the events store by filter, reading and writing the kv store, managing indexes, and handling schema migrations. Does not know about Nostr event semantics. Treats events as typed records. Exposes a change notification mechanism that QueryService uses to power reactive subscriptions.
+
+### 7.4 RelayService
+
+Responsible for all relay communication. Wraps nostr-tools `SimplePool`. Exposes `publish(event)`, `fetch(filters)`, and `subscribe(filters, onEvent)` methods. Manages connection state and reconnection. Reports sync status changes. Does not know about encryption or schema. Receives and sends raw Nostr events.
+
+### 7.5 EventBuilder
+
+Responsible for constructing valid Nostr events from application-level write operations. Takes a collection name, record id, and plaintext payload. Determines the correct event kind (30078 for replaceable, standard kind for append-only). Sets the `d` tag. Calls CryptoService to encrypt the content. Calls IdentityService to sign the event. Returns a complete signed event ready for storage and publication.
+
+### 7.6 QueryPlanner
+
+Responsible for splitting a query builder expression into a relay filter plan and a local IndexedDB filter plan. Inspects the schema to determine which fields are indexed. Produces a `NostrFilter` object for RelayService and an IndexedDB cursor strategy for LocalStore. Ensures that the two plans are semantically equivalent: the intersection of what the relay returns and what the local filter matches is the correct result set.
+
+### 7.7 Validator
+
+Responsible for runtime validation of write payloads against the schema. Checks that required fields are present and have the correct types. Checks that optional fields, if present, have the correct types. Returns typed errors rather than throwing. Called by the collection `add()` and `update()` implementations before any write is committed.
+
+### 7.8 SchemaManager
+
+Responsible for translating the schema definition into IndexedDB store configurations and managing migrations. On initialization, compares the current schema version against the stored version in IndexedDB. If the schema has changed, creates new indexes, drops removed indexes, and increments the store version. The schema version is a hash of the schema definition, not a manually incremented integer.
+
+---
+
+## 8. Dependencies
+
+The library has a minimal, carefully chosen dependency set. All dependencies must be tree-shakeable. The total bundle size target for a minimal integration (single collection, no collaboration) is under 50KB gzipped.
+
+| Package | Approx. Size | Purpose |
+|---|---|---|
+| `nostr-tools` | ~30KB tree-shaken | Event construction, signing, relay pool, NIP-44 encryption, NIP-59 gift wrap |
+| `idb` | ~1KB | Promise-based IndexedDB wrapper. Handles the async complexity and transaction management of raw IndexedDB. |
+| `@noble/hashes` | ~10KB | Argon2id implementation for key derivation. Also provides SHA-256 used in event id generation. |
+
+Effect is used internally for service composition, typed error handling, and dependency injection. It does not appear in the public API and is not a peer dependency. Consumers of the library do not need to know about or install Effect.
+
+---
+
+## 9. Error Handling
+
+All errors are typed and surfaced through the return types of async methods, not through untyped throws. Each service defines its own error variants. The public API methods surface a union of the errors that can occur in their call path.
+
+The developer can handle errors granularly or use a catch-all. Relay errors do not cause local operations to fail. A write that publishes successfully to IndexedDB but fails to reach any relay is considered a local success and a sync warning, not a write failure.
+
+| Error | Meaning |
+|---|---|
+| `ValidationError` | A write payload failed schema validation. Contains the field name and expected type. |
+| `StorageError` | IndexedDB operation failed. Includes `QuotaExceededError` wrapping. |
+| `CryptoError` | Encryption or decryption failed. Likely a key mismatch on shared collections. |
+| `RelayError` | A relay connection failed or rejected an event. Non-fatal for writes. |
+| `SyncError` | A sync cycle failed to reach any relay. Local data is unaffected. |
+| `InviteError` | An invite URL could not be parsed or decrypted. Likely wrong password or malformed URL. |
+| `NotFoundError` | An `update()` or `delete()` was called with an id that does not exist locally. |
+
+---
+
+## 10. Schema Migration
+
+When a developer adds, removes, or changes fields in the schema, the library detects the change on the next initialization. The SchemaManager computes a hash of the schema definition and compares it to the hash stored in IndexedDB metadata.
+
+If they differ, the following migration rules apply automatically:
+
+- **New required field added:** existing records will have the field set to `undefined` at runtime. TypeScript will not allow this because the field is required, so developers are expected to backfill via a one-time update loop. The library does not block startup waiting for backfill.
+- **New optional field added:** existing records return `undefined` for the new field. No action required.
+- **Field removed:** the field is dropped from new writes. Existing events in the events store retain the old field in their encrypted payload but it is not surfaced in query results.
+- **Field type changed:** treated as a remove and add. Old values are not migrated. The developer is responsible for data coercion if needed.
+
+The events store is the source of truth and is never modified by a migration. Migrations only affect the kv materialized view and the IndexedDB indexes. If migration fails, the library falls back to scanning from the events store to rebuild the kv store.
+
+---
+
+## 11. Offline Behaviour
+
+All read and write operations work offline. Reads query IndexedDB directly and never require a relay connection. Writes commit to IndexedDB immediately and queue relay publication for when connectivity is restored.
+
+The library does not implement its own connectivity detection. It relies on the browser's `navigator.onLine` and the `online`/`offline` events. When the browser comes back online, any queued relay publications are flushed.
+
+There is no explicit conflict resolution mechanism in v1. The last-write-wins semantics of Nostr replaceable events (kind 30078) handle concurrent edits: the event with the highest `created_at` timestamp wins. For append-only collections, all events are preserved.
+
+---
+
+## 12. Security Model
+
+All data is encrypted at rest in IndexedDB and in transit to relays. Relay operators see only encrypted ciphertext, event timestamps, and public keys. They cannot read the content of any event.
+
+Public keys derived from user passwords are pseudonymous. Two different applications using the same password with different application-level salts produce different keypairs, preventing cross-application identity correlation.
+
+The invite URL fragment is never sent to a server. URL fragments are not included in HTTP requests and are not logged by servers or CDNs. Password-protected invites require the password to be communicated out-of-band, ensuring that even if the URL is intercepted, the encrypted key material cannot be decrypted.
+
+The library does not implement server-side verification, authentication, or authorization. Access control is purely key-based: you can read a shared collection if and only if you have the shared encryption key.
+
+---
+
+## 13. Testing Strategy
+
+### 13.1 Unit Tests
+
+Each internal service is tested in isolation with mocked dependencies. The Validator, QueryPlanner, SchemaManager, and EventBuilder have no I/O dependencies and are pure functions suitable for direct unit testing. The CryptoService and IdentityService tests verify correctness of key derivation and encryption round-trips.
+
+### 13.2 Integration Tests
+
+The LocalStore service is tested against a real IndexedDB instance using a browser test runner (Vitest with happy-dom or a real browser via Playwright). Tests cover schema migration, index correctness, and concurrent write behaviour. The RelayService is tested against a local relay process spun up for tests.
+
+### 13.3 End-to-End Tests
+
+A small set of Playwright tests cover the full developer-facing API: initialization, write, query, sync, and the share/join collaboration flow across two simulated browser contexts with a local relay.
+
+---
+
+## 14. Package Structure
+
+```
+localstr/
+  src/
+    index.ts                  — Public API exports
+    schema/
+      collection.ts           — collection() builder
+      field.ts                — field.* builders and type inference
+      types.ts                — Inferred type utilities
+    services/
+      identity.ts             — IdentityService
+      crypto.ts               — CryptoService
+      local-store.ts          — LocalStore (idb wrapper)
+      relay.ts                — RelayService (nostr-tools wrapper)
+      event-builder.ts        — EventBuilder
+      query-planner.ts        — QueryPlanner
+      validator.ts            — Validator
+      schema-manager.ts       — SchemaManager
+    api/
+      collection.ts           — Collection query builder implementation
+      kv.ts                   — Key-value API implementation
+      sync.ts                 — Sync API implementation
+      share.ts                — Collaboration API implementation
+    errors.ts                 — All typed error definitions
+    localstr.ts               — createLocalstr() implementation
+  test/
+    unit/
+    integration/
+    e2e/
+  package.json
+  tsconfig.json
+  vite.config.ts
+```
+
+---
+
+## 15. Explicit Non-Goals
+
+This section records deliberate decisions not to do certain things, to prevent them from being relitigated during implementation.
+
+- localstr does not expose Nostr concepts to the developer. No event kinds, no NIPs, no relay filters, no keypair management surfaces in the public API.
+- localstr does not use SQLite WASM. The query surface is constrained by what Nostr relay filters can express, so the additional power of SQL is not useful. The cold start cost and WASM complexity is not justified.
+- localstr does not use OPFS directly. The performance benefit of raw OPFS requires building a custom storage engine. `idb` on IndexedDB is sufficient for the event log sizes typical in local-first applications.
+- localstr does not use Dexie. The query API is Dexie-inspired but built from scratch on `idb`, keeping the dependency surface minimal and avoiding the mismatch between Dexie's schema model and localstr's schema model.
+- localstr does not use NDK. NDK is a social Nostr client library with wallet integration, web-of-trust, and NIP-90 support. It is not appropriate as a foundation for a general-purpose sync library.
+- localstr does not implement CRDT merge semantics. Last-write-wins is the conflict resolution strategy. For the target use cases (personal data, collaborative documents with low write contention), this is sufficient.
+
+---
+
+## 16. Open Questions
+
+| Question | Notes |
+|---|---|
+| Final package name | Settled: `localstr` |
+| npm scope | Publish as standalone `localstr` package. |
+| `autoSync` default | Currently defaults to `false` (manual sync). Should it default to `true` for better out-of-box experience? |
+| Append-only collection syntax | How does the developer declare a collection as append-only in the schema? Flag on `collection()`? Separate `appendCollection()` builder? |
+| Record id generation | Library-generated UUIDs, or developer-supplied ids? Or both? |
+| Relay failure threshold | How many relay failures before `syncStatus` returns `'error'` vs `'degraded'`? |
+| Private browsing | IndexedDB is available in private browsing but may have reduced quota. Should the library warn or degrade gracefully? |

package/.context/plans/add-changesets-to-douala-v4.md

@@ -0,0 +1,48 @@
+# Add Changesets to douala-v4
+
+## Context
+The library (`douala-v4`, version `0.0.1`) needs release management tooling. Changesets will handle versioning, changelog generation, and npm publish workflows. The project uses Bun as its package manager and is a single package (not a monorepo).
+
+## Steps
+
+### 1. Install `@changesets/cli`
+```bash
+bun add -D @changesets/cli
+```
+
+### 2. Initialize changesets
+```bash
+bunx changeset init
+```
+This creates the `.changeset/` directory with a `config.json` and a `README.md`.
+
+### 3. Update `.changeset/config.json`
+Set appropriate defaults:
+- `"access": "public"` (assuming this will be a public npm package)
+- `"baseBranch": "main"`
+- `"commit": false` (don't auto-commit version bumps)
+
+### 4. Add scripts to `package.json`
+Add convenience scripts:
+```json
+"changeset": "changeset",
+"version": "changeset version",
+"release": "changeset publish"
+```
+
+### 5. Add GitHub Actions release workflow
+Create `.github/workflows/release.yml` that:
+- Triggers on push to `main`
+- Runs `changeset version` to bump versions and update CHANGELOG
+- Opens a "Version Packages" PR via `changesets/action`
+- When that PR merges, publishes to npm via `changeset publish`
+- Uses `NPM_TOKEN` secret for publishing
+
+## Files to modify
+- `package.json` — add devDependency + scripts
+- `.changeset/config.json` — created by init, set `access: "public"`, `baseBranch: "main"`
+- `.github/workflows/release.yml` — new file for CI release automation
+
+## Verification
+- Run `bunx changeset` to confirm it prompts for a new changeset
+- Run `bunx changeset status` to confirm it reports no changesets

package/.context/plans/dexie-js-style-query-language-for-localstr.md

@@ -0,0 +1,115 @@
+# Dexie.js-style Query Language for localstr
+
+## Context
+
+localstr currently only supports `where(field).equals(value)` with no sorting, range queries, or pagination. We want a rich, chainable query API inspired by Dexie.js so users can filter, sort, and paginate data expressively.
+
+**Key decision: in-memory execution.** All collections share one IDB object store with nested `data.*` fields, so native IDB indices would span all collections and require complex cursor logic for marginal gain on typical local-first dataset sizes. We'll build the query API as in-memory operations on the `getAllRecords()` result set. The `indices` schema option is stored for future optimization but not enforced at the type level yet.
+
+## Target API
+
+```typescript
+// Schema with optional index hints
+const todos =
+  yield *
+  collection(
+    "todos",
+    {
+      title: field.string(),
+      done: field.boolean(),
+      priority: field.number(),
+    },
+    { indices: ["done", "priority"] },
+  );
+
+// Range queries
+yield * (yield * col.where("priority")).above(3).toArray();
+yield * (yield * col.where("priority")).between(1, 5).toArray();
+yield * (yield * col.where("title")).startsWith("Buy").toArray();
+yield * (yield * col.where("done")).anyOf([true, false]).toArray();
+
+// Sorting
+yield * col.orderBy("priority").toArray();
+yield * col.orderBy("priority").reverse().toArray();
+
+// Pagination
+yield * col.orderBy("priority").offset(10).limit(5).toArray();
+
+// Chained filter + sort
+yield * (yield * col.where("done")).equals(false).sortBy("priority").toArray();
+```
+
+## Files to Modify
+
+### 1. `src/schema/collection.ts` — Add indices option
+
+- Add optional third parameter `options?: { indices?: ReadonlyArray<string & keyof F> }`
+- Store `indices` on `CollectionDef` (default `[]`)
+- Validate each index key exists in `fields` and is not `json`/`array` type
+- Fully backwards compatible — existing calls without options still work
+
+### 2. `src/schema/types.ts` — Add IndexedFields type
+
+- Add `IndexedFields<C>` utility type extracting index field names from a `CollectionDef`
+- Not used for enforcement yet, but available for future type narrowing
+
+### 3. `src/crud/query-builder.ts` — Rewrite with rich query builder
+
+Replace the current simple WhereClause/QueryExecutor with three interfaces:
+
+**`WhereClause<T>`** — returned by `col.where(field)`:
+
+- `equals(value)` → `QueryBuilder<T>`
+- `above(value)` / `aboveOrEqual(value)` → `QueryBuilder<T>`
+- `below(value)` / `belowOrEqual(value)` → `QueryBuilder<T>`
+- `between(lower, upper)` → `QueryBuilder<T>`
+- `startsWith(prefix)` → `QueryBuilder<T>`
+- `anyOf(values)` / `noneOf(values)` → `QueryBuilder<T>`
+
+**`QueryBuilder<T>`** — chainable intermediate:
+
+- `and(fn)` → `QueryBuilder<T>` (JS predicate filter)
+- `sortBy(field)` → `QueryBuilder<T>`
+- `reverse()` → `QueryBuilder<T>`
+- `offset(n)` / `limit(n)` → `QueryBuilder<T>`
+- Terminal: `toArray()`, `first()`, `count()`, `watch()`
+- Alias: `get()` → `toArray()` (backwards compat)
+
+**`OrderByBuilder<T>`** — returned by `col.orderBy(field)`:
+
+- `reverse()` → `OrderByBuilder<T>`
+- `offset(n)` / `limit(n)` → `OrderByBuilder<T>`
+- Terminal: `toArray()`, `first()`, `count()`, `watch()`
+
+Internal `executeQuery()` function applies the pipeline: filter deleted → apply predicates → sort → offset → limit → map.
+
+For `watch()`, build a stream that re-executes the full query pipeline on each PubSub change event (reuses `WatchContext` pattern from `watch.ts` but doesn't require modifying it).
+
+### 4. `src/crud/collection-handle.ts` — Add orderBy method
+
+- Add `orderBy(field)` to `CollectionHandle` interface returning `OrderByBuilder<InferRecord<C>>`
+- `orderBy` is synchronous (returns builder directly, not wrapped in Effect) — validates field at build time
+- Update `where()` to use the new `createWhereClause` that returns the richer `WhereClause<T>`
+
+### 5. `src/index.ts` — Update exports
+
+- Export `QueryBuilder`, `OrderByBuilder` types
+- Keep `QueryExecutor` as deprecated type alias for backwards compat
+
+### 6. `demo/app.ts` — Update demo
+
+- Add examples using `orderBy`, `above`, `between`, `sortBy`, `limit`
+
+## Implementation Order
+
+1. `src/schema/collection.ts` + `src/schema/types.ts` (schema changes)
+2. `src/crud/query-builder.ts` (core query builder rewrite)
+3. `src/crud/collection-handle.ts` (wire up orderBy + updated where)
+4. `src/index.ts` (exports)
+5. `demo/app.ts` (usage examples)
+
+## Verification
+
+- `bun run check` (typecheck)
+- Update demo to exercise new query methods and run it
+- Verify backwards compat: existing `where("field").equals(val).get()` still works