oneie/one/things/tests/2-1-dataprovider-interface.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
title: 2 1 Dataprovider Interface
dimension: things
category: tests
tags: agent, ai, architecture, backend, frontend, ontology
related_dimensions: connections, events, groups, knowledge, people
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
  This document is part of the things dimension in the tests category.
  Location: one/things/tests/2-1-dataprovider-interface.md
  Purpose: Documents test specification: feature 2-1 - dataprovider interface & convexprovider
  Related dimensions: connections, events, groups, knowledge, people
  For AI agents: Read this to understand 2 1 dataprovider interface.
---

# Test Specification: Feature 2-1 - DataProvider Interface & ConvexProvider

**Feature ID:** `2-1-dataprovider-interface`
**Plan:** Backend-Agnostic Frontend Architecture
**Status:** Ready for Implementation
**Created:** 2025-10-13
**Quality Agent:** Claude (Intelligence Agent)

---

## Executive Summary

This document defines comprehensive tests for the DataProvider interface and ConvexProvider implementation BEFORE implementation begins. The tests validate that the backend abstraction layer correctly implements all 6 ontology dimensions while maintaining zero functionality regression from current Convex SDK usage.

**Success Criteria:**

- [ ] 90%+ unit test coverage
- [ ] 80%+ integration test coverage
- [ ] All 6-dimension operations fully tested
- [ ] Performance overhead <10ms per operation
- [ ] Zero TypeScript errors
- [ ] ConvexProvider passes all existing auth tests (50+)

---

## Test Categories

### Category 1: Interface Contract Tests (Unit)

Tests the DataProvider interface definition and type contracts.

### Category 2: ConvexProvider Tests (Unit)

Tests the ConvexProvider implementation wrapping Convex SDK.

### Category 3: Integration Tests

Tests full data flow through provider with real backend.

### Category 4: Performance Tests

Tests performance overhead of abstraction layer.

### Category 5: Error Handling Tests

Tests typed error patterns and edge cases.

### Category 6: Real-time Subscription Tests

Tests reactive data subscriptions through provider.

---

## Ontology Coverage Matrix

| Dimension     | CRUD Operations | Real-time | Auth | Multi-tenant |
| ------------- | --------------- | --------- | ---- | ------------ |
| Organizations | ✅              | ✅        | ✅   | ✅           |
| People        | ✅              | ✅        | ✅   | ✅           |
| Things        | ✅              | ✅        | ✅   | ✅           |
| Connections   | ✅              | ✅        | ✅   | ✅           |
| Events        | ✅              | ✅        | ✅   | ✅           |
| Knowledge     | ✅              | ✅        | ✅   | ✅           |

**Total Operations to Test:** 6 dimensions × 5 operations = 30+ test cases

---

## Category 1: Interface Contract Tests (Unit)

### 1.1 Type Safety Tests

**Test:** DataProvider interface type definitions

```typescript
describe("DataProvider Interface Types", () => {
  it("should define all 6-dimension operations", () => {
    // Verify interface has: organizations, people, things, connections, events, knowledge
  });

  it("should type all CRUD operations correctly", () => {
    // Verify get, list, create, update, delete signatures
  });

  it("should use Effect.ts for all operations", () => {
    // Verify return types are Effect<Success, Error, Never>
  });

  it("should define typed errors with _tag pattern", () => {
    // Verify ThingNotFoundError, CreateError, QueryError, etc.
  });
});
```

**Expected Behavior:**

- All operations return `Effect<T, E, never>`
- All errors extend base `DataProviderError` with `_tag` field
- Type cycle works correctly (no `any` types)
- Autocomplete works in IDE

**Performance:** N/A (type-only)
**Coverage Target:** 100%

---

### 1.2 Organizations Dimension Tests

**Test Suite:** Organizations CRUD

