@bcts/uniform-resources 1.0.0-alpha.12 → 1.0.0-alpha.14

package/src/xoshiro.ts

@@ -5,8 +5,11 @@
  * for deterministic fragment selection in fountain codes.
  *
  * Reference: https://prng.di.unimi.it/
+ * BC-UR Reference: https://github.com/nicklockwood/fountain-codes
  */
 
+import { sha256 } from "@bcts/crypto";
+
 const MAX_UINT64 = BigInt("0xffffffffffffffff");
 
 /**
@@ -28,25 +31,33 @@ export class Xoshiro256 {
   private s: [bigint, bigint, bigint, bigint];
 
   /**
-   * Creates a new Xoshiro256** instance from a seed.
+   * Creates a new Xoshiro256** instance from a 32-byte seed.
    *
-   * The seed is hashed using SHA-256 to initialize the state.
-   * For consistent results across encoder/decoder, use the same seed.
+   * The seed must be exactly 32 bytes (256 bits). The bytes are interpreted
+   * using the BC-UR reference algorithm: each 8-byte chunk is read as
+   * big-endian then stored as little-endian for the state.
    *
-   * @param seed - The seed bytes (any length)
+   * @param seed - The seed bytes (must be exactly 32 bytes)
    */
   constructor(seed: Uint8Array) {
-    // Hash the seed using a simple hash function
-    // In production, you'd use SHA-256 here
-    const hash = this.hashSeed(seed);
-
-    // Initialize the 4x64-bit state from the hash
-    this.s = [
-      this.bytesToBigInt(hash.slice(0, 8)),
-      this.bytesToBigInt(hash.slice(8, 16)),
-      this.bytesToBigInt(hash.slice(16, 24)),
-      this.bytesToBigInt(hash.slice(24, 32)),
-    ];
+    if (seed.length !== 32) {
+      throw new Error(`Seed must be 32 bytes, got ${seed.length}`);
+    }
+
+    // BC-UR reference implementation:
+    // For each 8-byte chunk, read as big-endian u64, then convert to little-endian bytes
+    // This effectively swaps the byte order within each 8-byte segment
+    const s: [bigint, bigint, bigint, bigint] = [0n, 0n, 0n, 0n];
+    for (let i = 0; i < 4; i++) {
+      // Read 8 bytes as big-endian u64
+      let v = 0n;
+      for (let n = 0; n < 8; n++) {
+        v = (v << 8n) | BigInt(seed[8 * i + n] ?? 0);
+      }
+      s[i] = v;
+    }
+
+    this.s = s;
   }
 
   /**
@@ -59,47 +70,6 @@ export class Xoshiro256 {
     return instance;
   }
 
-  /**
-   * Simple hash function for seeding.
-   * This is a basic implementation - in production use SHA-256.
-   */
-  private hashSeed(seed: Uint8Array): Uint8Array {
-    // Simple hash expansion using CRC32-like operations
-    const result = new Uint8Array(32);
-
-    if (seed.length === 0) {
-      return result;
-    }
-
-    // Expand seed to 32 bytes using a simple mixing function
-    for (let i = 0; i < 32; i++) {
-      let hash = 0;
-      for (const byte of seed) {
-        hash = (hash * 31 + byte + i) >>> 0;
-      }
-      // Mix the hash further
-      hash ^= hash >>> 16;
-      hash = (hash * 0x85ebca6b) >>> 0;
-      hash ^= hash >>> 13;
-      hash = (hash * 0xc2b2ae35) >>> 0;
-      hash ^= hash >>> 16;
-      result[i] = hash & 0xff;
-    }
-
-    return result;
-  }
-
-  /**
-   * Converts 8 bytes to a 64-bit BigInt (little-endian).
-   */
-  private bytesToBigInt(bytes: Uint8Array): bigint {
-    let result = 0n;
-    for (let i = 7; i >= 0; i--) {
-      result = (result << 8n) | BigInt(bytes[i] ?? 0);
-    }
-    return result;
-  }
-
   /**
    * Generates the next 64-bit random value.
    */
