@q-ching/core 0.1.0

package/src/casting.ts

@@ -0,0 +1,131 @@
+import type { Bit, CastMethod, HexBits, Line, LineValue, Reading } from './types.js';
+import { BitReader } from './util.js';
+import { EntropyPool } from './entropy/pool.js';
+import { gatherEntropy, localCsprng, type QrngConfig, type QrngResult } from './entropy/qrng.js';
+import { hexagramByBits } from './hexagrams.js';
+
+/**
+ * Coin method (three coins). Each coin: heads = 3, tails = 2. Three fair bits
+ * decide the line. With h = number of heads, value = 6 + h, giving
+ *   6 (old yin)   1/8
+ *   7 (young yang) 3/8
+ *   8 (young yin)  3/8
+ *   9 (old yang)  1/8
+ */
+function coinLine(reader: BitReader): LineValue {
+  const h = reader.readBit() + reader.readBit() + reader.readBit();
+  return (6 + h) as LineValue;
+}
+
+/**
+ * Yarrow-stalk method. The traditional stalk ritual yields an asymmetric
+ * distribution that makes changing lines rarer:
+ *   6 (old yin)    1/16
+ *   7 (young yang) 5/16
+ *   8 (young yin)  7/16
+ *   9 (old yang)   3/16
+ * Drawn from four uniform bits (0..15), since 16 is a power of two.
+ */
+function yarrowLine(reader: BitReader): LineValue {
+  const v = reader.readBits(4); // 0..15, uniform
+  if (v === 0) return 6;        // 1/16
+  if (v <= 3) return 9;         // 3/16  (1,2,3)
+  if (v <= 8) return 7;         // 5/16  (4,5,6,7,8)
+  return 8;                      // 7/16  (9..15)
+}
+
+export interface CastInput {
+  /** 'coin' (default) or 'yarrow'. */
+  method?: CastMethod;
+  /** Bytes captured from a human gesture (mouse, touch, motion, keystrokes). */
+  userEntropy?: Uint8Array | number[];
+  /**
+   * Quantum entropy: pass `true` to auto-gather, a QrngConfig to configure the
+   * gather, or a pre-fetched QrngResult[] (e.g. fetched server-side).
+   */
+  qrng?: boolean | QrngConfig | QrngResult[];
+  /** Reproduce a prior cast from its seed (hex fingerprint). */
+  seed?: string;
+  /** Override the clock (mainly for tests/determinism). */
+  now?: () => number;
+}
+
+const BYTES_TO_GATHER = 48;
+const STREAM_BYTES = 64; // 6 lines need at most 24 bits; 64 bytes is generous headroom
+
+/**
+ * Cast a reading. Builds an entropy pool from the querent's gesture, optional
+ * quantum sources, and the local CSPRNG; squeezes a whitened stream; and draws
+ * six lines bottom -> top, deriving the primary hexagram, the changing lines,
+ * and the transformed hexagram.
+ */
+export async function cast(input: CastInput = {}): Promise<Reading> {
+  const method: CastMethod = input.method ?? 'coin';
+  const now = input.now ?? (() => Date.now());
+
+  let pool: EntropyPool;
+  if (input.seed) {
+    pool = EntropyPool.fromSeed(input.seed);
+  } else {
+    pool = new EntropyPool();
+    if (input.userEntropy && input.userEntropy.length) {
+      pool.absorb('gesture', input.userEntropy);
+    }
+    if (input.qrng) {
+      let results: QrngResult[];
+      if (Array.isArray(input.qrng)) {
+        results = input.qrng;
+      } else {
+        const config = input.qrng === true ? {} : input.qrng;
+        results = await gatherEntropy(BYTES_TO_GATHER, config);
+      }
+      for (const r of results) {
+        if (r.ok && r.bytes && r.bytes.length) pool.absorb(`qrng:${r.source}`, r.bytes);
+      }
+    }
+    // Always fold in a fresh local CSPRNG draw and a timestamp salt.
+    pool.absorb('csprng', localCsprng(32));
+    pool.absorb('time', String(now()));
+  }
+
+  const stream = await pool.squeeze(STREAM_BYTES);
+  const reader = new BitReader(stream);
+
+  const lines: Line[] = [];
+  for (let i = 0; i < 6; i++) {
+    const value = method === 'coin' ? coinLine(reader) : yarrowLine(reader);
+    lines.push({
+      position: i + 1,
+      value,
+      yang: value === 7 || value === 9,
+      changing: value === 6 || value === 9,
+    });
+  }
+
+  const primaryBits = lines.map((l) => (l.yang ? 1 : 0)) as Bit[] as HexBits;
+  const primary = hexagramByBits(primaryBits);
+
+  const changingPositions = lines.filter((l) => l.changing).map((l) => l.position);
+
+  let transformed = null as Reading['transformed'];
+  if (changingPositions.length > 0) {
+    const tBits = lines.map((l) => {
+      if (l.changing) return (l.yang ? 0 : 1) as Bit; // old yang -> yin, old yin -> yang
+      return (l.yang ? 1 : 0) as Bit;
+    }) as Bit[] as HexBits;
+    transformed = hexagramByBits(tBits);
+  }
+
+  return {
+    method,
+    lines,
+    primary,
+    transformed,
+    changingPositions,
+    seed: await pool.fingerprint(),
+    sources: pool.transcript,
+    createdAt: new Date(now()).toISOString(),
+  };
+}
+
+export { coinLine, yarrowLine };