```typescript
describe("DataProvider.organizations", () => {
  it("should get organization by id", async () => {
    // Test: provider.organizations.get(orgId)
    // Expected: Returns organization or ThingNotFoundError
  });

  it("should list organizations with filters", async () => {
    // Test: provider.organizations.list({ plan: "pro" })
    // Expected: Returns filtered array
  });

  it("should create organization", async () => {
    // Test: provider.organizations.create({ name, plan })
    // Expected: Returns organization id
  });

  it("should update organization", async () => {
    // Test: provider.organizations.update(id, { plan: "enterprise" })
    // Expected: Updates successfully
  });

  it("should enforce multi-tenant isolation", async () => {
    // Test: Org A cannot access Org B's data
    // Expected: Returns empty or error
  });
});
```

**Expected Behavior:**

- Organizations table correctly mapped to `things` with `type: "organization"`
- Multi-tenant filtering automatic
- Plan validation (starter/pro/enterprise)
- Usage tracking accurate

**Performance:** <10ms per operation
**Coverage Target:** 95%

---

### 1.3 People Dimension Tests

**Test Suite:** People CRUD & Roles

```typescript
describe("DataProvider.people", () => {
  it("should get person by id", async () => {
    // Test: provider.people.get(personId)
    // Expected: Returns person with role
  });

  it("should list people by role", async () => {
    // Test: provider.people.list({ role: "org_owner" })
    // Expected: Returns filtered by role
  });

  it("should list people by organization", async () => {
    // Test: provider.people.list({ organizationId })
    // Expected: Returns org members only
  });

  it("should enforce 4 roles: platform_owner, org_owner, org_user, customer", () => {
    // Test: Role validation
    // Expected: Rejects invalid roles
  });

  it("should link people to organizations via connections", async () => {
    // Test: provider.connections.create({ person → org, type: "member_of" })
    // Expected: Creates membership connection
  });
});
```

**Expected Behavior:**

- People represented as `things` with `type: "creator"` and `properties.role`
- Role validation strict (4 roles only)
- Organization membership via `connections`
- Authorization checks included

**Performance:** <10ms per operation
**Coverage Target:** 95%

---

### 1.4 Things Dimension Tests

**Test Suite:** Things CRUD for all 66 types

```typescript
describe("DataProvider.things", () => {
  it("should create thing with correct type", async () => {
    // Test: provider.things.create({ type: "blog_post", name, properties })
    // Expected: Returns thing id
  });

  it("should get thing by id", async () => {
    // Test: provider.things.get(thingId)
    // Expected: Returns thing or ThingNotFoundError
  });

  it("should list things by type", async () => {
    // Test: provider.things.list({ type: "course" })
    // Expected: Returns all courses
  });

  it("should list things by status", async () => {
    // Test: provider.things.list({ status: "published" })
    // Expected: Returns published things only
  });

  it("should update thing properties", async () => {
    // Test: provider.things.update(id, { properties: {...} })
    // Expected: Merges properties correctly
  });

  it("should soft delete thing (set deletedAt)", async () => {
    // Test: provider.things.delete(id)
    // Expected: Sets deletedAt timestamp
  });

  it("should support all 66 thing types", async () => {
    // Test: Create one of each type
    // Expected: All types validate correctly
  });

  it("should validate thing type enum", () => {
    // Test: Invalid type rejected
    // Expected: ThingTypeError
  });
});
```

**Expected Behavior:**

- All 66 thing types supported
- Type validation strict
- Properties flexible (any JSON)
- Status lifecycle: draft → active → published → archived
- Soft delete (deletedAt)

**Performance:** <10ms per operation
**Coverage Target:** 90%

---

### 1.5 Connections Dimension Tests

**Test Suite:** Connections CRUD for all 25 types

