wip

rewrite.md

···
-# Redesigning docstore architecture layers
+# Docstore Query Engine Architecture
+
+A layered query engine for IndexedDB with support for compound indexes, spread (denormalized) indexes, joins, and aggregations.
 
-## Current Architecture Analysis
+> **Implementation Status Legend:**
+>
+> - ✅ = Fully implemented
+> - 🟡 = Partially implemented
+> - ❌ = Not yet implemented
 
-What you've built is impressive — it's essentially a **relational query engine on top of IndexedDB**. The key components:
+---
 
-1. **Schema Layer** (`z.object` + `StorageRef`) — Zod-based type definitions with special handling for blob references
-2. **Index Definition** (`IndexBuilder`, `IndexDef`) — Declarative compound/spread indexes with replication
-3. **Denormalization Engine** (`ingest()`) — Cartesian product expansion for spread indexes into separate IDB stores
-4. **Statistics** (`StatsManager`, `HyperLogLog`) — Cardinality estimation for query planning
-5. **Query Planning** (`QueryPlanner`) — Cost-based index selection, intersection detection, self-join handling
-6. **Execution** (`rows()`, `docs()`, `rowsPage()`) — Batched iteration, keyset pagination, intersection execution
-7. **Joins** (in `docstore-joins.ts`) — Hash join, left join, nested loop for cross-store queries
+## Query DSL ❌
 
-### Pain Points I See
+Three top-level combinators build queries from stores:
 
-1. **Monolithic file** — 4000+ lines, hard to reason about individual concerns
-2. **Schema and storage tightly coupled** — Can't easily swap IDB for another backend
-3. **Query DSL is implicit** — `QuerySpec` is just data, no builder ergonomics
-4. **Cross-store joins are separate** — `docstore-joins.ts` is disconnected from the planner
-5. **Observables vs AsyncGenerators** — Two streaming models that don't integrate
-6. **No transaction abstraction** — Raw IDB transactions leak through
+> **Status:** The high-level DSL (`where()`, `aggregate()`, `join()` combinators) is **not implemented**. Instead, queries are built imperatively using `QuerySpec` objects and executed via `QueryPlanner.plan()` + `rows()`/`docs()`.
 
----
+### `where(source, filter)` 🟡
 
-## Proposed Layered Architecture
+Filters a store or query. Returns `Query<T>`.
 
-Here's a modular redesign that separates concerns cleanly:
+> **Status:** Filtering exists but via `QuerySpec.where` (array of `WhereClause`) and `QuerySpec.matches` (array of `SpreadMatch`), not as a combinator function. Supports `=`, `!=`, `<`, `>`, `<=`, `>=`, `in` operators. Boolean `and`/`or` combinators are **not implemented** - all clauses are implicitly AND'd.
 
+```typescript
+// Simple predicate
+where(entries, ['feedId', '=', 'f1'])
+
+// Spread match (all fields must match same array element)
+where(entries, ['...tags', 'contains', {tag: 'javascript'}])
+
+// AND
+where(entries, {
+  and: [
+    ['feedId', '=', 'f1'],
+    ['readState', '=', 'unread'],
+  ],
+})
+
+// OR
+where(entries, {
+  or: [
+    ['...tags', 'contains', {tag: 'javascript'}],
+    ['...tags', 'contains', {tag: 'typescript'}],
+  ],
+})
+
+// Nested boolean logic
+where(entries, {
+  and: [
+    ['feedId', '=', 'f1'],
+    {
+      or: [
+        ['readState', '=', 'unread'],
+        ['starred', '=', true],
+      ],
+    },
+  ],
+})
+
+// Chaining is implicit AND
+where(where(entries, ['feedId', '=', 'f1']), ['readState', '=', 'unread'])
 ```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                           QUERY DSL (Layer 6)                                │
-│                                                                              │
-│   q.from('entries')                                                         │
-│     .where('feedId', '=', 'f1')                                             │
-│     .where('...tags.tag', '=', 'javascript')                                │
-│     .join('feeds', 'feedId', 'id')                                          │
-│     .select('title', 'feeds.name')                                          │
-│     .orderBy('publishedAt', 'desc')                                         │
-│     .limit(50)                                                              │
-│                                                                              │
-│   Compiles to → QueryAST                                                    │
-└──────────────────────────────────────┬──────────────────────────────────────┘
-                                       │
-┌──────────────────────────────────────▼──────────────────────────────────────┐
-│                      CROSS-STORE PLANNER (Layer 5)                          │
-│                                                                              │
-│   • Resolves joins across stores                                            │
-│   • Picks join strategy (hash, merge, nested-loop)                          │
-│   • Estimates cardinalities across stores                                   │
-│   • Produces JoinPlan (tree of store-level plans)                           │
-│                                                                              │
-│   Input: QueryAST + Catalog                                                 │
-│   Output: JoinPlan { left: StorePlan, right: StorePlan, strategy, ... }     │
-└──────────────────────────────────────┬──────────────────────────────────────┘
-                                       │
-┌──────────────────────────────────────▼──────────────────────────────────────┐
-│                       STORE-LEVEL PLANNER (Layer 4)                         │
-│                                                                              │
-│   • Single-store index selection                                            │
-│   • Intersection detection (self-join on spread)                            │
-│   • Predicate pushdown to key ranges                                        │
-│   • Covering index detection                                                │
-│   • Cost estimation from stats                                              │
-│                                                                              │
-│   Input: StorePredicate[] + IndexCatalog + Stats                            │
-│   Output: StorePlan { source, index, keyRange, filter, intersection?, ... } │
-└──────────────────────────────────────┬──────────────────────────────────────┘
-                                       │
-┌──────────────────────────────────────▼──────────────────────────────────────┐
-│                           EXECUTOR (Layer 3)                                │
-│                                                                              │
-│   Volcano-style streaming operators:                                        │
-│   • ScanOp       — iterate index with key range                             │
-│   • FilterOp     — apply residual predicates                                │
-│   • ProjectOp    — select fields                                            │
-│   • SortOp       — in-memory sort when needed                               │
-│   • LimitOp      — early termination                                        │
-│   • HashJoinOp   — build/probe join                                         │
-│   • MergeJoinOp  — sorted merge join                                        │
-│   • IntersectOp  — set intersection on doc IDs                              │
-│   • LookupOp     — point lookup by key                                      │
-│                                                                              │
-│   All operators: AsyncGenerator<Row> → AsyncGenerator<Row>                  │
-└──────────────────────────────────────┬──────────────────────────────────────┘
-                                       │
-┌──────────────────────────────────────▼──────────────────────────────────────┐
-│                        INDEX STORE (Layer 2)                                │
-│                                                                              │
-│   IndexStore {                                                              │
-│     schema: SchemaDefinition                                                │
-│     indexes: IndexDefinition[]                                              │
-│     denormalizedStores: DenormalizedStore[]                                 │
-│                                                                              │
-│     put(doc): Promise<void>                                                 │
-│     get(key): Promise<Doc | undefined>                                      │
-│     delete(key): Promise<void>                                              │
-│     scan(index, range, direction): AsyncGenerator<Row>                      │
-│     count(index, range): Promise<number>                                    │
-│   }                                                                         │
-│                                                                              │
-│   • Manages primary + denormalized stores                                   │
-│   • Handles ingest/denormalization on write                                 │
-│   • Maintains statistics                                                    │
-│   • Abstracts IDB transactions                                              │
-└──────────────────────────────────────┬──────────────────────────────────────┘
-                                       │
-┌──────────────────────────────────────▼──────────────────────────────────────┐
-│                         SCHEMA (Layer 1)                                    │
-│                                                                              │
-│   SchemaDefinition {                                                        │
-│     name: string                                                            │
-│     fields: Map<string, FieldType>                                          │
-│     primaryKey: string                                                      │
-│     storageRefs: Map<string, StorageRefSchema>                              │
-│   }                                                                         │
-│                                                                              │
-│   IndexDefinition {                                                         │
-│     name: string                                                            │
-│     keys: IndexKey[]        // supports '...spread.path' notation           │
-│     replicate: string[]                                                     │
-│     sparse: boolean                                                         │
-│     spreadRoots: Set<string>                                                │
-│   }                                                                         │
-│                                                                              │
-│   • Pure data definitions, no behavior                                      │
-│   • Zod integration for validation                                          │
-│   • Type inference utilities                                                │
-└──────────────────────────────────────┬──────────────────────────────────────┘
-                                       │
-┌──────────────────────────────────────▼──────────────────────────────────────┐
-│                      STORAGE ADAPTER (Layer 0)                              │
-│                                                                              │
-│   interface StorageAdapter {                                                │
-│     transaction(stores: string[], mode: 'r' | 'rw'): Transaction            │
-│   }                                                                         │
-│                                                                              │
-│   interface Transaction {                                                   │
-│     store(name: string): ObjectStore                                        │
-│     commit(): Promise<void>                                                 │
-│   }                                                                         │
-│                                                                              │
-│   interface ObjectStore {                                                   │
-│     get(key): Promise<unknown>                                              │
-│     put(value): Promise<void>                                               │
-│     delete(key): Promise<void>                                              │
-│     getAll(range?, count?): Promise<unknown[]>                              │
-│     getAllKeys(range?, count?): Promise<IDBValidKey[]>                      │
-│     count(range?): Promise<number>                                          │
-│     index(name): Index                                                      │
-│   }                                                                         │
-│                                                                              │
-│   Implementations:                                                          │
-│   • IDBStorageAdapter (browser)                                             │
-│   • SQLiteStorageAdapter (server/testing)                                   │
-│   • MemoryStorageAdapter (unit tests)                                       │
-└─────────────────────────────────────────────────────────────────────────────┘
+
+Filter type:
+
+```typescript
+type Filter<T> =
+  | [keyof T | string, Op, unknown] // predicate (string for spread paths)
+  | {and: Filter<T>[]}
+  | {or: Filter<T>[]}
+
+type Op = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'contains'
 ```
 
----
+> **Status:** Current implementation uses `WhereClause` interface: `{key: string, op: CompareOp, value: unknown}`. Supports `=`, `!=`, `<`, `>`, `<=`, `>=`, `in` (but not `contains`). No boolean `and`/`or` combinators yet. For spread matching, use `SpreadMatch` which handles the "all fields must match same array element" case.
+>
+> **Design Note — Boolean Combinators:**
+> The `or` combinator requires special handling since IDB can only scan one index at a time. Two approaches:
+>
+> 1. **Union of plans**: Execute each OR branch as a separate query plan, collect doc IDs, deduplicate. Works well when branches use different indexes.
+> 2. **CNF normalization**: Convert to conjunctive normal form, then use `IN` queries for small disjunctions on the same key (e.g., `status = 'a' OR status = 'b'` becomes `status IN ['a', 'b']`, already supported via cursor hopping).
+>
+> For nested boolean logic, represent as a tree in `QuerySpec`, then flatten during planning. The planner already handles `IN` efficiently via `plan.inValues`.
+
+### `aggregate(source, groupKeys, aggregateFn)` 🟡
+
+Groups and aggregates a store or query. Returns `Query<GroupedRow>`.
+
+> **Status:** Aggregation exists via `collectIndexValues()` and `collectKeyPairs()` for tag-cloud/faceted-search use cases. General `aggregate()` combinator with fold functions (`count()`, `sum()`, `topN()`, etc.) is **not implemented**.
+>
+> **Design Note — General Aggregation:**
+> The existing `collectIndexValues()` is essentially `aggregate(source, [keyField], count())`. To generalize:
+>
+> 1. Define `AggregateFn<T, Acc, Out>` as shown above - this is a standard fold interface.
+> 2. `aggregate(source, groupKeys, aggFn)` would:
+>    - Plan index selection favoring indexes that cover `groupKeys` (enables streaming aggregation without collecting all rows)
+>    - Stream rows via `rows()`, accumulate into `Map<groupKey, Acc>`
+>    - For `topN()`, maintain a bounded heap per group
+> 3. When groupKeys match index prefix, can use IDB's natural ordering to detect group boundaries and emit incrementally.
+> 4. Built-in aggregators: `count()`, `sum(field)`, `min/max(field)`, `collect()`, `topN(n, cmp)` - all are just `{init, step, finalize}` objects.
+
+```typescript
+// Count entries per feed
+aggregate(entries, ['feedId'], count())
+// -> Query<{ feedId: string, count: number }>
 
-## Layer Details
+// Multiple group keys
+aggregate(entries, ['feedId', 'readState'], count())
+// -> Query<{ feedId: string, readState: string, count: number }>
 
-### Layer 0: Storage Adapter
+// Different aggregators
+aggregate(entries, ['feedId'], sum('duration'))
+aggregate(entries, ['feedId'], max('publishedAt'))
+aggregate(
+  entries,
+  ['feedId'],
+  topN(3, (a, b) => b.publishedAt - a.publishedAt),
+)
+```
 
-**Goal:** Abstract away IDB specifics so we can test with in-memory storage or port to SQLite.
+Aggregator functions are folds:
 
 ```typescript
-// storage-adapter.ts
-interface StorageAdapter {
-  transaction(stores: string[], mode: 'readonly' | 'readwrite'): Transaction
-  install(schemas: StoreSchema[]): Promise<void>
+type AggregateFn<T, Acc, Out = Acc> = {
+  init: () => Acc
+  step: (acc: Acc, row: T) => Acc
+  finalize?: (acc: Acc) => Out
 }
 
-interface Transaction {
-  store(name: string): ObjectStore
-  done: Promise<void> // resolves when committed
-}
+// Built-ins
+count() // -> number
+sum(field) // -> number
+;(min(field), max(field)) // -> T[field] | undefined
+collect() // -> T[]
+topN(n, compareFn) // -> T[]
+```
 
-interface ObjectStore {
-  get(key: IDBValidKey): Promise<unknown>
-  put(value: unknown): Promise<void>
-  delete(key: IDBValidKey): Promise<void>
-  getAll(range?: KeyRange, count?: number): Promise<unknown[]>
-  getAllKeys(range?: KeyRange, count?: number): Promise<IDBValidKey[]>
-  count(range?: KeyRange): Promise<number>
-  index(name: string): Index
-}
+### `join(left, right, template)` 🟡
+
+Joins two stores/queries. Returns `Query<TemplateOutput>`.
 
-interface Index extends Omit<ObjectStore, 'put' | 'delete' | 'index'> {}
+> **Status:** Joins exist in `docstore-joins.ts` as pure in-memory functions: `hashJoin()`, `leftJoin()`, `hashJoinAggregate()`, `nestedLoopJoin()`, `nestedLoopLeftJoin()`. These work on already-materialized arrays, not as query combinators integrated with the planner.
+>
+> **Design Note — Planner-Integrated Joins:**
+> The current join functions work but require manual orchestration. To integrate with the planner:
+>
+> 1. `join()` combinator returns a `JoinQuery<L, R, Out>` that captures both sources and key extractors
+> 2. Planner produces a `JoinPlan` with strategy selection:
+>    - **Hash join** (current): When right side is small enough to fit in memory. Build hash map from right, probe with left.
+>    - **Nested loop with batched lookup**: When left is much smaller than right. Use `getMany()` for batched fetches (already used in `docs()`)
+>    - **Merge join**: When both sides are ordered by join key (requires index). Stream both sides, merge on matching keys.
+> 3. Key insight: The existing `docs()` function IS a nested loop join (index rows → primary store). Generalizing this pattern to arbitrary stores is straightforward.
 
-// Key range abstraction (maps to IDBKeyRange)
-type KeyRange =
-  | {type: 'only'; value: unknown}
-  | {type: 'bound'; lower?: unknown; upper?: unknown; lowerOpen?: boolean; upperOpen?: boolean}
-  | {type: 'lowerBound'; value: unknown; open?: boolean}
-  | {type: 'upperBound'; value: unknown; open?: boolean}
+```typescript
+join(
+  [feeds, 'id'], // left source + join key
+  [entries, 'feedId'], // right source + join key
+  (f, e) => ({
+    // template callback
+    ...f.row(),
+    entries: e.row(),
+  }),
+)
+// -> Query<Feed & { entries: Entry }>
 ```
 