package/src/engine.test.ts

@@ -0,0 +1,77 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { cast } from './casting.js';
+import { EntropyPool } from './entropy/pool.js';
+import { HEXAGRAMS, hexagramByBits, hexagramByNumber, validateHexagrams } from './hexagrams.js';
+import { BitReader } from './util.js';
+import { coinLine, yarrowLine } from './casting.js';
+
+test('dataset passes deterministic structural validation', () => {
+  const result = validateHexagrams();
+  assert.equal(result.ok, true, result.errors.join('\n'));
+  assert.equal(HEXAGRAMS.length, 64);
+});
+
+test('every hexagram has complete prose', () => {
+  for (const h of HEXAGRAMS) {
+    assert.ok(h.judgment.length > 10, `#${h.number} judgment`);
+    assert.ok(h.image.length > 10, `#${h.number} image`);
+    assert.ok(h.gloss.length > 2, `#${h.number} gloss`);
+    assert.equal(h.lineTexts.length, 6, `#${h.number} lineTexts`);
+    for (const lt of h.lineTexts) assert.ok(lt.length > 3, `#${h.number} line text`);
+  }
+});
+
+test('hexagram 1 is Qian (all yang), 2 is Kun (all yin)', () => {
+  assert.equal(hexagramByNumber(1).bits.join(''), '111111');
+  assert.equal(hexagramByNumber(2).bits.join(''), '000000');
+  assert.equal(hexagramByBits([1, 1, 1, 1, 1, 1]).number, 1);
+  assert.equal(hexagramByBits([0, 0, 0, 0, 0, 0]).number, 2);
+});
+
+test('a seed reproduces an identical reading', async () => {
+  const a = await cast({ userEntropy: [1, 2, 3, 4, 5], now: () => 1000 });
+  const b = await cast({ seed: a.seed, now: () => 1000 });
+  assert.equal(a.primary.number, b.primary.number);
+  assert.equal(a.transformed?.number ?? null, b.transformed?.number ?? null);
+  assert.deepEqual(a.lines.map((l) => l.value), b.lines.map((l) => l.value));
+});
+
+test('coin distribution ~ 1/8, 3/8, 3/8, 1/8', async () => {
+  const counts: Record<number, number> = { 6: 0, 7: 0, 8: 0, 9: 0 };
+  const N = 200_000;
+  // deterministic uniform bytes from the pool, expanded large
+  const stream = await EntropyPool.fromSeed('00'.repeat(32)).squeeze(Math.ceil((N * 3) / 8) + 64);
+  const reader = new BitReader(stream);
+  for (let i = 0; i < N; i++) counts[coinLine(reader)]++;
+  assert.ok(Math.abs(counts[6] / N - 1 / 8) < 0.01, `6: ${counts[6] / N}`);
+  assert.ok(Math.abs(counts[7] / N - 3 / 8) < 0.01, `7: ${counts[7] / N}`);
+  assert.ok(Math.abs(counts[8] / N - 3 / 8) < 0.01, `8: ${counts[8] / N}`);
+  assert.ok(Math.abs(counts[9] / N - 1 / 8) < 0.01, `9: ${counts[9] / N}`);
+});
+
+test('yarrow distribution ~ 1/16, 5/16, 7/16, 3/16', async () => {
+  const counts: Record<number, number> = { 6: 0, 7: 0, 8: 0, 9: 0 };
+  const N = 200_000;
+  const stream = await EntropyPool.fromSeed('a5'.repeat(32)).squeeze(Math.ceil((N * 4) / 8) + 64);
+  const reader = new BitReader(stream);
+  for (let i = 0; i < N; i++) counts[yarrowLine(reader)]++;
+  assert.ok(Math.abs(counts[6] / N - 1 / 16) < 0.01, `6: ${counts[6] / N}`);
+  assert.ok(Math.abs(counts[7] / N - 5 / 16) < 0.01, `7: ${counts[7] / N}`);
+  assert.ok(Math.abs(counts[8] / N - 7 / 16) < 0.01, `8: ${counts[8] / N}`);
+  assert.ok(Math.abs(counts[9] / N - 3 / 16) < 0.01, `9: ${counts[9] / N}`);
+});
+
+test('changing lines produce a distinct transformed hexagram', async () => {
+  // search seeds for a cast with changing lines
+  let found = false;
+  for (let i = 0; i < 50 && !found; i++) {
+    const r = await cast({ userEntropy: [i], now: () => i });
+    if (r.changingPositions.length > 0) {
+      assert.ok(r.transformed, 'should have transformed hexagram');
+      assert.notEqual(r.transformed!.number, r.primary.number);
+      found = true;
+    }
+  }
+  assert.ok(found, 'expected at least one changing-line cast in 50 tries');
+});

