dpth 0.3.0 → 0.4.0

package/README.md

@@ -1,198 +1,151 @@
 # dpth.io
 
 [![CI](https://github.com/rightclickable420/dpth/actions/workflows/ci.yml/badge.svg)](https://github.com/rightclickable420/dpth/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dpth)](https://www.npmjs.com/package/dpth)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-**The distributed intelligence layer.**
+**Your data is scattered. dpth connects it.**
 
-dpth.io is an open-source intelligence layer that turns every AI agent into infrastructure. Agents contribute storage, compute, and GPU power to the network — and in return, they get access to distributed inference, entity resolution, and cross-source pattern detection they couldn't build alone. Think BitTorrent economics meets AI: the more agents that join, the smarter and cheaper the network gets for everyone.
+dpth is a TypeScript library that resolves entities across APIs, detects cross-source patterns, and gives every data point a history. One `npm install`, zero dependencies, works anywhere Node runs.
 
-No single point of failure. No vendor lock-in. Zero infrastructure cost at scale.
-
-## Architecture
+## Install
 
-```
-┌─────────────────────────────────────────────────┐
-│                  Applications                    │
-│          (Fathom, your app, any client)          │
-├─────────────────────────────────────────────────┤
-│                   dpth.io                        │
-│  ┌───────────┐ ┌──────────┐ ┌────────────────┐  │
-│  │ Intelligence│ │ Inference │ │  Agent Network │  │
-│  │   Layer    │ │  Routing  │ │  (Contribute)  │  │
-│  └───────────┘ └──────────┘ └────────────────┘  │
-│  ┌───────────┐ ┌──────────┐ ┌────────────────┐  │
-│  │  Entity   │ │  Model   │ │   Reputation   │  │
-│  │Resolution │ │ Registry │ │   & Rewards    │  │
-│  └───────────┘ └──────────┘ └────────────────┘  │
-├─────────────────────────────────────────────────┤
-│              Agent Network (P2P)                 │
-│     Storage │ Compute │ GPU │ Verification      │
-└─────────────────────────────────────────────────┘
+```bash
+npm install dpth
 ```
 
-## Core Modules
+## Quick Start
 
-### Intelligence Layer
-- **Entity Resolution** — Unified identity across data sources with temporal history
-- **Correlation Engine** — Cross-source pattern detection and causality discovery
-- **Temporal Data** — Time-native storage where every value has history
-- **Semantic Search** — Embedding-based similarity across all data
+```typescript
+import { dpth } from 'dpth/dpth';
 
-### Agent Network
-- **Registration** — Agents join with cryptographic identity
-- **Contributions** — Storage, compute, and GPU resource sharing
-- **Reputation** — 5-tier system (newcomer → legendary) with earned privileges
-- **Rewards** — Intelligence access, priority, storage, and features based on contribution
-- **Storage Proofs** — Challenge-response verification that agents store what they claim
+const db = dpth();
 
-### Distributed Inference
-- **Model Registry** — Agents register available AI models with capabilities
-- **Smart Routing** — Reputation + performance + reliability scoring for request assignment
-- **Priority Queue** — Low/normal/high/critical priority with deadline support
-- **SSE Streaming** — Real-time token-by-token delivery via Server-Sent Events
-- **Centralized Fallback** — Transparent fallback to OpenAI/Anthropic/Groq/Together when no agents available
+// Entity resolution — same person in Stripe and GitHub? Merged automatically.
+await db.entity.resolve('person', 'John Smith', 'stripe', 'cus_123', {
+  email: 'john@company.com'
+});
+await db.entity.resolve('person', 'jsmith', 'github', 'jsmith-gh', {
+  email: 'john@company.com'
+});
+// ^ auto-merged — same entity, two sources
+
+// Temporal history — every value has a timeline
+await db.temporal.snapshot('dashboard', { revenue: 50000, users: 200 });
+await db.temporal.snapshot('dashboard', { revenue: 55000, users: 220 });
+const history = await db.temporal.history('dashboard');
+const diff = db.temporal.diff(history[0], history[1]);
+// { changed: [{ key: 'revenue', from: 50000, to: 55000 }, ...] }
+
+// Correlation — finds patterns you'd never think to look for
+await db.correlation.track('mrr', 50000);
+await db.correlation.track('deploys', 12);
+const patterns = await db.correlation.find('mrr');
+// "deploys correlates with mrr (r=0.87, 3-day lag)"
+```
 
-## Install
+## Add Persistence
 
-```bash
-npm install dpth
+```typescript
+// In-memory by default (great for testing, serverless, scripts)
+const db = dpth();
+
+// Add SQLite for persistence — survives restarts
+// npm install better-sqlite3
+import { SQLiteAdapter } from 'dpth/adapter-sqlite';
+import { configure } from 'dpth/storage';
+configure({ adapter: new SQLiteAdapter('./myapp.db') });
+
+// Add vector search — semantic similarity on top
+import { VectorOverlay } from 'dpth/adapter-vector';
+configure({ adapter: new VectorOverlay(new SQLiteAdapter('./myapp.db')) });
 ```
 
-The core library (entity resolution, correlation, temporal, embeddings, agent SDK, fallback) works standalone with zero dependencies. Next.js API routes for the full server are available in the [repo source](src/api/).
+## What You Get
 
-## Quick Start
+### Entity Resolution
+`john@company.com` in Stripe and `jsmith` on GitHub are the same person. dpth figures that out automatically — fuzzy name matching, email matching, alias tracking, confidence scoring.
 
-### As a Client
+### Temporal History
+Every value you store has a full timeline. Not just "revenue is $50K" but "$30K → $42K → $50K over 3 months" with automatic change detection and diffing.
 
-```typescript
-// Request inference from the network
-const response = await fetch('/api/dpth/inference', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    modelId: 'llama-3.3-70b',
-    input: {
-      messages: [{ role: 'user', content: 'Hello!' }]
-    },
-    params: { maxTokens: 1000, temperature: 0.7 }
-  })
-});
+### Cross-Source Correlation
+Revenue went up 20% the same month commits doubled? Your biggest customer just opened 3 support tickets? dpth finds these connections across any data sources you feed it. Pearson correlation, lag detection, anomaly alerts.
 
-// If agents are online → distributed processing
-// If no agents → automatic centralized fallback
-// Same API either way
-```
+### Content-Addressed Storage
+SHA-256 hashed chunks. Immutable, deduplicated, cache forever. Like git for your data.
 
-### Use the Core Library
+### Vector Search
+Semantic similarity built in. Works with any embedding model — store vectors, search by similarity, power smarter entity matching.
 
-```typescript
-import { resolveOrCreate, getEntitiesByType } from 'dpth/entity';
-import { registerMetric, addMetricPoints } from 'dpth/correlation';
-import { takeSnapshot, diffSnapshots } from 'dpth/temporal';
-
-// Entity resolution across sources
-const { entity, isNew } = resolveOrCreate('person', 'Jane Smith', 'github', 'jsmith');
-
-// Track metrics with correlation detection
-registerMetric({ id: 'mrr', entityId: entity.id, name: 'MRR', points: [], aggregation: 'sum' });
-addMetricPoints('mrr', [
-  { timestamp: new Date('2024-01'), value: 10000, source: 'stripe', confidence: 1 },
-  { timestamp: new Date('2024-02'), value: 12500, source: 'stripe', confidence: 1 },
-]);
-
-// Temporal snapshots with diffing
-takeSnapshot('dashboard-1', { revenue: 50000, users: 200 });
-// ...later...
-takeSnapshot('dashboard-1', { revenue: 62000, users: 245 });
-const diff = diffSnapshots(snapshots[0], snapshots[1]); // → changed: ['revenue', 'users']
+### Pluggable Storage
+Memory adapter (default, zero config) → SQLite adapter (persistence) → Vector overlay (semantic search). Or write your own — implement `StorageAdapter` for any backend.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│              Your Application                 │
+├──────────────────────────────────────────────┤
+│                  dpth()                       │
+│  entity    temporal    correlation    vector  │
+├──────────────────────────────────────────────┤
+│             Storage Adapter                   │
+│  Memory │ SQLite │ Vector │ Custom            │
+└──────────────────────────────────────────────┘
 ```
 
-### As an Agent
+## Module Exports
+
+| Import | What it does |
+|--------|-------------|
+| `dpth/dpth` | Unified API — `dpth()` factory, entity/temporal/correlation/vector |
+| `dpth/entity` | Standalone entity resolution |
+| `dpth/correlation` | Standalone correlation engine |
+| `dpth/temporal` | Standalone temporal storage |
+| `dpth/embed` | Embedding and similarity search |
+| `dpth/storage` | Adapter interface, `MemoryAdapter`, `configure()` |
+| `dpth/adapter-sqlite` | SQLite persistence adapter |
+| `dpth/adapter-vector` | Vector search adapter + overlay |
+| `dpth/agent-sdk` | Agent network participation |
+| `dpth/economics` | Credit earn/spend/transfer system |
+| `dpth/federation` | Federated learning coordination |
+| `dpth/fallback` | Centralized inference fallback |
+
+## Agent Network (Advanced)
+
+dpth also includes a protocol for distributed intelligence — agents contribute storage, compute, and GPU power, earn credits, and access shared inference. [See PROTOCOL.md](PROTOCOL.md) for the full spec.
 
 ```typescript
 import { DpthAgent } from 'dpth/agent-sdk';
 
 const agent = new DpthAgent({
   name: 'my-agent',
-  apiUrl: 'https://your-dpth-instance/api/dpth',
+  apiUrl: 'https://your-instance/api/dpth',
   capabilities: {
     storageCapacityMb: 10000,
     cpuCores: 8,
     hasGpu: true,
     gpuVramMb: 24576,
-    taskTypes: ['embed', 'inference', 'correlate']
+    taskTypes: ['embed', 'inference', 'train']
   }
 });
 
-// Register and start working
 await agent.register();
 await agent.startWorking();
 ```
 
-### Streaming Inference
+## Stats
 
-```typescript
-// Connect to SSE stream
-const eventSource = new EventSource(`/api/dpth/inference/stream?id=${requestId}`);
-
-eventSource.addEventListener('token', (e) => {
-  const { text } = JSON.parse(e.data);
-  process.stdout.write(text); // Real-time tokens
-});
-
-eventSource.addEventListener('done', (e) => {
-  const { stats } = JSON.parse(e.data);
-  console.log(`\n${stats.tokensPerSecond} tok/s`);
-});
-```
+- **15 modules** — entity, correlation, temporal, embed, storage, adapters, agent-sdk, economics, federation, fallback
+- **171 tests** — smoke, integration, API routes, adapters, unified API
+- **79KB** packed — zero production dependencies
+- **5 phases complete** — core → agents → inference → federation → economics
 
-## API Reference
+## Contributing
 
-| Endpoint | Description |
-|----------|-------------|
-| `POST /api/dpth/agents` | Register an agent |
-| `GET /api/dpth/agents` | List online agents |
-| `POST /api/dpth/tasks` | Submit/claim/complete tasks |
-| `POST /api/dpth/storage` | Store content-addressed data |
-| `GET /api/dpth/storage?cid=xxx` | Retrieve by CID |
-| `POST /api/dpth/contribute?type=storage\|compute\|gpu` | Record contributions |
-| `GET /api/dpth/reputation?agentId=xxx` | Get reputation & tier |
-| `GET /api/dpth/rewards?agentId=xxx` | Available rewards |
-| `POST /api/dpth/models` | Register a model |
-| `GET /api/dpth/models` | List available models |
-| `POST /api/dpth/inference` | Create inference request |
-| `GET /api/dpth/inference/stream?id=xxx` | SSE token stream |
-| `POST /api/dpth/proofs?action=challenge` | Storage verification |
-| `GET /api/dpth/status` | Network dashboard data |
-
-## Protocol
-
-See [PROTOCOL.md](src/lib/dpth/PROTOCOL.md) for the full protocol specification.
-
-## Economics
-
-dpth.io uses a contribution-based reward system:
-
-1. **Agents contribute** — storage, compute, GPU inference
-2. **Agents earn reputation** — 5 tiers with increasing privileges
-3. **Agents claim rewards** — intelligence queries, storage, priority, features
-4. **Network grows** — more agents = more capacity = better for everyone
-
-The architecture is designed to be tokenizable in the future without rebuilding — contribution scores map naturally to emission schedules. But for now, it's credits, not crypto.
-
-## Roadmap
-
-- [x] **Phase 1:** Core Infrastructure (entity, correlation, temporal, storage)
-- [x] **Phase 2:** Agent Network (contribution, reputation, rewards, GPU, proofs)
-- [x] **Phase 3:** Distributed Inference (model registry, routing, streaming, fallback)
-- [ ] **Phase 4:** Network Models (federated fine-tuning, weight distribution)
-- [ ] **Phase 5:** Economics (credit system, tokenization readiness)
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
 ## License
 
 MIT — see [LICENSE](LICENSE)
-
----
-
-*Built by humans and agents, working together.*

package/dist/adapter-sqlite.d.ts

@@ -36,14 +36,29 @@ export declare class SQLiteAdapter implements StorageAdapter {
     delete(collection: string, key: string): Promise<boolean>;
     has(collection: string, key: string): Promise<boolean>;
     query(filter: QueryFilter): Promise<unknown[]>;
+    /** Fallback query using JS filtering (for SQLite versions without json_extract) */
+    private queryFallback;
+    /** Escape a field name for use in json_extract path */
+    private escapeJsonPath;
     keys(collection: string): Promise<string[]>;
     count(collection: string): Promise<number>;
     clear(collection?: string): Promise<void>;
     close(): Promise<void>;
     /**
-     * Run a batch of operations in a transaction (SQLite-specific)
+     * Run a synchronous batch of operations in a transaction.
+     * NOTE: better-sqlite3 transactions are synchronous. The callback
+     * MUST be synchronous — async work will execute outside the transaction.
      */
-    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    transactionSync<T>(fn: () => T): T;
+    /**
+     * Bulk put — writes multiple key-value pairs in a single transaction.
+     * Much faster than individual put() calls for large imports.
+     */
+    putBatch(operations: Array<{
+        collection: string;
+        key: string;
+        value: unknown;
+    }>): Promise<void>;
     /**
      * Get database stats (SQLite-specific)
      */

package/dist/adapter-sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter-sqlite.d.ts","sourceRoot":"","sources":["../src/adapter-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAsBhE,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,IAAI,CAAiC;gBAEjC,UAAU,EAAE,MAAM,GAAG,oBAAoB;YASvC,IAAI;YAwBJ,WAAW;IAIzB,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;IAgBb,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAOlE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOzD,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOtD,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IA0D9C,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAO3C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO1C,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;OAEG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAMtD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CAsB1G"}
+{"version":3,"file":"adapter-sqlite.d.ts","sourceRoot":"","sources":["../src/adapter-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAsBhE,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,IAAI,CAAiC;gBAEjC,UAAU,EAAE,MAAM,GAAG,oBAAoB;YASvC,IAAI;YAqCJ,WAAW;IAIzB,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;IAgBb,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAOlE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOzD,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOtD,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IA0FpD,mFAAmF;IACnF,OAAO,CAAC,aAAa;IA+CrB,uDAAuD;IACvD,OAAO,CAAC,cAAc;IAKhB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAO3C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO1C,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;;;OAIG;IACH,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAKlC;;;OAGG;IACG,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrG;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CAsB1G"}

package/dist/adapter-sqlite.js

@@ -61,6 +61,19 @@ export class SQLiteAdapter {
       CREATE INDEX IF NOT EXISTS idx_dpth_collection ON dpth_store(collection);
       CREATE INDEX IF NOT EXISTS idx_dpth_updated ON dpth_store(collection, updated_at);
     `);
+        // Computed indexes on common JSON fields for fast entity queries
+        // json_extract requires SQLite 3.38+ (available since 2022)
+        try {
+            this.db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_dpth_type 
+          ON dpth_store(collection, json_extract(value, '$.type'));
+        CREATE INDEX IF NOT EXISTS idx_dpth_email 
+          ON dpth_store(collection, json_extract(value, '$.attributes.email.current'));
+      `);
+        }
+        catch {
+            // Older SQLite without json_extract — fall back to JS filtering
+        }
     }
     async ensureReady() {
         await this.ready;
@@ -124,26 +137,102 @@ export class SQLiteAdapter {
     }
     async query(filter) {
         await this.ensureReady();
-        // Get all items in collection, then filter in JS
-        // (JSON values can't be efficiently queried in SQL without json_extract)
+        // Build SQL query using json_extract for filtering
+        const params = [filter.collection];
+        const clauses = ['collection = ?'];
+        // Push where filters to SQL via json_extract
+        if (filter.where) {
+            for (const [field, value] of Object.entries(filter.where)) {
+                clauses.push(`json_extract(value, '$.${this.escapeJsonPath(field)}') = ?`);
+                params.push(value);
+            }
+        }
+        // Push comparison filters to SQL via json_extract
+        if (filter.compare) {
+            for (const cmp of filter.compare) {
+                const jsonPath = `json_extract(value, '$.${this.escapeJsonPath(cmp.field)}')`;
+                switch (cmp.op) {
+                    case 'gt':
+                        clauses.push(`${jsonPath} > ?`);
+                        params.push(cmp.value);
+                        break;
+                    case 'gte':
+                        clauses.push(`${jsonPath} >= ?`);
+                        params.push(cmp.value);
+                        break;
+                    case 'lt':
+                        clauses.push(`${jsonPath} < ?`);
+                        params.push(cmp.value);
+                        break;
+                    case 'lte':
+                        clauses.push(`${jsonPath} <= ?`);
+                        params.push(cmp.value);
+                        break;
+                    case 'ne':
+                        clauses.push(`${jsonPath} != ?`);
+                        params.push(cmp.value);
+                        break;
+                    case 'in': {
+                        const arr = cmp.value;
+                        if (arr.length > 0) {
+                            clauses.push(`${jsonPath} IN (${arr.map(() => '?').join(', ')})`);
+                            params.push(...arr);
+                        }
+                        else {
+                            clauses.push('0'); // empty IN → no results
+                        }
+                        break;
+                    }
+                    case 'contains':
+                        clauses.push(`${jsonPath} LIKE ?`);
+                        params.push(`%${cmp.value}%`);
+                        break;
+                }
+            }
+        }
+        // Build ORDER BY
+        let orderSql = '';
+        if (filter.orderBy) {
+            const dir = filter.orderBy.direction === 'desc' ? 'DESC' : 'ASC';
+            orderSql = ` ORDER BY json_extract(value, '$.${this.escapeJsonPath(filter.orderBy.field)}') ${dir}`;
+        }
+        // Build LIMIT/OFFSET
+        let limitSql = '';
+        if (filter.limit) {
+            limitSql += ` LIMIT ?`;
+            params.push(filter.limit);
+        }
+        if (filter.offset) {
+            if (!filter.limit) {
+                limitSql += ` LIMIT -1`; // SQLite requires LIMIT before OFFSET
+            }
+            limitSql += ` OFFSET ?`;
+            params.push(filter.offset);
+        }
+        const sql = `SELECT value FROM dpth_store WHERE ${clauses.join(' AND ')}${orderSql}${limitSql}`;
+        try {
+            const rows = this.db.prepare(sql).all(...params);
+            return rows.map(r => this.deserialize(r.value));
+        }
+        catch {
+            // Fallback: if json_extract not available (SQLite < 3.38), use JS filtering
+            return this.queryFallback(filter);
+        }
+    }
+    /** Fallback query using JS filtering (for SQLite versions without json_extract) */
+    queryFallback(filter) {
         const rows = this.stmt('SELECT value FROM dpth_store WHERE collection = ?')
             .all(filter.collection);
         let results = rows.map(r => this.deserialize(r.value));
-        // Apply where filters
         if (filter.where) {
             for (const [field, value] of Object.entries(filter.where)) {
-                results = results.filter(item => {
-                    const obj = item;
-                    return obj[field] === value;
-                });
+                results = results.filter(item => item[field] === value);
             }
         }
-        // Apply comparison filters
         if (filter.compare) {
             for (const cmp of filter.compare) {
                 results = results.filter(item => {
-                    const obj = item;
-                    const fieldVal = obj[cmp.field];
+                    const fieldVal = item[cmp.field];
                     switch (cmp.op) {
                         case 'gt': return fieldVal > cmp.value;
                         case 'gte': return fieldVal >= cmp.value;
@@ -157,7 +246,6 @@ export class SQLiteAdapter {
                 });
             }
         }
-        // Apply ordering
         if (filter.orderBy) {
             const { field, direction } = filter.orderBy;
             results.sort((a, b) => {
@@ -169,13 +257,17 @@ export class SQLiteAdapter {
                 return direction === 'asc' ? cmp : -cmp;
             });
         }
-        // Apply pagination
         if (filter.offset)
             results = results.slice(filter.offset);
         if (filter.limit)
             results = results.slice(0, filter.limit);
         return results;
     }
+    /** Escape a field name for use in json_extract path */
+    escapeJsonPath(field) {
+        // Prevent SQL injection in JSON path: only allow alphanumeric, dots, underscores
+        return field.replace(/[^a-zA-Z0-9._]/g, '');
+    }
     async keys(collection) {
         await this.ensureReady();
         const rows = this.stmt('SELECT key FROM dpth_store WHERE collection = ?')
@@ -203,13 +295,32 @@ export class SQLiteAdapter {
         this.db.close();
     }
     /**
-     * Run a batch of operations in a transaction (SQLite-specific)
+     * Run a synchronous batch of operations in a transaction.
+     * NOTE: better-sqlite3 transactions are synchronous. The callback
+     * MUST be synchronous — async work will execute outside the transaction.
      */
-    async transaction(fn) {
-        await this.ensureReady();
-        const tx = this.db.transaction(() => fn());
+    transactionSync(fn) {
+        const tx = this.db.transaction(fn);
         return tx();
     }
+    /**
+     * Bulk put — writes multiple key-value pairs in a single transaction.
+     * Much faster than individual put() calls for large imports.
+     */
+    async putBatch(operations) {
+        await this.ensureReady();
+        const insert = this.stmt(`
+      INSERT INTO dpth_store (collection, key, value, updated_at)
+      VALUES (?, ?, ?, unixepoch())
+      ON CONFLICT(collection, key)
+      DO UPDATE SET value = excluded.value, updated_at = unixepoch()
+    `);
+        this.transactionSync(() => {
+            for (const op of operations) {
+                insert.run(op.collection, op.key, this.serialize(op.value));
+            }
+        });
+    }
     /**
      * Get database stats (SQLite-specific)
      */

package/dist/adapter-sqlite.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter-sqlite.js","sourceRoot":"","sources":["../src/adapter-sqlite.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter-sqlite.js","sourceRoot":"","sources":["../src/adapter-sqlite.ts"],"names":[],"mappings":"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"}

package/dist/dpth.d.ts

@@ -33,6 +33,25 @@ export interface DpthOptions {
     /** Path to SQLite database (convenience — creates SQLiteAdapter) */
     path?: string;
 }
+/** Object-style options for entity.resolve() */
+export interface ResolveOptions {
+    /** Entity type (e.g. 'person', 'company', or any custom string) */
+    type: EntityType;
+    /** Display name */
+    name: string;
+    /** Source system identifier (e.g. 'stripe', 'github') */
+    source: SourceId;
+    /** External ID in the source system (e.g. 'cus_123') */
+    externalId: string;
+    /** Email for matching (strong signal) */
+    email?: string;
+    /** Alternative names / aliases */
+    aliases?: string[];
+    /** Additional attributes to store */
+    attributes?: Record<string, unknown>;
+    /** Minimum confidence for auto-merge (default: 0.7) */
+    minConfidence?: number;
+}
 export interface ResolveResult {
     entity: Entity;
     isNew: boolean;
@@ -89,7 +108,16 @@ export declare class Dpth {
 declare class EntityAPI {
     private adapter;
     constructor(adapter: StorageAdapter);
-    /** Resolve an entity — find existing match or create new */
+    /**
+     * Resolve an entity — find existing match or create new.
+     *
+     * Preferred (object form):
+     *   db.entity.resolve({ type: 'person', name: 'John', source: 'stripe', externalId: 'cus_123' })
+     *
+     * Legacy (positional form — deprecated, will be removed in v1.0):
+     *   db.entity.resolve('person', 'John', 'stripe', 'cus_123', { email: '...' })
+     */
+    resolve(opts: ResolveOptions): Promise<ResolveResult>;
     resolve(type: EntityType, name: string, sourceId: SourceId, externalId: string, options?: {
         email?: string;
         aliases?: string[];
@@ -108,6 +136,8 @@ declare class EntityAPI {
     merge(keepId: EntityId, mergeId: EntityId): Promise<Entity | undefined>;
     /** Count entities */
     count(type?: EntityType): Promise<number>;
+    /** Update the email index for an entity */
+    private updateEmailIndex;
     private findBestMatch;
     private fuzzyScore;
 }
@@ -117,7 +147,10 @@ declare class TemporalAPI {
     /** Take a snapshot of any data */
     snapshot<T = Record<string, unknown>>(key: string, data: T, source?: SourceId): Promise<SnapshotRecord<T>>;
     /** Get all snapshots for a key (ordered by time) */
-    history<T = Record<string, unknown>>(key: string): Promise<SnapshotRecord<T>[]>;
+    history<T = Record<string, unknown>>(key: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<SnapshotRecord<T>[]>;
     /** Get the latest snapshot for a key */
     latest<T = Record<string, unknown>>(key: string): Promise<SnapshotRecord<T> | undefined>;
     /** Get snapshot closest to a specific time */