hbengine 0.2.3

package/engine-shell/verifiers/badcat/rps.tsv

@@ -0,0 +1,3 @@
+1	{"hand":"rock"}
+1	{"hand":"paper"}
+1	{"hand":"scissors"}

package/engine-shell/verifiers/badcat/triple.tsv

@@ -0,0 +1,66 @@
+1	{"coin":0,"hand":"rock","sum":2}
+1	{"coin":0,"hand":"paper","sum":2}
+1	{"coin":0,"hand":"scissors","sum":2}
+2	{"coin":0,"hand":"rock","sum":3}
+2	{"coin":0,"hand":"paper","sum":3}
+2	{"coin":0,"hand":"scissors","sum":3}
+3	{"coin":0,"hand":"rock","sum":4}
+3	{"coin":0,"hand":"paper","sum":4}
+3	{"coin":0,"hand":"scissors","sum":4}
+4	{"coin":0,"hand":"rock","sum":5}
+4	{"coin":0,"hand":"paper","sum":5}
+4	{"coin":0,"hand":"scissors","sum":5}
+5	{"coin":0,"hand":"rock","sum":6}
+5	{"coin":0,"hand":"paper","sum":6}
+5	{"coin":0,"hand":"scissors","sum":6}
+6	{"coin":0,"hand":"rock","sum":7}
+6	{"coin":0,"hand":"paper","sum":7}
+6	{"coin":0,"hand":"scissors","sum":7}
+5	{"coin":0,"hand":"rock","sum":8}
+5	{"coin":0,"hand":"paper","sum":8}
+5	{"coin":0,"hand":"scissors","sum":8}
+4	{"coin":0,"hand":"rock","sum":9}
+4	{"coin":0,"hand":"paper","sum":9}
+4	{"coin":0,"hand":"scissors","sum":9}
+3	{"coin":0,"hand":"rock","sum":10}
+3	{"coin":0,"hand":"paper","sum":10}
+3	{"coin":0,"hand":"scissors","sum":10}
+2	{"coin":0,"hand":"rock","sum":11}
+2	{"coin":0,"hand":"paper","sum":11}
+2	{"coin":0,"hand":"scissors","sum":11}
+1	{"coin":0,"hand":"rock","sum":12}
+1	{"coin":0,"hand":"paper","sum":12}
+1	{"coin":0,"hand":"scissors","sum":12}
+1	{"coin":1,"hand":"rock","sum":2}
+1	{"coin":1,"hand":"paper","sum":2}
+1	{"coin":1,"hand":"scissors","sum":2}
+2	{"coin":1,"hand":"rock","sum":3}
+2	{"coin":1,"hand":"paper","sum":3}
+2	{"coin":1,"hand":"scissors","sum":3}
+3	{"coin":1,"hand":"rock","sum":4}
+3	{"coin":1,"hand":"paper","sum":4}
+3	{"coin":1,"hand":"scissors","sum":4}
+4	{"coin":1,"hand":"rock","sum":5}
+4	{"coin":1,"hand":"paper","sum":5}
+4	{"coin":1,"hand":"scissors","sum":5}
+5	{"coin":1,"hand":"rock","sum":6}
+5	{"coin":1,"hand":"paper","sum":6}
+5	{"coin":1,"hand":"scissors","sum":6}
+6	{"coin":1,"hand":"rock","sum":7}
+6	{"coin":1,"hand":"paper","sum":7}
+6	{"coin":1,"hand":"scissors","sum":7}
+5	{"coin":1,"hand":"rock","sum":8}
+5	{"coin":1,"hand":"paper","sum":8}
+5	{"coin":1,"hand":"scissors","sum":8}
+4	{"coin":1,"hand":"rock","sum":9}
+4	{"coin":1,"hand":"paper","sum":9}
+4	{"coin":1,"hand":"scissors","sum":9}
+3	{"coin":1,"hand":"rock","sum":10}
+3	{"coin":1,"hand":"paper","sum":10}
+3	{"coin":1,"hand":"scissors","sum":10}
+2	{"coin":1,"hand":"rock","sum":11}
+2	{"coin":1,"hand":"paper","sum":11}
+2	{"coin":1,"hand":"scissors","sum":11}
+1	{"coin":1,"hand":"rock","sum":12}
+1	{"coin":1,"hand":"paper","sum":12}
+1	{"coin":1,"hand":"scissors","sum":12}