package/src/entropy/gesture.ts

@@ -0,0 +1,57 @@
+/**
+ * A platform-agnostic accumulator for human "gesture" entropy: pointer moves,
+ * touch paths, device-motion samples, keystroke timings — anything the
+ * querent's body does while they hold their question in mind.
+ *
+ * It does not try to estimate entropy precisely; it simply captures the raw
+ * float bytes of each sample. The EntropyPool hashes everything afterward, so
+ * over-capture is harmless and a few genuinely unpredictable bits (the timing
+ * jitter of a human hand) are what matter.
+ */
+export class GestureEntropy {
+  private buf: number[] = [];
+  private _count = 0;
+
+  /** Number of samples captured. */
+  get count(): number {
+    return this._count;
+  }
+
+  private pushFloat(v: number): void {
+    if (!Number.isFinite(v)) v = 0;
+    const dv = new DataView(new ArrayBuffer(4));
+    dv.setFloat32(0, v, true);
+    this.buf.push(dv.getUint8(0), dv.getUint8(1), dv.getUint8(2), dv.getUint8(3));
+  }
+
+  /** Record a pointer/touch sample at (x, y) with a high-resolution timestamp. */
+  push(x: number, y: number, t: number): this {
+    this.pushFloat(x);
+    this.pushFloat(y);
+    this.pushFloat(t);
+    this._count += 1;
+    return this;
+  }
+
+  /** Record a single scalar (e.g. an accelerometer axis or a key interval). */
+  pushScalar(v: number): this {
+    this.pushFloat(v);
+    this._count += 1;
+    return this;
+  }
+
+  /** The captured bytes. */
+  get bytes(): Uint8Array {
+    return Uint8Array.from(this.buf);
+  }
+
+  /** A coarse 0..1 sense of "how much" the querent has stirred — for UI meters. */
+  get fill(): number {
+    return Math.min(1, this._count / 96);
+  }
+
+  reset(): void {
+    this.buf = [];
+    this._count = 0;
+  }
+}

package/src/entropy/pool.ts

