npm package: @loosechain/delta-engine-core
Description: Loosechain Layer 1: Delta Engine Core - Deterministic protocol infrastructure (engine-law)
Latest version: 1.0.0

# @loosechain/delta-engine-core

> **Loosechain Layer 1: Delta Engine Core**  
> Deterministic protocol infrastructure for AI-native data verification

[![npm version](https://img.shields.io/npm/v/@loosechain/delta-engine-core.svg)](https://www.npmjs.com/package/@loosechain/delta-engine-core)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

## Overview

The **Delta Engine Core** is the foundational Layer 1 protocol for Loosechain's deterministic verification system. It provides pure, stateless functions for processing data bundles, computing convergence metrics, and generating cryptographically-signed receipts.

**Key Features:**
- 🔒 **Deterministic:** Same input always produces same output
- 🚀 **Zero Dependencies:** Pure TypeScript implementation
- ✅ **Type-Safe:** Full TypeScript type definitions
- 📦 **Lightweight:** Minimal footprint for maximum portability
- 🔐 **Cryptographic Receipts:** SHA-256 hashing for verification

---

## Installation

```bash
npm install @loosechain/delta-engine-core
```

---

## Quick Start

```typescript
import { DeltaEngine, validateBundle, verifyReceipt } from '@loosechain/delta-engine-core';

// Define your data bundle
const bundle = {
  bundleId: 'example-001',
  claim: 'Q4 revenue consensus',
  thresholdPct: 0.05, // 5% convergence threshold
  dataSpecs: [
    {
      id: 'source-a',
      label: 'Financial Report A',
      sourceKind: 'report',
      originDocIds: ['doc-123'],
      metrics: [
        { key: 'revenue', value: 1000000, unit: 'USD' }
      ]
    },
    {
      id: 'source-b',
      label: 'Financial Report B',
      sourceKind: 'report',
      originDocIds: ['doc-456'],
      metrics: [
        { key: 'revenue', value: 1050000, unit: 'USD' }
      ]
    }
  ]
};

// Validate bundle structure
const validation = validateBundle(bundle);
if (!validation.valid) {
  throw new Error(`Invalid bundle: ${validation.error}`);
}

// Run the Delta Engine
const receipt = DeltaEngine(bundle);

console.log(`Outcome: ${receipt.outcome}`);
console.log(`Final Delta: ${receipt.deltaFinal}`);
console.log(`Receipt Hash: ${receipt.hash}`);

// Verify receipt integrity
const verification = verifyReceipt(receipt);
console.log(`Receipt verified: ${verification.verified}`);
```

---

## Core Concepts

### DeltaBundle
A collection of data specifications to be processed for convergence analysis.

```typescript
interface DeltaBundle {
  bundleId: string;           // Unique identifier
  claim: string;              // Human-readable claim description
  dataSpecs: DataSpec[];      // Array of data sources
  thresholdPct: number;       // Convergence threshold (0.0 to 1.0)
  maxRounds?: number;         // Max iterations (default: 5)
}
```

### DeltaReceipt
Cryptographically-signed proof of processing with convergence metrics.

```typescript
interface DeltaReceipt {
  bundleId: string;           // References source bundle
  deltaFinal: number;         // Final convergence delta
  sources: string[];          // Ordered source labels
  rounds: DeltaRound[];       // Processing history
  outcome: 'consensus' | 'indeterminate';
  hash: string;               // SHA-256 cryptographic signature
}
```

---

## API Reference

### Engine Functions

#### `DeltaEngine(bundle: DeltaBundle, opts?: EngineOpts): DeltaReceipt`
Processes a data bundle and returns a cryptographically-signed receipt.

**Parameters:**
- `bundle` - The data bundle to process
- `opts` - Optional configuration (timestamp injection)

**Returns:** `DeltaReceipt` with outcome and verification hash

---

### Validation Functions

#### `validateBundle(bundle: DeltaBundle): ValidationResult`
Validates bundle structure and data integrity.

**Returns:**
```typescript
{ valid: boolean; error?: string }
```

#### `verifyReceipt(receipt: DeltaReceipt): VerifyResult`
Verifies receipt hash integrity by recomputing the cryptographic signature.

**Returns:**
```typescript
{ verified: boolean; recomputedHash?: string; error?: string }
```

---

### Serialization Functions

#### `serializeReceipt(receipt: DeltaReceipt): string`
Converts receipt to canonical JSON string for hashing or storage.

---

## Architecture

**Layer 1 Protocol ("Engine Law")**
- Pure deterministic functions
- Zero external dependencies
- Cryptographic verification
- Stable type definitions

**Design Principles:**
1. **Determinism First:** Same input → same output, always
2. **Stateless:** No side effects, no mutations
3. **Portable:** Works in any JavaScript runtime
4. **Verifiable:** All receipts are cryptographically signed

---

## Use Cases

- **Financial Reconciliation:** Multi-source revenue verification
- **Data Quality Assurance:** Cross-validation of metrics
- **Audit Trails:** Cryptographic proof of convergence
- **AI Training Data:** Verification of consensus accuracy
- **Compliance Reporting:** Deterministic audit receipts

---

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Lint code
npm run lint
```

---

## TypeScript Support

This package includes full TypeScript type definitions. All core types are exported:

```typescript
import type {
  DeltaBundle,
  DeltaReceipt,
  DataSpec,
  MetricPoint,
  ValidationResult,
  VerifyResult
} from '@loosechain/delta-engine-core';
```

---

## Repository

[https://github.com/loosechain-ai/lc_delta-core](https://github.com/loosechain-ai/lc_delta-core)

---

## License

MIT © 2026 Loosechain

---

## Related Packages

- **[@loosechain/delta-engine-mcp](https://www.npmjs.com/package/@loosechain/delta-engine-mcp)** - MCP Server for Claude Desktop integration
- **More coming soon...**