npm package: @jordanranz/lattice-core
Description: Lattice: A domain-agnostic context and confidence engine. Transform raw signals into structured understanding with explicit confidence bounds.
Author: Jordan Ranz
Latest version: 0.1.0

# @lattice/core

A domain-agnostic context and confidence engine. Transform raw signals into structured understanding with explicit confidence bounds.

## Philosophy

**Context is a compiled artifact, not a prompt.** Lattice is infrastructure for building intelligent products—not a chatbot, not a product, but the substrate on which they can be built.

## Installation

```bash
npm install @lattice/core
```

## Core Concepts

Lattice operates on four core abstractions:

### Signals
Raw, timestamped observations from the external world. Schema-validated, immutable, with source provenance.

```typescript
import { Signal, signalId, subjectId } from '@lattice/core';

const signal: Signal<TransactionData, 'plaid'> = {
  id: signalId('sig_abc123'),
  subjectId: subjectId('user_456'),
  source: 'plaid',
  payload: { amount: 150.00, merchant: 'Grocery Store' },
  observedAt: new Date(),
  provenance: {
    sourceType: 'api',
    reliability: { trustLevel: 0.95, latencyMs: 120 },
    version: '2024-01'
  }
};
```

### Events
Semantic assertions derived from signals, produced by interpreters (deterministic rules or ML models).

```typescript
import { Event, eventId } from '@lattice/core';

const event: Event<GroceryPurchase, 'rule'> = {
  id: eventId('evt_def456'),
  type: 'grocery_purchase',
  payload: { category: 'groceries', amount: 150.00 },
  attribution: {
    signalRefs: [{ signalId: signal.id, contribution: 1.0 }],
    method: { type: 'rule', ruleId: 'categorize_merchant' },
    confidence: 0.98
  },
  temporalScope: {
    validFrom: new Date(),
    decayRate: 0.1
  },
  producedAt: new Date()
};
```

### Context Snapshots
Point-in-time compilations of beliefs, organized into orthogonal facets.

```typescript
import { ContextSnapshot, summarizeContext } from '@lattice/core';

// Snapshots contain facets like income_stability, expense_patterns, etc.
const summary = summarizeContext(snapshot);
// { overallConfidence: 0.82, facetCount: 5, eventCount: 47, ... }
```

### Confidence
Structured, multi-dimensional trust measurement—not a single number.

```typescript
import { createConfidence, confidenceLevel } from '@lattice/core';

const confidence = createConfidence({
  completeness: 0.85,
  recency: 0.92,
  consistency: 0.78,
  stability: 0.88
}, [
  { factor: 'missing_3_months_history', impact: -0.15, category: 'completeness' }
]);

confidenceLevel(confidence.overall); // 'high' | 'medium' | 'low' | 'insufficient'
```

## API Overview

### Signal Types
- `Signal<T, P>` - Core signal type
- `SignalId`, `SubjectId` - Branded ID types
- `signalId()`, `subjectId()`, `signalRef()` - Factory functions
- `isSignal()` - Type guard

### Event Types
- `Event<T, M>` - Core event type
- `EventId`, `EventAttribution`, `EventTemporalScope` - Supporting types
- `eventId()`, `eventRef()`, `calculateEventImpact()` - Factory functions
- `isEvent()` - Type guard

### Confidence Types
- `Confidence`, `ConfidenceScore`, `ConfidenceDimensions` - Core types
- `createConfidence()`, `aggregateConfidence()` - Building confidence
- `confidenceLevel()`, `detectConfidenceChange()` - Analysis
- `DEFAULT_CONFIDENCE_WEIGHTS`, `SIGNIFICANCE_THRESHOLD` - Constants

### Context Types
- `ContextSnapshot`, `Facet<T>`, `DerivedMetric<T>` - Core types
- `snapshotId()`, `facetType()` - Factory functions
- `summarizeContext()`, `isSnapshotStale()`, `identifyDataGaps()` - Analysis

## Design Principles

1. **Domain-agnostic core** - Lattice provides infrastructure; domain logic lives in adapters
2. **Explicit confidence** - Every assertion carries structured confidence metadata
3. **Determinism over models** - Prefer rule-based interpretation; models incur confidence penalties
4. **Full attribution** - Every event traces back to its source signals
5. **Temporal awareness** - Beliefs decay over time; staleness is explicit

## What Belongs in Lattice vs. Adapters

| In Lattice Core | In Domain Adapters |
|-----------------|-------------------|
| Signal ingestion | Domain-specific APIs (Plaid, Stripe) |
| Event production | Domain schemas and validation |
| Context compilation | Business logic and recommendations |
| Confidence computation | User interfaces |
| Query interfaces | Natural language generation |

## Documentation

See [ARCHITECTURE.md](./docs/architecture/ARCHITECTURE.md) for the complete design specification.

## License

Apache-2.0 - see [LICENSE](./LICENSE) for details.