@@ -0,0 +1,74 @@
+import { concatBytes, fromHex, sha256, toBytes, toHex } from '../util.js';
+import type { EntropySourceRecord } from '../types.js';
+
+/**
+ * An entropy pool that absorbs bytes from many labelled sources (a human
+ * gesture, one or more quantum RNGs, a local CSPRNG) and squeezes a
+ * whitened, uniform byte stream out of them.
+ *
+ * Design: extract-then-expand, HKDF-style.
+ *   PRK        = SHA-256( source_1 || source_2 || ... )      (the "seed")
+ *   output_i   = SHA-256( PRK || counter_i )                 (the expansion)
+ *
+ * No single source can bias the result, a dead QRNG can't block a cast, and
+ * the PRK is exposed as a hex `fingerprint()` so a reading is fully
+ * reproducible from its seed — the basis for shareable, auditable casts.
+ */
+export class EntropyPool {
+  private chunks: { label: string; bytes: Uint8Array }[] = [];
+  private _prk: Uint8Array | null = null;
+
+  /** Absorb bytes from a source. Chainable. */
+  absorb(label: string, data: Uint8Array | number[] | string): this {
+    if (this._prk) {
+      throw new Error('Cannot absorb into a pool created from a fixed seed.');
+    }
+    const bytes = toBytes(data);
+    if (bytes.length > 0) this.chunks.push({ label, bytes });
+    return this;
+  }
+
+  /** A transcript of what contributed entropy and how much. */
+  get transcript(): EntropySourceRecord[] {
+    if (this._prk) return [{ label: 'seed', bytes: this._prk.length }];
+    return this.chunks.map((c) => ({ label: c.label, bytes: c.bytes.length }));
+  }
+
+  private async prk(): Promise<Uint8Array> {
+    if (this._prk) return this._prk;
+    const all = concatBytes(this.chunks.map((c) => c.bytes));
+    this._prk = await sha256(all);
+    return this._prk;
+  }
+
+  /** The reproducible seed: hex of the extracted pseudo-random key. */
+  async fingerprint(): Promise<string> {
+    return toHex(await this.prk());
+  }
+
+  /** Produce `numBytes` of uniform output, deterministic for a given PRK. */
+  async squeeze(numBytes: number): Promise<Uint8Array> {
+    const prk = await this.prk();
+    const out = new Uint8Array(numBytes);
+    let off = 0;
+    let counter = 0;
+    while (off < numBytes) {
+      const input = new Uint8Array(prk.length + 4);
+      input.set(prk, 0);
+      new DataView(input.buffer).setUint32(prk.length, counter, false);
+      counter += 1;
+      const block = await sha256(input);
+      const take = Math.min(block.length, numBytes - off);
+      out.set(block.subarray(0, take), off);
+      off += take;
+    }
+    return out;
+  }
+
+  /** Reconstruct a pool from a previously emitted seed (hex of the PRK). */
+  static fromSeed(seedHex: string): EntropyPool {
+    const pool = new EntropyPool();
+    pool._prk = fromHex(seedHex);
+    return pool;
+  }
+}

package/src/entropy/qrng.ts