```typescript
describe("DataProvider.connections", () => {
  it("should create connection between things", async () => {
    // Test: provider.connections.create({ fromThingId, toThingId, relationshipType: "owns" })
    // Expected: Returns connection id
  });

  it("should get connection by id", async () => {
    // Test: provider.connections.get(connectionId)
    // Expected: Returns connection or NotFoundError
  });

  it("should list connections from a thing", async () => {
    // Test: provider.connections.list({ fromThingId })
    // Expected: Returns all outgoing connections
  });

  it("should list connections to a thing", async () => {
    // Test: provider.connections.list({ toThingId })
    // Expected: Returns all incoming connections
  });

  it("should list connections by type", async () => {
    // Test: provider.connections.list({ relationshipType: "authored" })
    // Expected: Returns filtered connections
  });

  it("should delete connection", async () => {
    // Test: provider.connections.delete(connectionId)
    // Expected: Removes connection
  });

  it("should support metadata on connections", async () => {
    // Test: Create connection with metadata: { balance: 100 }
    // Expected: Metadata stored correctly
  });

  it("should support temporal validity (validFrom/validTo)", async () => {
    // Test: Create connection with validFrom, validTo
    // Expected: Timestamps stored
  });

  it("should support all 25 relationship types", async () => {
    // Test: Create one of each type
    // Expected: All types validate correctly
  });

  it("should prevent self-connections (unless justified)", () => {
    // Test: fromThingId === toThingId
    // Expected: SelfConnectionError (or allow with justification)
  });
});
```

**Expected Behavior:**

- All 25 connection types supported
- Bidirectional queries efficient (indexes)
- Metadata flexible (JSON)
- Temporal validity optional
- Self-connections validated

**Performance:** <10ms per operation
**Coverage Target:** 90%

---

### 1.6 Events Dimension Tests

**Test Suite:** Events CRUD for all 67 types

```typescript
describe("DataProvider.events", () => {
  it("should create event with actor and target", async () => {
    // Test: provider.events.create({ type: "entity_created", actorId, targetId })
    // Expected: Returns event id
  });

  it("should get event by id", async () => {
    // Test: provider.events.get(eventId)
    // Expected: Returns event or NotFoundError
  });

  it("should list events by type", async () => {
    // Test: provider.events.list({ type: "payment_event" })
    // Expected: Returns filtered events
  });

  it("should list events by actor", async () => {
    // Test: provider.events.list({ actorId })
    // Expected: Returns user's actions
  });

  it("should list events by target", async () => {
    // Test: provider.events.list({ targetId })
    // Expected: Returns events affecting target
  });

  it("should list events with time range", async () => {
    // Test: provider.events.list({ startTime, endTime })
    // Expected: Returns events in range
  });

  it("should store metadata with events", async () => {
    // Test: Create event with metadata: { amount: 100, currency: "USD" }
    // Expected: Metadata stored correctly
  });

  it("should support all 67 event types", async () => {
    // Test: Create one of each type
    // Expected: All types validate correctly
  });

  it("should auto-set timestamp if not provided", () => {
    // Test: Create event without timestamp
    // Expected: Timestamp = Date.now()
  });
});
```

**Expected Behavior:**

- All 67 event types supported
- Timestamps immutable
- Metadata flexible (JSON)
- Complete audit trail
- Efficient queries by actor/target/type/time

**Performance:** <10ms per operation
**Coverage Target:** 90%

---

### 1.7 Knowledge Dimension Tests

**Test Suite:** Knowledge CRUD & RAG

```typescript
describe("DataProvider.knowledge", () => {
  it("should create knowledge item (label)", async () => {
    // Test: provider.knowledge.create({ knowledgeType: "label", text: "industry:fitness" })
    // Expected: Returns knowledge id
  });

  it("should create knowledge item (chunk with embedding)", async () => {
    // Test: provider.knowledge.create({ knowledgeType: "chunk", text, embedding })
    // Expected: Returns knowledge id
  });

  it("should get knowledge by id", async () => {
    // Test: provider.knowledge.get(knowledgeId)
    // Expected: Returns knowledge or NotFoundError
  });

  it("should list knowledge by type", async () => {
    // Test: provider.knowledge.list({ knowledgeType: "label" })
    // Expected: Returns labels only
  });

  it("should link knowledge to thing", async () => {
    // Test: provider.knowledge.link(thingId, knowledgeId, "label")
    // Expected: Creates thingKnowledge junction
  });

  it("should search by embedding (vector search)", async () => {
    // Test: provider.knowledge.search(embedding, { limit: 10 })
    // Expected: Returns similar chunks
  });

  it("should filter search by source thing", async () => {
    // Test: provider.knowledge.search(embedding, { sourceThingId })
    // Expected: Returns chunks from source only
  });

  it("should support 4 knowledge types: label, document, chunk, vector_only", () => {
    // Test: Create each type
    // Expected: All types validate
  });
});
```

