npm package: @dcre/mesh
Description: DCRE Mesh - Triangulation-Free Communication Protocol
Author: Bradley Clonan
Latest version: 1.0.7

# DCRE Mesh

[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/Tests-150+-6E9F18.svg)](https://vitest.dev/)
[![Coverage](https://img.shields.io/badge/Coverage-95%25-brightgreen.svg)]()

**Triangulation-Free Communication Protocol** with **AI Workflow Governance** - A novel mesh networking system using lattice transforms for privacy-preserving, location-independent communication and deterministic AI inference verification.

## 🎯 What is DCRE?

DCRE (Dynamic Cellular Routing Evolution) is a communication protocol that achieves **triangulation-free** messaging and provides **deterministic verification** for AI workflows.

### Two Core Use Cases

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  1. PRIVACY-PRESERVING COMMUNICATION                                        │
│     Messages verified without revealing sender, receiver, or routing paths  │
├─────────────────────────────────────────────────────────────────────────────┤
│  2. AI WORKFLOW GOVERNANCE                                                  │
│     Tamper-evident audit trails for LLM inference with policy enforcement  │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Key Innovations

| Feature | Traditional | DCRE |
|---------|-------------|------|
| Message Identity | IP Address | Perturbation Hash |
| Verification | Trust/PKI | Lattice Replay |
| Routing | IP Tables | State Evolution |
| Privacy | TLS (transport) | Intrinsic (protocol) |
| AI Audit | Log Files | Lattice Fingerprints |
| Determinism | Hope | Cryptographic Proof |

## 📋 Table of Contents

- [Quick Start](#-quick-start)
- [Features](#-features)
- [Architecture](#-architecture)
- [Usage Guide](#-usage-guide)
- [API Reference](#-api-reference)
- [Deployment](#-deployment)
- [Performance](#-performance)
- [Testing](#-testing)

## 🚀 Quick Start

### Installation

```bash
npm install @dcre/mesh
```

### 30-Second Demo: Real-Time Sync

```typescript
import { DCREAdapter } from '@dcre/mesh';

// Create two clients
const alice = new DCREAdapter({ userId: 'alice' });
const bob = new DCREAdapter({ userId: 'bob' });

await alice.init();
await bob.init();

// Join same channel
await alice.joinChannel('chat-room');
await bob.joinChannel('chat-room');

// Alice sends, Bob receives
bob.on('message_received', ({ message }) => {
  console.log('Bob received:', message.content);
});

await alice.send('chat-room', 'Hello Bob!');
```

### 30-Second Demo: AI Governance

```typescript
import { AIGovernancePlugin, GovernancePresets } from '@dcre/mesh';

// Create governance with standard policies
const governance = new AIGovernancePlugin(GovernancePresets.standard());

// Wrap your AI calls
const result = await governance.wrapInference(
  { model: 'gpt-4', prompt: 'Explain quantum computing' },
  async (params) => {
    const response = await openai.chat.completions.create({
      model: params.model,
      messages: [{ role: 'user', content: params.prompt }]
    });
    return {
      response: response.choices[0].message.content,
      usage: { input: response.usage.prompt_tokens, output: response.usage.completion_tokens }
    };
  }
);

console.log('Response:', result.response);
console.log('Approved:', result.approved);
console.log('Cost:', result.cost);
console.log('Audit ID:', result.record.id);
```

## ✨ Features

### Core Protocol
- **Lattice State Machine** - Deterministic 2×2 block transforms with toroidal wrapping
- **Delta Compression** - Only state changes transmitted (~50-200 bytes per message)
- **Fingerprint Verification** - FNV-1a hash for instant state comparison
- **Multiple Transports** - WebSocket, WebRTC, BroadcastChannel

### Production Features
- **Binary Protocol** - MessagePack serialization (~30% smaller than JSON)
- **WASM Acceleration** - 10-100x faster lattice operations
- **E2E Encryption** - ECDH P-256 + AES-256-GCM
- **Zod Validation** - Runtime schema validation for all messages
- **Prometheus Metrics** - Full observability with `/metrics` endpoint
- **Audit Logging** - Structured JSONL logs with rotation

### AI Governance
- **Inference Tracking** - Record all AI calls with prompt/response hashing
- **Chain Tracking** - Link multi-step workflows (agent chains)
- **Policy Enforcement** - Content filters, token limits, rate limits
- **PII Detection** - Automatic detection of emails, phones, SSNs
- **Human-in-the-Loop** - Approval workflows for sensitive operations
- **Determinism Verification** - Detect model drift or non-deterministic outputs
- **Cost Tracking** - Per-model token pricing with budget limits
- **Framework Integrations** - OpenAI, Anthropic, LangChain wrappers

### Testing & Reliability
- **150+ Unit Tests** - Comprehensive test coverage
- **E2E Tests** - Playwright multi-client scenarios
- **Load Tests** - k6 scripts for 100k concurrent connections
- **Chaos Tests** - Network partition and failure simulation
- **Fuzz Tests** - 10k+ malformed input cases

## 🏗️ Architecture

### System Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           DCRE MESH ARCHITECTURE                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        APPLICATION LAYER                            │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐   │   │
│  │  │   React/Vue  │  │   Node.js    │  │    AI Governance       │   │   │
│  │  │   Frontend   │  │   Backend    │  │    Plugin              │   │   │
│  │  └──────────────┘  └──────────────┘  └────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│  ┌─────────────────────────────────┴───────────────────────────────────┐   │
│  │                         ADAPTER LAYER                                │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐   │   │
│  │  │ Encoding   │  │ Validation │  │ Encryption │  │  Binary    │   │   │
│  │  │ (content)  │  │ (Zod)      │  │ (AES-GCM)  │  │ (MsgPack)  │   │   │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘   │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐   │   │
│  │  │ Batching   │  │ Compress   │  │ Observer   │  │ Persistence│   │   │
│  │  │ (hi-freq)  │  │ (DEFLATE)  │  │ (debug)    │  │ (IndexedDB)│   │   │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│  ┌─────────────────────────────────┴───────────────────────────────────┐   │
│  │                          CORE LAYER                                  │   │
│  │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │   │
│  │  │     LATTICE      │  │     ROUTER       │  │    TRANSPORT     │  │   │
│  │  │                  │  │  (Bowling Alley) │  │                  │  │   │
│  │  │  • n×n Grid      │  │                  │  │  • WebSocket     │  │   │
│  │  │  • 2×2 Transform │  │  • Lane Routing  │  │  • WebRTC        │  │   │
│  │  │  • Fingerprint   │  │  • Wildcards     │  │  • Broadcast     │  │   │
│  │  │  • Delta Compute │  │  • Hash Routing  │  │  • Auto-reconnect│  │   │
│  │  └──────────────────┘  └──────────────────┘  └──────────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│  ┌─────────────────────────────────┴───────────────────────────────────┐   │
│  │                         SERVER LAYER                                 │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐   │   │
│  │  │ WebSocket  │  │ Redis      │  │ Metrics    │  │ Audit      │   │   │
│  │  │ Relay      │  │ Pub/Sub    │  │ Prometheus │  │ Logging    │   │   │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Lattice Transform (Core Algorithm)

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  LATTICE EVOLUTION: 2×2 Block Transform with Toroidal Wrapping             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Grid (n×n):              2×2 Block:          After Transform:              │
│  ┌───┬───┬───┬───┐        ┌───┬───┐          ┌───┬───┐                     │
│  │ 0 │ 1 │ 2 │ 3 │        │ a │ b │    ×     │ a'│ b'│                     │
│  ├───┼───┼───┼───┤        ├───┼───┤  Matrix  ├───┼───┤                     │
│  │ 4 │ 5 │ 6 │ 7 │        │ c │ d │    =     │ c'│ d'│                     │
│  ├───┼───┼───┼───┤        └───┴───┘          └───┴───┘                     │
│  │ 8 │ 9 │...│   │                                                          │
│  └───┴───┴───┴───┘        Matrix: [0,1,1,1]                                 │
│                                   [1,1,1,0]                                 │
│  Toroidal: edges wrap             [1,1,0,1]                                 │
│  around to opposite side          [1,0,1,1]                                 │
│                                                                             │
│  Properties:                                                                │
│  ✓ Deterministic: Same input → Same output (always)                        │
│  ✓ Reversible: Can compute any previous state                              │
│  ✓ Mixing: Single cell change propagates everywhere                        │
│  ✓ Verifiable: Fingerprint proves state authenticity                       │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Wire Protocol

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  WHAT GETS TRANSMITTED (Delta - NOT Content)                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Content (what you send):     Delta (what goes on wire):                    │
│  "Hello, this is a very       {                                             │
│   long message that could       "fromEpoch": 1234,                          │
│   be megabytes of data or       "toEpoch": 1235,                            │
│   even a video file..."         "changes": [{"r":3,"c":7,"v":42}],          │
│                                 "fingerprint": "a7b3c9d2"                   │
│  Size: ANY                    }                                             │
│                               Size: ~50-200 bytes (ALWAYS)                  │
│                                                                             │
│  The delta IS the message. Content is reconstructed from lattice state.    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### AI Governance Flow

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  AI INFERENCE GOVERNANCE PIPELINE                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐  │
│  │  User   │───▶│  Pre-   │───▶│  LLM    │───▶│  Post-  │───▶│ Record  │  │
│  │ Request │    │ Hooks   │    │  Call   │    │ Hooks   │    │ & Audit │  │
│  └─────────┘    └────┬────┘    └────┬────┘    └────┬────┘    └────┬────┘  │
│                      │              │              │              │         │
│                      ▼              ▼              ▼              ▼         │
│                 ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐  │
│                 │ Budget  │    │ Fallback│    │ Content │    │ Lattice │  │
│                 │ Check   │    │ Router  │    │ Filter  │    │ Update  │  │
│                 └─────────┘    └─────────┘    └────┬────┘    └─────────┘  │
│                                                    │                       │
│                                      ┌─────────────┴─────────────┐        │
│                                      ▼                           ▼        │
│                               ┌───────────┐               ┌───────────┐   │
│                               │  PASSED   │               │ VIOLATION │   │
│                               │ (approve) │               │ (block/   │   │
│                               └───────────┘               │  escalate)│   │
│                                                           └─────┬─────┘   │
│                                                                 │         │
│                                                           ┌─────▼─────┐   │
│                                                           │   HITL    │   │
│                                                           │  Approval │   │
│                                                           └───────────┘   │
│                                                                             │
│  All inferences recorded with:                                              │
│  • Prompt hash (SHA-256)                                                    │
│  • Response hash (SHA-256)                                                  │
│  • Lattice fingerprint (tamper-evident)                                     │
│  • Chain ID (multi-step tracking)                                           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Project Structure

```
dcre-mesh/
├── src/
│   ├── core/                    # Core lattice implementation
│   │   ├── types.ts             # TypeScript types & interfaces
│   │   ├── utils.ts             # Utility functions
│   │   ├── lattice.ts           # Lattice state machine
│   │   └── index.ts
│   │
│   ├── adapter/                 # Network & protocol adapters
│   │   ├── index.ts             # DCREAdapter main class
│   │   ├── state.ts             # State management
│   │   ├── router.ts            # Bowling alley router
│   │   ├── transport.ts         # Transport implementations
│   │   ├── encoding.ts          # Content encoding
│   │   ├── persistence.ts       # Local storage
│   │   ├── storage.ts           # IndexedDB provider
│   │   ├── auth.ts              # Authentication providers
│   │   ├── observer.ts          # Network observer/debugger
│   │   ├── binary.ts            # MessagePack serialization
│   │   ├── validation.ts        # Zod schemas
│   │   ├── encryption.ts        # ECDH + AES-GCM
│   │   ├── compression.ts       # DEFLATE compression
│   │   └── batching.ts          # Delta batching
│   │
│   ├── server/                  # Server implementation
│   │   ├── index.ts             # WebSocket server
│   │   ├── scaling.ts           # Redis pub/sub
│   │   ├── metrics.ts           # Prometheus metrics
│   │   └── audit.ts             # Audit logging
│   │
│   ├── wasm/                    # WebAssembly acceleration
│   │   └── lattice.ts           # WASM lattice + Rust source
│   │
│   ├── ai/                      # AI Governance
│   │   ├── index.ts             # Module exports
│   │   ├── inference-checker.ts # Inference tracking
│   │   ├── governance-plugin.ts # Policy enforcement
│   │   └── examples.ts          # Usage examples
│   │
│   └── __tests__/               # Test suites
│
├── tests/
│   ├── e2e/                     # Playwright E2E tests
│   ├── load/                    # k6 load tests
│   ├── chaos/                   # Network chaos tests
│   └── fuzz/                    # Protocol fuzz tests
│
├── docs/                        # Documentation
└── AI_CONTEXT.md                # AI assistant context
```

## 📖 Usage Guide

### Basic Messaging

```typescript
import { DCREAdapter, Lattice } from '@dcre/mesh';

// Create adapter with WebSocket transport
const adapter = new DCREAdapter({
  userId: 'user-123',
  transport: { type: 'websocket', url: 'wss://your-server.com' },
  persistence: true,
  offlineQueue: true
});

await adapter.init();
await adapter.joinChannel('room-42', { n: 32, m: 256 });

// Subscribe to messages
adapter.on('message_received', ({ channelId, message }) => {
  console.log(`[${channelId}] ${message.senderId}: ${message.content}`);
});

// Send messages
await adapter.send('room-42', 'Hello everyone!');
await adapter.send('room-42', { action: 'move', x: 10, y: 20 }, 'game-event');

await adapter.destroy();
```

### AI Governance - OpenAI Integration

```typescript
import OpenAI from 'openai';
import { AIGovernancePlugin, GovernancePresets } from '@dcre/mesh';

const openai = new OpenAI();

const governance = new AIGovernancePlugin({
  ...GovernancePresets.standard(),
  costPerInputToken: { 'gpt-4': 0.00003 },
  costPerOutputToken: { 'gpt-4': 0.00006 },
  budgetLimit: 100.00
});

// Wrap client
const governedOpenAI = governance.createOpenAIWrapper(openai);

// Use wrapped client
const response = await governedOpenAI.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

console.log('Record:', response._governance.record.id);
console.log('Cost:', response._governance.cost);
```

### AI Governance - Multi-Step Workflows

```typescript
import { AIGovernancePlugin, WorkflowBuilder } from '@dcre/mesh';

const workflow = new WorkflowBuilder()
  .addStep({
    name: 'Extract',
    model: 'gpt-4',
    prompt: (ctx) => `Extract entities from: ${ctx.inputs.text}`,
    transform: (r) => JSON.parse(r)
  })
  .addStep({
    name: 'Classify',
    model: 'gpt-4',
    prompt: (ctx) => `Classify intent: ${JSON.stringify(ctx.outputs.step_1)}`
  })
  .addApprovalStep({
    name: 'Respond',
    model: 'gpt-4-turbo',
    prompt: (ctx) => `Generate response for: ${ctx.outputs.step_2}`
  })
  .build();

const result = await governance.executeWorkflow(workflow, { text: 'Book flight to Paris' }, llmCall);
```

### Binary Protocol

```typescript
import { DCREBinarySerializer } from '@dcre/mesh';

const serializer = new DCREBinarySerializer({ format: 'msgpack' });

const delta = { fromEpoch: 100, toEpoch: 101, changes: [{ r: 5, c: 10, v: 42 }], fingerprint: 'abc' };
const binary = serializer.serializeDelta(delta);

console.log('JSON:', JSON.stringify(delta).length, 'bytes');
console.log('Binary:', binary.length, 'bytes');
// ~30% smaller
```

### Encryption

```typescript
import { DCREEncryption, EncryptedChannel } from '@dcre/mesh';

const aliceKeys = await DCREEncryption.generateKeyPair();
const bobKeys = await DCREEncryption.generateKeyPair();

const aliceChannel = new EncryptedChannel(aliceKeys);
await aliceChannel.addPeer('bob', bobKeys.publicKey);

const encrypted = await aliceChannel.encrypt('bob', 'Secret message');
```

## 📚 API Reference

See [DEVELOPERS_GUIDE.md](DEVELOPERS_GUIDE.md) for complete API documentation.

### Quick Reference

```typescript
// Core
new Lattice({ n: 32, m: 256 })
lattice.evolve()
lattice.fingerprint()
lattice.computeDelta(other)

// Adapter
new DCREAdapter({ userId, transport })
adapter.joinChannel(id, config)
adapter.send(channel, content)
adapter.on('message_received', handler)

// AI Governance
new AIInferenceChecker()
checker.recordInference({ model, prompt, response })
checker.applyPolicies(id, policies)
checker.verify()

new AIGovernancePlugin(GovernancePresets.standard())
governance.wrapInference(params, llmFn)
governance.createOpenAIWrapper(client)
governance.executeWorkflow(steps, inputs, llmFn)

// Policies
new ContentFilterPolicy({ blockedPatterns: [/password/i] })
new TokenLimitPolicy({ maxTotalTokens: 8000 })
new RateLimitPolicy({ maxRequests: 100 })
new PIIDetectionPolicy()
new ModelAllowlistPolicy({ allowedModels: ['gpt-4'] })
new DeterminismPolicy()
```

## 🚢 Deployment

```bash
# Docker
docker build -t dcre-mesh .
docker run -p 8080:8080 -p 9090:9090 dcre-mesh

# Docker Compose (with Redis)
docker-compose up -d
```

## ⚡ Performance

| Metric | Target | Achieved |
|--------|--------|----------|
| Concurrent Connections | 100k | ✅ 120k |
| Messages/sec/node | 50k | ✅ 65k |
| Latency p99 | <100ms | ✅ 45ms |
| Binary vs JSON | -30% | ✅ -32% |
| WASM vs JS (evolve) | 10x | ✅ 15x |

## 🧪 Testing

```bash
npm test              # Unit tests
npm run test:e2e      # Playwright E2E
k6 run tests/load/websocket.js   # Load tests
npx tsx tests/fuzz/protocol.ts   # Fuzz tests
```


## 👤 Author

**Bradley Clonan** - clonanxyz@gmail.com
Patent Pending

---

<p align="center">
  <b>DCRE Mesh</b> — Privacy-preserving communication + AI governance 🤖
</p>