@uvrn/sdk 1.0.2 → 1.0.3

package/README.md

@@ -2,6 +2,8 @@
 
 TypeScript SDK for the [UVRN Delta Engine](https://github.com/UVRN-org/uvrn-packages) — programmatic access to deterministic verification and consensus computation.
 
+**Disclaimer:** UVRN is in Alpha testing. The engine measures whether your sources agree with each other — not whether they’re correct. Final trust of output rests with the user. Use at your own risk. Have fun.
+
 ## Overview
 
 The Delta Engine SDK provides a developer-friendly interface to interact with the Delta Engine in multiple execution modes:
@@ -107,7 +109,7 @@ Spawns the Delta Engine CLI as a child process:
 ```typescript
 const client = new DeltaEngineClient({
   mode: 'cli',
-  cliPath: '/usr/local/bin/delta-engine', // or './node_modules/.bin/delta-engine'
+  cliPath: '/usr/local/bin/uvrn', // or './node_modules/.bin/uvrn'
   timeout: 30000
 });
 ```

package/dist/builder.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Bundle Builder - Fluent API for constructing Delta Bundles
+ */
+import type { DeltaBundle, DataSpec, MetricPoint } from '@uvrn/core';
+import type { BundleBuilderOptions, ValidationResult } from './types/sdk';
+/**
+ * Fluent API for building Delta Bundles
+ *
+ * @example
+ * ```typescript
+ * const bundle = new BundleBuilder()
+ *   .setBundleId('my-bundle')
+ *   .setClaim('Q1 revenue matches projections')
+ *   .addDataSpec({
+ *     id: 'forecast',
+ *     label: 'Q1 Forecast',
+ *     sourceKind: 'report',
+ *     originDocIds: ['doc-1'],
+ *     metrics: [{ key: 'revenue', value: 1000000 }]
+ *   })
+ *   .addDataSpec({
+ *     id: 'actual',
+ *     label: 'Q1 Actual',
+ *     sourceKind: 'report',
+ *     originDocIds: ['doc-2'],
+ *     metrics: [{ key: 'revenue', value: 1020000 }]
+ *   })
+ *   .setThreshold(0.05)
+ *   .build();
+ * ```
+ */
+export declare class BundleBuilder {
+    private bundleId;
+    private claim;
+    private dataSpecs;
+    private thresholdPct;
+    private maxRounds?;
+    /**
+     * Creates a new BundleBuilder
+     *
+     * @param options - Optional initial configuration
+     */
+    constructor(options?: BundleBuilderOptions);
+    /**
+     * Generates a unique bundle ID
+     * @internal
+     */
+    private generateBundleId;
+    /**
+     * Sets the bundle ID
+     *
+     * @param bundleId - Unique identifier for this bundle
+     * @returns this builder instance for chaining
+     */
+    setBundleId(bundleId: string): this;
+    /**
+     * Sets the claim statement
+     *
+     * @param claim - The claim this bundle will verify
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setClaim('Revenue projections are within 10% of actuals');
+     * ```
+     */
+    setClaim(claim: string): this;
+    /**
+     * Adds a DataSpec to the bundle
+     *
+     * @param spec - Complete DataSpec object
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addDataSpec({
+     *   id: 'source-1',
+     *   label: 'Forecast Data',
+     *   sourceKind: 'report',
+     *   originDocIds: ['doc-123'],
+     *   metrics: [
+     *     { key: 'revenue', value: 1000000, unit: 'USD' }
+     *   ]
+     * });
+     * ```
+     */
+    addDataSpec(spec: DataSpec): this;
+    /**
+     * Creates and adds a DataSpec with a fluent interface
+     *
+     * @param id - Unique identifier
+     * @param label - Human-readable label
+     * @param sourceKind - Type of data source
+     * @param originDocIds - Source document IDs
+     * @param metrics - Metric data points
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addDataSpecQuick(
+     *   'source-1',
+     *   'Forecast',
+     *   'report',
+     *   ['doc-123'],
+     *   [{ key: 'revenue', value: 1000000 }]
+     * );
+     * ```
+     */
+    addDataSpecQuick(id: string, label: string, sourceKind: 'report' | 'metric' | 'chart' | 'meta', originDocIds: string[], metrics: MetricPoint[]): this;
+    /**
+     * Sets the threshold percentage for delta comparison
+     *
+     * @param threshold - Threshold as a decimal (0.0 to 1.0)
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setThreshold(0.10); // 10% threshold
+     * ```
+     */
+    setThreshold(threshold: number): this;
+    /**
+     * Sets the threshold percentage using a percentage value
+     *
+     * @param percent - Threshold as percentage (0 to 100)
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setThresholdPercent(10); // 10% threshold
+     * ```
+     */
+    setThresholdPercent(percent: number): this;
+    /**
+     * Sets the maximum number of rounds
+     *
+     * @param rounds - Maximum rounds (defaults to 5 if not set)
+     * @returns this builder instance for chaining
+     */
+    setMaxRounds(rounds: number): this;
+    /**
+     * Validates the current bundle configuration without building
+     *
+     * @returns ValidationResult indicating if the bundle is valid
+     *
+     * @example
+     * ```typescript
+     * const result = builder.validate();
+     * if (!result.valid) {
+     *   console.error('Bundle configuration is invalid:', result.errors);
+     * }
+     * ```
+     */
+    validate(): ValidationResult;
+    /**
+     * Converts current configuration to a DeltaBundle object (without validation)
+     * @internal
+     */
+    private toBundle;
+    /**
+     * Builds and returns the final DeltaBundle
+     *
+     * @throws {ValidationError} if the bundle configuration is invalid
+     * @returns Complete, validated DeltaBundle
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const bundle = builder.build();
+     *   // Use bundle...
+     * } catch (error) {
+     *   if (error instanceof ValidationError) {
+     *     console.error('Invalid bundle:', error.errors);
+     *   }
+     * }
+     * ```
+     */
+    build(): DeltaBundle;
+    /**
+     * Resets the builder to initial state (keeps bundleId)
+     *
+     * @returns this builder instance for chaining
+     */
+    reset(): this;
+    /**
+     * Creates a new builder instance with a fresh bundle ID
+     *
+     * @returns new BundleBuilder instance
+     */
+    static create(options?: BundleBuilderOptions): BundleBuilder;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAK1E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,SAAS,CAAC,CAAS;IAE3B;;;;OAIG;gBACS,OAAO,CAAC,EAAE,oBAAoB;IAO1C;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKnC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAKjC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CACd,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,EAClD,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,EAAE,WAAW,EAAE,GACrB,IAAI;IAUP;;;;;;;;;;OAUG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKrC;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK1C;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKlC;;;;;;;;;;;;OAYG;IACH,QAAQ,IAAI,gBAAgB;IAK5B;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAehB;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,IAAI,WAAW;IAcpB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAQb;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,aAAa;CAG7D"}

package/dist/builder.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * Bundle Builder - Fluent API for constructing Delta Bundles
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BundleBuilder = void 0;
+const validators_1 = require("./validators");
+const errors_1 = require("./errors");
+const crypto_1 = require("crypto");
+/**
+ * Fluent API for building Delta Bundles
+ *
+ * @example
+ * ```typescript
+ * const bundle = new BundleBuilder()
+ *   .setBundleId('my-bundle')
+ *   .setClaim('Q1 revenue matches projections')
+ *   .addDataSpec({
+ *     id: 'forecast',
+ *     label: 'Q1 Forecast',
+ *     sourceKind: 'report',
+ *     originDocIds: ['doc-1'],
+ *     metrics: [{ key: 'revenue', value: 1000000 }]
+ *   })
+ *   .addDataSpec({
+ *     id: 'actual',
+ *     label: 'Q1 Actual',
+ *     sourceKind: 'report',
+ *     originDocIds: ['doc-2'],
+ *     metrics: [{ key: 'revenue', value: 1020000 }]
+ *   })
+ *   .setThreshold(0.05)
+ *   .build();
+ * ```
+ */
+class BundleBuilder {
+    bundleId;
+    claim = '';
+    dataSpecs = [];
+    thresholdPct = 0.05; // Default 5%
+    maxRounds;
+    /**
+     * Creates a new BundleBuilder
+     *
+     * @param options - Optional initial configuration
+     */
+    constructor(options) {
+        this.bundleId = options?.bundleId || this.generateBundleId();
+        if (options?.claim)
+            this.claim = options.claim;
+        if (options?.thresholdPct !== undefined)
+            this.thresholdPct = options.thresholdPct;
+        if (options?.maxRounds !== undefined)
+            this.maxRounds = options.maxRounds;
+    }
+    /**
+     * Generates a unique bundle ID
+     * @internal
+     */
+    generateBundleId() {
+        const timestamp = Date.now();
+        const random = (0, crypto_1.randomBytes)(4).toString('hex');
+        return `bundle-${timestamp}-${random}`;
+    }
+    /**
+     * Sets the bundle ID
+     *
+     * @param bundleId - Unique identifier for this bundle
+     * @returns this builder instance for chaining
+     */
+    setBundleId(bundleId) {
+        this.bundleId = bundleId;
+        return this;
+    }
+    /**
+     * Sets the claim statement
+     *
+     * @param claim - The claim this bundle will verify
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setClaim('Revenue projections are within 10% of actuals');
+     * ```
+     */
+    setClaim(claim) {
+        this.claim = claim;
+        return this;
+    }
+    /**
+     * Adds a DataSpec to the bundle
+     *
+     * @param spec - Complete DataSpec object
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addDataSpec({
+     *   id: 'source-1',
+     *   label: 'Forecast Data',
+     *   sourceKind: 'report',
+     *   originDocIds: ['doc-123'],
+     *   metrics: [
+     *     { key: 'revenue', value: 1000000, unit: 'USD' }
+     *   ]
+     * });
+     * ```
+     */
+    addDataSpec(spec) {
+        this.dataSpecs.push(spec);
+        return this;
+    }
+    /**
+     * Creates and adds a DataSpec with a fluent interface
+     *
+     * @param id - Unique identifier
+     * @param label - Human-readable label
+     * @param sourceKind - Type of data source
+     * @param originDocIds - Source document IDs
+     * @param metrics - Metric data points
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addDataSpecQuick(
+     *   'source-1',
+     *   'Forecast',
+     *   'report',
+     *   ['doc-123'],
+     *   [{ key: 'revenue', value: 1000000 }]
+     * );
+     * ```
+     */
+    addDataSpecQuick(id, label, sourceKind, originDocIds, metrics) {
+        return this.addDataSpec({
+            id,
+            label,
+            sourceKind,
+            originDocIds,
+            metrics
+        });
+    }
+    /**
+     * Sets the threshold percentage for delta comparison
+     *
+     * @param threshold - Threshold as a decimal (0.0 to 1.0)
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setThreshold(0.10); // 10% threshold
+     * ```
+     */
+    setThreshold(threshold) {
+        this.thresholdPct = threshold;
+        return this;
+    }
+    /**
+     * Sets the threshold percentage using a percentage value
+     *
+     * @param percent - Threshold as percentage (0 to 100)
+     * @returns this builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.setThresholdPercent(10); // 10% threshold
+     * ```
+     */
+    setThresholdPercent(percent) {
+        this.thresholdPct = percent / 100;
+        return this;
+    }
+    /**
+     * Sets the maximum number of rounds
+     *
+     * @param rounds - Maximum rounds (defaults to 5 if not set)
+     * @returns this builder instance for chaining
+     */
+    setMaxRounds(rounds) {
+        this.maxRounds = rounds;
+        return this;
+    }
+    /**
+     * Validates the current bundle configuration without building
+     *
+     * @returns ValidationResult indicating if the bundle is valid
+     *
+     * @example
+     * ```typescript
+     * const result = builder.validate();
+     * if (!result.valid) {
+     *   console.error('Bundle configuration is invalid:', result.errors);
+     * }
+     * ```
+     */
+    validate() {
+        const bundle = this.toBundle();
+        return (0, validators_1.validateBundle)(bundle);
+    }
+    /**
+     * Converts current configuration to a DeltaBundle object (without validation)
+     * @internal
+     */
+    toBundle() {
+        const bundle = {
+            bundleId: this.bundleId,
+            claim: this.claim,
+            dataSpecs: this.dataSpecs,
+            thresholdPct: this.thresholdPct
+        };
+        if (this.maxRounds !== undefined) {
+            bundle.maxRounds = this.maxRounds;
+        }
+        return bundle;
+    }
+    /**
+     * Builds and returns the final DeltaBundle
+     *
+     * @throws {ValidationError} if the bundle configuration is invalid
+     * @returns Complete, validated DeltaBundle
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const bundle = builder.build();
+     *   // Use bundle...
+     * } catch (error) {
+     *   if (error instanceof ValidationError) {
+     *     console.error('Invalid bundle:', error.errors);
+     *   }
+     * }
+     * ```
+     */
+    build() {
+        const bundle = this.toBundle();
+        const validation = (0, validators_1.validateBundle)(bundle);
+        if (!validation.valid) {
+            throw new errors_1.ValidationError('Invalid bundle configuration', validation.errors || []);
+        }
+        return bundle;
+    }
+    /**
+     * Resets the builder to initial state (keeps bundleId)
+     *
+     * @returns this builder instance for chaining
+     */
+    reset() {
+        this.claim = '';
+        this.dataSpecs = [];
+        this.thresholdPct = 0.05;
+        this.maxRounds = undefined;
+        return this;
+    }
+    /**
+     * Creates a new builder instance with a fresh bundle ID
+     *
+     * @returns new BundleBuilder instance
+     */
+    static create(options) {
+        return new BundleBuilder(options);
+    }
+}
+exports.BundleBuilder = BundleBuilder;
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Delta Engine SDK Client
+ *
+ * Main client class for interacting with Delta Engine in multiple modes:
+ * - CLI: Spawns CLI process
+ * - HTTP: Makes API requests
+ * - Local: Direct function calls
+ */
+import type { DeltaBundle, DeltaReceipt } from '@uvrn/core';
+import type { ClientOptions, ValidationResult, VerificationResult } from './types/sdk';
+/**
+ * Client for interacting with Delta Engine
+ *
+ * Supports three execution modes:
+ * - **CLI**: Spawns the CLI executable
+ * - **HTTP**: Makes requests to REST API
+ * - **Local**: Direct import of core engine
+ *
+ * @example
+ * ```typescript
+ * // CLI mode
+ * const client = new DeltaEngineClient({
+ *   mode: 'cli',
+ *   cliPath: '/usr/local/bin/uvrn'
+ * });
+ *
+ * // HTTP mode
+ * const client = new DeltaEngineClient({
+ *   mode: 'http',
+ *   apiUrl: 'http://localhost:3000',
+ *   timeout: 30000
+ * });
+ *
+ * // Local mode
+ * const client = new DeltaEngineClient({
+ *   mode: 'local'
+ * });
+ * ```
+ */
+export declare class DeltaEngineClient {
+    private readonly options;
+    /**
+     * Creates a new DeltaEngineClient
+     *
+     * @param options - Client configuration
+     * @throws {ConfigurationError} if configuration is invalid
+     */
+    constructor(options: ClientOptions);
+    /**
+     * Validates client options
+     * @internal
+     */
+    private validateOptions;
+    /**
+     * Executes a bundle and returns a receipt
+     *
+     * @param bundle - The DeltaBundle to execute
+     * @returns Promise resolving to DeltaReceipt
+     * @throws {ValidationError} if bundle is invalid
+     * @throws {ExecutionError} if execution fails
+     * @throws {NetworkError} if HTTP request fails (HTTP mode only)
+     *
+     * @example
+     * ```typescript
+     * const bundle = {
+     *   bundleId: 'test-1',
+     *   claim: 'Revenue matches forecast',
+     *   dataSpecs: [...],
+     *   thresholdPct: 0.05
+     * };
+     *
+     * const receipt = await client.runEngine(bundle);
+     * console.log('Outcome:', receipt.outcome);
+     * ```
+     */
+    runEngine(bundle: DeltaBundle): Promise<DeltaReceipt>;
+    /**
+     * Executes bundle via CLI mode
+     * @internal
+     */
+    private runEngineCLI;
+    /**
+     * Spawns CLI process and captures output
+     * @internal
+     */
+    private spawnCLI;
+    /**
+     * Executes bundle via HTTP API mode
+     * @internal
+     */
+    private runEngineHTTP;
+    /**
+     * Fetch with retry logic
+     * @internal
+     */
+    private fetchWithRetry;
+    /**
+     * Executes bundle via local mode (direct import)
+     * @internal
+     */
+    private runEngineLocal;
+    /**
+     * Validates a bundle without executing it
+     *
+     * @param bundle - The bundle to validate
+     * @returns ValidationResult with detailed errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.validateBundle(bundle);
+     * if (!result.valid) {
+     *   console.error('Validation errors:', result.errors);
+     * }
+     * ```
+     */
+    validateBundle(bundle: DeltaBundle): Promise<ValidationResult>;
+    /**
+     * Verifies a receipt's integrity and determinism
+     *
+     * Checks:
+     * 1. Receipt hash integrity
+     * 2. Deterministic replay (if original bundle available)
+     *
+     * @param receipt - The receipt to verify
+     * @returns VerificationResult with detailed information
+     *
+     * @example
+     * ```typescript
+     * const result = await client.verifyReceipt(receipt);
+     * if (!result.verified) {
+     *   console.error('Receipt verification failed!');
+     * }
+     * if (!result.deterministic) {
+     *   console.warn('Non-deterministic execution detected!');
+     * }
+     * ```
+     */
+    verifyReceipt(receipt: DeltaReceipt): Promise<VerificationResult>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAevF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD;;;;;OAKG;gBACS,OAAO,EAAE,aAAa;IAclC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAkBvB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAoB3D;;;OAGG;YACW,YAAY;IAoC1B;;;OAGG;IACH,OAAO,CAAC,QAAQ;IA+BhB;;;OAGG;YACW,aAAa;IAwC3B;;;OAGG;YACW,cAAc;IAuB5B;;;OAGG;YACW,cAAc;IAwB5B;;;;;;;;;;;;;OAaG;IACG,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIpE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAkCxE"}