**Expected Behavior:**

- All 4 knowledge types supported
- Vector search efficient (ANN)
- Junction table (thingKnowledge) managed
- Embeddings stored correctly
- Labels searchable

**Performance:** <50ms for vector search, <10ms for others
**Coverage Target:** 85%

---

## Category 2: ConvexProvider Tests (Unit)

### 2.1 ConvexProvider Implementation Tests

**Test Suite:** ConvexProvider wraps Convex SDK correctly

```typescript
describe("ConvexProvider", () => {
  it("should implement DataProvider interface", () => {
    // Test: ConvexProvider satisfies DataProvider type
    // Expected: TypeScript compiles
  });

  it("should wrap Convex queries correctly", async () => {
    // Test: provider.things.get() calls convex.query(api.queries.things.get)
    // Expected: Correct API call
  });

  it("should wrap Convex mutations correctly", async () => {
    // Test: provider.things.create() calls convex.mutation(api.mutations.things.create)
    // Expected: Correct API call
  });

  it("should convert Convex errors to DataProvider errors", async () => {
    // Test: Convex error → typed DataProviderError
    // Expected: Error has _tag field
  });

  it("should pass auth context to Convex", async () => {
    // Test: Auth token passed to Convex client
    // Expected: Authenticated requests
  });

  it("should support real-time subscriptions", async () => {
    // Test: useQuery hook through provider
    // Expected: Reactive updates
  });
});
```

**Expected Behavior:**

- Zero functionality regression
- All existing Convex queries work
- All existing Convex mutations work
- Error mapping correct
- Auth works identically

**Performance:** <10ms overhead per operation
**Coverage Target:** 95%

---

### 2.2 ConvexProvider Auth Integration Tests

**Test Suite:** Auth flows through ConvexProvider

```typescript
describe("ConvexProvider Auth", () => {
  it("should pass all 50+ existing auth tests", async () => {
    // Test: Run entire auth test suite with ConvexProvider
    // Expected: All tests pass
  });

  it("should support email/password auth", async () => {
    // Test: Sign up, sign in through provider
    // Expected: Works identically to direct Convex
  });

  it("should support OAuth (GitHub, Google)", async () => {
    // Test: OAuth flow through provider
    // Expected: Works identically to direct Convex
  });

  it("should support magic links", async () => {
    // Test: Magic link flow through provider
    // Expected: Works identically to direct Convex
  });

  it("should support password reset", async () => {
    // Test: Password reset flow through provider
    // Expected: Works identically to direct Convex
  });

  it("should support email verification", async () => {
    // Test: Email verification flow through provider
    // Expected: Works identically to direct Convex
  });

  it("should support 2FA (TOTP)", async () => {
    // Test: 2FA flow through provider
    // Expected: Works identically to direct Convex
  });
});
```

**Expected Behavior:**

- All 50+ auth tests pass
- Zero regression in auth functionality
- Better Auth integration unchanged
- Session management identical

**Performance:** Same as baseline
**Coverage Target:** 100% (all existing tests)

---

## Category 3: Integration Tests

### 3.1 Full Data Flow Tests

**Test Suite:** Complete user journeys through provider

```typescript
describe("DataProvider Integration - Full Flows", () => {
  it("should complete user signup → create content → publish flow", async () => {
    // 1. Create user (people dimension)
    // 2. Create organization (organizations dimension)
    // 3. Create membership connection
    // 4. Create blog post (things dimension)
    // 5. Create ownership connection
    // 6. Log creation event
    // 7. Publish blog post
    // 8. Log publish event
    // Expected: Full flow works end-to-end
  });

  it("should complete token purchase flow", async () => {
    // 1. Get user
    // 2. Get token
    // 3. Create payment (things dimension)
    // 4. Create holds_tokens connection
    // 5. Log payment_event
    // 6. Update token balance
    // Expected: Full flow works end-to-end
  });

  it("should complete course enrollment flow", async () => {
    // 1. Get user
    // 2. Get course
    // 3. Create enrolled_in connection
    // 4. Log enrollment event
    // 5. Track progress
    // Expected: Full flow works end-to-end
  });
});
```