@@ -0,0 +1,170 @@
+import { fromHex, getCrypto } from '../util.js';
+
+/**
+ * Quantum / true random number sources.
+ *
+ * Honest note: a local CSPRNG is already statistically perfect for casting an
+ * oracle. The quantum sources are here for *meaning* — your hexagram drawn
+ * from vacuum fluctuations and an atmospheric hiss — and for transparency, not
+ * because they are "more random". Every gather always folds in the local
+ * CSPRNG so a cast can never be blocked or biased by a flaky remote API.
+ */
+
+export type QrngSourceName = 'nist' | 'anu' | 'random.org' | 'csprng';
+
+export interface QrngResult {
+  source: QrngSourceName;
+  ok: boolean;
+  bytes: Uint8Array | null;
+  detail?: string;
+}
+
+export interface QrngConfig {
+  /** Which sources to attempt. Default: ['nist', 'csprng']. csprng is always included. */
+  sources?: QrngSourceName[];
+  anuApiKey?: string;
+  randomOrgApiKey?: string;
+  /** Inject a fetch implementation (defaults to global fetch). */
+  fetchImpl?: typeof fetch;
+  /** Per-request timeout in ms (default 6000). */
+  timeoutMs?: number;
+}
+
+export function localCsprng(numBytes: number): Uint8Array {
+  const out = new Uint8Array(numBytes);
+  getCrypto().getRandomValues(out);
+  return out;
+}
+
+function getFetch(config: QrngConfig): typeof fetch {
+  const f = config.fetchImpl ?? (globalThis as { fetch?: typeof fetch }).fetch;
+  if (!f) throw new Error('No fetch implementation available.');
+  return f;
+}
+
+async function withTimeout<T>(p: (signal: AbortSignal) => Promise<T>, ms: number): Promise<T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  try {
+    return await p(controller.signal);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * NIST Randomness Beacon (v2). Public, keyless, quantum-seeded. Publishes a
+ * 512-bit value every 60s — the same for everyone in a given minute, which is
+ * its own kind of poetry: the cosmic pulse at the moment you asked.
+ */
+export async function fetchNistBeacon(numBytes: number, config: QrngConfig = {}): Promise<QrngResult> {
+  const fetchImpl = getFetch(config);
+  try {
+    const res = await withTimeout(
+      (signal) =>
+        fetchImpl('https://beacon.nist.gov/beacon/2.0/pulse/last', { signal }),
+      config.timeoutMs ?? 6000,
+    );
+    if (!res.ok) return { source: 'nist', ok: false, bytes: null, detail: `HTTP ${res.status}` };
+    const json = (await res.json()) as { pulse?: { outputValue?: string } };
+    const hex = json?.pulse?.outputValue;
+    if (!hex) return { source: 'nist', ok: false, bytes: null, detail: 'no outputValue' };
+    const full = fromHex(hex);
+    return { source: 'nist', ok: true, bytes: full.subarray(0, numBytes) };
+  } catch (err) {
+    return { source: 'nist', ok: false, bytes: null, detail: String(err) };
+  }
+}
+
+/**
+ * ANU Quantum Random Numbers — vacuum fluctuations. The classic public
+ * endpoint is now rate-limited and may require an API key; we pass one if
+ * provided and fail gracefully otherwise.
+ */
+export async function fetchAnu(numBytes: number, config: QrngConfig = {}): Promise<QrngResult> {
+  const fetchImpl = getFetch(config);
+  try {
+    const url = `https://qrng.anu.edu.au/API/jsonI.php?length=${numBytes}&type=uint8`;
+    const headers: Record<string, string> = {};
+    if (config.anuApiKey) headers['x-api-key'] = config.anuApiKey;
+    const res = await withTimeout(
+      (signal) => fetchImpl(url, { headers, signal }),
+      config.timeoutMs ?? 6000,
+    );
+    if (!res.ok) return { source: 'anu', ok: false, bytes: null, detail: `HTTP ${res.status}` };
+    const json = (await res.json()) as { success?: boolean; data?: number[] };
+    if (!json?.success || !Array.isArray(json.data)) {
+      return { source: 'anu', ok: false, bytes: null, detail: 'unsuccessful response' };
+    }
+    return { source: 'anu', ok: true, bytes: Uint8Array.from(json.data.slice(0, numBytes)) };
+  } catch (err) {
+    return { source: 'anu', ok: false, bytes: null, detail: String(err) };
+  }
+}
+
+/** RANDOM.ORG atmospheric noise (JSON-RPC v4). Requires an API key. */
+export async function fetchRandomOrg(numBytes: number, config: QrngConfig = {}): Promise<QrngResult> {
+  const fetchImpl = getFetch(config);
+  if (!config.randomOrgApiKey) {
+    return { source: 'random.org', ok: false, bytes: null, detail: 'no API key' };
+  }
+  try {
+    const body = {
+      jsonrpc: '2.0',
+      method: 'generateIntegers',
+      params: { apiKey: config.randomOrgApiKey, n: numBytes, min: 0, max: 255, replacement: true },
+      id: 1,
+    };
+    const res = await withTimeout(
+      (signal) =>
+        fetchImpl('https://api.random.org/json-rpc/4/invoke', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(body),
+          signal,
+        }),
+      config.timeoutMs ?? 6000,
+    );
+    if (!res.ok) return { source: 'random.org', ok: false, bytes: null, detail: `HTTP ${res.status}` };
+    const json = (await res.json()) as { result?: { random?: { data?: number[] } } };
+    const data = json?.result?.random?.data;
+    if (!Array.isArray(data)) {
+      return { source: 'random.org', ok: false, bytes: null, detail: 'no data' };
+    }
+    return { source: 'random.org', ok: true, bytes: Uint8Array.from(data) };
+  } catch (err) {
+    return { source: 'random.org', ok: false, bytes: null, detail: String(err) };
+  }
+}
+
+/**
+ * Attempt every configured source concurrently and always include the local
+ * CSPRNG. Returns one result per attempted source (failures included, so the
+ * UI can show what answered the call).
+ */
+export async function gatherEntropy(numBytes: number, config: QrngConfig = {}): Promise<QrngResult[]> {
+  const requested = config.sources ?? ['nist', 'csprng'];
+  const set = new Set<QrngSourceName>(requested);
+  set.add('csprng'); // guaranteed fallback, always present
+
+  const jobs: Promise<QrngResult>[] = [];
+  for (const source of set) {
+    switch (source) {
+      case 'nist':
+        jobs.push(fetchNistBeacon(numBytes, config));
+        break;
+      case 'anu':
+        jobs.push(fetchAnu(numBytes, config));
+        break;
+      case 'random.org':
+        jobs.push(fetchRandomOrg(numBytes, config));
+        break;
+      case 'csprng':
+        jobs.push(
+          Promise.resolve({ source: 'csprng' as const, ok: true, bytes: localCsprng(numBytes) }),
+        );
+        break;
+    }
+  }
+  return Promise.all(jobs);
+}