tablinum 0.0.1

package/.context/plans/dexie-js-style-query-language-with-per-collection-.md

@@ -0,0 +1,336 @@
+# Dexie.js-style Query Language with Per-Collection IDB Stores
+
+## Context
+
+localstr currently only supports `where(field).equals(value)` with no sorting, range queries, or pagination. All collections share a single IDB `records` object store with nested `data.*` fields, making real indices impossible. We're migrating to per-collection IDB object stores with native indices, enabling a rich chainable query API inspired by Dexie.js.
+
+## Target API
+
+```typescript
+// Schema with indices
+const todos =
+  yield *
+  collection(
+    "todos",
+    {
+      title: field.string(),
+      done: field.boolean(),
+      priority: field.number(),
+    },
+    { indices: ["done", "priority"] },
+  );
+
+// Range queries — single yield* at the terminal only
+yield * col.where("priority").above(3).get();
+yield * col.where("priority").between(1, 5).get();
+yield * col.where("title").startsWith("Buy").get();
+
+// Sorting & pagination
+yield * col.orderBy("priority").get();
+yield * col.orderBy("priority").reverse().get();
+yield * col.orderBy("priority").offset(10).limit(5).get();
+
+// Chained filter + sort
+yield * col.where("done").equals(false).sortBy("priority").get();
+```
+
+**Key design choice:** `where()` and `orderBy()` are synchronous — they return builder objects directly, not Effects. The entire chain before a terminal (`.get()`, `.first()`, etc.) is pure data describing a query plan. Only the terminal returns an `Effect`. Field validation is deferred to execution time. TypeScript catches field name typos at compile time anyway.
+
+**Effect v4 note:** Uses `effect@4.0.0-beta.28`. All code follows v4 patterns: `Data.TaggedError("Tag")<{ fields }>`, `Effect.gen(function* () { ... })` (no adapter), `yield* new ErrorClass(...)` to fail. Plan follows these same conventions.
+
+---
+
+## Step 1: Schema — Add indices to `CollectionDef`
+
+**File: `src/schema/collection.ts`**
+
+- Add optional third parameter: `options?: { indices?: ReadonlyArray<string & keyof F> }`
+- Add `indices` field to `CollectionDef` interface (default `[]`)
+- Validate each index key exists in `fields` and is not `json` or `array` type
+- Backwards compatible — existing two-arg calls still work
+
+**File: `src/schema/types.ts`**
+
+- Add `IndexedFields<C>` utility type (for future type-level enforcement)
+
+---
+
+## Step 2: Storage — Per-collection IDB object stores
+
+**File: `src/storage/idb.ts`**
+
+This is the biggest change. Replace the shared `records` store with per-collection stores.
+
+### New `StoredRecord` shape (flattened)
+
+```typescript
+// Before: { id, collection, data: { title, done, ... }, deleted, updatedAt }
+// After:  { id, _deleted, _updatedAt, title, done, ... }
+```
+
+Drop the `collection` and `data` wrapper — fields live at top level. `_deleted` and `_updatedAt` use underscore prefix to avoid conflicts (already reserved in schema validation).
+
+### Schema-aware `openDB`
+
+`openIDBStorage` needs the schema config passed in so it can create per-collection object stores and indices:
+
+```typescript
+export function openIDBStorage(
+  dbName: string | undefined,
+  schema: SchemaConfig, // NEW: needed to create stores + indices
+): Effect.Effect<IDBStorageHandle, StorageError, Scope.Scope>;
+```
+
+**Version strategy:** Compute a deterministic version number from the schema. Hash the sorted collection names + their sorted index declarations → produce a numeric version. When schema changes, version bumps, triggering `onupgradeneeded`.
+
+**`upgrade` handler:**
+
+- For each collection in schema, create object store `col_{name}` with keyPath `"id"` if it doesn't exist
+- Create IDB indices for each declared index field (keyPath is the field name directly since data is flattened)
+- Remove old stores/indices that no longer exist in schema
+- Keep `events` and `giftwraps` stores unchanged
+- If old shared `records` store exists, migrate data out then delete it
+
+### Updated `IDBStorageHandle` interface
+
+```typescript
+// Records — now collection-scoped with flat shape
+readonly putRecord: (collection: string, record: Record<string, unknown>) => Effect.Effect<void, StorageError>;
+readonly getRecord: (collection: string, id: string) => Effect.Effect<Record<string, unknown> | undefined, StorageError>;
+readonly getAllRecords: (collection: string) => Effect.Effect<ReadonlyArray<Record<string, unknown>>, StorageError>;
+readonly countRecords: (collection: string) => Effect.Effect<number, StorageError>;
+readonly clearRecords: (collection: string) => Effect.Effect<void, StorageError>;
+
+// NEW: index-based queries
+readonly getByIndex: (collection: string, indexName: string, value: IDBValidKey) => Effect.Effect<ReadonlyArray<Record<string, unknown>>, StorageError>;
+readonly getByIndexRange: (collection: string, indexName: string, range: IDBKeyRange) => Effect.Effect<ReadonlyArray<Record<string, unknown>>, StorageError>;
+readonly getAllSorted: (collection: string, indexName: string, direction?: "next" | "prev") => Effect.Effect<ReadonlyArray<Record<string, unknown>>, StorageError>;
+```
+
+The store name for a collection is `col_{collectionName}`.
+
+### Events and giftwraps stores — unchanged
+
+These stay as shared stores. No changes needed.
+
+---
+
+## Step 3: Update `records-store.ts` — Flattened record shape
+
+**File: `src/storage/records-store.ts`**
+
+Update `applyEvent` to write flattened records:
+
+```typescript
+// Before
+const record: StoredRecord = {
+  id: event.recordId,
+  collection: event.collection,
+  data: event.data ?? {},
+  deleted: event.kind === "delete",
+  updatedAt: event.createdAt,
+};
+yield * storage.putRecord(record);
+
+// After
+const record = {
+  id: event.recordId,
+  _deleted: event.kind === "delete",
+  _updatedAt: event.createdAt,
+  ...(event.data ?? {}),
+};
+yield * storage.putRecord(event.collection, record);
+```
+
+Update `rebuild` similarly — it now calls `storage.clearRecords(collection)` per collection and writes flattened records.
+
+The `rebuild` function needs access to collection names. Options:
+
+- Accept `collections: string[]` parameter
+- Or clear each collection store encountered in events
+
+Simplest: accept `collections: string[]` from caller (create-localstr already knows all collection names).
+
+---
+
+## Step 4: Query Builder — Rich chainable API
+
+**File: `src/crud/query-builder.ts`** (major rewrite)
+
+### Internal query plan
+
+```typescript
+interface QueryPlan {
+  filters: Array<(record: Record<string, unknown>) => boolean>;
+  orderBy?: { field: string; direction: "asc" | "desc" };
+  offset?: number;
+  limit?: number;
+  // Index hint for IDB-accelerated queries
+  indexQuery?: { field: string; range: IDBKeyRange | IDBValidKey; type: "value" | "range" };
+}
+```
+
+### `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>
+```
+
+Each method sets both a filter predicate AND an index hint (if the field is indexed). For `startsWith`, the IDB range is `IDBKeyRange.bound(prefix, prefix + '\uffff')`.
+
+### `QueryBuilder<T>` — chainable
+
+```
+and(fn) → QueryBuilder<T>         // JS predicate
+sortBy(field) → QueryBuilder<T>   // set orderBy
+reverse() → QueryBuilder<T>       // flip direction
+offset(n) / limit(n) → QueryBuilder<T>
+get() → Effect<T[], StorageError>        // terminal: all matching records
+first() → Effect<T | null, StorageError> // terminal
+count() → Effect<number, StorageError>   // terminal
+watch() → Stream<T[], StorageError>      // terminal
+```
+
+### `OrderByBuilder<T>` — returned by `col.orderBy(field)`
+
+Same chain/terminal methods as QueryBuilder minus `and/sortBy`:
+
+```
+reverse() → OrderByBuilder<T>
+offset(n) / limit(n) → OrderByBuilder<T>
+get() → Effect<T[], StorageError>        // terminal
+first() → Effect<T | null, StorageError> // terminal
+count() → Effect<number, StorageError>   // terminal
+watch() → Stream<T[], StorageError>      // terminal
+```
+
+### Execution strategy
+
+The `executeQuery` function:
+
+1. If there's an `indexQuery` hint → use `storage.getByIndex` or `storage.getByIndexRange`
+2. Otherwise → `storage.getAllRecords`
+3. Filter `_deleted` records
+4. Apply remaining filter predicates
+5. Sort (if `orderBy` set and not already sorted by IDB)
+6. Apply offset/limit
+7. Map to user-facing record type (strip `_deleted`, `_updatedAt`)
+
+### Watch implementation
+
+`QueryBuilder.watch()` builds a stream that re-executes the full query on each PubSub change event, same pattern as current `watchCollection` but self-contained (no changes to `watch.ts` needed).
+
+---
+
+## Step 5: Update `collection-handle.ts`
+
+**File: `src/crud/collection-handle.ts`**
+
+- Add `orderBy(field)` method to `CollectionHandle` interface
+- Both `where()` and `orderBy()` return builders directly (synchronous, not wrapped in Effect)
+- Field validation deferred to terminal execution — errors surface as `ValidationError` in the Effect
+- This is a **breaking change** to `where()` signature (was `Effect<WhereClause>`, now just `WhereClause`)
+- Update `mapRecord` — now maps from flat `Record<string, unknown>` instead of `StoredRecord`:
+  ```typescript
+  // Before: { id: record.id, ...record.data }
+  // After: strip _deleted, _updatedAt from flat record
+  function mapRecord(record: Record<string, unknown>): InferRecord<C> {
+    const { _deleted, _updatedAt, ...fields } = record;
+    return fields as InferRecord<C>;
+  }
+  ```
+- Update all CRUD methods (`add`, `update`, `delete`, `get`, `first`, `count`) to use new `putRecord(collection, record)` signature and flat record shape
+- Pass `CollectionDef` (with indices) to query builder so it knows which fields are indexed
+
+---
+
+## Step 6: Update `create-localstr.ts`
+
+**File: `src/db/create-localstr.ts`**
+
+- Pass `config.schema` to `openIDBStorage(config.dbName, config.schema)` so it can create per-collection stores
+- Pass collection names to `rebuild()`: `rebuildRecords(storage, Object.keys(config.schema))`
+- No other changes needed — sync, identity, watch infra all stay the same
+
+---
+
+## Step 7: Update exports
+
+**File: `src/index.ts`**
+
+- Export `QueryBuilder`, `OrderByBuilder` types
+- Keep `QueryExecutor` as deprecated alias → `QueryBuilder`
+
+---
+
+## Step 8: Update demo
+
+**File: `demo/app.ts`**
+
+- Add indices to collection definition
+- Add examples using `orderBy`, `above`, `between`, `limit`
+
+---
+
+## Files changed (in order)
+
+| #   | File                            | Nature of change                                        |
+| --- | ------------------------------- | ------------------------------------------------------- |
+| 1   | `src/schema/collection.ts`      | Add indices option                                      |
+| 2   | `src/schema/types.ts`           | Add IndexedFields type                                  |
+| 3   | `src/storage/idb.ts`            | Per-collection stores, index queries, schema-aware open |
+| 4   | `src/storage/records-store.ts`  | Flat record shape, collection-aware rebuild             |
+| 5   | `src/crud/query-builder.ts`     | Full rewrite: WhereClause, QueryBuilder, OrderByBuilder |
+| 6   | `src/crud/collection-handle.ts` | Add orderBy, update where, flat record mapping          |
+| 7   | `src/crud/watch.ts`             | Minor: update filter signature for flat records         |
+| 8   | `src/db/create-localstr.ts`     | Pass schema to openIDBStorage                           |
+| 9   | `src/index.ts`                  | Export new types                                        |
+| 10  | `demo/app.ts`                   | Demo new query API                                      |
+
+**Files NOT changed:** `src/schema/field.ts`, `src/schema/validate.ts`, `src/storage/lww.ts`, `src/sync/*`, `src/errors.ts`, `src/db/database-handle.ts`
+
+Note: Sync code (`sync-service.ts`, `records-store.ts`) creates `StoredEvent` objects and calls `applyEvent` → `storage.putRecord`. Since we're updating `applyEvent` to write flat records with the new `putRecord(collection, record)` signature, sync continues to work without changes to sync-service.ts itself.
+
+---
+
+## Version bump strategy
+
+Compute IDB version deterministically from schema:
+
+```typescript
+function schemaVersion(schema: SchemaConfig): number {
+  const sig = Object.entries(schema)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, def]) => {
+      const indices = (def.indices ?? []).slice().sort().join(",");
+      return `${name}:${indices}`;
+    })
+    .join("|");
+  // Simple hash → positive integer
+  let hash = 1;
+  for (let i = 0; i < sig.length; i++) {
+    hash = (hash * 31 + sig.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash) + 1; // IDB versions must be >= 1
+}
+```
+
+The `upgrade` handler uses `database.objectStoreNames` to detect what exists and creates/removes stores+indices as needed.
+
+---
+
+## Verification
+
+1. `bun run check` — typecheck passes
+2. Run demo app — CRUD still works, queries work
+3. Test new queries in demo: `orderBy("priority")`, `where("priority").above(2)`, `where("title").startsWith("B")`
+4. Test sync still works: add items, sync, verify they appear
+5. Test rebuild: `db.rebuild()` reconstructs records correctly
+6. Verify `where("done").equals(false).get()` works
+7. Note: `where()` signature changed from `Effect<WhereClause>` to `WhereClause` — demo code updated accordingly
+8. Note: `col.get(id)` is by-ID lookup (single record), `col.where(...).get()` is query result (array)

package/.context/plans/implementation-plan-localstr-v0-2.md

@@ -0,0 +1,263 @@
+# Implementation Plan: localstr v0.2
+
+## Context
+
+localstr is a browser-first local-first sync library that gives developers a typed Effect API for defining collections, performing CRUD, and syncing data across devices through Nostr relays. The project scaffold exists (Effect 4.0.0-beta.28, Bun, vitest, oxlint) but no library code has been written yet. This plan implements all 7 user stories (US-001 through US-007) and 23 functional requirements from `prds/localstr-v0.2.md`.
+
+## Dependencies to Install
+
+**Runtime:**
+
+- `idb` — Promise-based IndexedDB wrapper
+- `nostr-tools` — Nostr event creation, signing, NIP-44, NIP-59
+- `@noble/hashes` — SHA-256, etc. (peer dep of nostr-tools)
+- `@noble/curves` — secp256k1 (peer dep of nostr-tools)
+- negentropy from `github:hoytech/negentropy` — NIP-77 set reconciliation
+
+**Dev:**
+
+- `fake-indexeddb` — IndexedDB polyfill for vitest
+
+**Config changes:**
+
+- `tsconfig.json`: add `"DOM"` to `lib` for IndexedDB + crypto types
+- `vitest.config.ts`: add `setupFiles: ["tests/setup.ts"]`
+
+## File Structure
+
+```
+src/
+  index.ts                      -- Public API barrel
+  errors.ts                     -- All Data.TaggedError definitions
+  schema/
+    field.ts                    -- field.* builders + FieldDef types
+    collection.ts               -- collection() builder
+    types.ts                    -- InferRecord<C> type utilities
+    validate.ts                 -- Runtime validation via Effect Schema
+  utils/
+    uuid.ts                     -- UUIDv7 generation
+  storage/
+    idb.ts                      -- IDBStorage Effect service
+    events-store.ts             -- Events store operations
+    records-store.ts            -- Records store + LWW materialization
+    giftwraps-store.ts          -- Giftwraps store operations
+    lww.ts                      -- LWW resolution (pure function)
+  crud/
+    collection-handle.ts        -- CollectionHandle: add/update/delete/get/first/count/watch
+    query-builder.ts            -- .where().equals() chain
+    watch.ts                    -- watch() via PubSub + Stream
+  db/
+    create-localstr.ts          -- createLocalstr() entrypoint
+    database-handle.ts          -- DatabaseHandle interface
+    identity.ts                 -- Key generation + exportKey()
+  sync/
+    gift-wrap.ts                -- NIP-59 wrap/unwrap using nostr-tools
+    relay.ts                    -- WebSocket relay I/O + NIP-77 messages
+    negentropy.ts               -- NIP-77 set reconciliation
+    publish-queue.ts            -- Offline retry queue
+    sync-service.ts             -- Main sync orchestrator
+    sync-status.ts              -- SyncStatus type + SubscriptionRef
+tests/
+  setup.ts                      -- fake-indexeddb/auto polyfill
+  schema/
+    field.test.ts
+    collection.test.ts
+    validate.test.ts
+  storage/
+    idb.test.ts
+    lww.test.ts
+  crud/
+    collection-handle.test.ts
+    query-builder.test.ts
+    watch.test.ts
+  db/
+    create-localstr.test.ts
+    identity.test.ts
+  sync/
+    gift-wrap.test.ts
+    sync-service.test.ts
+```
+
+## Effect v4 Patterns
+
+Services use `ServiceMap.Service`:
+
+```typescript
+class IDBStorage extends ServiceMap.Service<IDBStorage, IDBStorageShape>()("IDBStorage") {}
+```
+
+Errors use `Data.TaggedError`:
+
+```typescript
+class ValidationError extends Data.TaggedError("ValidationError")<{ readonly message: string }> {}
+```
+
+Layers use `Layer.effect(ServiceTag)(Effect.gen(...))`.
+
+## Implementation Order
+
+### Phase 1: Foundation (no I/O)
+
+**Step 1: `src/errors.ts`**
+
+- Define: `ValidationError`, `StorageError`, `CryptoError`, `RelayError`, `SyncError`, `NotFoundError`, `ClosedError`
+- All extend `Data.TaggedError` with descriptive fields
+
+**Step 2: `src/schema/field.ts` + `src/schema/collection.ts` + `src/schema/types.ts`**
+
+- `field.string()`, `field.number()`, `field.boolean()`, `field.json()` return `FieldDef<T>`
+- `.optional()` and `.array()` modifiers via builder pattern
+- `collection(fields)` returns `CollectionDef<F>`
+- `InferRecord<C>` infers TS type from collection def (auto-injects `id: string`)
+- Reject empty fields, reserved names (`id`, `_deleted`, `_createdAt`, `_updatedAt`) at init
+
+**Step 3: `src/schema/validate.ts`**
+
+- Build `Schema.Struct` from `CollectionDef` at init time
+- Map FieldDef kinds to Effect Schema types
+- Return validator function: `(input: unknown) => Effect<T, ValidationError>`
+
+**Step 4: `src/utils/uuid.ts`**
+
+- UUIDv7 implementation (~25 lines using `crypto.getRandomValues`)
+
+**Step 5: `src/storage/lww.ts`**
+
+- Pure function `resolveWinner(existing, incoming)`: compare `createdAt`, tie-break by lowest event ID lexicographically
+
+### Phase 2: Storage Layer
+
+**Step 6: Install deps, config changes**
+
+- `bun add idb` + `bun add -d fake-indexeddb`
+- Add `"DOM"` to tsconfig lib
+- Create `tests/setup.ts` with `import "fake-indexeddb/auto"`
+- Update `vitest.config.ts` with setupFiles
+
+**Step 7: `src/storage/idb.ts`**
+
+- `IDBStorage` Effect service wrapping `idb`'s `openDB`
+- Three object stores: `giftwraps` (key: event id), `events` (key: event id), `records` (key: `[collection, id]`)
+- Scope finalizer to close DB connection
+- Methods: putRecord, getRecord, getAllRecords, deleteRecord, putEvent, getAllEvents, clearRecords, countRecords, close
+
+**Step 8: `src/storage/events-store.ts` + `src/storage/records-store.ts` + `src/storage/giftwraps-store.ts`**
+
+- Higher-level operations on each store
+- `applyEvent`: LWW-resolve incoming event against records store
+- `rebuild()`: clear records, replay all events with LWW
+
+### Phase 3: CRUD & Query
+
+**Step 9: `src/crud/watch.ts`**
+
+- `PubSub<ChangeEvent>` for change notification (one per DB instance)
+- `ChangeEvent = { collection, recordId, kind }`
+- `watch()` returns `Stream` — emits initial results, then re-queries on relevant changes
+- Batching during sync replay via `Ref<boolean>` replaying flag
+
+**Step 10: `src/crud/query-builder.ts`**
+
+- `.where(field).equals(value)` captures a `QuerySpec`
+- Execution scans records store, filters in-memory, excludes tombstones
+- Reject `json`/`array` fields with `ValidationError`
+- Returns `QueryExecutor` with `get()`, `first()`, `count()`, `watch()`
+
+**Step 11: `src/crud/collection-handle.ts`**
+
+- `add(data)`: validate → generate UUIDv7 → create event → store in events + records → notify PubSub → return id
+- `update(id, partial)`: get existing → merge → validate → create event → store → notify
+- `delete(id)`: verify exists → create tombstone event → store → notify
+- `get(id)`: read from records store, fail with NotFoundError if missing/deleted
+- `first(query?)`, `count(query?)`: scan records with optional filter
+- `watch(query?)`: delegate to watch.ts
+
+### Phase 4: Database Handle
+
+**Step 12: `src/db/identity.ts`**
+
+- Generate 32-byte random key via `crypto.getRandomValues`
+- Accept optional supplied key
+- `exportKey()` returns hex-encoded private key
+- Derive pubkey using `@noble/curves` secp256k1
+
+**Step 13: `src/db/database-handle.ts` + `src/db/create-localstr.ts`**
+
+- `DatabaseHandle<S>`: `collection(name)`, `exportKey()`, `close()`, `rebuild()`, `sync()`, `getSyncStatus()`
+- `createLocalstr(config)`: validate config (non-empty relays, valid schema) → generate key → open IDB → build validators → create PubSub → build collection handles → register Scope finalizer → return handle
+- `close()` sets `Ref<boolean>` closed flag; all subsequent ops fail with `ClosedError`
+
+### Phase 5: Sync Layer
+
+**Step 14: Install Nostr deps**
+
+- `bun add nostr-tools @noble/hashes @noble/curves`
+- Install negentropy: `bun add github:hoytech/negentropy` (or vendor the ~400-line JS file)
+
+**Step 15: `src/sync/gift-wrap.ts`**
+
+- `wrap(rumor)`: rumor → NIP-44-encrypted seal (signed by author) → NIP-44-encrypted gift wrap (signed by random disposable key, randomized timestamp)
+- `unwrap(giftWrap)`: decrypt gift wrap → decrypt seal → extract rumor
+- Self-encryption: encrypt to own pubkey
+- Uses `nostr-tools/nip59` and `nostr-tools/nip44`
+
+**Step 16: `src/sync/relay.ts`**
+
+- Raw WebSocket management with `Effect.acquireRelease`
+- `publish(event, urls)`: send `["EVENT", event]` to each relay
+- `fetchEvents(ids, url)`: send `["REQ", ...]` with id filter
+- NIP-77 messages: `negentropyOpen`, `negentropySend`, `negentropyClose` for `NEG-OPEN`/`NEG-MSG`/`NEG-CLOSE`
+
+**Step 17: `src/sync/negentropy.ts`**
+
+- Load all local gift wrap IDs from giftwraps store
+- Build `NegentropyStorageVector`, insert each, seal
+- Run reconciliation rounds via relay NIP-77 messages
+- Return `{ haveIds, needIds }`
+
+**Step 18: `src/sync/publish-queue.ts`**
+
+- In-memory queue (backed by `Ref<Set<string>>`) of pending gift wrap event IDs
+- `enqueue(giftWrap)`: add to pending set
+- `flush()`: read events from giftwraps store, publish, remove successful ones
+- Auto-flush on browser `online` event
+
+**Step 19: `src/sync/sync-status.ts`**
+
+- `SyncStatus = "idle" | "syncing"` via `SubscriptionRef`
+- `getSyncStatus()` reads the ref
+
+**Step 20: `src/sync/sync-service.ts`**
+
+- `sync()`: set status → for each relay: negentropy reconcile → fetch missing → unwrap → store → LWW resolve → upload missing → flush queue → set idle
+- `publishLocal(giftWrap)`: fire-and-forget publish via `Effect.fork`, enqueue on failure
+- Wrap in `Effect.ensuring` to guarantee status reset on failure
+- Signal replay start/end for watch() batching
+
+### Phase 6: Public API & Integration
+
+**Step 21: `src/index.ts`**
+
+- Export: `createLocalstr`, `collection`, `field`, type `InferRecord`, type `DatabaseHandle`, type `CollectionHandle`, all error types
+
+**Step 22: Wire sync into CRUD**
+
+- On local write: create rumor → gift wrap → store in giftwraps → publishLocal (async)
+- On sync receive: store giftwrap → unwrap → store event → LWW resolve → notify watch
+
+**Step 23: Integration tests + `bun run validate`**
+
+## Key Design Decisions
+
+1. **Schema builders are plain descriptors, not Effect Schemas** — Effect Schema is derived internally for validation. Keeps the developer API simple.
+2. **IDBStorage is the only Effect Service in core** — CRUD/query are plain functions receiving storage. Avoids over-engineering DI.
+3. **PubSub for change notification** — subscribers filter by collection. watch() emits full result sets (not deltas).
+4. **Tombstone deletes** — delete events stored in events store; records marked `_deleted: true`; excluded from queries; deterministic on rebuild.
+5. **Raw WebSocket for relays** — nostr-tools Relay class doesn't support NIP-77 custom messages.
+6. **No `idb` if too heavy** — fallback to raw IndexedDB API wrapped in Effect.tryPromise if the `idb` package causes issues.
+
+## Verification
+
+1. `bun run validate` passes (oxfmt + oxlint + vitest)
+2. Tests cover: schema building + type inference, runtime validation, IDB CRUD, LWW resolution, watch() reactivity + batching, query filtering, identity key gen/export, gift wrap round-trip, full create→add→get→update→delete→close lifecycle
+3. Integration test: create DB → add records → query → delete → rebuild → verify state

package/.context/plans/project-init-effect-v4-bun-oxlint-oxfmt-vitest.md

@@ -0,0 +1,71 @@
+# Project Init: Effect v4 + Bun + Oxlint/oxfmt + Vitest
+
+## Context
+
+Setting up a fresh TypeScript project ("douala-v4" / "localstr") using Effect v4 beta, Bun as runtime/package manager, Oxlint+oxfmt for linting/formatting, and Vitest for testing (with `@effect/vitest`).
+
+## Files to Create
+
+### 1. `package.json`
+
+- `"type": "module"`
+- Dependencies: `effect@4.0.0-beta.28`
+- Dev deps: `@effect/vitest@4.0.0-beta.28`, `oxlint@^1.51.0`, `oxfmt@latest`, `typescript@^5.7.0`, `vitest@^3.0.0`, `@j178/prek@latest`
+- Scripts: `dev`, `lint`, `format`, `format:check`, `test`, `test:watch`, `validate`
+
+### 2. `tsconfig.json`
+
+- `strict: true` (required by Effect)
+- `target/module: ES2022`, `moduleResolution: bundler`
+- `exactOptionalPropertyTypes: true`, `noEmit: true`, `skipLibCheck: true`
+
+### 3. `vitest.config.ts`
+
+- Minimal config, test files in `tests/**/*.test.ts`
+
+### 4. `.oxlintrc.json`
+
+- Minimal rules, `$schema` pointing to node_modules schema
+
+### 5. `.gitignore`
+
+- `node_modules/`, `dist/`, `*.tsbuildinfo`
+
+### 6. `src/main.ts`
+
+- Minimal Effect program to verify setup works
+
+### 7. `tests/main.test.ts`
+
+- Minimal test using `@effect/vitest` to verify test setup
+
+### 8. `prek.toml`
+
+- Pre-commit hook config using prek (https://prek.j178.dev/)
+- Single local hook that runs `bun run scripts/validate.ts` on commit
+- Uses `language = "system"` since bun is already in PATH
+
+### 9. `scripts/validate.ts`
+
+- Runs `bun run test`, `bun run lint`, and `bun run format:check` sequentially
+- Exits with non-zero if any step fails
+
+## Execution Order
+
+1. Create `package.json`
+2. Run `bun install`
+3. Create `tsconfig.json`, `vitest.config.ts`, `.oxlintrc.json`, `.gitignore`
+4. Create `src/main.ts`, `tests/main.test.ts`, `scripts/validate.ts`
+5. Create `prek.toml` and run `bunx prek install` to install the git hook
+6. Verify: `bun run src/main.ts` runs
+7. Verify: `bun run test` passes
+8. Verify: `bun run lint` works
+9. Verify: `bun run format:check` works (if oxfmt installs successfully — it's beta)
+10. Verify: `bunx prek run validate` runs the hook
+
+## Notes
+
+- Vitest is the right choice: `@effect/vitest` provides Effect-native test helpers with synchronized beta versions
+- oxfmt reached beta in Feb 2026 and is viable, but if it causes issues we can skip it
+- Pin exact Effect beta versions (not `@beta` tag) for reproducibility
+- Use `bun run vitest` not `bun test` (the latter invokes Bun's built-in test runner)