**Expected Behavior:**

- Multi-step flows work correctly
- Transactions atomic (if supported)
- Events logged completely
- Connections created correctly

**Performance:** <100ms for full flow
**Coverage Target:** 80%

---

### 3.2 Multi-Tenant Isolation Tests

**Test Suite:** Organization data isolation

```typescript
describe("DataProvider Integration - Multi-Tenant", () => {
  it("should isolate organization data", async () => {
    // 1. Create Org A with user A
    // 2. Create Org B with user B
    // 3. User A creates thing in Org A
    // 4. User B tries to access Org A's thing
    // Expected: User B cannot access Org A's data
  });

  it("should isolate organization events", async () => {
    // Test: Org A events not visible to Org B
    // Expected: Events filtered by organization
  });

  it("should isolate organization connections", async () => {
    // Test: Org A connections not visible to Org B
    // Expected: Connections filtered by organization
  });

  it("should allow platform_owner to access all orgs", async () => {
    // Test: Platform owner can query across orgs
    // Expected: No isolation for platform_owner role
  });
});
```

**Expected Behavior:**

- Perfect data isolation between orgs
- Platform owner has full access
- Org owners have org-level access
- Org users have limited access

**Performance:** <10ms per query (with proper indexes)
**Coverage Target:** 100% (critical security)

---

### 3.3 Real-time Subscription Tests

**Test Suite:** Reactive data updates

```typescript
describe("DataProvider Integration - Real-time", () => {
  it("should update when thing changes", async () => {
    // 1. Subscribe to thing via useQuery
    // 2. Update thing via mutation
    // 3. Verify subscription receives update
    // Expected: Reactive update received
  });

  it("should update when connection added", async () => {
    // 1. Subscribe to connections list
    // 2. Add new connection
    // 3. Verify subscription receives update
    // Expected: List updates automatically
  });

  it("should update when event logged", async () => {
    // 1. Subscribe to events list
    // 2. Log new event
    // 3. Verify subscription receives update
    // Expected: List updates automatically
  });

  it("should unsubscribe correctly", async () => {
    // Test: Component unmounts, subscription closes
    // Expected: No memory leaks
  });
});
```

**Expected Behavior:**

- Real-time updates work correctly
- Subscriptions clean up properly
- No memory leaks
- Performance maintained

**Performance:** <50ms latency for updates
**Coverage Target:** 85%

---

## Category 4: Performance Tests

### 4.1 Operation Performance Tests

**Test Suite:** Measure provider overhead

```typescript
describe("DataProvider Performance", () => {
  it("should add <10ms overhead for get operations", async () => {
    // Measure: Direct Convex vs. ConvexProvider
    // Expected: <10ms difference
  });

  it("should add <10ms overhead for list operations", async () => {
    // Measure: Direct Convex vs. ConvexProvider
    // Expected: <10ms difference
  });

  it("should add <10ms overhead for create operations", async () => {
    // Measure: Direct Convex vs. ConvexProvider
    // Expected: <10ms difference
  });

  it("should add <10ms overhead for update operations", async () => {
    // Measure: Direct Convex vs. ConvexProvider
    // Expected: <10ms difference
  });

  it("should add <10ms overhead for delete operations", async () => {
    // Measure: Direct Convex vs. ConvexProvider
    // Expected: <10ms difference
  });
});
```

**Performance Baseline (Direct Convex):**

- Get: ~5ms
- List: ~10ms
- Create: ~15ms
- Update: ~10ms
- Delete: ~8ms

**Performance Target (ConvexProvider):**

- Get: <15ms (<10ms overhead)
- List: <20ms (<10ms overhead)
- Create: <25ms (<10ms overhead)
- Update: <20ms (<10ms overhead)
- Delete: <18ms (<10ms overhead)

**Coverage Target:** 100% (all operations measured)

---