-### Layer 1: Schema
-
-**Goal:** Pure data definitions, fully decoupled from storage.
+The template callback receives extractors for each side:
 
 ```typescript
-// schema/types.ts
-interface SchemaDefinition<S extends FieldShape = FieldShape> {
-  name: string
-  fields: S
-  primaryKey: keyof S & string
-  storageRefs: Map<string, StorageRefSchema>
+interface Extractor<T> {
+  row(): T // full document
+  field<K extends keyof T>(k: K): T[K] // single field
 }
+```
 
-interface IndexDefinition<S extends FieldShape = FieldShape> {
-  name: string
-  keys: IndexKey<S>[]
-  replicate: (keyof S & string)[]
-  sparse: boolean
-  spreadRoots: Set<string>
-}
+#### Aggregated joins ❌
 
-// schema/builder.ts
-function defineStore<S extends FieldShape>(
-  name: string,
-  options: { schema: S; primaryKey?: keyof S; indexes?: IndexBuilder<S>[] }
-): SchemaDefinition<S>
+The template can include aggregates, producing per-left-row aggregate values:
 
-function defineIndex<S extends FieldShape>(name?: string): IndexBuilder<S>
+> **Status:** Not implemented. Use `hashJoinAggregate()` from `docstore-joins.ts` for similar functionality on materialized arrays.
+>
+> **Design Note — Aggregate Joins:**
+> `hashJoinAggregate()` already implements the core algorithm. To integrate with the DSL:
+>
+> 1. Template callback returns an object with `aggregate()` calls for specific fields
+> 2. Planner detects these aggregate markers and collects them into an `AggregateSpec[]`
+> 3. Execution builds a single hash map from right side, but instead of emitting per-match, accumulates into aggregator per left row
+> 4. **Batching optimization**: When multiple aggregates share the same grouping, compute all in a single pass over the right side. The template `{unreadCount: aggregate(...), latestUnread: aggregate(...)}` becomes one scan with two accumulators.
 
-// schema/paths.ts
-// Type-level path extraction (the IndexablePath magic)
-type IndexKey<S> = /* ... recursive path extraction ... */
+```typescript
+join([feeds, 'id'], [where(entries, ['readState', '=', 'unread']), 'feedId'], (f, e) => ({
+  ...f.row(),
+  unreadCount: aggregate(e, ['feedId'], count()),
+  latestUnread: aggregate(e, ['feedId'], topN(1, byPublishedDesc)),
+}))
+// -> Query<Feed & { unreadCount: number, latestUnread: Entry[] }>
 ```
 
-### Layer 2: Index Store
+The planner detects aggregate-joins and batches multiple aggregates into a single pass over the right side.
 
-**Goal:** Encapsulate all storage operations for a single store + its denormalized indexes.
+**Constraint:** Cannot mix `e.row()` and `aggregate(e, ...)` in the same template—that would produce ambiguous output multiplicity.
 
-```typescript
-// store/index-store.ts
-class IndexStore<S extends FieldShape> {
-  readonly schema: SchemaDefinition<S>
-  readonly indexes: IndexDefinition<S>[]
-  readonly stats: StatsManager
+---
 
-  constructor(adapter: StorageAdapter, schema: SchemaDefinition<S>, indexes: IndexDefinition<S>[])
+## Ordering, Pagination, Execution ✅
 
-  // CRUD
-  async put(doc: Infer<S>): Promise<void>
-  async putMany(docs: Infer<S>[]): Promise<void>
-  async get(key: IDBValidKey): Promise<Infer<S> | undefined>
-  async getMany(keys: IDBValidKey[]): Promise<Map<IDBValidKey, Infer<S>>>
-  async delete(key: IDBValidKey): Promise<void>
+Queries are inert until executed. Ordering and limits are specified at execution time:
 
-  // Scanning (used by executor)
-  scan(options: ScanOptions): AsyncGenerator<Row>
-  countRows(options: ScanOptions): Promise<number>
+> **Status:** Implemented. `rows()` and `docs()` are async generators. `rowsPage()` supports cursor-based pagination. `collect()`, `take()`, `skip()` helpers exist. Ordering via `QuerySpec.orderBy` and `RowsOptions.orderBy`.
 
-  // Stats access (used by planner)
-  getStats(): StoreStats
-  getCardinality(field: string): Promise<number>
+```typescript
+// Streaming execution
+for await (const row of query.rows({orderBy: ['publishedAt', 'desc'], limit: 50})) {
+  console.log(row)
 }
 
-interface ScanOptions {
-  store: 'primary' | string // primary or denormalized store name
-  index?: string // null = full scan
-  range?: KeyRange
-  direction?: 'next' | 'prev'
+// Collect all
+const rows = await query.rows({orderBy: ['publishedAt', 'desc']}).collect()
+
+// First match
+const first = await query.rows({limit: 1}).first()
+
+// Hydrate to full documents (lookup join to primary store)
+for await (const doc of query.docs({orderBy: ['publishedAt', 'desc']})) {
+  console.log(doc)
 }
 ```
 
-### Layer 3: Executor
+- `rows()` returns what the chosen index provides (may be denormalized rows with `_docId` + replicated fields)
+- `docs()` always returns full documents from the primary store via lookup join
 
-**Goal:** Streaming operators that compose to execute query plans.
+### Keyset pagination ✅
 
 ```typescript
-// executor/operators.ts
+const page1 = await query.rows({orderBy: ['publishedAt', 'desc'], limit: 20}).collect()
+const cursor = page1.cursor // opaque cursor from last row
 
-// Base type: all operators are async generators
-type RowStream = AsyncGenerator<Row, void, undefined>
+const page2 = await query.rows({orderBy: ['publishedAt', 'desc'], limit: 20, after: cursor}).collect()
+```
 
-// Scan operator - entry point from storage
-function scan(store: IndexStore, options: ScanOptions): RowStream
+> **Status:** Implemented via `rowsPage()` returning `PageResult<T>` with `cursor: PageCursor | null`. Cursor contains `indexKeyValues`, `primaryKey`, and `direction`. Serialization via `serializeCursor()`/`deserializeCursor()`. Batched iteration via `iterateRows()` uses keyset pagination internally.
 
-// Filter - apply residual predicates
-function filter(source: RowStream, predicates: Predicate[]): RowStream
+---
 
-// Project - select fields
-function project(source: RowStream, fields: string[]): RowStream
+## Planner ✅
 
-// Sort - materialize and sort (when index order doesn't match)
-function sort(source: RowStream, key: string, direction: 'asc' | 'desc'): RowStream
+The planner transforms a `Query` into an `ExecutionPlan`. Two layers:
+
+> **Status:** Implemented as `QueryPlanner` class. Takes `QuerySpec`, produces `QueryPlan`. Includes index selection, predicate pushdown, intersection planning, and cost-based decisions using stats.
+
+### Store-Level Planner ✅
+
+Optimizes queries against a single store:
 
-// Limit - early termination
-function limit(source: RowStream, n: number): RowStream
+1. **Index selection** — picks the index that best satisfies filters + orderBy ✅
+2. **Predicate pushdown** — converts equality/range predicates to IDB key ranges ✅ (`KeyRangeSpec`, compound keys supported)
+3. **Intersection detection** — for spread indexes with multiple `contains` predicates, plans set intersection on `_docId` ✅ (`IntersectionPlan` with chained `.next`)
+4. **Residual filters** — predicates that can't be pushed down become post-scan filters ✅ (`plan.filter`)
+5. **Available fields** — tracks which fields are present in the chosen index's rows ✅ (`plan.availableFields`)
 
-// Skip - offset (avoid if possible, use keyset pagination instead)
-function skip(source: RowStream, n: number): RowStream
+Output:
 
-// executor/joins.ts
+```typescript
+interface StorePlan {
+  source: string // primary store or denormalized index store name
+  index: string | null // which index (null = primary key scan)
+  range: KeyRange | null // pushed-down predicates
+  direction: 'next' | 'prev'
+  residualFilter: Filter | null
+  availableFields: string[] // fields present in result rows
+  estimatedRows: number
+}
+```
 
-// Hash join - build map from right, probe with left
-function hashJoin<L, R, Out>(
-  left: RowStream,
-  right: RowStream,
-  leftKey: (row: L) => unknown,
-  rightKey: (row: R) => unknown,
-  project: (l: L, r: R) => Out,
-): AsyncGenerator<Out>
+> **Status:** Implemented as `QueryPlan` interface. Also includes `selectivity`, `docIdField`, `intersection?: IntersectionPlan`, `inValues`/`inPrefix` for cursor-hopping `IN` queries.
 
-// Merge join - both sides sorted on join key
-function mergeJoin<L, R, Out>(
-  left: RowStream,
-  right: RowStream,
-  leftKey: (row: L) => unknown,
-  rightKey: (row: R) => unknown,
-  project: (l: L, r: R) => Out,
-): AsyncGenerator<Out>
+### Cross-Store Planner 🟡
 
-// Nested loop with lookup - for small outer, indexed inner
-function nestedLoopJoin<L, R, Out>(
-  outer: RowStream,
-  lookup: (key: unknown) => Promise<R | undefined>,
-  outerKey: (row: L) => unknown,
-  project: (l: L, r: R) => Out,
-): AsyncGenerator<Out>
+Handles joins and sorting that requires fields not in the chosen index:
 
-// executor/intersect.ts
+1. **Join strategy** — picks hash join, merge join, nested loop, or lookup join based on cardinality estimates ❌ (joins are manual via `docstore-joins.ts`)
+2. **Aggregate-join detection** — when template contains aggregates, plans grouped aggregation during join ❌
+3. **Lookup join insertion** — when `orderBy` field isn't in `availableFields`, wraps with lookup join to primary store ✅ (`docs()` handles this automatically)
+4. **Sort operator insertion** — when index order doesn't match requested order ✅ (`plan.needsSort`, in-memory sort in `rowsSortedDirect()`)
 
-// Set intersection - collect IDs from multiple sources
-function intersect(sources: {stream: RowStream; docIdField: string}[]): AsyncGenerator<IDBValidKey> // yields doc IDs in intersection
+Output:
 
-// executor/execute.ts
+```typescript
+interface ExecutionPlan {
+  root: PlanNode
+  finalSort?: {field: string; direction: 'asc' | 'desc'}
+  limit?: number
+}
 
-// Main entry point - takes a plan tree, returns row stream
-function execute(plan: ExecutionPlan, catalog: Catalog): RowStream
+type PlanNode =
+  | {type: 'scan'; plan: StorePlan}
+  | {type: 'filter'; source: PlanNode; filter: Filter}
+  | {type: 'sort'; source: PlanNode; field: string; direction: 'asc' | 'desc'}
+  | {type: 'limit'; source: PlanNode; n: number}
+  | {type: 'hashJoin'; left: PlanNode; right: PlanNode; leftKey: string; rightKey: string}
+  | {type: 'lookupJoin'; source: PlanNode; targetStore: string; sourceKey: string; targetKey: string}
+  | {
+      type: 'aggregateJoin'
+      left: PlanNode
+      right: PlanNode
+      leftKey: string
+      rightKey: string
+      aggregates: AggregateSpec[]
+    }
+  | {type: 'intersect'; sources: PlanNode[]; docIdField: string}
 ```
 
-### Layer 4: Store-Level Planner
+> **Status:** The current implementation uses a flat `QueryPlan` object rather than a tree of `PlanNode`s. Operators are hardcoded in the executor functions. The intersection is embedded in `QueryPlan.intersection` as a linked list.
+>
+> **Design Note — Plan Node Tree:**
+> The flat `QueryPlan` structure works well for single-store queries. A tree structure becomes valuable when:
+>
+> 1. **Joins are planner-integrated**: `{type: 'hashJoin', left: PlanNode, right: PlanNode}` naturally represents the join structure
+> 2. **Plan visualization**: Tree structure maps directly to EXPLAIN output
+> 3. **Operator composition**: Each node type has a corresponding executor generator, composed via `yield*`
+>
+> Migration path: Keep `QueryPlan` for single-store, introduce `PlanNode` when adding join planning. The `intersection` linked list is already tree-like; could become `{type: 'intersect', sources: PlanNode[]}`.
+
+### Lookup join for sorting
 
-**Goal:** Optimize single-store queries - index selection, intersection, predicate pushdown.
+When a query filters on a denormalized index but sorts on a non-replicated field:
 
 ```typescript
-// planner/store-planner.ts
+where(entries, ['...tags', 'contains', {tag: 'audio'}])
+// executed with: .rows({ orderBy: ['duration', 'desc'] })
+```
+
+The planner:
+
+1. Picks `entries_idx:tags` store with `by_tag` index for filtering
+2. Sees `duration` not in `availableFields`
+3. Wraps with lookup join to `entries` primary store
+4. Adds sort operator on `duration`
+
+---
+
+## Executor ✅
 
-interface StorePlan {
-  source: 'primary' | string // which IDB store to read from
-  index: string | null // which index (null = full scan or pk lookup)
-  range: KeyRange | null // pushed-down predicates as key range
-  direction: 'next' | 'prev'
-  filter: Predicate[] // residual predicates
-  projection: string[] | null // covering index fields, or null for full doc
-  intersection?: IntersectionPlan
-  estimatedRows: number
-  selectivity: number
-  availableFields: string[] // fields available in result rows (for sort validation)
-}
+Volcano-style streaming operators. All operators are `AsyncGenerator<Row>`.
 
-interface IntersectionPlan {
-  source: string
-  index: string
-  range: KeyRange
-  docIdField: string
-  next?: IntersectionPlan // chain for N-way
-}
+> **Status:** Implemented. Uses batched `getAll()` with keyset pagination (`iterateRows()`) for ~1000x fewer IDB round-trips than cursor loops.
 
-class StorePlanner {
-  constructor(schema: SchemaDefinition, indexes: IndexDefinition[], stats: StoreStats)
+```typescript
+// Scan — entry point from storage
+function* scan(store: IndexStore, plan: StorePlan): AsyncGenerator<Row>
 
-  plan(predicates: Predicate[], orderBy?: OrderBy): Promise<StorePlan>
-}
+// Filter — apply residual predicates
+function* filter(source: AsyncGenerator<Row>, predicate: Filter): AsyncGenerator<Row>
+
+// Sort — materialize and sort (when index order doesn't match)
+function* sort(source: AsyncGenerator<Row>, field: string, direction: 'asc' | 'desc'): AsyncGenerator<Row>
+
+// Limit — early termination
+function* limit(source: AsyncGenerator<Row>, n: number): AsyncGenerator<Row>
+
+// Hash join — build hash map from right, probe with left
+function* hashJoin(left: AsyncGenerator<Row>, right: AsyncGenerator<Row>, leftKey, rightKey): AsyncGenerator<Row>
+
+// Lookup join — for each left row, batch lookup from target store
+function* lookupJoin(source: AsyncGenerator<Row>, targetStore: IndexStore, sourceKey, targetKey): AsyncGenerator<Row>
+
+// Aggregate join — hash join with grouped aggregation on right side
+function* aggregateJoin(left, right, leftKey, rightKey, aggregates): AsyncGenerator<Row>
+
+// Intersect — set intersection on doc IDs from multiple index scans
+function* intersect(sources: AsyncGenerator<Row>[], docIdField: string): AsyncGenerator<IDBValidKey>
 ```
 
-**Important:** The Store-Level Planner reports `availableFields` in the plan. If the
-caller requests `orderBy` on a field not in `availableFields`, this signals to the
-Cross-Store Planner (Layer 5) that a **lookup join** back to the primary store is needed.
-The Store-Level Planner doesn't handle this itself — it just provides the information.
+> **Status:**
+>
+> - `scan` ✅ — `rowsDirect()` with batched `iterateRows()`
+> - `filter` ✅ — inline via `matchesFilters()` in scan loop
+> - `sort` ✅ — `rowsSortedDirect()` materializes and sorts
+> - `limit` ✅ — `take()` helper, or just break the generator loop
+> - `hashJoin` ✅ — `hashJoin()` in `docstore-joins.ts` (but on arrays, not generators)
+> - `lookupJoin` ✅ — `docs()` batches lookups to primary store
+> - `aggregateJoin` ❌ — not as a streaming operator
+> - `intersect` ✅ — `rowsIntersectDirect()` with chained `IntersectionPlan`
+>
+> **Design Note — Streaming Aggregate Join:**
+> To add as an `AsyncGenerator` operator:
+>
+> 1. Materialize right side into `Map<K, Acc[]>` (one accumulator array per group, one entry per aggregate function)
+> 2. Stream left side, for each row: lookup by key, call `finalize()` on accumulators, yield combined result
+> 3. For memory efficiency when right side is huge but ordered by join key: detect group boundaries during streaming, finalize and evict completed groups incrementally
 
-### Layer 5: Cross-Store Planner
+Execution reads from storage using paginated cursors to reduce await overhead.
 
-**Goal:** Handle joins, pick join strategies, optimize across stores.
+---
+
+## Index Store 🟡
+
+Encapsulates a primary store and its denormalized index stores.
+
+> **Status:** No `IndexStore` class. Instead, `StoreDef<S>` holds schema/index definitions, and `docstore.install()`, `put()`, `get()`, etc. operate directly on IDB.
+>
+> **Design Note — IndexStore Class:**
+> The current function-based API (`put(db, storeDef, doc)`) is explicit but verbose. An `IndexStore` class could:
+>
+> - Bind `db` and `storeDef` once: `const entries = new IndexStore(db, entriesStoreDef)`
+> - Provide `entries.put(doc)`, `entries.get(key)`, `entries.query({where: ...})`
+> - Hold a reference to `StatsManager` for automatic stats updates
+>
+> Trade-off: Class adds convenience but hides the db/storeDef dependency. The current explicit style is more functional and testable. Consider a thin wrapper class that delegates to the existing functions rather than moving logic into the class.
 
 ```typescript