@@ -121,19 +91,21 @@ export class Xoshiro256 {
 
   /**
    * Generates a random double in [0, 1).
+   * Matches BC-UR reference: self.next() as f64 / (u64::MAX as f64 + 1.0)
    */
   nextDouble(): number {
-    // Use the upper 53 bits for double precision
     const value = this.next();
-    return Number(value >> 11n) / Number(1n << 53n);
+    // u64::MAX as f64 + 1.0 = 18446744073709551616.0
+    return Number(value) / 18446744073709551616.0;
   }
 
   /**
-   * Generates a random integer in [low, high).
+   * Generates a random integer in [low, high] (inclusive).
+   * Matches BC-UR reference: (self.next_double() * ((high - low + 1) as f64)) as u64 + low
    */
   nextInt(low: number, high: number): number {
-    const range = high - low;
-    return low + Math.floor(this.nextDouble() * range);
+    const range = high - low + 1;
+    return Math.floor(this.nextDouble() * range) + low;
   }
 
   /**
@@ -153,28 +125,150 @@ export class Xoshiro256 {
     }
     return result;
   }
+
+  /**
+   * Shuffles items by repeatedly picking random indices.
+   * Matches BC-UR reference implementation.
+   */
+  shuffled<T>(items: T[]): T[] {
+    const source = [...items];
+    const shuffled: T[] = [];
+    while (source.length > 0) {
+      const index = this.nextInt(0, source.length - 1);
+      const item = source.splice(index, 1)[0];
+      if (item !== undefined) {
+        shuffled.push(item);
+      }
+    }
+    return shuffled;
+  }
+
+  /**
+   * Chooses the degree (number of fragments to mix) using a weighted sampler.
+   * Uses the robust soliton distribution with weights [1/1, 1/2, 1/3, ..., 1/n].
+   * Matches BC-UR reference implementation.
+   */
+  chooseDegree(seqLen: number): number {
+    // Create weights: [1/1, 1/2, 1/3, ..., 1/seqLen]
+    const weights: number[] = [];
+    for (let i = 1; i <= seqLen; i++) {
+      weights.push(1.0 / i);
+    }
+
+    // Use Vose's alias method for weighted sampling
+    const sampler = new WeightedSampler(weights);
+    return sampler.next(this) + 1; // 1-indexed degree
+  }
 }
 
 /**
- * Creates a seed for the Xoshiro PRNG from message checksum and sequence number.
+ * Weighted sampler using Vose's alias method.
+ * Allows O(1) sampling from a discrete probability distribution.
+ */
+class WeightedSampler {
+  private readonly aliases: number[];
+  private readonly probs: number[];
+
+  constructor(weights: number[]) {
+    const n = weights.length;
+    if (n === 0) {
+      throw new Error("Weights array cannot be empty");
+    }
+
+    // Normalize weights
+    const sum = weights.reduce((a, b) => a + b, 0);
+    if (sum <= 0) {
+      throw new Error("Weights must sum to a positive value");
+    }
+
+    const normalized = weights.map((w) => (w * n) / sum);
+
+    // Initialize alias table
+    this.aliases = Array.from<number>({ length: n }).fill(0);
+    this.probs = Array.from<number>({ length: n }).fill(0);
+
+    // Partition into small and large
+    const small: number[] = [];
+    const large: number[] = [];
+
+    for (let i = n - 1; i >= 0; i--) {
+      if (normalized[i] < 1.0) {
+        small.push(i);
+      } else {
+        large.push(i);
+      }
+    }
+
+    // Build the alias table
+    while (small.length > 0 && large.length > 0) {
+      const a = small.pop();
+      const g = large.pop();
+      if (a === undefined || g === undefined) break;
+      this.probs[a] = normalized[a] ?? 0;
+      this.aliases[a] = g;
+      const normalizedG = normalized[g] ?? 0;
+      const normalizedA = normalized[a] ?? 0;
+      normalized[g] = normalizedG + normalizedA - 1.0;
+      if (normalized[g] !== undefined && normalized[g] < 1.0) {
+        small.push(g);
+      } else {
+        large.push(g);
+      }
+    }
+
+    while (large.length > 0) {
+      const g = large.pop();
+      if (g === undefined) break;
+      this.probs[g] = 1.0;
+    }
+
+    while (small.length > 0) {
+      const a = small.pop();
+      if (a === undefined) break;
+      this.probs[a] = 1.0;
+    }
+  }
+
+  /**
+   * Sample from the distribution.
+   */
+  next(rng: Xoshiro256): number {
+    const r1 = rng.nextDouble();
+    const r2 = rng.nextDouble();
+    const n = this.probs.length;
+    const i = Math.floor(n * r1);
+    if (r2 < this.probs[i]) {
+      return i;
+    } else {
+      return this.aliases[i];
+    }
+  }
+}
+
+/**
+ * Creates a Xoshiro256 PRNG instance from message checksum and sequence number.
+ *
+ * This creates an 8-byte seed by concatenating seqNum and checksum (both in
+ * big-endian), then hashes it with SHA-256 to get the 32-byte seed for Xoshiro.
  *
- * This ensures that both encoder and decoder produce the same random sequence
- * for a given message and part number.
+ * This matches the BC-UR reference implementation.
  */
 export function createSeed(checksum: number, seqNum: number): Uint8Array {
-  const seed = new Uint8Array(8);
+  // Create 8-byte seed: seqNum (big-endian) || checksum (big-endian)
+  const seed8 = new Uint8Array(8);
 
-  // Pack checksum (4 bytes, big-endian)
-  seed[0] = (checksum >>> 24) & 0xff;
-  seed[1] = (checksum >>> 16) & 0xff;
-  seed[2] = (checksum >>> 8) & 0xff;
-  seed[3] = checksum & 0xff;
+  // seqNum in big-endian (bytes 0-3)
+  seed8[0] = (seqNum >>> 24) & 0xff;
+  seed8[1] = (seqNum >>> 16) & 0xff;
+  seed8[2] = (seqNum >>> 8) & 0xff;
+  seed8[3] = seqNum & 0xff;
 
-  // Pack seqNum (4 bytes, big-endian)
-  seed[4] = (seqNum >>> 24) & 0xff;
-  seed[5] = (seqNum >>> 16) & 0xff;
-  seed[6] = (seqNum >>> 8) & 0xff;
-  seed[7] = seqNum & 0xff;
+  // checksum in big-endian (bytes 4-7)
+  seed8[4] = (checksum >>> 24) & 0xff;
+  seed8[5] = (checksum >>> 16) & 0xff;
+  seed8[6] = (checksum >>> 8) & 0xff;
+  seed8[7] = checksum & 0xff;
 
-  return seed;
+  // Hash with SHA-256 to get 32 bytes
+  return sha256(seed8);
 }