### 4.2 Large Dataset Performance Tests

**Test Suite:** Performance with scale

```typescript
describe("DataProvider Performance - Scale", () => {
  it("should list 1000 things efficiently", async () => {
    // Test: List 1000 things
    // Expected: <100ms
  });

  it("should list 1000 connections efficiently", async () => {
    // Test: List 1000 connections from a thing
    // Expected: <100ms
  });

  it("should list 1000 events efficiently", async () => {
    // Test: List 1000 events for a thing
    // Expected: <100ms
  });

  it("should handle 100 concurrent requests", async () => {
    // Test: 100 parallel operations
    // Expected: All complete, no errors
  });
});
```

**Performance Targets:**

- 1000 items: <100ms
- 10,000 items: <500ms
- 100 concurrent requests: <1000ms total

**Coverage Target:** 80%

---

## Category 5: Error Handling Tests

### 5.1 Typed Error Tests

**Test Suite:** Error handling patterns

```typescript
describe("DataProvider Error Handling", () => {
  it("should throw ThingNotFoundError for missing thing", async () => {
    // Test: Get non-existent thing
    // Expected: ThingNotFoundError with _tag
  });

  it("should throw CreateError on creation failure", async () => {
    // Test: Create thing with invalid data
    // Expected: CreateError with _tag and details
  });

  it("should throw QueryError on query failure", async () => {
    // Test: Query with invalid parameters
    // Expected: QueryError with _tag and details
  });

  it("should throw AuthError on auth failure", async () => {
    // Test: Unauthorized access
    // Expected: AuthError with _tag
  });

  it("should throw ValidationError on validation failure", async () => {
    // Test: Invalid input
    // Expected: ValidationError with _tag and field details
  });

  it("should provide error recovery via Effect.ts", async () => {
    // Test: Effect.catchTag for error handling
    // Expected: Graceful recovery
  });
});
```

**Expected Behavior:**

- All errors have `_tag` field
- Error messages descriptive
- Error types exported
- Effect.ts error handling works

**Coverage Target:** 95%

---

### 5.2 Edge Case Tests

**Test Suite:** Edge cases and failure modes

```typescript
describe("DataProvider Edge Cases", () => {
  it("should handle network failures gracefully", async () => {
    // Test: Simulate network failure
    // Expected: NetworkError thrown
  });

  it("should handle timeout errors", async () => {
    // Test: Operation exceeds timeout
    // Expected: TimeoutError thrown
  });

  it("should handle concurrent updates", async () => {
    // Test: Two updates to same thing
    // Expected: Last write wins or conflict error
  });

  it("should handle large payloads", async () => {
    // Test: Create thing with 1MB properties
    // Expected: Success or PayloadTooLargeError
  });

  it("should handle invalid types", async () => {
    // Test: Create thing with invalid type
    // Expected: ValidationError
  });

  it("should handle circular connections", async () => {
    // Test: A → B → A
    // Expected: Allowed (circular references valid)
  });
});
```

**Expected Behavior:**

- Graceful degradation
- Clear error messages
- No silent failures
- Proper cleanup

**Coverage Target:** 85%

---

## Category 6: Real-time Subscription Tests

### 6.1 React Hooks Tests

**Test Suite:** useQuery and useMutation hooks

```typescript
describe("DataProvider React Hooks", () => {
  it("should work with useQuery hook", async () => {
    // Test: const things = useQuery(provider.things.list, { type: "blog_post" })
    // Expected: Returns loading, data, error states
  });

  it("should work with useMutation hook", async () => {
    // Test: const create = useMutation(provider.things.create)
    // Expected: Returns loading, success, error states
  });

  it("should handle loading state correctly", async () => {
    // Test: useQuery returns undefined while loading
    // Expected: UI shows loading indicator
  });

  it("should handle error state correctly", async () => {
    // Test: useQuery returns error when query fails
    // Expected: UI shows error message
  });

  it("should refetch on parameter change", async () => {
    // Test: Change query parameters
    // Expected: New query triggered
  });
});
```

**Expected Behavior:**