package/engine-shell/verifiers/engine-verify.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+'use strict';
+// House Engine `engine-v1` verifier (SPEC.md §1–2), independent of the Go
+// server. Node ≥ 18, no dependencies. Reproduces a math pack's hash and
+// re-derives any round from (serverSeed, clientSeed, nonce, mode, bet).
+//
+//   node engine-verify.js <packDir> [vectors.json]
+//
+// With vectors.json (the Go package's golden file) it checks every vector
+// and exits non-zero on the first difference. As a module it exports
+// loadPack, mathHash, play and canonicalJSON for the SDK and the public
+// fairness page.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+// ---- bytes → text, as the Go reference reads them ----------------------------
+// A pack is UTF-8. The manifest's bytes are the document's — hashed, served
+// and kept as they are — so a manifest that is not well-formed UTF-8 is
+// refused, as the Go gate refuses it (mathpack.Load). A table's bytes are
+// canonicalised on the way in: there Go's decoder turns every byte that does
+// not start a well-formed UTF-8 sequence into U+FFFD, one per byte (a
+// truncated three-byte sequence is two U+FFFD). Node's own decoder folds such
+// a sequence into one, so a table file is walked here and only well-formed
+// runs are handed to it.
+
+function readManifestText(file) {
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(file));
+  } catch (e) {
+    throw new Error(`${path.basename(file)}: not valid UTF-8`);
+  }
+}
+
+function readText(file) {
+  const b = fs.readFileSync(file);
+  const parts = [];
+  let start = 0;
+  for (let i = 0; i < b.length; ) {
+    const n = b[i] < 0x80 ? 1 : utf8Length(b, i);
+    if (n > 0) { i += n; continue; }
+    parts.push(b.toString('utf8', start, i), '\ufffd');
+    i++;
+    start = i;
+  }
+  if (start === 0) return b.toString('utf8');
+  parts.push(b.toString('utf8', start));
+  return parts.join('');
+}
+
+// utf8Length is the length of the well-formed sequence starting at i, or 0
+// (overlong forms, encoded surrogates and code points past U+10FFFF are not
+// well-formed, as for Go's utf8.DecodeRune).
+function utf8Length(b, i) {
+  const c = b[i];
+  const cont = (k, lo = 0x80, hi = 0xbf) => i + k < b.length && b[i + k] >= lo && b[i + k] <= hi;
+  if (c >= 0xc2 && c <= 0xdf) return cont(1) ? 2 : 0;
+  if (c === 0xe0) return cont(1, 0xa0) && cont(2) ? 3 : 0;
+  if ((c >= 0xe1 && c <= 0xec) || c === 0xee || c === 0xef) return cont(1) && cont(2) ? 3 : 0;
+  if (c === 0xed) return cont(1, 0x80, 0x9f) && cont(2) ? 3 : 0;
+  if (c === 0xf0) return cont(1, 0x90) && cont(2) && cont(3) ? 4 : 0;
+  if (c >= 0xf1 && c <= 0xf3) return cont(1) && cont(2) && cont(3) ? 4 : 0;
+  if (c === 0xf4) return cont(1, 0x80, 0x8f) && cont(2) && cont(3) ? 4 : 0;
+  return 0;
+}
+
+// ---- canonical JSON: keys sorted, no whitespace, numbers as written ---------
+// A tiny parser that keeps each number's source text, so `2.50` stays `2.50`
+// exactly as the Go reference does. Strings are escaped the way Go's
+// encoding/json escapes them: `"` `\` and the short escapes \b \f \n \r \t,
+// every other control character as \u00xx, `<` `>` `&` U+2028 U+2029 as
+// \uXXXX, everything else as itself. An escaped surrogate pair is one code
+// point; a lone surrogate is U+FFFD. Keys sort by code point.
+
+function canonicalJSON(text) {
+  let i = 0;
+  const ws = () => { while (i < text.length && ' \t\r\n'.includes(text[i])) i++; };
+  const fail = (m) => { throw new Error(`canonical json: ${m} at ${i}`); };
+  function value() {
+    ws();
+    const c = text[i];
+    if (c === '{') return object();
+    if (c === '[') return array();
+    if (c === '"') return string();
+    if (c === 't' && text.startsWith('true', i)) { i += 4; return 'true'; }
+    if (c === 'f' && text.startsWith('false', i)) { i += 5; return 'false'; }
+    if (c === 'n' && text.startsWith('null', i)) { i += 4; return 'null'; }
+    const m = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/.exec(text.slice(i));
+    if (!m) fail('unexpected token');
+    i += m[0].length;
+    return m[0];
+  }
+  function object() {
+    i++; ws();
+    const entries = [];
+    if (text[i] === '}') { i++; return '{}'; }
+    for (;;) {
+      ws();
+      if (text[i] !== '"') fail('expected key');
+      const k = rawString();
+      ws();
+      if (text[i] !== ':') fail('expected :');
+      i++;
+      entries.push([k, value()]);
+      ws();
+      if (text[i] === ',') { i++; continue; }
+      if (text[i] === '}') { i++; break; }
+      fail('expected , or }');
+    }
+    if (new Set(entries.map(([k]) => k)).size !== entries.length) fail('duplicate key');
+    entries.sort((a, b) => compareCodePoints(a[0], b[0]));
+    return '{' + entries.map(([k, v]) => escapeString(k) + ':' + v).join(',') + '}';
+  }
+  function array() {
+    i++; ws();
+    const items = [];
+    if (text[i] === ']') { i++; return '[]'; }
+    for (;;) {
+      items.push(value());
+      ws();
+      if (text[i] === ',') { i++; continue; }
+      if (text[i] === ']') { i++; break; }
+      fail('expected , or ]');
+    }
+    return '[' + items.join(',') + ']';
+  }
+  function rawString() {
+    // returns the decoded string
+    i++;
+    let out = '';
+    for (;;) {
+      if (i >= text.length) fail('unterminated string');
+      const c = text[i++];
+      if (c === '"') return out;
+      // A raw control character inside a string is not JSON; Go's scanner
+      // refuses it, so a verifier that escaped it would hash a pack the
+      // gate never takes.
+      if (c.charCodeAt(0) < 0x20) fail('control character in string');
+      if (c !== '\\') { out += c; continue; }
+      const e = text[i++];
+      if (e === 'u') { out += String.fromCodePoint(unicodeEscape()); continue; }
+      const short = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' }[e];
+      if (short === undefined) fail('bad escape');
+      out += short;
+    }
+  }
+  // unicodeEscape reads the XXXX of a \uXXXX (i is just past the u). A high
+  // surrogate followed by an escaped low surrogate is one code point. A
+  // surrogate on its own is U+FFFD, as Go's decoder has it, and whatever
+  // escape follows a lone high surrogate is read on its own.
+  function unicodeEscape() {
+    const cp = hex4(i);
+    i += 4;
+    if (cp < 0xd800 || cp > 0xdfff) return cp;
+    if (cp <= 0xdbff && text[i] === '\\' && text[i + 1] === 'u') {
+      const low = hex4(i + 2);
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        i += 6;
+        return 0x10000 + ((cp - 0xd800) << 10) + (low - 0xdc00);
+      }
+    }
+    return 0xfffd;
+  }
+  function hex4(at) {
+    const h = text.slice(at, at + 4);
+    if (!/^[0-9a-fA-F]{4}$/.test(h)) fail('bad \\u escape');
+    return parseInt(h, 16);
+  }
+  function string() { return escapeString(rawString()); }
+  const out = value();
+  ws();
+  if (i !== text.length) fail('trailing data');
+  return out;
+}
+
+// compareCodePoints orders keys as the Go reference does: by code point,
+// which is UTF-8 byte order. JavaScript's own `<` compares UTF-16 code
+// units, which would put an emoji before U+E000..U+FFFF.
+function compareCodePoints(a, b) {
+  let i = 0, j = 0;
+  while (i < a.length && j < b.length) {
+    const x = a.codePointAt(i), y = b.codePointAt(j);
+    if (x !== y) return x - y;
+    i += x > 0xffff ? 2 : 1;
+    j += y > 0xffff ? 2 : 1;
+  }
+  return (a.length - i) - (b.length - j);
+}
+
+function escapeString(s) {
+  let out = '"';
+  for (const ch of s) {
+    const cp = ch.codePointAt(0);
+    if (ch === '"') out += '\\"';
+    else if (ch === '\\') out += '\\\\';
+    else if (ch === '\b') out += '\\b';
+    else if (ch === '\f') out += '\\f';
+    else if (ch === '\n') out += '\\n';
+    else if (ch === '\r') out += '\\r';
+    else if (ch === '\t') out += '\\t';
+    else if (cp < 0x20 || ch === '<' || ch === '>' || ch === '&' || cp === 0x2028 || cp === 0x2029) {
+      out += '\\u' + cp.toString(16).padStart(4, '0');
+    } else out += ch;
+  }
+  return out + '"';
+}
+
+// ---- pack ------------------------------------------------------------------------
+
+// A weight is what Go's strconv.ParseUint(s, 10, 64) takes: ASCII digits and
+// nothing else. BigInt() alone would also take `0x10`, `+5` and ` 5`, and a
+// verifier must not hash a table the gate refuses.
+const WEIGHT = /^[0-9]+$/;
+
+function parseTable(name, text) {
+  const rows = [];
+  const lines = text.split('\n');
+  if (lines[lines.length - 1] === '') lines.pop();
+  for (const line of lines) {
+    if (line.startsWith('#') && rows.length === 0) continue;
+    const tab = line.indexOf('\t');
+    const field = tab < 0 ? line : line.slice(0, tab);
+    if (!WEIGHT.test(field)) throw new Error(`${name}: weight ${JSON.stringify(field)} is not a decimal integer`);
+    const w = BigInt(field);
+    if (w <= 0n) throw new Error(`${name}: weight must be > 0`);
+    let data = null;
+    if (tab >= 0) {
+      // The data column is one JSON value: never empty, never holding a
+      // second tab or a carriage return (a CRLF file is refused, as in Go).
+      const rest = line.slice(tab + 1);
+      if (rest === '' || /[\t\r]/.test(rest)) throw new Error(`${name}: malformed data column`);
+      data = canonicalJSON(rest);
+    }
+    rows.push({ weight: w, data });
+  }
+  if (rows.length < 2) throw new Error(`${name}: needs at least 2 rows`);
+  const cum = [];
+  let sum = 0n;
+  for (const r of rows) { sum += r.weight; cum.push(sum); }
+  if (sum > (1n << 63n)) throw new Error(`${name}: weights sum past 2^63`);
+  return { name, rows, cum, sum };
+}
+
+function tableBytes(t) {
+  return t.rows.map((r) => r.weight.toString() + (r.data === null ? '' : '\t' + r.data) + '\n').join('');
+}
+
+function loadPack(dir) {
+  const manifestText = readManifestText(path.join(dir, 'manifest.json'));
+  const manifest = JSON.parse(manifestText);
+  const tables = {};
+  for (const m of manifest.modes) {
+    const names = m.kind === 'table' ? [m.table] : m.steps.map((s) => s.table);
+    for (const n of names) if (!tables[n]) tables[n] = parseTable(n, readText(path.join(dir, n)));
+  }
+  return { manifest, manifestText, tables };
+}
+
+function mathHash(pack) {
+  let s = 'house-engine-math/1\n';
+  s += 'manifest\n' + canonicalJSON(pack.manifestText) + '\n';
+  for (const name of Object.keys(pack.tables).sort()) s += 'table ' + name + '\n' + tableBytes(pack.tables[name]);
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+// ---- engine-v1 stream and draw ----------------------------------------------------
+
+function stream(serverSeed, clientSeed, nonce) {
+  let block = 0, buf = Buffer.alloc(0), off = 0;
+  const byte = () => {
+    if (off >= buf.length) {
+      buf = crypto.createHmac('sha256', serverSeed).update(`${clientSeed}:${nonce}:${block}`).digest();
+      block++; off = 0;
+    }
+    return buf[off++];
+  };
+  return { u64() { let v = 0n; for (let k = 0; k < 8; k++) v = (v << 8n) | BigInt(byte()); return v; } };
+}
+
+const TWO64 = 1n << 64n;
+
+function pick(table, s) {
+  const rem = TWO64 % table.sum;
+  const limit = TWO64 - rem;
+  let rejected = 0;
+  for (;;) {
+    const v = s.u64();
+    if (v < limit) {
+      const r = v % table.sum;
+      let lo = 0, hi = table.cum.length - 1;
+      while (lo < hi) { const mid = (lo + hi) >> 1; if (table.cum[mid] > r) hi = mid; else lo = mid + 1; }
+      return { raw: v, rejected, index: lo };
+    }
+    rejected++;
+  }
+}
+
+const inRanges = (rs, i) => rs.some(([lo, hi]) => i >= lo && i <= hi);
+
+function play(pack, modeId, betId, serverSeed, clientSeed, nonce) {
+  const mode = pack.manifest.modes.find((m) => m.id === modeId);
+  if (!mode) throw new Error(`no mode ${modeId}`);
+  const bet = mode.bets.find((b) => b.id === betId);
+  if (!bet) throw new Error(`no bet ${betId}`);
+  const s = stream(serverSeed, clientSeed, nonce);
+  if (mode.kind === 'table') {
+    const d = pick(pack.tables[mode.table], s);
+    const tier = bet.tiers.find((t) => inRanges(t.outcomes, d.index));
+    return { mode: modeId, bet: betId, draws: [d], multBp: tier ? tier.multBp : 0 };
+  }
+  const draws = []; let survived = 0, busted = false;
+  for (const step of mode.steps) {
+    const d = pick(pack.tables[step.table], s);
+    draws.push(d);
+    if (!busted && inRanges(bet.survive, d.index)) survived++; else busted = true;
+  }
+  busted = survived < mode.steps.length;
+  const multBp = mode.autoAdvance && !busted ? mode.ladderBp[mode.steps.length - 1] : 0;
+  return { mode: modeId, bet: betId, draws, multBp, survived, busted };
+}
+
+// ---- CLI -------------------------------------------------------------------------
+
+function checkVectors(pack, file) {
+  // A vector's raw draw is a decimal string: a u64 does not survive a JSON number.
+  const v = JSON.parse(readText(file));
+  const hash = mathHash(pack);
+  if (hash !== v.mathHash) return `mathHash ${hash} != ${v.mathHash}`;
+  for (const vec of v.vectors) {
+    const got = play(pack, vec.mode, vec.bet, v.serverSeed, v.clientSeed, vec.nonce);
+    const want = vec.draws;
+    if (got.draws.length !== want.length) return `${vec.mode}/${vec.bet}: ${got.draws.length} draws, want ${want.length}`;
+    for (let k = 0; k < want.length; k++) {
+      const g = got.draws[k], w = want[k];
+      if (g.raw.toString() !== w.raw || g.index !== w.index || (g.rejected || 0) !== (w.rejected || 0)) {
+        return `${vec.mode}/${vec.bet} draw ${k}: ${g.raw}/${g.index}/${g.rejected} want ${w.raw}/${w.index}/${w.rejected || 0}`;
+      }
+    }
+    if (got.multBp !== vec.multBp) return `${vec.mode}/${vec.bet}: multBp ${got.multBp} want ${vec.multBp}`;
+    if ((got.survived || 0) !== (vec.survived || 0)) return `${vec.mode}/${vec.bet}: survived ${got.survived} want ${vec.survived}`;
+  }
+  return null;
+}
+
+if (require.main === module) {
+  const [dir, vectors] = process.argv.slice(2);
+  if (!dir) { console.error('usage: engine-verify.js <packDir> [vectors.json]'); process.exit(2); }
+  const pack = loadPack(dir);
+  console.log('mathHash ' + mathHash(pack));
+  if (vectors) {
+    const problem = checkVectors(pack, vectors);
+    if (problem) { console.error('MISMATCH ' + problem); process.exit(1); }
+    console.log('vectors OK');
+  }
+}
+
+module.exports = { canonicalJSON, loadPack, mathHash, play, stream, pick, checkVectors };

package/engine-shell/verifiers/package.json

@@ -0,0 +1,5 @@
+{
+    "type": "commonjs",
+    "private": true,
+    "description": "The backend's reference verifier, byte for byte (housegames-backend internal/engine/verifiers/engine-verify.js): CommonJS, so this marker keeps it runnable beside the ESM shell."
+}

package/engine-shell/verifiers/parity/manifest.json

@@ -0,0 +1,27 @@
+{
+  "format": "house-engine-math/1",
+  "game": "parity",
+  "rtpBp": 9900,
+  "modes": [
+    {
+      "id": "pick",
+      "label": "Pick \ud83d\udc31",
+      "kind": "table",
+      "table": "wide.tsv",
+      "bets": [
+        { "id": "first", "label": "First third", "tiers": [{ "outcomes": [[0, 0]], "multBp": 29700 }] },
+        { "id": "either", "tiers": [{ "outcomes": [[0, 1]], "multBp": 14850 }] },
+        { "id": "third", "tiers": [{ "outcomes": [[2, 2]], "multBp": 59400 }] },
+        { "id": "last", "tiers": [{ "outcomes": [[3, 3]], "multBp": 59400 }] }
+      ]
+    },
+    {
+      "id": "climb",
+      "kind": "ladder",
+      "steps": [{ "table": "wide.tsv" }, { "table": "wide.tsv" }],
+      "cashout": true,
+      "ladderBp": [14850, 22275],
+      "bets": [{ "id": "go", "survive": [[0, 1]] }]
+    }
+  ]
+}

package/engine-shell/verifiers/parity/wide.tsv

@@ -0,0 +1,5 @@
+# parity: weights sum to 3*2^61, so one draw in four is rejected; row data holds every escape the canonical form has a rule for
+2305843009213693952	{"z":"tab\tnew\nline","a":"back\bform\f","b":"\u0001\u001f"}
+2305843009213693952	{"html":"<a href=\"x\">&</a>","sep":"\u2028\u2029","del":"\u007f"}
+1152921504606846976	{"raw":"🐱","cat":"\ud83d\udc31","lone":"\ud83d x","low":"\udc31","hi":"\ud83d\u0041","pair":"\ud83d\ude00","num":[1,2.50,-0,1E5,10000000000000000000]}
+1152921504606846976	{"\ud83d\ude00":1,"\ufb01":2,"z":3,"\u00e9":4,"bad":"�� ok"}