yakmesh 2.9.0 → 3.0.0

package/oracle/packet-checksum.js

@@ -17,6 +17,7 @@
  */
 
 import { YPC27Checksum, ypc27, bytesToTrits, tritsToBytes, seedFromPeerId, Poly27 } from './ypc27.js';
+import { YPC27_SST } from './ypc27.js';
 
 // =============================================================================
 // PROTOCOL DOMAIN TAGS
@@ -327,6 +328,204 @@ export function unwrapWithChecksum(wrappedMessage, domain, nodeId = null) {
   }
 }
 
+// =============================================================================
+// BATCH CHECKSUM VERIFICATION ENGINE
+// =============================================================================
+
+/**
+ * BatchChecksumVerifier — Batched YPC-27 verification for high-throughput
+ * packet processing. Collects individual verify requests and processes them
+ * in a single flush, suitable for routing through the ComputeScheduler.
+ * 
+ * Why batch?
+ * - YPC-27 verification involves Poly27 cyclic convolution (O(N²) per check)
+ * - Batching amortizes JS object creation overhead
+ * - The batch can be routed to GPU via ComputeScheduler for parallel execution
+ * - Under load, 50-100 packets/cycle is typical — perfect batch size
+ * 
+ * Usage patterns:
+ * 
+ * 1. Direct (no scheduler):
+ *    const verifier = new BatchChecksumVerifier();
+ *    const p1 = verifier.enqueue(data1, checksum1, PROTOCOL_DOMAIN.STUPA);
+ *    const p2 = verifier.enqueue(data2, checksum2, PROTOCOL_DOMAIN.NAKPAK);
+ *    // Auto-flushes after threshold or timer
+ * 
+ * 2. Via ComputeScheduler (recommended for production):
+ *    const result = await scheduler.submit({
+ *      type: 'ypc27-batch-verify',
+ *      priority: Priority.HIGH,
+ *      affinity: Affinity.GPU_PREFERRED,
+ *      executors: {
+ *        gpu: () => verifier.flush(),
+ *        cpu: () => verifier.flush(),
+ *      }
+ *    });
+ */
+export class BatchChecksumVerifier {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.minBatchSize=8] — Minimum items before auto-flush
+   * @param {number} [options.maxBatchSize=128] — Maximum items per flush
+   * @param {number} [options.flushInterval=5] — Ms before timer-triggered flush
+   * @param {boolean} [options.useSST=false] — Use YPC27_SST enhanced checksums
+   */
+  constructor(options = {}) {
+    this.minBatchSize = options.minBatchSize ?? 8;
+    this.maxBatchSize = options.maxBatchSize ?? 128;
+    this.flushInterval = options.flushInterval ?? 5;
+    this.useSST = options.useSST ?? false;
+    
+    /** @type {Array<{data: Buffer, checksum: Poly27, domain: string, nodeId: string|null, resolve: Function, reject: Function}>} */
+    this._queue = [];
+    this._timer = null;
+    
+    // Telemetry
+    this._stats = {
+      totalEnqueued: 0,
+      totalFlushed: 0,
+      totalValid: 0,
+      totalInvalid: 0,
+      totalErrors: 0,
+      batchCount: 0,
+      avgBatchSize: 0,
+      lastFlushMs: 0,
+    };
+  }
+
+  /**
+   * Enqueue a checksum verification.
+   * Returns a promise that resolves with { valid: boolean, index: number }.
+   * 
+   * @param {Object|string|Buffer|Uint8Array} data — Packet data to verify
+   * @param {Poly27|string} checksum — Expected checksum (Poly27 or wire format)
+   * @param {string} domain — Protocol domain from PROTOCOL_DOMAIN
+   * @param {string} [nodeId] — Optional node ID for seed derivation
+   * @returns {Promise<{valid: boolean, index: number}>}
+   */
+  enqueue(data, checksum, domain, nodeId = null) {
+    return new Promise((resolve, reject) => {
+      const parsedChecksum = typeof checksum === 'string' 
+        ? checksumFromWire(checksum)
+        : checksum;
+      
+      this._queue.push({
+        data,
+        checksum: parsedChecksum,
+        domain,
+        nodeId,
+        resolve,
+        reject,
+      });
+      
+      this._stats.totalEnqueued++;
+      
+      if (this._queue.length >= this.minBatchSize) {
+        this.flush();
+      } else if (!this._timer) {
+        this._timer = setTimeout(() => this.flush(), this.flushInterval);
+      }
+    });
+  }
+
+  /**
+   * Process all queued verifications in a single batch.
+   * This is the method to pass as an executor to ComputeScheduler.
+   * 
+   * The batch verification leverages:
+   * - Shared seed derivation (reuse for same domain+nodeId pairs)
+   * - Pre-allocated typed arrays for trit conversion
+   * - Sequential Poly27 operations (GPU-parallelizable in future)
+   * 
+   * @returns {{ verified: number, valid: number, invalid: number, errors: number, durationMs: number }}
+   */
+  flush() {
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+    
+    if (this._queue.length === 0) {
+      return { verified: 0, valid: 0, invalid: 0, errors: 0, durationMs: 0 };
+    }
+    
+    const batch = this._queue.splice(0, this.maxBatchSize);
+    const t0 = performance.now();
+    
+    // Cache engines by domain+nodeId to avoid redundant seed derivation
+    const engineCache = new Map();
+    
+    let valid = 0;
+    let invalid = 0;
+    let errors = 0;
+    
+    for (let i = 0; i < batch.length; i++) {
+      const item = batch[i];
+      try {
+        const cacheKey = `${item.domain}:${item.nodeId || ''}`;
+        
+        if (!engineCache.has(cacheKey)) {
+          engineCache.set(cacheKey, new PacketChecksum(item.domain, item.nodeId));
+        }
+        
+        const engine = engineCache.get(cacheKey);
+        const isValid = engine.verify(item.data, item.checksum);
+        
+        if (isValid) {
+          valid++;
+          this._stats.totalValid++;
+        } else {
+          invalid++;
+          this._stats.totalInvalid++;
+        }
+        
+        item.resolve({ valid: isValid, index: i });
+      } catch (err) {
+        errors++;
+        this._stats.totalErrors++;
+        item.reject(err);
+      }
+    }
+    
+    const durationMs = performance.now() - t0;
+    
+    // Update telemetry
+    this._stats.totalFlushed += batch.length;
+    this._stats.batchCount++;
+    this._stats.avgBatchSize = this._stats.totalFlushed / this._stats.batchCount;
+    this._stats.lastFlushMs = durationMs;
+    
+    return { verified: batch.length, valid, invalid, errors, durationMs };
+  }
+
+  /**
+   * Get verification statistics.
+   * @returns {Object}
+   */
+  getStats() {
+    return {
+      ...this._stats,
+      queueDepth: this._queue.length,
+      avgBatchSize: +this._stats.avgBatchSize.toFixed(1),
+      lastFlushMs: +this._stats.lastFlushMs.toFixed(2),
+    };
+  }
+
+  /**
+   * Drain queue and release timer.
+   */
+  destroy() {
+    this.flush();
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+  }
+}
+
+/** Singleton batch verifier for packet checksums */
+export const batchChecksumVerifier = new BatchChecksumVerifier();
+
 // =============================================================================
 // EXPORTS
 // =============================================================================
@@ -343,4 +542,6 @@ export default {
   createMantraChecksum,
   wrapWithChecksum,
   unwrapWithChecksum,
+  BatchChecksumVerifier,
+  batchChecksumVerifier,
 };