- Hook API matches Convex hooks
- Loading states accurate
- Error states accurate
- Refetch works correctly

**Coverage Target:** 90%

---

## Test Infrastructure Requirements

### Required Test Utilities

1. **Mock DataProvider** (in-memory)
   - For unit tests
   - Fast execution
   - Predictable behavior

2. **Test Convex Deployment**
   - For integration tests
   - Real backend
   - Isolated test data

3. **Performance Benchmarking**
   - Measure operation times
   - Compare with baseline
   - Track over time

4. **Test Data Generators**
   - Create test organizations
   - Create test users
   - Create test things/connections/events

5. **Auth Test Helpers**
   - Sign up test users
   - Generate auth tokens
   - Clean up test data

### Test Environment Setup

```bash
# Backend test deployment
CONVEX_URL=https://test-deployment.convex.cloud
CONVEX_DEPLOYMENT=test:shocking-falcon-870

# Test database (separate from prod)
TEST_ORG_ID=test-org-123

# Performance monitoring
PERFORMANCE_BASELINE_FILE=./tests/performance/baseline.json
```

---

## Coverage Targets by Category

| Category           | Unit Coverage | Integration Coverage | Total Tests |
| ------------------ | ------------- | -------------------- | ----------- |
| Interface Contract | 95%           | N/A                  | 30+         |
| Organizations      | 95%           | 85%                  | 10+         |
| People             | 95%           | 85%                  | 12+         |
| Things             | 90%           | 80%                  | 20+         |
| Connections        | 90%           | 80%                  | 18+         |
| Events             | 90%           | 80%                  | 15+         |
| Knowledge          | 85%           | 75%                  | 12+         |
| ConvexProvider     | 95%           | 90%                  | 15+         |
| Integration Flows  | N/A           | 80%                  | 8+          |
| Performance        | 100%          | 80%                  | 15+         |
| Error Handling     | 95%           | 85%                  | 12+         |
| Real-time          | 90%           | 85%                  | 10+         |
| **TOTAL**          | **90%+**      | **80%+**             | **177+**    |

---

## Test Execution Plan

### Phase 1: Unit Tests (Day 1-2)

1. Interface contract tests (type-only)
2. Mock provider tests
3. Error handling tests
4. ConvexProvider implementation tests

**Goal:** 90%+ unit coverage

### Phase 2: Integration Tests (Day 3-4)

1. Full flow tests with real backend
2. Multi-tenant isolation tests
3. Auth integration tests (50+ existing)
4. Real-time subscription tests

**Goal:** 80%+ integration coverage

### Phase 3: Performance Tests (Day 5)

1. Operation overhead tests
2. Large dataset tests
3. Concurrent request tests
4. Establish baseline

**Goal:** <10ms overhead validated

### Phase 4: Edge Cases (Day 6-7)

1. Error scenarios
2. Network failures
3. Concurrent updates
4. Large payloads

**Goal:** All edge cases covered

---

## Acceptance Criteria

### Must Pass Before Approval

- [ ] All 177+ tests pass
- [ ] 90%+ unit test coverage achieved
- [ ] 80%+ integration test coverage achieved
- [ ] All 50+ existing auth tests pass (zero regression)
- [ ] Performance overhead <10ms per operation
- [ ] All 6 dimensions fully tested (organizations, people, things, connections, events, knowledge)
- [ ] All 66 thing types validated
- [ ] All 25 connection types validated
- [ ] All 67 event types validated
- [ ] Multi-tenant isolation verified
- [ ] Real-time subscriptions working
- [ ] Error handling comprehensive
- [ ] TypeScript compiles with zero errors
- [ ] Documentation complete

### Performance Benchmarks

| Operation     | Baseline (Convex) | Target (Provider) | Max Acceptable |
| ------------- | ----------------- | ----------------- | -------------- |
| Get           | 5ms               | 10ms              | 15ms           |
| List          | 10ms              | 15ms              | 20ms           |
| Create        | 15ms              | 20ms              | 25ms           |
| Update        | 10ms              | 15ms              | 20ms           |
| Delete        | 8ms               | 13ms              | 18ms           |
| Vector Search | 40ms              | 50ms              | 90ms           |