-// planner/join-planner.ts
+class IndexStore<T> {
+  readonly schema: SchemaDefinition<T>
+  readonly indexes: IndexDefinition[]
 
-interface JoinPlan {
-  type: 'hash' | 'merge' | 'nestedLoop' | 'lookup'
-  left: StorePlan | JoinPlan // can be nested for multi-way
-  right: StorePlan
-  leftKey: string
-  rightKey: string
-  estimatedRows: number
-}
+  // CRUD
+  put(doc: T): Promise<void>
+  putMany(docs: T[]): Promise<void>
+  get(key: IDBValidKey): Promise<T | undefined>
+  getMany(keys: IDBValidKey[]): Promise<Map<IDBValidKey, T>>
+  delete(key: IDBValidKey): Promise<void>
 
-interface ExecutionPlan {
-  root: StorePlan | JoinPlan
-  finalProjection?: string[]
-  finalSort?: OrderBy
-  limit?: number
-}
+  // Scanning (used by executor)
+  scan(options: ScanOptions): AsyncGenerator<Row>
 
-class JoinPlanner {
-  constructor(catalog: Catalog) // Catalog knows all stores and their stats
-
-  plan(ast: QueryAST): Promise<ExecutionPlan>
+  // Stats (used by planner)
+  getStats(): StoreStats
 }
 ```
 
-#### Cross-Store Self-Join (Lookup Join)
+> **Status:** CRUD operations exist as standalone functions: `put()`, `putMany()`, `get()`, `getMany()`, `del()`. Scanning via `rows()` generator. Stats via `StatsManager` class (separate from store).
 
-A critical pattern is the **cross-store self-join** — when a query uses a denormalized
-index store for filtering but needs fields from the primary store that aren't replicated.
+### Denormalization ✅
 
-**Example:** Query audio entries sorted by duration:
+Indexes with spread paths (e.g., `['...tags.tag', '...tags.value']`) create separate IDB object stores. On write, `put()` expands documents into the cartesian product of spread array elements:
 
 ```typescript
-q.from('entries').whereMatch('tags', {tag: 'media-type', value: 'audio'}).orderBy('duration', 'desc')
+// Document
+{ id: '1', title: 'Post', tags: [{ tag: 'a', value: '1' }, { tag: 'b', value: '2' }] }
+
+// Denormalized rows in entries_idx:tags store
+{ _docId: '1', _tag: 'a', _value: '1', title: 'Post', ...replicated }
+{ _docId: '1', _tag: 'b', _value: '2', title: 'Post', ...replicated }
 ```
 
-The denormalized index `entries_idx:tags` has the `by_tag` index for efficient filtering,
-but only replicates `[title, publishedAt, feedId]` — not `duration`.
+The index definition specifies which fields to replicate into denormalized rows.
 
-**Current problem:** The planner picks `entries_idx:tags` for filtering, sets `needsSort: true`,
-but the executor sorts on `undefined` values because `duration` isn't in the rows.
+> **Status:** Fully implemented via `ingest()` function. Index stores use compound primary key `[_docId, _rowId]`. Keys are translated via `toStorageKey()`/`fromStorageKey()` (e.g., `...tags.tag` → `_spread_tags_tag`). Cartesian product computed via `cartesianProduct()` when multiple spread roots exist.
+
+---
+
+## Schema & Index Definitions ✅
 
-**Solution:** The Cross-Store Planner detects this pattern and produces a **lookup join**:
+Pure data definitions, no behavior:
 
 ```typescript
-// Detected: orderBy.key ('duration') not in availableFields from entries_idx:tags
-// Solution: Self-join back to primary store
+interface SchemaDefinition<T> {
+  name: string
+  shape: ZodSchema<T>
+  primaryKey: keyof T
+}
 
-{
-  type: 'lookup',
-  left: {
-    // Filter side: use denormalized index
-    source: 'entries_idx:tags',
-    index: 'by_tag',
-    range: { type: 'only', lower: ['media-type', 'audio'] },
-    // Only need docId for the join
-    projection: ['_docId']
-  },
-  right: {
-    // Lookup side: primary store has all fields
-    source: 'primary',
-    index: null,  // lookup by primary key
-  },
-  leftKey: '_docId',
-  rightKey: 'id',
-  // Now we have full docs, can sort properly
-  finalSort: { key: 'duration', direction: 'desc' }
+interface IndexDefinition {
+  name: string
+  keys: string[] // supports '...spread.path' notation
+  replicate: string[] // fields to copy into denormalized rows
+  sparse: boolean
 }
 ```
 
-**Execution pattern:**
+> **Status:** Implemented as `StoreDef<S>` and `IndexDef<S>`. Also tracks `spreadRoots: Set<string>`, groups indexes into `nativeIndexes` (on primary) and `indexStoreGroups` (denormalized stores). Supports `StorageRef` fields for external blob storage (schema-level, not index-related).
 
-1. Scan `entries_idx:tags` with filter → collect `_docId` values
-2. Batch lookup from `entries` primary store by IDs (use `getMany`)
-3. Sort full documents by `duration`
-4. Yield results
+Builder API:
+
+```typescript
+const entries = defineStore('entries', {
+  schema: z.object({
+    id: z.string(),
+    feedId: z.string(),
+    title: z.string(),
+    publishedAt: z.date(),
+    duration: z.number().optional(),
+    readState: z.enum(['unread', 'read']),
+    tags: z.array(z.object({tag: z.string(), value: z.string()})),
+  }),
+  primaryKey: 'id',
+  indexes: [
+    index('by_feed_date').keys('feedId', 'publishedAt'),
+    index('by_tags').keys('...tags.tag', '...tags.value').replicate('title', 'publishedAt', 'feedId'),
+  ],
+})
+```
 
-This is conceptually a join between two "stores" that happen to be the same logical
-entity (entries) — hence "cross-store self-join". The denormalized index store is
-treated as a separate store for planning purposes.
+> **Status:** Implemented via `docstore.define()` and `IndexBuilder` class. Use `.on()` for keys, `.replicate()` for replicated fields, `.sparse()` for sparse indexes. Type-safe `IndexKey<S>` constrains keys to indexable paths.
 
-**Detection heuristic in planner:**
+---
+
+## Storage Adapter ❌
+
+Abstracts IndexedDB so the engine can be tested with in-memory storage or ported to other backends:
+
+> **Status:** Not implemented. Code directly uses `idb` library (`IDBPDatabase`). No `MemoryStorageAdapter` for testing - tests use real IndexedDB (via happy-dom or jsdom).
+>
+> **Design Note — Storage Adapter:**
+> Whether to add this abstraction depends on goals:
+>
+> - **For testing**: happy-dom's IDB works well, and testing against real IDB catches edge cases (key ordering, transaction semantics). An in-memory adapter risks hiding bugs.
+> - **For portability** (e.g., to SQLite/OPFS): Worth doing. The adapter interface should mirror IDB closely but allow different backends.
+> - **Minimal interface**: `Transaction`, `ObjectStore`, `Index` with `get/put/delete/getAll/getAllKeys/count`. The existing `KeyRangeSpec` type already abstracts `IDBKeyRange`.
+>
+> If added, inject adapter via `ExecutionContext` rather than changing all function signatures. The current direct `idb` usage is actually quite clean.
 
 ```typescript
-// In StorePlanner or JoinPlanner
-if (plan.needsSort && orderBy) {
-  const sortKeyAvailable = plan.availableFields.includes(orderBy.key)
-  if (!sortKeyAvailable && plan.source !== 'primary') {
-    // Need lookup join back to primary
-    return wrapWithLookupJoin(plan, orderBy)
-  }
+interface StorageAdapter {
+  transaction(stores: string[], mode: 'readonly' | 'readwrite'): Transaction
+  createStores(schemas: StoreSchema[]): Promise<void>
+}
+
+interface Transaction {
+  store(name: string): ObjectStore
+  done: Promise<void>
+}
+
+interface ObjectStore {
+  get(key: IDBValidKey): Promise<unknown>
+  put(value: unknown): Promise<void>
+  delete(key: IDBValidKey): Promise<void>
+  getAll(range?: KeyRange, count?: number): Promise<unknown[]>
+  getAllKeys(range?: KeyRange, count?: number): Promise<IDBValidKey[]>
+  count(range?: KeyRange): Promise<number>
+  index(name: string): Index
 }
+
+interface Index {
+  getAll(range?: KeyRange, count?: number): Promise<unknown[]>
+  getAllKeys(range?: KeyRange, count?: number): Promise<IDBValidKey[]>
+  count(range?: KeyRange): Promise<number>
+}
+
+type KeyRange =
+  | {type: 'only'; value: unknown}
+  | {type: 'bound'; lower?: unknown; upper?: unknown; lowerOpen?: boolean; upperOpen?: boolean}
 ```
 
-````
+Implementations: `IDBStorageAdapter`, `MemoryStorageAdapter`.
+
+> **Status:** Neither implemented. Direct `idb` library usage throughout.
+
+---
+
+## Key Design Decisions
+
+- **Queries are combinators, not methods.** `where()`, `aggregate()`, `join()` are functions that compose stores and queries. Stores don't grow method surfaces.
 
-### Layer 6: Query DSL
+  > ❌ Not implemented. Current API is imperative (`QuerySpec` objects + `plan()` + `rows()`).
 
-**Goal:** Ergonomic, type-safe query builder that compiles to AST.
+- **No projection.** IDB reads whole documents regardless. Shaping output happens outside the query engine. `rows()` returns index rows, `docs()` returns full documents.
 
-```typescript
-// dsl/query.ts
+  > ✅ Implemented exactly as described.
 
-interface Query<S extends FieldShape, Selected = Infer<S>> {
-  // Filtering
-  where<K extends keyof S>(
-    field: K,
-    op: CompareOp,
-    value: FieldValue<S[K]>
-  ): Query<S, Selected>
+- **Spread match is an operator.** `['...tags', 'contains', { tag: 'x', value: 'y' }]` means "some array element matches all these fields." This is distinct from equality on a path.
 
-  whereMatch(spread: string, match: Record<string, unknown>): Query<S, Selected>
+  > ✅ Implemented via `SpreadMatch` interface in `QuerySpec.matches`. Uses explicit `{spread: 'tags', where: {tag: 'x', value: 'y'}}` syntax.
 
-  // Joins
-  join<T extends FieldShape>(
-    store: SchemaDefinition<T>,
-    leftKey: keyof S,
-    rightKey: keyof T
-  ): JoinedQuery<S, T, Selected>
+- **AsyncGenerator everywhere.** Native, composable, supports early termination. Observables are for live queries (a separate layer on top).
 
-  leftJoin<T extends FieldShape>(
-    store: SchemaDefinition<T>,
-    leftKey: keyof S,
-    rightKey: keyof T
-  ): JoinedQuery<S, T, Selected>
+  > ✅ `rows()`, `docs()`, `iterateRows()`, `iterateKeys()` are all `AsyncGenerator`s. No live query/observable layer yet.
 
-  // Projection
-  select<K extends keyof S>(...fields: K[]): Query<S, Pick<Infer<S>, K>>
+- **Denormalized indexes are separate stores.** The planner treats them as distinct data sources. A "lookup join" back to the primary store is just another join.
 
-  // Ordering
-  orderBy(field: keyof S, direction?: 'asc' | 'desc'): Query<S, Selected>
+  > ✅ Index store groups (`IndexStoreGroup`) create separate IDB object stores named `{primary}_idx:{spreadRoots}`. `docs()` handles lookup join to primary.
 
-  // Pagination
-  limit(n: number): Query<S, Selected>
-  skip(n: number): Query<S, Selected>
-  cursor(c: PageCursor): Query<S, Selected>
+- **Sorting informs index selection.** The DSL captures `orderBy`, the planner tries to satisfy it with index order, falls back to sort operator + lookup join if needed.
 
-  // Execution
-  toAST(): QueryAST
-  plan(): Promise<ExecutionPlan>
-  execute(): AsyncGenerator<Selected>
-  collect(): Promise<Selected[]>
-  first(): Promise<Selected | undefined>
-  count(): Promise<number>
-}
+  > ✅ `QuerySpec.orderBy` informs planner. `candidate.coversOrderBy` scoring. `plan.needsSort` triggers in-memory sort. `plan.direction` set to 'prev' for desc when index covers it.
 
-// Entry point
-function from<S extends FieldShape>(store: IndexStore<S>): Query<S>
-````
+- **Stats drive planning.** HyperLogLog cardinality sketches and row counts inform index selection and join strategy.
+  > ✅ `HyperLogLog` class for cardinality. `StatsManager` tracks per-store `IndexStatsRecord` with `rowCount`, `cardinalitySketch`, `bounds`. Used by `QueryPlanner` for selectivity estimation. Vacuum support for drift correction.
 
 ---
 
-## Key Design Decisions
+## Build Order
 
-### 1. AsyncGenerator Everywhere (not Observable)
+### 1. Storage Adapter ❌
+
+Start with the abstraction layer. Implement `MemoryStorageAdapter` first—it's simpler and lets you test everything without browser IDB. The interface mirrors IDB's API closely, so `IDBStorageAdapter` is mostly passthrough.
 
-The Observable layer adds complexity without clear benefit for query execution. AsyncGenerators:
+Key pieces: `Transaction`, `ObjectStore`, `Index`, `KeyRange` type and utilities for building/intersecting ranges.
 
-- Are native, no polyfill needed
-- Compose naturally with `for await`
-- Support early termination via `return()`
-- Work with existing `collect()`, `take()`, `skip()` utilities
+> **Status:** Skipped. Direct `idb` library usage. `KeyRangeSpec` exists for serializable key ranges, converted via `toIDBKeyRange()`.
 
-Keep Observable for **live queries** where you need push-based updates.
+### 2. Schema & Index Definitions ✅
 
-### 2. Catalog as Central Registry
+Pure types and builders. `defineStore()` and `index()` produce `SchemaDefinition` and `IndexDefinition` objects. No runtime behavior yet—just data describing the shape of stores and their indexes.
 
-```typescript
-interface Catalog {
-  stores: Map<string, IndexStore>
+Include the path parsing logic for spread notation (`...tags.tag` -> `{ spread: 'tags', path: 'tag' }`).
 
-  getStore(name: string): IndexStore
-  getStats(name: string): StoreStats
+> **Status:** Complete. `docstore.define()`, `IndexBuilder`, `explodeKey()` for path parsing, `computeSpreadRoots()`, `groupIndexesBySpreadRoots()`.
 
-  // For cross-store planning
-  estimateJoinCardinality(leftStore: string, leftKey: string, rightStore: string, rightKey: string): number
-}
-```
+### 3. Index Store ✅
 
-The catalog is the bridge between stores and the planner.
+The core storage abstraction. Wraps a primary IDB store plus any denormalized index stores.
 
-### 3. Predicate Representation
+Build in order:
 
-```typescript
-type Predicate =
-  | {type: 'eq'; field: string; value: unknown}
-  | {type: 'neq'; field: string; value: unknown}
-  | {type: 'lt' | 'lte' | 'gt' | 'gte'; field: string; value: unknown}
-  | {type: 'in'; field: string; values: unknown[]}
-  | {type: 'spreadMatch'; spread: string; match: Record<string, unknown>}
-  | {type: 'and'; predicates: Predicate[]}
-  | {type: 'or'; predicates: Predicate[]}
-```
+1. Basic CRUD (`put`, `get`, `delete`) on primary store only ✅
+2. `scan()` with key ranges and direction ✅ (via `rows()`)
+3. Denormalization logic—on `put()`, expand spread indexes into their stores ✅ (`ingest()` + index store writes)
+4. `getMany()` for batch lookups ✅
 
-This is the internal representation. The DSL compiles to this.
+Test with `MemoryStorageAdapter`.
 
-### 4. SpreadMatch as First-Class Concept
+> **Status:** All implemented as standalone functions. No `IndexStore` class wrapper, but all functionality present.
 
-Your current `SpreadMatch` is great — it explicitly says "match these fields on ONE row of the spread array." Make it a core predicate type rather than a separate query path.
+### 4. Stats ✅
 
-### 5. Separate Statistics Store
+`HyperLogLog` for cardinality estimation. `StatsStore` tracks per-store row counts and per-field cardinality sketches. Updated on writes, persisted to a `_stats` store.
 
-```typescript
-// stats/stats-store.ts
-class StatsStore {
-  // Per-store, per-field cardinality sketches
-  private sketches: Map<string, Map<string, HyperLogLog>>
+This can be built independently and plugged into `IndexStore` later.
 
-  // Row counts per store (primary + denormalized)
-  private rowCounts: Map<string, number>
+> **Status:** Complete. `HyperLogLog` class (1024 registers, FNV-1a hash). `StatsManager` with `recordWrite()`, `recordWriteBatch()`, `recordDelete()`, `getCardinality()`, `getStats()`, `vacuum()`. Min/max bounds tracking. Idle-time vacuum scheduling via `requestIdleCallback`.
 
-  // Bounds per field
-  private bounds: Map<string, Map<string, {min: unknown; max: unknown}>>
+### 5. Executor Operators ✅
 
-  // Async persist to IDB _stats store
-  async flush(): Promise<void>
+Build the streaming operators bottom-up:
 
-  // Background vacuum scheduling
-  scheduleVacuum(storeId: string): void
-}
-```
+1. `scan()` — wraps `IndexStore.scan()` ✅ (`rowsDirect()`)
+2. `filter()` — predicate evaluation on rows ✅ (`matchesFilters()` inline)
+3. `limit()` — early termination ✅ (`take()`)
+4. `sort()` — materialize + sort (needed when index order doesn't match) ✅ (`rowsSortedDirect()`)
+5. `intersect()` — collect doc IDs from multiple scans, yield intersection ✅ (`rowsIntersectDirect()`, `filterByIntersection()`)
+6. `lookupJoin()` — batch lookup by key ✅ (`docs()` with batched fetches)
+7. `hashJoin()` — build/probe pattern ✅ (`hashJoin()` in docstore-joins.ts)
+8. `aggregateJoin()` — hash join with grouped aggregation ✅ (`hashJoinAggregate()` in docstore-joins.ts)
 
----
+Each operator is independently testable.
 
-## File Structure
+> **Status:** All core operators implemented. Join operators are in separate module, work on arrays not generators.
 
-```
-src/lib/docstore/
-├── storage/
-│   ├── adapter.ts           # StorageAdapter interface
-│   ├── idb-adapter.ts       # IDB implementation
-│   ├── memory-adapter.ts    # In-memory for testing
-│   └── key-range.ts         # KeyRange utilities
-│
-├── schema/
-│   ├── types.ts             # SchemaDefinition, IndexDefinition
-│   ├── builder.ts           # defineStore(), defineIndex()
-│   ├── paths.ts             # IndexablePath type magic
-│   ├── infer.ts             # Type inference utilities
-│   └── storage-ref.ts       # StorageRef for blobs
-│
-├── store/
-│   ├── index-store.ts       # IndexStore class
-│   ├── denormalize.ts       # ingest() and cartesian product
-│   └── catalog.ts           # Catalog registry
-│
-├── stats/
-│   ├── hll.ts               # HyperLogLog
-│   ├── stats-store.ts       # StatsStore
-│   └── vacuum.ts            # Background vacuum
-│
-├── executor/
-│   ├── operators.ts         # scan, filter, project, sort, limit
-│   ├── joins.ts             # hashJoin, mergeJoin, nestedLoopJoin
-│   ├── intersect.ts         # Set intersection for self-joins
-│   ├── execute.ts           # Plan → RowStream
-│   └── page.ts              # Keyset pagination
-│
-├── planner/
-│   ├── predicates.ts        # Predicate types and matching
-│   ├── store-planner.ts     # Single-store optimization
-│   ├── join-planner.ts      # Cross-store join planning
-│   └── cost.ts              # Cost estimation utilities
-│
-├── dsl/
-│   ├── query.ts             # Query builder
-│   ├── ast.ts               # QueryAST types
-│   └── compile.ts           # AST → ExecutionPlan
-│
-├── live/
-│   ├── live-query.ts        # Observable-based live queries
-│   └── diff.ts              # Result diffing for updates
-│
-├── analyzer.ts              # Query tracing (keep as-is)
-└── index.ts                 # Public API exports
-```
+### 6. Store-Level Planner ✅
 
----
+Takes predicates + orderBy + index definitions + stats, produces `StorePlan`.
 
-## Migration Path
+Build incrementally:
 
-1. **Extract Schema** — Pull out `SchemaDefinition`, `IndexDefinition`, `IndexBuilder` into `schema/`
-2. **Extract Storage Adapter** — Create `StorageAdapter` interface, wrap current IDB code
-3. **Extract Stats** — Pull `HyperLogLog`, `StatsManager` into `stats/`
-4. **Refactor IndexStore** — Encapsulate put/get/scan with adapter abstraction
-5. **Extract Executor** — Pull operator functions into `executor/`
-6. **Extract Planner** — Pull `QueryPlanner` into `planner/store-planner.ts`
-7. **Add Join Planner** — New `planner/join-planner.ts` that uses `docstore-joins.ts` strategies
-8. **Build DSL** — New `dsl/query.ts` that compiles to AST and executes
+1. Simple index selection (first index that matches any predicate) ✅
+2. Predicate pushdown to key ranges ✅ (`#buildKeyRange()`, `#buildCompoundKeyRange()`)
+3. Compound index prefix matching ✅ (`eqPrefixLength`)
+4. Cost-based selection using stats ✅ (`#scoreCandidate()`, selectivity from HLL)
+5. Intersection planning for multiple spread predicates ✅ (`#evaluateIntersection()`, `#evaluateSelfJoin()`, `#evaluateSpreadMatches()`)
+6. `availableFields` tracking ✅ (`#getAvailableFields()`)
 
-Each step is independently testable. The current tests should keep passing as you refactor.
+> **Status:** Complete in `QueryPlanner` class. Also handles `IN` queries via cursor hopping (`inValues`/`inPrefix`).
 
----
+### 7. Cross-Store Planner 🟡
 
-## Wild Ideas (Bonus)
+Takes a `Query` (possibly a join), produces `ExecutionPlan`.
 
-### Materialized Views
+Build incrementally:
 
-```typescript
-const unreadByFeed = defineView('unread_by_feed', {
-  source: entries,
-  groupBy: 'feedId',
-  aggregate: {
-    count: count(),
-    latest: max('publishedAt'),
-  },
-  where: [{field: 'readState', op: '=', value: 'unread'}],
-})
-```
+1. Single-store queries (delegate to store planner, add sort/limit nodes) ✅
+2. Simple joins (hash join strategy) ❌ (manual via `docstore-joins.ts`)
+3. Lookup join insertion when sort field unavailable ✅ (`docs()` handles)
+4. Aggregate-join detection and planning ❌
+5. Join strategy selection based on cardinality ❌
 
-Maintained incrementally on write. Query it like a store.
+> **Status:** Single-store planning complete. Cross-store joins are manual—user composes queries and join functions explicitly.
+>
+> **Design Note — Cross-Store Planner:**
+> To integrate joins into the planner:
+>
+> 1. **Join strategy selection**: Compare cardinalities from `StatsManager`:
+>    - Left << Right → nested loop with batched lookup (like `docs()`)
+>    - Left ≈ Right → hash join (materialize smaller side)
+>    - Both ordered by join key → merge join (stream both)
+> 2. **Aggregate-join detection**: When the DSL template contains `aggregate()` calls, extract them during planning. The planner groups aggregates by their source/key and batches them into a single `AggregateJoinNode`.
+> 3. **Cost model**: `scanCost = rowCount * (indexMatch ? 0.01 : 1.0)`, `joinCost = leftRows + rightRows * hashFactor`. Pick plan with lowest total cost.
 
-### Declarative Indexes from Queries
+### 8. Query DSL ❌
 
-```typescript
-// Analyze query patterns, suggest indexes
-const suggestions = catalog.analyzeQueryPatterns(queryLog)
-// => "Consider adding index on [feedId, readState, publishedAt] - would improve 47% of queries"
-```
+The user-facing API. `where()`, `aggregate()`, `join()` build `Query<T>` objects that capture the query structure. `rows()` and `docs()` compile to a plan and execute.
 
-### Query Plan Caching
+This is mostly glue—the hard work is in the planner and executor.
 
-```typescript
-const prepared = query.prepare() // Plans once
-const results1 = await prepared.execute({feedId: 'f1'})
-const results2 = await prepared.execute({feedId: 'f2'}) // Reuses plan
-```
+> **Status:** Not implemented. Current API is imperative:
+>
+> ```typescript
+> const plan = await planner.plan({store: 'entries', where: [...], orderBy: {...}})
+> for await (const row of rows(ctx, plan)) { ... }
+> ```
+>
+> DSL layer would wrap this in a fluent/combinator style.
+>
+> **Design Note — DSL Implementation:**
+> The DSL is a thin layer that builds `QuerySpec` objects and calls the existing planner/executor:
+>
+> ```typescript
+> class Query<T> {
+>   #spec: QuerySpec
+>   #planner: QueryPlanner
+>   #ctx: ExecutionContext
+>
+>   where(filter: Filter<T>): Query<T> {
+>     // Clone spec, append to where array, return new Query
+>   }
+>
+>   async *rows(opts?: RowsOptions): AsyncGenerator<T> {
+>     const plan = await this.#planner.plan(this.#spec)
+>     yield* rows(this.#ctx, plan, opts)
+>   }
+> }
+>
+> // Factory function
+> function from<S>(store: StoreDef<S>, ctx: ExecutionContext): Query<Infer<S>>
+> ```
+>
+> Key: `Query<T>` is immutable—each combinator returns a new instance. This enables safe composition and potential plan caching (same spec → same plan).
 
 ---
 
-What aspects of this would you like to dig into? I'm happy to:
+## Future Considerations
+
+- **Live queries.** Observable layer on top of the generator-based execution. Cold observables that re-execute on relevant writes.
+
+  > ❌ Not implemented.
+  >
+  > **Design Note:** Two approaches:
+  >
+  > 1. **Re-execution**: Track which stores/indexes a query touches. On write to those stores, invalidate and re-run. Simple but potentially expensive.
+  > 2. **Differential**: For simple queries, compute delta from the write. E.g., for `where(entries, ['feedId', '=', 'f1'])`, a new entry with `feedId='f1'` can be appended without re-querying.
+  >
+  > Start with (1), optimize hot paths with (2). Use `WriteBatch` events from `put()`/`del()` to trigger invalidation. Return `Observable<T[]>` or `Observable<Delta<T>>` depending on use case.
+
+- **Plan caching.** Queries with parameters could cache the plan structure and just bind new values. Requires adding parameter placeholders to the DSL.
+
+  > ❌ Not implemented.
+  >
+  > **Design Note:** The planner is already fast (<1ms for typical queries), so caching is mainly useful for:
+  >
+  > 1. **Parameterized queries**: `where(entries, ['feedId', '=', $param])` caches the plan structure, binds `$param` at execution time. Store plans in `WeakMap<QuerySpec, QueryPlan>` keyed by spec identity.
+  > 2. **Prepared statements**: For hot paths, pre-plan and reuse. The plan's `keyRange` would need a "template" mode where values are bound later.
+  >
+  > Low priority—measure planning overhead first. If it becomes a bottleneck, the current planner outputs are already serializable (no closures).
 
-- Flesh out any layer in more detail
-- Prototype a specific piece
-- Discuss tradeoffs in the design
-- Think through the migration strategy
+- **Materialized views.** Pre-computed aggregates maintained incrementally on write.
 
----
+  > ❌ Not implemented.
+  >
+  > **Design Note:** Materialized views are essentially "derived stores" that update on write:
+  >
+  > 1. **Definition**: `defineView('unreadCounts', aggregate(entries, ['feedId'], count()), {where: ['readState', '=', 'unread']})`
+  > 2. **Storage**: Separate IDB store holding aggregated values keyed by group key
+  > 3. **Incremental update**: On `put(entry)`:
+  >    - If entry was updated: decrement old group's count, increment new group's count
+  >    - If entry is new: increment group's count
+  >    - Requires tracking previous state or computing delta
+  > 4. **Rebuild**: Periodic full recomputation to fix drift (similar to `StatsManager.vacuum()`)
+  >
+  > The existing `collectIndexValues()` is a non-materialized version of this. Materialization trades write cost for read speed.
+
+- **Query analysis.** Log query patterns, suggest missing indexes.
+  > 🟡 `Analyzer` class exists for structured timing/tracing (open/close spans, print). No automatic index suggestion.
+  >
+  > **Design Note — Index Suggestion:**
+  > The `Analyzer` already captures query execution details. To suggest indexes:
+  >
+  > 1. **Track slow queries**: Log queries where `plan.estimatedRows` >> actual rows returned (poor selectivity) or `plan.needsSort = true` (missing index for orderBy)
+  > 2. **Identify patterns**: Collect `{store, whereKeys[], orderByKey}` tuples from executed queries. Group by pattern, count frequency.
+  > 3. **Suggest indexes**: For frequent patterns with high scan counts:
+  >    - If `whereKeys` not covered by any index prefix → suggest `index.on(...whereKeys)`
+  >    - If `orderByKey` not covered → suggest adding to existing index or new index
+  >    - If spread key in where clause → suggest spread index with replication of filter/sort fields
+  > 4. **Output**: `analyzer.suggestIndexes()` returns `IndexDef[]` that could improve observed query patterns
+  >
+  > Could integrate with `StatsManager` to estimate cardinalities for suggested indexes and rank by expected impact.

src/lib/idbase/builder-scratch.ts

···
+// todo:
+
+export type MigrationTx<
+  ReadSchema extends SchemaConstraint,
+  WriteSchema extends SchemaConstraint
+> = any
+
+/////
+
+// todo: should eventually be "stuff that's serializable to idb"
+export type RowConstraint = Record<string | number | symbol, unknown>
+
+// store name -> document type
+export type SchemaConstraint = Record<string, RowConstraint>
+
+// generated index name -> keypaths
+// eg { idx_feedid_readat: readonly ['feedId', 'readAt'], ... }
+export type IndexesConstraint = Record<string, readonly string[]>
+
+///
+
+const autogen = Symbol.for('autogenerate')
+
+type PrimaryKey<Row> = typeof autogen | keyof Row & string | (keyof Row & string)[]
+type ReplicableKey<Row> = IndexPath<Row> | keyof Row & string
+
+///
+
+export interface DatabaseDef<Name extends string, Version extends number, Schema extends SchemaConstraint> {
+  name: Name
+  version: Version
+  versions: VersionDef<any>[]
+
+  // phantom types
+  __schema: Schema
+}
+
+export interface VersionDef<Schema extends SchemaConstraint> {
+  stores: Map<string, StoreDef<string, any, any>>
+  migrations: MigrationDef[]
+
+  // phantom types
+  __schema: Schema
+}
+
+export type MigrationDef =
+  | MigrationFn<any, any>
+  | ['create', string, StoreDef<string, any>]
+  | ['update', string, StoreDef<string, any>]
+  | ['drop', string]
+
+export type MigrationFn<
+  OldSchema extends SchemaConstraint,
+  NewSchema extends SchemaConstraint
+> = ((tx: MigrationTx<OldSchema, NewSchema>) => Promise<void>)
+
+interface StoreDef<
+  Name extends string,
+  Row extends RowConstraint,
+  Doc = Row,
+  Indexes extends IndexesConstraint = IndexesConstraint
+> {
+  name: Name
+  pkey: PrimaryKey<Row>
+  indexes: Map<keyof Indexes, IndexDef<Row>>
+  codec?: CodecDef<Row, Doc>
+
+  __row: Row
+  __doc: Doc
+  __indexes: Indexes
+}
+
+interface CodecDef<Row, Doc> {
+  encode: (doc: Doc) => Row
+  decode: (row: Row) => Doc
+}
+
+interface IndexDef<
+  Row extends RowConstraint,
+  Name extends string = string,
+  Keys extends readonly string [] = IndexPath<Row>[]
+> {
+  name: Name
+  keys: Keys
+  replicate: ReplicableKey<Row>[]
+  roots: Set<keyof Row>
+}
+
+export type ExtractIndexName<T> = T extends IndexDef<any, infer N, any> ? N : never
+export type ExtractIndexKeys<T> = T extends IndexDef<any, any, infer K> ? K : never
+
+// builders
+
+export class DatabaseBuilder<
+  Name extends string,
+  Version extends number = 0,
+  Schema extends SchemaConstraint = {}
+> {
+  #name: Name
+  #versions: VersionDef<any>[]
+
+  constructor(name: Name) {
+    this.#name = name
+    this.#versions = []
+  }
+
+  version<NewSchema extends SchemaConstraint>(
+    cb: (builder: VersionBuilder<Schema>) => VersionDef<NewSchema>
+  ): DatabaseBuilder<Name, Increment<Version>, NewSchema> {
+    this.#versions.push(cb(new VersionBuilder<Schema>()))
+    return this as unknown as DatabaseBuilder<Name, Increment<Version>, NewSchema>
+  }
+
+  build(): DatabaseDef<Name, Version, Schema> {
+    return {
+      name: this.#name,
+      version: this.#versions.length as Version,
+      versions: this.#versions,
+
+      __schema: undefined as unknown as Schema
+    }
+  }
+}
+
+class VersionBuilder<Schema extends SchemaConstraint> {
+  #stores: Map<string, StoreDef<string, any>>
+  #migrations: MigrationDef[]
+
+  constructor() {
+    this.#stores = new Map()
+    this.#migrations = []
+  }
+
+  store<Row extends RowConstraint, Name extends string>(
+    name: UnusedKey<Name, Schema>,
+    cb: (builder: StoreBuilder<Name, Row>) => StoreDef<Name, Row>
+  ): VersionBuilder<Schema & {[K in Name]: Row}>
+
+  store<Row extends RowConstraint, Name extends string>(
+    name: ExtantKey<Name, Schema>,
+    cb: (builder: StoreUpdater<Name, Schema[Name], any, any>) => StoreDef<Name, Row>
+  ): VersionBuilder<Schema & {[K in Name]: Row}>
+
+  store<Name extends string>(
+    name: ExtantKey<Name, Schema>,
+    cb: 'drop'
+  ): VersionBuilder<Omit<Schema, Name>>
+
+  store<Row extends RowConstraint, Name extends string>(
+    name: Name,
+    cb: 'drop' | ((builder: any) => StoreDef<Name, Row>)
+  ): VersionBuilder<any> {
+    if (cb === 'drop') {
+      return this.#dropStore(name)
+    }
+    else if (this.#stores.has(name)) {
+      return this.#updateStore(name, cb)
+    }
+    else {
+      return this.#createStore(name, cb)
+    }
+  }
+
+  migrate<NewSchema extends SchemaConstraint>(
+    cb: MigrationFn<Schema, NewSchema>
+  ): VersionBuilder<NewSchema> {
+    this.#migrations.push(cb)
+    return this as unknown as VersionBuilder<NewSchema>
+  }
+
+  build(): VersionDef<Schema> {
+    return {
+      stores: this.#stores,
+      migrations: this.#migrations,
+
+      __schema: undefined as unknown as Schema
+    }
+  }
+
+  #createStore<Row extends RowConstraint, Name extends string>(
+    name: Name,
+    cb: (builder: StoreBuilder<Name, Row>) => StoreDef<Name, Row>
+  ): VersionBuilder<Schema & {[K in Name]: Row}> {
+    if (this.#stores.has(name))
+      throw new Error(`cannot create store ${name} - already exists`)
+
+    const created = cb(new StoreBuilder<Name, Row>(name))
+    this.#stores.set(name, created)
+    this.#migrations.push(['create', name, created])
+
+    return this as unknown as VersionBuilder<Schema & {[K in Name]: Row}>
+  }
+
+  #updateStore<NewRow extends RowConstraint, Name extends string>(
+    name: Name,
+    cb: (u: StoreUpdater<Name, Schema[Name], any, any>) => StoreDef<Name, NewRow>
+  ): VersionBuilder<Schema & {[K in Name]: NewRow}> {
+    const extant = this.#stores.get(name as Name)
+    if (extant == null) throw new Error(`cannot update store ${name} - does not exist`)
+
+    const updated = cb(new StoreUpdater<Name, Schema[Name], typeof extant.__doc, typeof extant.__indexes>(extant as any))
+    this.#stores.set(name, updated)
+    this.#migrations.push(['update', name, updated])
+
+    return this as unknown as VersionBuilder<Schema & {[K in Name]: NewRow}>
+  }
+
+  #dropStore<Name extends string>(name: Name): VersionBuilder<Omit<Schema, Name>> {
+    this.#stores.delete(name)
+    this.#migrations.push(['drop', name])
+
+    return this as unknown as VersionBuilder<Omit<Schema, Name>>
+  }
+}
+
+class StoreBuilder<
+  Name extends string,
+  Row extends RowConstraint,
+  Doc = Row,
+  Indexes extends IndexesConstraint = {}
+> {
+  #name: Name
+  #pkey: PrimaryKey<Row> = autogen
+  #indexes: Map<keyof Indexes, IndexDef<Row>> = new Map()
+  #codec?: CodecDef<Row, Doc>
+
+  constructor(name: Name) {
+    this.#name = name
+  }
+
+  pkey(key: PrimaryKey<Row>): this {
+    this.#pkey = key
+    return this
+  }
+
+  codec<D>(codec: CodecDef<Row, D>): StoreBuilder<Name, Row, D, Indexes> {
+    this.#codec = codec as any
+    return this as unknown as StoreBuilder<Name, Row, D, Indexes>
+  }
+
+  index<
+    IDef extends IndexDef<Row>,
+    IName extends string = '<unnamed>',
+    IndexName = AutoIndexName<IName, ExtractIndexKeys<IDef>>,
+  > (
+    name: typeof autogen | UnusedKey<IName, Indexes>,
+    cb: ((builder: IndexBuilder<Row, IName>) => IDef)
+  ): StoreBuilder<Name, Row, Doc, Indexes & {[K in IndexName & string]: ExtractIndexKeys<IDef>}> {
+    this.#indexes.set(name as any, cb(new IndexBuilder<Row, IName>(name)))
+    return this as unknown as StoreBuilder<Name, Row, Doc, Indexes & {[K in IndexName & string]: ExtractIndexKeys<IDef>}>
+  }
+
+  build(): StoreDef<Name, Row, Doc, Indexes> {
+    return {
+      name: this.#name,
+      pkey: this.#pkey,
+      indexes: this.#indexes,
+      codec: this.#codec,
+
+      __row: undefined as unknown as Row,
+      __doc: undefined as unknown as Doc,
+      __indexes: undefined as unknown as Indexes
+    }
+  }
+}
+
+class StoreUpdater<
+  Name extends string,
+  Row extends RowConstraint,
+  Doc,
+  Indexes extends IndexesConstraint
+> {
+  #extant: StoreDef<Name, Row, Doc, Indexes>
+  #indexes: Map<keyof Indexes, IndexDef<Row>>
+  #codec?: CodecDef<Row, Doc>
+
+  constructor(extant: StoreDef<Name, Row, Doc, Indexes>) {
+    this.#extant  = extant
+    this.#indexes = extant.indexes
+    this.#codec   = extant.codec
+  }
+
+  codec<D>(codec: CodecDef<Row, D>): StoreUpdater<Name, Row, D, Indexes> {
+    this.#codec = codec as any
+    return this as unknown as StoreUpdater<Name, Row, D, Indexes>
+  }
+
+  index<
+    IDef extends IndexDef<Row>,
+    IName extends string = '<unnamed>',
+    IndexName = AutoIndexName<IName, ExtractIndexKeys<IDef>>,
+  > (
+    name: typeof autogen | UnusedKey<IName, Indexes>,
+    cb: ((builder: IndexBuilder<Row, IName>) => IDef)
+  ): StoreUpdater<Name, Row, Doc, Indexes & {[K in IndexName & string]: ExtractIndexKeys<IDef>}> {
+    this.#indexes.set(name as any, cb(new IndexBuilder<Row, IName>(name)))
+    return this as unknown as StoreUpdater<Name, Row, Doc, Indexes & {[K in IndexName & string]: ExtractIndexKeys<IDef>}>
+  }
+
+  dropIndex<IName extends string>(name: ExtantKey<IName, Indexes>): StoreUpdater<Name, Row, Doc, Omit<Indexes, IName>> {
+    this.#indexes.delete(name)
+    return this as unknown as StoreUpdater<Name, Row, Doc, Omit<Indexes, IName>>
+  }
+
+  build(): StoreDef<Name, Row, Doc, Indexes> {
+    return {
+      ...this.#extant,
+      indexes: this.#indexes,
+      codec: this.#codec,
+
+      __row: undefined as unknown as Row,
+      __doc: undefined as unknown as Doc,
+      __indexes: undefined as unknown as Indexes
+    }
+  }
+}
+
+class IndexBuilder<
+  Row extends RowConstraint,
+  Name extends typeof autogen | string,
+  Keys extends readonly IndexPath<Row>[] = []
+> {
+  #name: typeof autogen | string
+  #keys: Keys
+  #replicate: ReplicableKey<Row>[]
+
+  constructor(name: typeof autogen | string = autogen) {
+    this.#name = name
+    this.#keys = [] as unknown as Keys
+    this.#replicate = []
+  }
+
+  on<K extends readonly IndexPath<Row>[]>(...keys: K): IndexBuilder<Row, Name, K> {
+    const self = this as unknown as IndexBuilder<Row, Name, K>
+
+    self.#keys = keys
+    return self
+  }
+
+  replicate(...keys: ReplicableKey<Row>[]): this {
+    this.#replicate = keys
+    return this
+  }
+
+  build(): IndexDef<Row, AutoIndexName<Name, Keys> & string, Keys> {
+    if (this.#keys.length === 0)
+      throw new Error('no keys specified!')
+
+    const roots = computeIndexRoots(this.#keys)
+    const name = this.#name === autogen
+      ? computeIndexName(this.#keys)
+      : this.#name
+
+    return {
+      name: name as AutoIndexName<Name, Keys> & string,
+      keys: this.#keys,
+      replicate: this.#replicate,
+      roots
+    }
+  }
+}
+
+type ReplaceDotsWithUnderscores<S extends string> =
+  S extends `${infer Head}.${infer Tail}`
+    ? `${Head}_${ReplaceDotsWithUnderscores<Tail>}`
+    : S
+
+type KeyToNameSegment<K extends string> =
+  K extends `...${infer Rest}`
+    ? `multi_${ReplaceDotsWithUnderscores<Rest>}`
+    : ReplaceDotsWithUnderscores<K>
+
+type JoinWithUnderscore<T extends readonly string[]> =
+  T extends readonly [infer First extends string]
+    ? KeyToNameSegment<First>
+    : T extends readonly [infer First extends string, ...infer Rest extends readonly string[]]
+      ? `${KeyToNameSegment<First>}_${JoinWithUnderscore<Rest>}`
+      : ''
+
+type ComputedIndexName<Keys extends readonly string[]> =
+  `idx_${JoinWithUnderscore<Keys>}`
+
+type AutoIndexName<Name extends typeof autogen | string, Keys extends readonly string[]> =
+  Name extends typeof autogen
+  ? ComputedIndexName<Keys>
+  : Name
+
+function explodeIndexKey(key: string) {
+  const spread = key.startsWith('...')
+  const path   = key.slice(spread ? 3 : 0).split('.')
+  return {
+    spread, root: path[0], path
+  }
+}
+
+function computeIndexRoots(keys: readonly string[]): Set<string> {
+  const roots = new Set<string>()
+  for (const key of keys) {
+    const {spread, root} = explodeIndexKey(key)
+    if (spread && root) {
+      roots.add(root)
+    }
+  }
+
+  return roots
+}
+
+function computeIndexName<Keys extends readonly string[]>(keys: Keys): ComputedIndexName<Keys> {
+  const segments = keys.map((k: string) => k
+    .replaceAll('...', 'multi_')
+    .replaceAll('.', '_')
+  )
+
+  return `idx_${segments.join('_')}` as ComputedIndexName<Keys>
+}
+
+///////
+// fun types
+
+type Increment<N extends number> = [
+  1, 2, 3, 4, 5, 6, 7, 8, 9, 10,
+  11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
+  21, 22, 23, 24, 25, 26, 27, 28, 29, 30,
+  31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
+  41, 42, 43, 44, 45, 46, 47, 48, 49, 50,
+  51, 52, 53, 54, 55, 56, 57, 58, 59, 60,
+  61, 62, 63, 64, 65, 66, 67, 68, 69, 70,
+  71, 72, 73, 74, 75, 76, 77, 78, 79, 80,
+  81, 82, 83, 84, 85, 86, 87, 88, 89, 90,
+  91, 92, 93, 94, 95, 96, 97, 98, 99, 100
+][N]
+
+type UnusedKey<K extends string, T> =
+  K & (K extends keyof T ? never : K)
+
+type ExtantKey<K extends string, T> =
+  K & (K extends keyof T ? K : never)
+
+/** returns a path extended with a dot */
+type ExtendPath<Path extends string, Next extends string> = Path extends '' ? Next : `${Path}.${Next}`
+
+/** primitives that idb can index */
+export type Indexable = string | number | Date | boolean
+
+/** recursive path into an object. */
+export type IndexPath<T, Path extends string = '', Spread extends boolean = false> =
+  string & T extends Indexable
+    ? Spread extends true ? `...${Path}` : Path
+    : T extends Array<infer O>
+      ? IndexPath<O, Path, true>
+      : T extends Map<infer K, infer V>
+        ? | IndexPath<K, ExtendPath<Path, 'key'>, true>
+          | IndexPath<V, ExtendPath<Path, 'value'>, true>
+        : T extends object
+          ? {
+            [P in keyof T]:
+              IndexPath<
+                NonNullable<T[P]>, // strip null/undefined, as it's not part of the path
+                ExtendPath<Path, P & string>,
+                Spread
+              >
+            }[keyof T]
+          : never

src/lib/idbase/builder.ts

···
+/**
+ * Schema Builder DSL - Type Sketch
+ *
+ * This file sketches out the full DSL for defining versioned IndexedDB schemas
+ * with type-safe migrations. No implementation yet, just types and signatures.
+ */
+
+import type {IndexPath, ReplicablePath} from './schema'
+
+// =============================================================================
+// Core Type Definitions
+// =============================================================================
+
+/** Map of store names to their document types */
+type SchemaMap = Record<string, unknown>
+
+/** IDB-compatible primary key types */
+type ValidKey = string | number | Date | ArrayBufferView | ArrayBuffer | IDBValidKey[]
+
+// =============================================================================
+// Index Builder (reusing concepts from schema-index.ts)
+// =============================================================================
+
+type ReplaceDotsWithUnderscores<S extends string> =
+  S extends `${infer Head}.${infer Tail}`
+    ? `${Head}_${ReplaceDotsWithUnderscores<Tail>}`
+    : S
+
+type KeyToNameSegment<K extends string> =
+  K extends `...${infer Rest}`
+    ? `multi_${ReplaceDotsWithUnderscores<Rest>}`
+    : ReplaceDotsWithUnderscores<K>
+
+type JoinWithUnderscore<T extends readonly string[]> =
+  T extends readonly [infer First extends string]
+    ? KeyToNameSegment<First>
+    : T extends readonly [infer First extends string, ...infer Rest extends readonly string[]]
+      ? `${KeyToNameSegment<First>}_${JoinWithUnderscore<Rest>}`
+      : ''
+
+type ComputedIndexName<Keys extends readonly string[]> =
+  `idx_${JoinWithUnderscore<Keys>}`
+
+type AutoIndexName<Name extends string, Keys extends readonly string[]> =
+  Name extends '<unnamed>'
+  ? ComputedIndexName<Keys>
+  : Name
+
+function computeIndexName<Keys extends readonly string[]>(keys: Keys): ComputedIndexName<Keys> {
+  const segments = keys.map((k: string) => k
+    .replaceAll('...', 'multi_')
+    .replaceAll('.', '_')
+  )
+
+  return `idx_${segments.join('_')}` as ComputedIndexName<Keys>
+}
+
+function explodeKey(key: string) {
+  const spread = key.startsWith('...')
+  const path   = key.slice(spread ? 3 : 0).split('.')
+  return {
+    spread, root: path[0], path
+  }
+}
+
+function computeRoots(keys: readonly string[]): Set<string> {
+  const roots = new Set<string>()
+  for (const key of keys) {
+    const {spread, root} = explodeKey(key)
+    if (spread && root) {
+      roots.add(root)
+    }
+  }
+
+  return roots
+}
+
+//
+
+export interface IndexDef<
+  Row,
+  Name extends string = string,
+  Keys extends readonly string[] = readonly IndexPath<Row>[]
+> {
+  name: Name
+  keys: Keys
+  replicate: ReplicablePath<Row>[]
+  roots: Set<string>
+}
+
+export class IndexBuilder<
+  Row,
+  Name extends string = '<unnamed>',
+  Keys extends readonly IndexPath<Row>[] = []
+> {
+  declare __name: Name
+  declare __keys: Keys
+
+  #name?: Name
+  #keys?: Keys
+  #replicate?: ReplicablePath<Row>[]
+
+  constructor(name?: Name) {
+    this.#name = name
+  }
+
+  on<K extends readonly IndexPath<Row>[]>(...keys: K): IndexBuilder<Row, Name, K> {
+    this.#keys = keys as unknown as Keys
+    return this as unknown as IndexBuilder<Row, Name, K>
+  }
+
+  replicate(...keys: ReplicablePath<Row>[]): this {
+    this.#replicate = keys
+    return this
+  }
+
+  build(): IndexDef<Row, AutoIndexName<Name, Keys>, Keys> {
+    if (this.#keys === undefined)
+      throw new Error('no keys specified!')
+
+    const name = (this.#name ?? computeIndexName<Keys>(this.#keys)) as AutoIndexName<Name, Keys>
+    const roots = computeRoots(this.#keys)
+
+    return {
+      name,
+      keys: this.#keys,
+      replicate: this.#replicate ?? [],
+      roots
+    }
+  }
+}
+
+// =============================================================================
+// Store Builder (for new stores in addStore)
+// =============================================================================
+
+/**
+ * Indexes phantom type: a record from index name to its key paths tuple
+ * e.g. { idx_feedId_readAt: readonly ['feedId', 'readAt'], idx_multi_tags_tag: readonly ['...tags.tag'] }
+ */
+type StoreIndexesConstraint = Record<string, readonly string[]>
+
+/** Extract name from an IndexDef */
+type ExtractIndexName<T> = T extends IndexDef<any, infer N, any> ? N : never
+
+/** Extract keys from an IndexDef */
+type ExtractIndexKeys<T> = T extends IndexDef<any, any, infer K> ? K : never
+
+/** Build a record from a single index def */
+type IndexToRecord<T> = {
+  [K in ExtractIndexName<T>]: ExtractIndexKeys<T>
+}
+
+/** Recursively merge index records from a tuple */
+type MergeIndexRecords<T extends readonly unknown[]> = T extends readonly [infer First, ...infer Rest]
+  ? IndexToRecord<First> & MergeIndexRecords<Rest>
+  : {}
+
+/** Convert an array of index builders to a record */
+type IndexArrayToRecord<T extends readonly unknown[]> =
+  MergeIndexRecords<T> extends infer R ? {[K in keyof R]: R[K]} : never
+
+type CodecFns<Row, Doc> = {
+  encode: (value: Doc) => Row
+  decode: (value: Row) => Doc
+}
+
+export interface StoreDef<
+  Name extends string,
+  Doc,
+  Row = Doc,
+  Indexes extends StoreIndexesConstraint = StoreIndexesConstraint,
+> {
+  name: Name
+  pkey: IndexPath<Row> | IndexPath<Row>[]
+  indexes: IndexDef<Row, string, readonly string[]>[]
+  encode?: (value: Doc) => Row
+  decode?: (row: Row) => Doc
+
+  // phantom types for extraction
+  __row: Row
+  __doc: Doc
+  __indexes: Indexes
+}
+
+export class StoreBuilder<
+  Name extends string,
+  Doc,
+  Row = Doc,
+  Indexes extends StoreIndexesConstraint = {}
+> {
+  declare __doc: Doc
+  declare __row: Row
+  declare __indexes: Indexes
+
+  #name: Name
+  #pkey: IndexPath<Row> | IndexPath<Row>[]
+  #indexes?: IndexDef<Row>[]
+  #encoder?: (value: Doc) => Row
+  #decoder?: (value: Row) => Doc
+
+  constructor(name: Name, pkey: IndexPath<Row> | IndexPath<Row>[]) {
+    this.#name = name
+    this.#pkey = pkey
+  }
+
+  codec<R>(fns: CodecFns<R, Doc>) {
+    this.#encoder = fns.encode as any
+    this.#decoder = fns.decode as any
+
+    return this as unknown as StoreBuilder<Name, Doc, R, Indexes>
+  }
+
+  indexes<const T extends readonly IndexDef<Row>[]>(
+    fn: (maker: <N extends string = string>(name?: N) => IndexBuilder<Row, N, readonly []>) => T
+  ) {
+    const maker = <N extends string = string> (name?: N) => new IndexBuilder<Row, N>(name)
+    this.#indexes = fn(maker) as unknown as IndexDef<Row>[]
+
+    return this as unknown as StoreBuilder<Name, Doc, Row, IndexArrayToRecord<T>>
+  }
+
+  build(): StoreDef<Name, Doc, Row, Indexes> {
+    return {
+      name: this.#name,
+      pkey: this.#pkey,
+      indexes: this.#indexes ?? [],
+      encode: this.#encoder,
+      decode: this.#decoder,
+
+      __doc: undefined as unknown as Doc,
+      __row: undefined as unknown as Row,
+      __indexes: undefined as unknown as Indexes
+    }
+  }
+}
+
+// =============================================================================
+// Store Amender (for existing stores in mutateStore)
+// =============================================================================
+
+declare class StoreAmender<T, Row = T> {
+  /** Add an index to the store */
+  addIndex<N extends string, K extends readonly IndexPath<Row>[]>(
+    fn: (idx: IndexBuilder<Row, N, readonly []>) => IndexBuilder<Row, N, K>,
+  ): this
+
+  /** Drop an index by name */
+  dropIndex(name: string): this
+}
+
+// =============================================================================
+// Migration Transaction & Store
+// =============================================================================
+
+// TODO: replace with a specialization of the IDB ObjectStore
+
+/** A store handle during migration - reads return Old type, writes expect New type */
+interface MigrationStore<Old, New> {
+  get(key: ValidKey): Promise<Old | undefined>
+  getAll(): Promise<Old[]>
+  getAllKeys(): Promise<ValidKey[]>
+
+  put(value: New, key?: ValidKey): Promise<ValidKey>
+  add(value: New, key?: ValidKey): Promise<ValidKey>
+  delete(key: ValidKey): Promise<void>
+  clear(): Promise<void>
+
+  // Cursor iteration - yields old type, put expects new type
+  iterate(): AsyncIterable<{
+    key: ValidKey
+    value: Old
+    update(value: New): Promise<void>
+    delete(): Promise<void>
+  }>
+}
+
+/**
+ * Migration transaction type.
+ *
+ * - Schema: the current schema (types as they exist before this migration)
+ * - WriteOverrides: stores being migrated, mapping to their NEW type
+ *
+ * objectStore() returns MigrationStore<OldType, NewType> where:
+ * - OldType comes from Schema
+ * - NewType comes from WriteOverrides (or falls back to Schema if not overridden)
+ */
+type MigrationTx<Schema extends SchemaMap, WriteOverrides extends Partial<Schema> = {}> = {
+  objectStore<K extends keyof Schema & string>(
+    name: K,
+  ): MigrationStore<Schema[K], K extends keyof WriteOverrides ? WriteOverrides[K] : Schema[K]>
+}
+
+// =============================================================================
+// Version Builder
+// =============================================================================
+
+declare class VersionBuilder<Schema extends SchemaMap> {
+  /**
+   * Add a new store to the database.
+   * Only valid if the store doesn't already exist in the schema.
+   */
+  addStore<T, Name extends string>(
+    name: Name & (Name extends keyof Schema ? never : Name),
+    configure: (builder: StoreBuilder<T>) => StoreBuilder<T, any>,
+  ): VersionBuilder<Schema & {[K in Name]: T}>
+
+  /**
+   * Mutate an existing store (add/drop indexes).
+   * Only valid if the store already exists in the schema.
+   */
+  mutateStore<Name extends keyof Schema & string>(
+    name: Name,
+    configure: (amender: StoreAmender<Schema[Name]>) => StoreAmender<Schema[Name], any>,
+  ): VersionBuilder<Schema>
+
+  /**
+   * Drop a store from the database.
+   * Removes it from the schema, allowing re-creation with addStore.
+   */
+  dropStore<Name extends keyof Schema & string>(name: Name): VersionBuilder<Omit<Schema, Name>>
+
+  /**
+   * Run a data migration.
+   *
+   * WriteOverrides specifies which stores are being migrated and their NEW types.
+   * After this migration, those stores will have the new types in the schema.
+   *
+   * The migration function receives a transaction where:
+   * - Reads return the OLD type (from current schema)
+   * - Writes expect the NEW type (from WriteOverrides)
+   */
+  migrate<WriteOverrides extends Partial<Schema>>(
+    fn: (tx: MigrationTx<Schema, WriteOverrides>) => void | Promise<void>,
+  ): VersionBuilder<Omit<Schema, keyof WriteOverrides> & WriteOverrides>
+}
+
+// =============================================================================
+// Database Builder
+// =============================================================================
+
+declare class DatabaseBuilder<Schema extends SchemaMap = {}> {
+  /**
+   * Define a version of the database.
+   *
+   * Each version receives the schema from the previous version and can:
+   * - Add new stores
+   * - Mutate existing stores (add/drop indexes)
+   * - Drop stores
+   * - Run data migrations
+   *
+   * The returned schema becomes the input for the next version.
+   */
+  version<NewSchema extends SchemaMap>(
+    v: number,
+    fn: (vb: VersionBuilder<Schema>) => VersionBuilder<NewSchema>,
+  ): DatabaseBuilder<NewSchema>
+}
+
+// =============================================================================
+// Database Definition (output of the builder)
+// =============================================================================
+
+interface DatabaseDef<Schema extends SchemaMap> {
+  name: string
+  version: number
+  schema: Schema
+  // ... runtime stuff for opening, migrations, etc.
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+declare function db<Schema extends SchemaMap>(
+  name: string,
+  fn: (builder: DatabaseBuilder<{}>) => DatabaseBuilder<Schema>,
+): DatabaseDef<Schema>
+
+// =============================================================================
+// Example Usage
+// =============================================================================
+
+// --- Version 1 types ---
+type EntityV1 = {
+  id: string
+  name: string
+  createdAt: Date
+}
+
+type Feed = {
+  id: string
+  url: string
+  title: string
+}
+
+// --- Version 2 types ---
+type EntityV2 = {
+  id: string
+  name: string
+  createdAt: Date
+  updatedAt: Date // new field
+  tags: string[] // new field
+}
+
+// --- Version 3 types ---
+type EntityV3 = {
+  id: string
+  name: string
+  createdAt: number // changed from Date to timestamp
+  updatedAt: number // changed from Date to timestamp
+  tags: string[]
+}
+
+// --- Schema Definition ---
+const myDb = db('myapp', (builder) =>
+  builder
+    // Version 1: Initial schema
+    .version(1, (v) =>
+      v
+        .addStore<EntityV1>('entities', (s) =>
+          s.pkey('id').indexes((idx) => [idx().on('createdAt'), idx().on('name')]),
+        )
+        .addStore<Feed>('feeds', (s) => s.pkey('id').indexes((idx) => [idx().on('url').unique()])),
+    )
+
+    // Version 2: Add fields to Entity, add index
+    .version(2, (v) =>
+      v
+        .mutateStore('entities', (s) => s.addIndex((idx) => idx().on('...tags')))
+        .migrate<{entities: EntityV2}>(async (tx) => {
+          const store = tx.objectStore('entities')
+          // store.get() returns EntityV1
+          // store.put() expects EntityV2
+          for await (const cursor of store.iterate()) {
+            cursor.update({
+              ...cursor.value,
+              updatedAt: cursor.value.createdAt,
+              tags: [],
+            })
+          }
+        }),
+    )
+
+    // Version 3: Change Date to timestamp
+    .version(3, (v) =>
+      v.migrate<{entities: EntityV3}>(async (tx) => {
+        const store = tx.objectStore('entities')
+        // store.get() returns EntityV2
+        // store.put() expects EntityV3
+        for await (const cursor of store.iterate()) {
+          cursor.update({
+            ...cursor.value,
+            createdAt: cursor.value.createdAt.getTime(),
+            updatedAt: cursor.value.updatedAt.getTime(),
+          })
+        }
+      }),
+    )
+
+    // Version 4: Drop a store, recreate with different pkey
+    .version(4, (v) =>
+      v.dropStore('feeds').addStore<Feed>(
+        'feeds',
+        (s) => s.pkey('url'), // different primary key now
+      ),
+    ),
+)
+
+// =============================================================================
+// Type Tests (these will error until implementation exists)
+// =============================================================================
+
+// Once implemented, these should work:
+//
+// type _FinalSchema = typeof myDb.schema
+// type _Entities = _FinalSchema['entities']  // should be EntityV3
+// type _Feeds = _FinalSchema['feeds']        // should be Feed
+//
+// const _testEntity: _Entities = {
+//   id: '1',
+//   name: 'test',
+//   createdAt: 123456,  // number, not Date
+//   updatedAt: 123456,
+//   tags: ['a', 'b'],
+// }
+//
+// const _testFeed: _Feeds = {
+//   id: '1',
+//   url: 'https://example.com',
+//   title: 'Example',
+// }
+
+void myDb

src/lib/idbase/index.ts

···
+// hello

src/lib/idbase/schema-builder.ts

···
+import {
+  openDB,
+  type DBSchema,
+  type IDBPDatabase,
+  type IDBPTransaction,
+  type IndexNames,
+  type StoreNames,
+} from 'idb'
+import {IndexBuilder, type IndexDef} from './schema-index'
+
+type StringKeys<S> = keyof S & string
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Store Definition & Builder
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Indexes phantom type: a record from index name to its key paths tuple
+ * e.g. { idx_feedId_readAt: readonly ['feedId', 'readAt'], idx_multi_tags_tag: readonly ['...tags.tag'] }
+ */
+type IndexesConstraint = Record<string, readonly string[]>
+
+export interface StoreDef<
+  Name extends string,
+  Doc,
+  Row = Doc,
+  Indexes extends IndexesConstraint = IndexesConstraint,
+> {
+  name: Name
+  pkey: StringKeys<Row> | StringKeys<Row>[]
+  indexes: IndexDef<Row, string, readonly string[]>[]
+  encode?: (value: Doc) => Row
+  decode?: (row: Row) => Doc
+
+  // phantom types for extraction
+  __row: Row
+  __doc: Doc
+  __indexes: Indexes
+}
+
+/** Extract name from an IndexBuilder or IndexDef */
+type ExtractIndexName<T> =
+  T extends IndexBuilder<any, infer N, any> ? N : T extends IndexDef<any, infer N, any> ? N : never
+
+/** Extract keys from an IndexBuilder or IndexDef */
+type ExtractIndexKeys<T> =
+  T extends IndexBuilder<any, any, infer K> ? K : T extends IndexDef<any, any, infer K> ? K : never
+
+/** Build a record from a single index builder/def */
+type IndexToRecord<T> = {
+  [K in ExtractIndexName<T>]: ExtractIndexKeys<T>
+}
+
+/** Recursively merge index records from a tuple */
+type MergeIndexRecords<T extends readonly unknown[]> = T extends readonly [infer First, ...infer Rest]
+  ? IndexToRecord<First> & MergeIndexRecords<Rest>
+  : {}
+
+/** Convert an array of index builders to a record */
+type IndexArrayToRecord<T extends readonly unknown[]> =
+  MergeIndexRecords<T> extends infer R ? {[K in keyof R]: R[K]} : never
+
+/** Base type for IndexBuilder/IndexDef that allows any keys (used in constraints) */
+type AnyIndexBuilder<Row> = IndexBuilder<Row, string, readonly string[]>
+type AnyIndexDef<Row> = IndexDef<Row, string, readonly string[]>
+
+export class StoreBuilder<Name extends string, Doc, Row = Doc, Indexes extends IndexesConstraint = {}> {
+  readonly name: Name
+
+  declare __doc: Doc
+  declare __row: Row
+  declare __indexes: Indexes
+
+  #pkey: string | string[]
+  #indexes?: AnyIndexDef<Row>[]
+  #encoder?: (value: Doc) => Row
+  #decoder?: (row: Row) => Doc
+
+  constructor(name: Name, pkey: string | string[]) {
+    this.name = name
+    this.#pkey = pkey
+  }
+
+  codec<R>(fns: {encode: (value: Doc) => R; decode: (row: R) => Doc}): StoreBuilder<Name, Doc, R, {}> {
+    this.#encoder = fns.encode as any
+    this.#decoder = fns.decode as any
+    return this as unknown as StoreBuilder<Name, Doc, R, {}>
+  }
+
+  indexes<const T extends readonly (AnyIndexDef<Row> | AnyIndexBuilder<Row>)[]>(
+    cb: (maker: <N extends string = string>(name?: N) => IndexBuilder<Row, N, readonly []>) => T,
+  ): StoreBuilder<Name, Doc, Row, IndexArrayToRecord<T>> {
+    const defs = cb(<N extends string = string>(name?: N) => new IndexBuilder<Row, N, readonly []>(name)).map(
+      (v) => (v instanceof IndexBuilder ? v.build() : v) as AnyIndexDef<Row>,
+    )
+    this.#indexes = defs
+    return this as unknown as StoreBuilder<Name, Doc, Row, IndexArrayToRecord<T>>
+  }
+
+  build(): StoreDef<Name, Doc, Row, Indexes> {
+    return {
+      name: this.name,
+      pkey: this.#pkey as StringKeys<Row> | StringKeys<Row>[],
+      indexes: this.#indexes ?? [],
+      encode: this.#encoder,
+      decode: this.#decoder,
+      __doc: undefined as unknown as Doc,
+      __row: undefined as unknown as Row,
+      __indexes: undefined as unknown as Indexes,
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Database Definition
+// ─────────────────────────────────────────────────────────────────────────────
+
+type StoresConstraint = Record<string, StoreDef<string, any, any>>
+
+type SeedFn<Stores extends StoresConstraint> = (
+  tx: IDBPTransaction<ToDBSchema<Stores>, StoreNames<ToDBSchema<Stores>>[], 'versionchange'>,
+) => void
+
+type MigrationFn<Stores extends StoresConstraint> = (
+  tx: IDBPTransaction<ToDBSchema<Stores>, StoreNames<ToDBSchema<Stores>>[], 'versionchange'>,
+  oldVersion: number,
+  newVersion: number | null,
+) => void
+
+export interface DatabaseDef<Stores extends StoresConstraint> {
+  name: string
+  stores: Stores
+  seedFn?: SeedFn<Stores>
+  migrations: MigrationFn<Stores>[]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Path Resolution - convert index paths to their value types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Resolve a dot-path like "foo.bar" into its value type */
+type ResolvePath<T, Path extends string> = Path extends `${infer First}.${infer Rest}`
+  ? First extends keyof T
+    ? ResolvePath<NonNullable<T[First]>, Rest>
+    : never
+  : Path extends keyof T
+    ? T[Path]
+    : never
+
+/**
+ * Resolve a spread path like "...tags.tag" where tags is Tag[] and we want Tag['tag']
+ * Path format: "...arrayProp.nestedPath"
+ */
+type ResolveSpreadPath<Row, Path extends string> = Path extends `...${infer Rest}`
+  ? Rest extends `${infer ArrayProp}.${infer NestedPath}`
+    ? ArrayProp extends keyof Row
+      ? NonNullable<Row[ArrayProp]> extends Array<infer El>
+        ? ResolvePath<El, NestedPath>
+        : never
+      : never
+    : Rest extends keyof Row
+      ? NonNullable<Row[Rest]> extends Array<infer El>
+        ? El
+        : never
+      : never
+  : ResolvePath<Row, Path>
+
+/** Convert a single index key path to its runtime type (excludes undefined since it's not a valid IDBValidKey) */
+type PathToKeyType<Row, Path extends string> = NonNullable<
+  Path extends `...${string}` ? ResolveSpreadPath<Row, Path> : ResolvePath<Row, Path>
+>
+
+/** Convert a tuple of paths to a tuple of key types (preserves tuple structure) */
+type PathsToKeyTypes<Row, Paths extends readonly string[]> = Paths extends readonly [
+  infer First extends string,
+  ...infer Rest extends readonly string[],
+]
+  ? [PathToKeyType<Row, First>, ...PathsToKeyTypes<Row, Rest>]
+  : []
+
+/** Convert our __indexes phantom type to idb's indexes format */
+type IndexesToDBIndexes<Row, Indexes extends IndexesConstraint> = {
+  [Name in keyof Indexes]: Indexes[Name] extends readonly string[]
+    ? PathsToKeyTypes<Row, Indexes[Name]>
+    : never
+}
+
+// Convert our StoreDef types to idb's DBSchema format
+type ToDBSchema<Stores extends StoresConstraint> = {
+  [K in keyof Stores & string]: {
+    key: string
+    value: Stores[K]['__row']
+    indexes: IndexesToDBIndexes<Stores[K]['__row'], Stores[K]['__indexes']>
+  }
+}
+
+// The live database handle returned by open()
+export interface Database<Stores extends StoresConstraint> {
+  name: string
+  stores: Stores
+  idb: IDBPDatabase<ToDBSchema<Stores>>
+  close(): void
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Database Builder
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class DatabaseBuilder<Stores extends StoresConstraint = {}> {
+  readonly #name: string
+  readonly #storesList: StoreDef<string, any, any>[]
+  #seedFn?: SeedFn<Stores>
+  #migrations: MigrationFn<Stores>[] = []
+
+  constructor(name: string, stores: StoreDef<string, any, any>[] = []) {
+    this.#name = name
+    this.#storesList = stores
+  }
+
+  /**
+   * Add a store to the database.
+   * Usage: db.store<DocType>()('storeName', 'primaryKey', s => s.codec(...).indexes(...))
+   */
+  store<Doc>(): <Name extends string, Row = Doc, Indexes extends IndexesConstraint = {}>(
+    name: Name,
+    pkey: StringKeys<Doc> | StringKeys<Doc>[],
+    configure?: (builder: StoreBuilder<Name, Doc, Doc, {}>) => StoreBuilder<Name, Doc, Row, Indexes>,
+  ) => DatabaseBuilder<Stores & {[K in Name]: StoreDef<Name, Doc, Row, Indexes>}> {
+    return <Name extends string, Row = Doc, Indexes extends IndexesConstraint = {}>(
+      name: Name,
+      pkey: StringKeys<Doc> | StringKeys<Doc>[],
+      configure?: (builder: StoreBuilder<Name, Doc, Doc, {}>) => StoreBuilder<Name, Doc, Row, Indexes>,
+    ) => {
+      const builder = new StoreBuilder<Name, Doc, Doc, {}>(name, pkey)
+      const configured = configure ? configure(builder) : builder
+      const storeDef = configured.build()
+
+      this.#storesList.push(storeDef)
+      return this as unknown as DatabaseBuilder<Stores & {[K in Name]: StoreDef<Name, Doc, Row, Indexes>}>
+    }
+  }
+
+  seed(fn: SeedFn<Stores>): this {
+    this.#seedFn = fn
+    return this
+  }
+
+  migrate(fn: MigrationFn<Stores>): this {
+    this.#migrations.push(fn)
+    return this
+  }
+
+  build(): DatabaseDef<Stores> {
+    const stores: Record<string, StoreDef<string, any, any>> = {}
+    for (const def of this.#storesList) {
+      stores[def.name] = def
+    }
+    return {
+      name: this.#name,
+      stores: stores as Stores,
+      seedFn: this.#seedFn,
+      migrations: this.#migrations,
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Define a database schema.
+ * Returns a DatabaseDef that can be passed to open().
+ */
+export function define<Stores extends StoresConstraint>(
+  name: string,
+  cb: (db: DatabaseBuilder<{}>) => DatabaseBuilder<Stores>,
+): DatabaseDef<Stores> {
+  const builder = new DatabaseBuilder<{}>(name)
+  const configured = cb(builder)
+  return configured.build()
+}
+
+export interface MetaSchema extends DBSchema {
+  status: {
+    key: 'status'
+    value: {
+      version: number
+      applied: Date
+      schema: unknown
+    }
+  }
+}
+
+/**
+ * Open a database from a definition.
+ */
+export async function open<Stores extends StoresConstraint>(
+  def: DatabaseDef<Stores>,
+): Promise<Database<Stores>> {
+  const metadb = await openDB<MetaSchema>(`${def.name}-meta`, 1, {
+    upgrade(db, ov) {
+      console.log('upgrading metadb')
+      if (ov < 1) {
+        const store = db.createObjectStore('status')
+        store.put({version: 0, schema: undefined, applied: new Date()}, 'status')
+      }
+    },
+  })
+
+  console.log('upgrade metadb complete')
+  const current = await metadb.get('status', 'status')
+  if (!current) {
+    throw new Error('metadb upgrade never ran?')
+  }
+
+  let version = current.version
+  const schema = def.stores
+  if (version < 1 || current.schema != schema) {
+    version = version + 1
+  }
+
+  console.log('opening db', def, version)
+  const storedb = await openDB<ToDBSchema<Stores>>(def.name, version, {
+    upgrade(db, ov, nv, tx) {
+      try {
+        console.log('upgrading db', ov, nv)
+
+        // Create object stores if this is a fresh database
+        if (ov < 1) {
+          for (const key in def.stores) {
+            const store = def.stores[key]
+            db.createObjectStore(store.name as StoreNames<ToDBSchema<Stores>>, {keyPath: store.pkey})
+          }
+        }
+
+        // Create indexes (checking if they already exist)
+        for (const key in def.stores) {
+          const store = def.stores[key]
+          const table = tx.objectStore(store.name as StoreNames<ToDBSchema<Stores>>)
+          for (const idx of store.indexes) {
+            const idxname = idx.name as IndexNames<ToDBSchema<Stores>, StoreNames<ToDBSchema<Stores>>>
+            if (table.indexNames.contains(idxname)) {
+              continue // TODO: diff and rebuild
+            }
+
+            // TODO: this is wrong, should be getting index keys from row?
+            // strip "..." prefix from spread keys for IndexedDB
+            const keyPaths = idx.keys.map((k) => k.replace('...', 'multi_').replace('.', '_'))
+            console.log('creating index', idx.name, 'on', store.name, 'with keyPath', keyPaths)
+            table.createIndex(idxname, keyPaths)
+          }
+        }
+
+        if (ov < 1) {
+          console.log('running seed')
+          def.seedFn?.(tx)
+          console.log('seed complete')
+        }
+
+        console.log('running migrations from', ov, 'count:', def.migrations.slice(ov).length)
+        def.migrations.slice(ov).forEach((mig, i) => {
+          console.log('running migration', i + ov)
+          mig(tx, ov, nv)
+          console.log('migration', i + ov, 'complete')
+        })
+        console.log('upgrade complete')
+      } catch (e) {
+        console.error('error in upgrade', e)
+        throw e
+      }
+    },
+  })
+
+  console.log('we have database version:', storedb)
+
+  // TODO: implement the open logic
+  // 1. Probe current state
+  // 2. Compare schemas
+  // 3. Open with version bump if needed
+  // 4. Apply schema diff in onupgradeneeded
+  // 5. Run seed (if fresh) or migrations (if upgrade)
+  // 6. Save schema to _meta
+
+  return {
+    name: def.name,
+    stores: def.stores,
+    idb: null as any, // TODO: actual idb handle
+    close: () => {},
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Type Tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+type Feed = {
+  id: string
+  title: string
+  tags: {tag: string; value: string}[]
+}
+
+type Entry = {
+  id: string
+  readAt?: Date
+  feedId: string
+  tags: {tag: string; value: string}[]
+}
+
+const myDb = define('mydb', (db) =>
+  db
+    .store<Entry>()('entries', ['id', 'feedId'], (s) =>
+      s
+        .codec({
+          encode: (e) => ({...e, readAt: e.readAt?.getTime()}),
+          decode: (r) => ({...r, readAt: r.readAt ? new Date(r.readAt) : undefined}),
+        })
+        .indexes((idx) => [idx().on('feedId', 'readAt'), idx().on('...tags.tag')]),
+    )
+    .store<Feed>()('feeds', 'id', (s) => s.indexes((idx) => [idx().on('...tags.tag')]))
+    .seed((_tx) => {})
+    .migrate((_tx) => {}),
+)
+
+// Test type extraction
+type _TestStores = typeof myDb.stores
+type _TestEntries = _TestStores['entries']
+type _TestFeeds = _TestStores['feeds']
+type _TestEntryDoc = _TestEntries['__row']
+type _TestFeedDoc = _TestFeeds['__doc']
+
+// Should be EntryRow (with number) - will error if wrong
+const _e: _TestEntryDoc = {id: '1', feedId: 'f1', readAt: undefined, tags: []}
+void _e
+// Should be Feed - will error if wrong
+const _f: _TestFeedDoc = {id: '1', title: 'hi', tags: []}
+void _f
+
+// Negative test - should error if types are correct
+// @ts-expect-error - Entry doesn't have 'title'
+const _e2: _TestEntryDoc = {id: '1', title: 'wrong', tags: []}
+// @ts-expect-error - Feed doesn't have 'feedId'
+const _f2: _TestFeedDoc = {id: '1', feedId: 'wrong', tags: []}
+
+// Test open returns correct type
+void async function _testOpen() {
+  const db = await open(myDb)
+  // db.stores should have entries and feeds
+  const _entries: typeof db.stores.entries = db.stores.entries
+  void _entries
+  const _feeds: typeof db.stores.feeds = db.stores.feeds
+  void _feeds
+}
+
+// Test __indexes phantom type extraction
+type _TestEntryIndexes = _TestEntries['__indexes']
+type _TestFeedIndexes = _TestFeeds['__indexes']
+
+// Verify the index types are captured correctly
+// Entry should have: { idx_feedId_readAt: readonly ['feedId', 'readAt'], idx_multi_tags_tag: readonly ['...tags.tag'] }
+const _assertEntryIndex1: _TestEntryIndexes['idx_feedId_readAt'] = ['feedId', 'readAt'] as const
+const _assertEntryIndex2: _TestEntryIndexes['idx_multi_tags_tag'] = ['...tags.tag'] as const
+
+// Feed should have: { idx_multi_tags_tag: readonly ['...tags.tag'] }
+const _assertFeedIndex: _TestFeedIndexes['idx_multi_tags_tag'] = ['...tags.tag'] as const
+void [_assertEntryIndex1, _assertEntryIndex2, _assertFeedIndex]
+
+// Negative tests - these should error if types are correct
+// @ts-expect-error - wrong key order
+const _wrongOrder: _TestEntryIndexes['idx_feedId_readAt'] = ['readAt', 'feedId'] as const
+// @ts-expect-error - wrong key name
+const _wrongKey: _TestEntryIndexes['idx_feedId_readAt'] = ['feedId', 'wrongKey'] as const
+
+// Test DBSchema derivation - verify index key types are resolved
+type _TestDBSchema = ToDBSchema<typeof myDb.stores>
+type _TestEntriesDBSchema = _TestDBSchema['entries']
+type _TestEntriesIndexes = _TestEntriesDBSchema['indexes']
+
+// Direct test of PathsToKeyTypes with literal tuple
+type _DebugRow = _TestEntries['__row']
+type _DirectTest = PathsToKeyTypes<_DebugRow, readonly ['feedId', 'readAt']>
+
+// idx_feedId_readAt should resolve to [string, number | undefined]
+// idx_multi_tags_tag should resolve to [string]
+// But the actual types depend on whether the tuple literal is preserved through IndexesToDBIndexes
+
+// Use the direct test which should work - verifies path resolution logic is correct
+const _dbIndexKey1: _DirectTest = ['f1', 123]
+void _dbIndexKey1
+
+// Test that we can at least get the index names from the derived schema
+type _IndexNames = keyof _TestEntriesIndexes // should be 'idx_feedId_readAt' | 'idx_multi_tags_tag'
+const _indexName1: _IndexNames = 'idx_feedId_readAt'
+const _indexName2: _IndexNames = 'idx_multi_tags_tag'
+void [_indexName1, _indexName2]
+
+// Now test the full resolved key types from the DBSchema
+type _ResolvedIdx1 = _TestEntriesIndexes['idx_feedId_readAt'] // should be [string, number | undefined]
+type _ResolvedIdx2 = _TestEntriesIndexes['idx_multi_tags_tag'] // should be [string]
+
+// These should work if the types are correctly resolved
+const _resolvedKey1: _ResolvedIdx1 = ['feed123', 12345]
+const _resolvedKey2: _ResolvedIdx2 = ['mytag']
+void [_resolvedKey1, _resolvedKey2]
+
+// @ts-expect-error - wrong types should fail
+const _badResolvedKey1: _ResolvedIdx1 = [123, 'wrong']
+// @ts-expect-error - wrong tuple length
+const _badResolvedKey2: _ResolvedIdx2 = ['tag', 'extra']
+
+// Verify resolved types are tuples not unions
+// _ResolvedIdx1 should be [string, number | undefined], so [0] is string, [1] is number | undefined
+const _resolvedIdx1_0: _ResolvedIdx1[0] = 'test' // should be string
+const _resolvedIdx1_1: _ResolvedIdx1[1] = 123 // should be number | undefined
+// @ts-expect-error - [0] is string, not number
+const _badResolved1_0: _ResolvedIdx1[0] = 123
+// @ts-expect-error - [1] is number | undefined, not string
+const _badResolved1_1: _ResolvedIdx1[1] = 'wrong'
+void [_resolvedIdx1_0, _resolvedIdx1_1, _badResolved1_0, _badResolved1_1]
+
+// Debug: check actual structure of _TestEntryIndexes
+// If keys are tuples, these should work; if union, they'll be different
+const _debugIdx1: _TestEntryIndexes['idx_feedId_readAt'] = ['feedId', 'readAt']
+const _debugIdx1_0: _TestEntryIndexes['idx_feedId_readAt'][0] = 'feedId'
+const _debugIdx1_1: _TestEntryIndexes['idx_feedId_readAt'][1] = 'readAt'
+void [_debugIdx1, _debugIdx1_0, _debugIdx1_1]
+
+// This should fail if it's a proper tuple (not a union array)
+// @ts-expect-error - if tuple, index 0 should only be 'feedId', not 'readAt'
+const _debugBad: _TestEntryIndexes['idx_feedId_readAt'][0] = 'readAt'
+void _debugBad
+
+// Debug: what are the actual index names?
+type _DebugIndexNames = keyof _TestEntryIndexes
+const _debugName1: _DebugIndexNames = 'idx_feedId_readAt'
+// @ts-expect-error - should fail if names are literal
+const _debugBadName: _DebugIndexNames = 'wrong_name'
+void [_debugName1, _debugBadName]
+
+// Debug: check DBSchema index names
+type _DebugDBIndexNames = keyof _TestEntriesIndexes
+const _debugDBName1: _DebugDBIndexNames = 'idx_feedId_readAt'
+// @ts-expect-error - should fail if names are literal
+const _debugBadDBName: _DebugDBIndexNames = 'wrong_db_name'
+void [_debugDBName1, _debugBadDBName]

src/lib/idbase/schema-index.ts

···
+import type {IndexPath, ReplicablePath} from './schema'
+
+/** Replace all dots with underscores in a string */
+type ReplaceDotsWithUnderscores<S extends string> = S extends `${infer Head}.${infer Tail}`
+  ? `${Head}_${ReplaceDotsWithUnderscores<Tail>}`
+  : S
+
+/** Convert a key path to its index name segment (replace ... with multi_, and . with _) */
+type KeyToNameSegment<K extends string> = K extends `...${infer Rest}`
+  ? `multi_${ReplaceDotsWithUnderscores<Rest>}`
+  : ReplaceDotsWithUnderscores<K>
+
+/** Join segments with underscore */
+type JoinWithUnderscore<T extends readonly string[]> = T extends readonly [infer First extends string]
+  ? KeyToNameSegment<First>
+  : T extends readonly [infer First extends string, ...infer Rest extends readonly string[]]
+    ? `${KeyToNameSegment<First>}_${JoinWithUnderscore<Rest>}`
+    : ''
+
+/** Generate auto index name from keys */
+type AutoIndexName<Keys extends readonly string[]> = `idx_${JoinWithUnderscore<Keys>}`
+
+export interface IndexDef<
+  Row,
+  Name extends string = string,
+  Keys extends readonly string[] = readonly IndexPath<Row>[],
+> {
+  name: Name
+  keys: Keys
+  replicate: ReplicablePath<Row>[]
+  roots: Set<string>
+}
+
+//
+
+export class IndexBuilder<Proto, Name extends string = string, Keys extends readonly string[] = readonly []> {
+  #name?: Name
+  #keys?: Keys
+  #replicate?: ReplicablePath<Proto>[]
+
+  // Phantom types to extract Name and Keys
+  declare __name: Name
+  declare __keys: Keys
+
+  constructor(name?: Name) {
+    this.#name = name
+  }
+
+  /**
+   * Set the index keys. If no name was provided, the Name type will be derived from the keys.
+   */
+  on<K extends readonly IndexPath<Proto>[]>(
+    ...keys: K
+  ): IndexBuilder<Proto, Name extends string ? (string extends Name ? AutoIndexName<K> : Name) : Name, K> {
+    this.#keys = keys as unknown as Keys
+    return this as unknown as IndexBuilder<
+      Proto,
+      Name extends string ? (string extends Name ? AutoIndexName<K> : Name) : Name,
+      K
+    >
+  }
+
+  replicate(...keys: ReplicablePath<Proto>[]): this {
+    this.#replicate = keys
+    return this
+  }
+
+  #explodeRoot(key: string) {
+    const spread = key.startsWith('...')
+    if (spread) {
+      const path = key.slice(3).split('.')
+      return {
+        spread: true,
+        root: path[0],
+        path,
+      }
+    } else {
+      return {
+        spread: false,
+        root: null,
+        path: key.split('.'),
+      }
+    }
+  }
+
+  #computeRoots(keys: readonly string[]): Set<string> {
+    const roots = new Set<string>()
+    for (const key of keys) {
+      const {spread, root} = this.#explodeRoot(key)
+      if (spread && root) {
+        roots.add(root)
+      }
+    }
+
+    return roots
+  }
+
+  build(): IndexDef<Proto, Name, Keys> {
+    if (this.#keys === undefined) throw new Error('no keys specified')
+
+    const keys = this.#keys
+    const name = (this.#name ?? `idx_${keys.map((k) => k.replace('...', 'multi_')).join('_')}`) as Name
+
+    return {
+      name,
+      keys,
+      replicate: this.#replicate ?? [],
+      roots: this.#computeRoots(keys),
+    }
+  }
+}

src/lib/idbase/schema-mimetype.ts

···
+import {z} from 'zod/mini'
+
+export type MimeType = z.infer<typeof mimeTypeSchema>
+export const mimeTypeSchema = z.templateLiteral([z.string(), '/', z.string()])
+
+export type MimeTypeOutput<F extends MimeType> =
+  F extends `application/json`
+  ? unknown
+  : F extends `text/${string}`
+    ? string
+    : Uint8Array

src/lib/idbase/schema-store.ts

···
+// Re-export from schema-builder for backwards compatibility
+export type {StoreDef} from './schema-builder'
+export {StoreBuilder} from './schema-builder'

src/lib/idbase/schema.test.ts

···
+import {describe, it, expectTypeOf} from 'vitest'
+import type {DatabaseDefinition, IndexPath} from './schema'
+
+type Proto = {
+  id: string
+  title: string
+  optional?: string
+  meta: {
+    duration: number
+    authors: string[]
+  }
+  tags: {tag: string; value: string}[]
+  categories: Map<string, {category_id: string; title: string}>
+}
+
+type Indices = IndexPath<Proto>
+
+describe('IndexablePath', () => {
+  it('accepts valid scalar paths', () => {
+    expectTypeOf<'id'>().toExtend<Indices>()
+    expectTypeOf<'title'>().toExtend<Indices>()
+    expectTypeOf<'optional'>().toExtend<Indices>()
+  })
+
+  it('accepts valid nested paths', () => {
+    expectTypeOf<'meta.duration'>().toExtend<Indices>()
+  })
+
+  it('accepts spread paths for arrays', () => {
+    expectTypeOf<'...meta.authors'>().toExtend<Indices>()
+    expectTypeOf<'...tags.tag'>().toExtend<Indices>()
+    expectTypeOf<'...tags.value'>().toExtend<Indices>()
+  })
+
+  it('accepts spread paths for Map keys and values', () => {
+    expectTypeOf<'id'>().toExtend<Indices>()
+    expectTypeOf<'...categories.key'>().toExtend<Indices>()
+    expectTypeOf<'...categories.value.category_id'>().toExtend<Indices>()
+    expectTypeOf<'...categories.value.title'>().toExtend<Indices>()
+  })
+
+  it('rejects invalid paths', () => expectTypeOf<'hello'>().not.toExtend<Indices>())
+  it('rejects direct object access', () => expectTypeOf<'meta'>().not.toExtend<Indices>())
+  it('rejects direct index access', () => expectTypeOf<'tags'>().not.toExtend<Indices>())
+  it('rejects direct map access', () => expectTypeOf<'categories'>().not.toExtend<Indices>())
+  it('rejects direct map access', () => expectTypeOf<'categories.value'>().not.toExtend<Indices>())
+  it('rejects direct array access', () => expectTypeOf<'meta.authors'>().not.toExtend<Indices>())
+})

src/lib/idbase/schema.ts

···
+/** returns a path extended with a dot */
+type ExtendPath<Path extends string, Next extends string> = Path extends '' ? Next : `${Path}.${Next}`
+
+/** primitives that idb can index */
+export type Indexable = string | number | Date | boolean
+
+/** recursive path into an object. */
+export type IndexPath<T, Path extends string = '', Spread extends boolean = false> =
+  string & T extends Indexable
+    ? Spread extends true ? `...${Path}` : Path
+    : T extends Array<infer O>
+      ? IndexPath<O, Path, true>
+      : T extends Map<infer K, infer V>
+        ? | IndexPath<K, ExtendPath<Path, 'key'>, true>
+          | IndexPath<V, ExtendPath<Path, 'value'>, true>
+        : T extends object
+          ? {
+            [P in keyof T]:
+              IndexPath<
+                NonNullable<T[P]>, // strip null/undefined, as it's not part of the path
+                ExtendPath<Path, P & string>,
+                Spread
+              >
+            }[keyof T]
+          : never
+
+/** anything (including maybe recursing) */
+export type ReplicablePath<T> = IndexPath<T> | keyof T & string

src/lib/idbase/test-open.ts

···
+import 'fake-indexeddb/auto'
+import {define, open} from './schema-builder'
+
+type Feed = {
+  id: string
+  title: string
+  tags: {tag: string; value: string}[]
+}
+
+type Entry = {
+  id: string
+  readAt?: Date
+  feedId: string
+  tags: {tag: string; value: string}[]
+}
+
+const myDb = define('mydb', (db) =>
+  db
+    .store<Entry>()('entries', 'id', (s) =>
+      s
+        .codec({
+          encode: (e) => ({...e, readAt: e.readAt?.getTime()}),
+          decode: (r) => ({...r, readAt: r.readAt ? new Date(r.readAt) : undefined}),
+        })
+        .indexes((idx) => [idx().on('feedId', 'readAt'), idx().on('...tags.tag')]),
+    )
+    .store<Feed>()('feeds', 'id', (s) => s.indexes((idx) => [idx().on('...tags.tag')]))
+    .seed((tx) => {
+      const entriesStore = tx.objectStore('entries')
+      const feedsStore = tx.objectStore('feeds')
+
+      feedsStore.add({id: 'feed1', title: 'My Feed', tags: [{tag: 'tech', value: 'yes'}]})
+      entriesStore.add({id: 'entry1', feedId: 'feed1', readAt: Date.now(), tags: []})
+
+      console.log('Seeded database')
+    })
+    .migrate((tx, ov, nv) => {
+      const entriesStore = tx.objectStore('entries')
+      console.log('Running migration', ov, nv, entriesStore.name, entriesStore.indexNames, entriesStore.indexNames)
+    })
+    .migrate((tx, ov, nv) => {
+      const entriesStore = tx.objectStore('feeds')
+      console.log('Running a second migration', ov, nv, entriesStore.name, entriesStore.indexNames)
+    }),
+)
+
+async function main() {
+  console.log('Database definition:', myDb)
+  console.log('Stores:', Object.keys(myDb.stores))
+
+  for (const [name, store] of Object.entries(myDb.stores)) {
+    console.log(`Store "${name}":`, {
+      pkey: store.pkey,
+      indexes: store.indexes.map((i) => ({name: i.name, keys: i.keys})),
+    })
+  }
+
+  const db = await open(myDb)
+  console.log('Opened database:', db.name)
+
+  // Test transactions
+  // const tx = db.idb.transaction(['entries', 'feeds'], 'readonly')
+  // const entries = await tx.objectStore('entries').getAll()
+  // console.log('Entries:', entries)
+
+  db.close()
+}
+
+main().catch(console.error)

src/lib/idbase/type-utils.ts

···
+/** Replace all dots with underscores in a string */
+export type ReplaceDotsWithUnderscores<S extends string> = S extends `${infer Head}.${infer Tail}`
+  ? `${Head}_${ReplaceDotsWithUnderscores<Tail>}`
+  : S
+
+/** Convert a key path to its index name segment (replace ... with multi_, and . with _) */
+export type KeyToNameSegment<K extends string> = K extends `...${infer Rest}`
+  ? `multi_${ReplaceDotsWithUnderscores<Rest>}`
+  : ReplaceDotsWithUnderscores<K>
+
+/** Join segments with underscore */
+export type JoinWithUnderscore<T extends readonly string[]> = T extends readonly [infer First extends string]
+  ? KeyToNameSegment<First>
+  : T extends readonly [infer First extends string, ...infer Rest extends readonly string[]]
+    ? `${KeyToNameSegment<First>}_${JoinWithUnderscore<Rest>}`
+    : ''