tablinum 0.0.1

package/.context/plans/revise-localstr-prd-v0-2.md

@@ -0,0 +1,132 @@
+# Plan: Revise localstr PRD v0.2
+
+## Context
+
+The current PRD (`prds/localstr-v0.2.md`) has been critiqued and several design decisions have been made through discussion. The goal is to produce a revised PRD that incorporates all agreed-upon changes. This is a document revision task — no code changes.
+
+## Decisions Made
+
+1. **Effect as the core public API** — The library exports only an Effect API. Framework bindings (Svelte, React, etc.) come later as separate packages. No Promise wrapper in the core.
+
+2. **NIP-59 (Gift Wrap) + NIP-77 (Negentropy) from day one** — Full privacy stack. Events are triple-wrapped (rumor → seal → gift wrap) with randomized timestamps and disposable sender keys. Sync uses negentropy set reconciliation instead of timestamp-based `since` filters.
+
+3. **LWW conflict resolution** — Last-write-wins by `created_at`, ties broken by lowest event ID (lexicographic).
+
+4. **`d` tag = `{collectionName}:{recordId}`** with UUIDv7 record IDs. This is client-side only (relay never sees it due to NIP-59 encryption).
+
+5. **Remove KV API** — Cut from v0.2 entirely.
+
+6. **No schema migration in v0.2** — New optional fields are safe. Required field changes require manual rebuild. Document this as a known limitation.
+
+7. **Full query API** — Ship all query operators: `where().equals()`, `above()`, `below()`, `between()`, `anyOf()`, `sortBy()`, `limit()`, `offset()`.
+
+8. **NIP-77 for sync/dedup** — Negentropy handles cross-relay deduplication naturally. No timestamp-based sync checkpoints.
+
+9. **Storage limits** — Document that the library doesn't manage IndexedDB quota. Suggest `navigator.storage.persist()`. No compaction in v0.2.
+
+10. **`db.close()` lifecycle** — Add to the API for releasing IndexedDB connections and cleaning up subscriptions.
+
+11. **Identity: `exportKey()` + import via config** — Include key export/import in v0.2 since it's required for the cross-device sync success metric.
+
+12. **`watch()` returns an `Effect.Stream`** — Emits initial results then subsequent changes. During sync replay, batch changes and emit once after replay completes.
+
+## Key Changes to the PRD
+
+### Structural changes
+
+- **Remove US-008** (hiding Effect from public API) — replaced by the opposite: Effect IS the public API
+- **Add US for key export/import** or fold into US-002
+- **Remove KV from US-002** database handle description
+- **Add `close()` to US-002** acceptance criteria
+
+### US-004 (CRUD) changes
+
+- `watch()` returns `Effect.Stream<ReadonlyArray<Record>>`
+- Specify that all methods return `Effect` values with typed error channels
+
+### US-005 (Query) changes
+
+- Full query API (no tiering)
+- `watch()` batches changes during sync replay
+
+### US-006 (Sync) changes — Major rewrite
+
+- Replace "encrypt event payloads" with NIP-59 gift wrap (3-layer: rumor → seal → gift wrap)
+- Replace "parameterized replaceable event kind" with gift-wrapped events (kind 1059)
+- Replace "deterministic `d` tag" — still deterministic but client-side only, invisible to relay
+- Replace "scoped checkpoints" with NIP-77 negentropy set reconciliation
+- Add: "LWW by `created_at`, ties broken by lowest event ID"
+- Add: relay stores every version (no relay-side deduplication)
+- Add: client-side dedup and latest-version resolution after decryption
+
+### US-007 (Offline) changes
+
+- Queue refers to gift-wrapped events, not raw events
+
+### US-008 → Delete
+
+- The old "conventional public error model" story needs rewriting since errors are now in Effect's error channel
+- Fold error types into a new story or into Technical Considerations
+
+### New/revised Functional Requirements
+
+- Remove FR-20 (hide Nostr from CRUD API) — still true but reframe: the Effect API is the primary API, framework bindings hide everything
+- Add FR for NIP-59 gift wrapping
+- Add FR for NIP-77 negentropy sync
+- Add FR for LWW conflict resolution
+- Add FR for key export
+- Add FR for `close()` lifecycle
+- Remove any mention of KV
+
+### Technical Considerations updates
+
+- Effect is the public API; framework bindings are separate packages
+- NIP-59 for encryption (not NIP-44 directly — NIP-44 is used _within_ NIP-59)
+- NIP-77 for sync (not `since`-based filtering)
+- UUIDv7 for record IDs
+- `d` tag format: `{collectionName}:{recordId}` (client-side only)
+- No schema migration; new optional fields safe, other changes require rebuild
+- No IndexedDB quota management; recommend `navigator.storage.persist()`
+- Relay is untrusted; learns almost nothing about data structure
+
+### Non-Goals updates
+
+- Add: Promise-based public API (that's for framework bindings)
+- Add: Schema migration
+- Add: KV store
+- Add: IndexedDB quota management / compaction
+- Keep existing non-goals
+
+### Open Questions updates
+
+- Remove resolved questions (event kind → kind 1059 gift wraps, export/import → yes, autoSync → manual only, KV → cut, Effect adapter → Effect is the core API)
+- New open questions:
+  - Should there be a `rebuild()` method that replays all local events to regenerate materialized state?
+  - What's the maximum reasonable event count before negentropy reconciliation becomes slow in a browser?
+  - Should the library include a NIP-77-compatible negentropy implementation or depend on an external one?
+
+## IndexedDB Storage Architecture
+
+Three stores in IndexedDB:
+
+| Store       | Contents                                                            | Purpose                                     |
+| ----------- | ------------------------------------------------------------------- | ------------------------------------------- |
+| `giftwraps` | Gift wrap event IDs only (not full encrypted blobs)                 | Negentropy fingerprint computation for sync |
+| `events`    | Decrypted rumors (real events with `d` tags, `created_at`, content) | Source of truth, replay, rebuild            |
+| `records`   | Materialized current state per `d` tag (LWW winner)                 | Query performance                           |
+
+- On local write: create rumor + gift wrap. Store gift wrap ID in `giftwraps`, decrypted rumor in `events`, LWW-resolved state in `records`. Publish gift wrap to relay async.
+- On sync: negentropy over `giftwraps` IDs → fetch missing gift wraps → decrypt → store rumor in `events` + gift wrap ID in `giftwraps` → LWW resolve into `records`.
+- On rebuild: clear `records`, replay all `events` applying LWW, regenerate `records`.
+- `giftwraps` grows with every write (one per mutation). `records` stays at one entry per unique `d` tag.
+
+## File to modify
+
+- `prds/localstr-v0.2.md` — full rewrite incorporating all changes above
+
+## Verification
+
+- Read through the revised PRD and confirm all 12 decisions are reflected
+- Confirm no references to KV, Promise wrappers, NIP-04, `since`-based sync, or "hide Effect"
+- Confirm NIP-59, NIP-77, LWW, UUIDv7, `close()`, `exportKey()` are all present
+- Run `bun run validate` to ensure no code breakage (though this is a doc-only change)

package/.context/plans/svelte-5-runes-bindings-for-localstr.md

@@ -0,0 +1,233 @@
+# Svelte 5 Runes Bindings for localstr
+
+## Context
+
+localstr has a fully Effect-based API where all operations return `Effect` and reactive streams return `Stream`. This is powerful but requires Effect knowledge to use. We want Svelte 5 bindings that wrap this API into idiomatic Svelte runes classes — `$state` for reactive data, Promises for CRUD, and auto-cleanup via `$effect`.
+
+## API Design
+
+```svelte
+<script>
+  import { createLocalstr, field, collection } from 'localstr/svelte'
+
+  const todos = collection("todos", {
+    title: field.string(),
+    done: field.boolean(),
+    priority: field.number(),
+  }, { indices: ["done", "priority"] })
+
+  const db = await createLocalstr({
+    schema: { todos },
+    relays: ["wss://relay.example.com"],
+  })
+
+  const col = db.collection("todos")
+  // col.items    → $state, auto-watched, all records (live)
+  // col.status   → $state, 'idle' | 'syncing'
+  // col.error    → $state, last error or null
+
+  const incomplete = col.where("done").equals(false).live()
+  // incomplete.items → $state, filtered live query
+
+  // CRUD — returns Promises, sets col.error on failure
+  const id = await col.add({ title: "Buy milk", done: false, priority: 1 })
+  await col.update(id, { done: true })
+  await col.delete(id)
+  const todo = await col.get(id)
+</script>
+
+{#if col.error}<p class="error">{col.error.message}</p>{/if}
+{#each incomplete.items as todo}
+  <p>{todo.title}</p>
+{/each}
+```
+
+## Files to Create
+
+### `src/svelte/index.svelte.ts` — Main entry point
+
+- Re-exports `field`, `collection` from core (unchanged)
+- Exports wrapped `createLocalstr` that returns `Promise<Database>`
+- Exports `Database`, `Collection`, `LiveQuery` classes
+
+### `src/svelte/database.svelte.ts` — Database class
+
+```typescript
+class Database<S extends SchemaConfig> {
+  #handle: DatabaseHandle<S>
+  #scope: Scope.CloseableScope
+  #fiber: Fiber<...> | null  // for sync status polling
+
+  status = $state<SyncStatus>('idle')
+  error = $state<Error | null>(null)
+
+  collection<K extends keyof S>(name: K): Collection<S[K]>
+  exportKey(): string
+  async close(): Promise<void>  // closes scope + handle
+  async sync(): Promise<void>
+  async rebuild(): Promise<void>
+}
+```
+
+### `src/svelte/collection.svelte.ts` — Collection class
+
+```typescript
+class Collection<C extends CollectionDef> {
+  #handle: CollectionHandle<C>;
+  #cleanup: (() => void) | null; // fiber interrupt for watch stream
+
+  items = $state<ReadonlyArray<InferRecord<C>>>([]);
+  error = $state<Error | null>(null);
+
+  // CRUD — Promise-based, sets this.error on failure
+  async add(data): Promise<string>;
+  async update(id, data): Promise<void>;
+  async delete(id): Promise<void>;
+  async get(id): Promise<InferRecord<C>>;
+  async first(): Promise<InferRecord<C> | null>;
+  async count(): Promise<number>;
+
+  // Query builders — return Svelte-wrapped builders with .live()
+  where(field): SvelteWhereClause<InferRecord<C>>;
+  orderBy(field): SvelteOrderByBuilder<InferRecord<C>>;
+}
+```
+
+### `src/svelte/live-query.svelte.ts` — LiveQuery class
+
+```typescript
+class LiveQuery<T> {
+  items = $state<ReadonlyArray<T>>([]);
+  #cleanup: (() => void) | null;
+
+  constructor(stream: Stream<ReadonlyArray<T>>) {
+    // Fork stream processing, update items on each emission
+    // Return cleanup function that interrupts the fiber
+  }
+
+  destroy(): void; // manual cleanup if needed
+}
+```
+
+### `src/svelte/query.svelte.ts` — Svelte query builder wrappers
+
+Thin wrappers over the Effect query builders that add `.live()` terminal:
+
+```typescript
+interface SvelteQueryBuilder<T> {
+  and(fn): SvelteQueryBuilder<T>;
+  sortBy(field): SvelteQueryBuilder<T>;
+  reverse(): SvelteQueryBuilder<T>;
+  offset(n): SvelteQueryBuilder<T>;
+  limit(n): SvelteQueryBuilder<T>;
+  get(): Promise<ReadonlyArray<T>>; // Effect.runPromise
+  first(): Promise<T | null>;
+  count(): Promise<number>;
+  live(): LiveQuery<T>; // NEW: returns reactive LiveQuery
+}
+
+interface SvelteWhereClause<T> {
+  equals(value): SvelteQueryBuilder<T>;
+  above(value): SvelteQueryBuilder<T>;
+  // ... all WhereClause methods, returning SvelteQueryBuilder
+}
+
+interface SvelteOrderByBuilder<T> {
+  reverse(): SvelteOrderByBuilder<T>;
+  offset(n): SvelteOrderByBuilder<T>;
+  limit(n): SvelteOrderByBuilder<T>;
+  get(): Promise<ReadonlyArray<T>>;
+  first(): Promise<T | null>;
+  count(): Promise<number>;
+  live(): LiveQuery<T>;
+}
+```
+
+## Key Implementation Details
+
+### Effect Scope Management
+
+`createLocalstr` returns `Effect<DatabaseHandle, ..., Scope.Scope>`. The scope must stay alive until `close()` is called:
+
+```typescript
+// In createLocalstr wrapper:
+const scope = Effect.runSync(Scope.make());
+const handle = await Effect.runPromise(
+  coreCreateLocalstr(config).pipe(Effect.provideService(Scope.Scope, scope)),
+);
+// scope is stored in Database, closed on db.close()
+```
+
+### Stream → $state Bridging
+
+For auto-watching `items` and `LiveQuery`:
+
+```typescript
+// Fork a fiber that processes the stream
+const fiber = Effect.runFork(
+  stream.pipe(
+    Stream.runForEach((records) =>
+      Effect.sync(() => {
+        this.items = records;
+      }),
+    ),
+  ),
+);
+// Store fiber reference for cleanup
+this.#cleanup = () => Effect.runFork(Fiber.interrupt(fiber));
+```
+
+### Collection Auto-Watch Lifecycle
+
+- Watch stream starts in the constructor (items immediately populated)
+- Fiber is stored for cleanup
+- `Database.close()` interrupts all collection fibers
+
+### LiveQuery Auto-Dispose
+
+LiveQuery uses `$effect` cleanup in Svelte 5. When the component unmounts, `$effect` teardown interrupts the stream fiber. Since LiveQuery is created inside component `<script>`, Svelte tracks it.
+
+However, `$effect` cleanup only works if the LiveQuery is created inside a tracking context. For safety, LiveQuery also exposes a `.destroy()` method for manual cleanup, and Database.close() cleans up all active queries.
+
+### Error Handling
+
+CRUD methods catch Effect failures and:
+
+1. Set `collection.error = extractedError`
+2. Re-throw as a plain Error (so `await` callers can also catch)
+
+This gives both template-friendly `{#if col.error}` and traditional `try/catch`.
+
+### Sync Status
+
+Database polls `getSyncStatus()` periodically or listens to sync events to update `database.status` and propagate to collections.
+
+## Files to Modify
+
+### `src/index.ts`
+
+Add svelte re-export:
+
+```typescript
+// Svelte bindings
+export * from "./svelte/index.svelte.ts";
+```
+
+Actually — better to keep it as a separate import path. Users import from `localstr/svelte` or `./svelte/index.svelte.ts`. No changes to `src/index.ts` needed.
+
+## Implementation Order
+
+1. `src/svelte/live-query.svelte.ts` — LiveQuery class (standalone, testable)
+2. `src/svelte/query.svelte.ts` — SvelteWhereClause/SvelteQueryBuilder/SvelteOrderByBuilder wrappers
+3. `src/svelte/collection.svelte.ts` — Collection class with auto-watch + CRUD
+4. `src/svelte/database.svelte.ts` — Database class with scope management
+5. `src/svelte/index.svelte.ts` — Entry point with createLocalstr wrapper + re-exports
+6. Update `package.json` exports map if needed for `localstr/svelte` path
+
+## Verification
+
+1. TypeScript compilation: `bun run tsc --noEmit` (ensure .svelte.ts files compile)
+2. Create a demo Svelte component using the new API
+3. Test that Effect scope is properly managed (no leaked fibers)
+4. Test LiveQuery cleanup on destroy
+5. Test error propagation to $state

package/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Create Release Pull Request or Publish
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: bun run version
+          publish: bun run release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true

package/.oxlintrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "rules": {
+    "no-unused-vars": "warn",
+    "eqeqeq": "error"
+  },
+  "ignorePatterns": ["node_modules", "dist"]
+}

package/README.md

@@ -0,0 +1 @@
+# localstr