**If ANY operation exceeds max acceptable, feature is REJECTED.**

---

## Quality Gates

### Gate 1: Unit Tests (End of Day 2)

- [ ] All interface tests pass
- [ ] All mock provider tests pass
- [ ] 90%+ unit coverage
- [ ] Zero TypeScript errors

### Gate 2: Integration Tests (End of Day 4)

- [ ] All integration flows pass
- [ ] All 50+ auth tests pass
- [ ] 80%+ integration coverage
- [ ] Multi-tenant isolation verified

### Gate 3: Performance Tests (End of Day 5)

- [ ] All operations within acceptable range
- [ ] Baseline established
- [ ] Performance report generated

### Gate 4: Final Validation (End of Day 7)

- [ ] All 177+ tests pass
- [ ] All acceptance criteria met
- [ ] Documentation complete
- [ ] Ready for code review

---

## Test Failure Protocol

### If Tests Fail During Implementation

1. **STOP** - Do not proceed with implementation
2. **ANALYZE** - Identify root cause of failure
3. **EMIT EVENT** - Log `test_failed` event with details
4. **TRIGGER PROBLEM SOLVER** - Problem solver agent monitors test failures
5. **FIX** - Backend specialist fixes issue
6. **RETEST** - Run failed tests again
7. **VALIDATE** - Ensure fix doesn't break other tests

### Common Failure Modes

1. **Type Errors** - Interface contract violated
2. **Auth Regression** - Existing auth tests fail
3. **Performance Degradation** - Overhead exceeds 10ms
4. **Multi-tenant Leak** - Data isolation broken
5. **Connection Type Mismatch** - Wrong relationship types used

---

## Success Metrics

### Technical Quality

- **Test Coverage:** 90%+ unit, 80%+ integration
- **Performance:** <10ms overhead per operation
- **Type Safety:** 100% typed (no `any`)
- **Error Handling:** All errors have `_tag`
- **Regression:** Zero functionality loss

### Ontology Alignment

- **6 Dimensions:** All fully tested
- **66 Thing Types:** All validated
- **25 Connection Types:** All validated
- **67 Event Types:** All validated
- **Multi-tenant:** Perfect isolation

### Developer Experience

- **Hook API:** Matches Convex ergonomics
- **Error Messages:** Clear and actionable
- **Type Cycle:** Full autocomplete
- **Documentation:** Complete examples
- **Migration Path:** Straightforward

---

## Related Documents

- **Plan:** `/Users/toc/Server/ONE/one/things/plans/2-backend-agnostic-frontend.md`
- **Feature Spec:** `/Users/toc/Server/ONE/one/things/features/2-1-dataprovider-interface.md` (to be created)
- **Implementation:** `/Users/toc/Server/ONE/frontend/src/providers/`
- **Existing Tests:** `/Users/toc/Server/ONE/frontend/tests/auth/` (50+ auth tests)
- **Mock Provider:** `/Users/toc/Server/ONE/frontend/src/providers/__tests__/DataProvider.test.ts` (existing)

---

## Notes for Backend Specialist

**Context Budget:** This test spec is designed to fit within 2,000 token context when implementing.

**Key Points:**

1. Read this spec BEFORE writing any code
2. Implement tests BEFORE implementation (TDD)
3. Use existing test patterns from `/frontend/tests/auth/`
4. Use existing mock provider pattern from `/__tests__/DataProvider.test.ts`
5. Run tests continuously during implementation
6. Target: 90%+ unit, 80%+ integration coverage
7. Zero regression on auth tests (50+)

**Critical Success Factor:**
The DataProvider interface is the foundation for the entire backend-agnostic architecture. These tests MUST pass before proceeding to Features 2-2 through 2-7. Quality cannot be compromised.

---

**Test Specification Status:** ✅ Complete and Ready for Implementation
**Created:** 2025-10-13
**Validated By:** Quality Agent (Intelligence Agent)
**Approval Required From:** Engineering Director Agent
**Next Step:** Backend Specialist begins implementation with tests first (TDD)