@uvrn/delta-engine-core

Deterministic multi-source comparison engine with canonical hashing.

Compares data from multiple sources, computes per-metric deltas using the Δ formula, and produces a canonical, SHA-256 hash-verified DeltaReceipt.

Install

npm install @uvrn/delta-engine-core

Quick Start

import { runDeltaEngine } from '@uvrn/delta-engine-core';

const result = runDeltaEngine({
  bundleId: 'comparison-001',
  claim: 'Page views should match across providers',
  thresholdPct: 0.10, // 10% tolerance
  dataSpecs: [
    {
      id: 'ga4',
      label: 'Google Analytics 4',
      sourceKind: 'report',
      originDocIds: ['ga4-export-001'],
      metrics: [
        { key: 'pageviews', value: 10000 },
        { key: 'sessions', value: 5200 },
      ],
    },
    {
      id: 'plausible',
      label: 'Plausible Analytics',
      sourceKind: 'report',
      originDocIds: ['plausible-export-001'],
      metrics: [
        { key: 'pageviews', value: 10300 },
        { key: 'sessions', value: 5100 },
      ],
    },
  ],
});

console.log(result.outcome);    // 'consensus' or 'indeterminate'
console.log(result.deltaFinal); // Max delta across all metrics
console.log(result.hash);       // SHA-256 of canonical receipt

The Delta Formula

For each comparable metric across sources:

Δ = |a - b| / ((a + b) / 2)

Edge cases:

• Both values zero → Δ = 0 (perfect agreement)
• One value zero → Δ = 1.0 (maximum variance)

Convergence: If all metric deltas are ≤ thresholdPct, the outcome is consensus. Otherwise the engine runs up to maxRounds (default: 5) before returning indeterminate.

API

runDeltaEngine(bundle, opts?)

Runs the comparison engine on a DeltaBundle and returns a DeltaReceipt.

validateBundle(bundle)

Structural validation of a DeltaBundle. Returns { valid: boolean, error?: string }.

verifyDeltaReceipt(receipt)

Recomputes the hash of a DeltaReceipt and verifies it matches the stored hash.

canonicalSerialize(obj)

RFC 8785 (JCS) canonical serialization using json-canonicalize.

hashDeltaReceipt(payload)

SHA-256 hash of the canonical serialization of a receipt payload (excluding the hash field itself).

Types

| Type | Description | |---|---| | DeltaBundle | Input: bundleId, claim, dataSpecs, thresholdPct, maxRounds | | DeltaReceipt | Output: bundleId, deltaFinal, sources, rounds, outcome, hash | | DeltaRound | Per-round detail: deltasByMetric, withinThreshold | | DataSpec | Single data source: id, label, sourceKind, metrics | | MetricPoint | Key-value metric: key, value, optional unit and timestamp | | Outcome | 'consensus' \| 'indeterminate' | | EngineOpts | Optional engine configuration (e.g., inject timestamp) |

Build

npm run build     # ESM + CJS + DTS via tsup
npm run typecheck  # tsc --noEmit

UVRN Protocol · github.com/UVRN-org