tinydecide 0.0.0-stage → 0.1.2

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "tinydecide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Wrap your decision API. TinyDecide learns from its answers and takes over the calls it can answer locally, in microseconds, with agreement certified.",
+  "keywords": [
+    "classification",
+    "classifier",
+    "llm",
+    "distillation",
+    "cost",
+    "latency",
+    "routing",
+    "conformal",
+    "edge",
+    "bun"
+  ],
+  "author": "Christian Yun",
+  "license": "MIT",
+  "homepage": "https://github.com/Christian1011/tinydecide#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Christian1011/tinydecide.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Christian1011/tinydecide/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "browser": "./src/index.js",
+      "node": "./src/node.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./types/index.d.ts",
+  "bin": {
+    "tinydecide": "./bin/tinydecide.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "types",
+    "examples/support-api.js"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "test:bun": "bun test ./test/",
+    "typecheck": "npx -y -p typescript@5.9.3 tsc -p test/tsconfig.json",
+    "bench:guard": "node bench/guard-drift.js change 10",
+    "prepublishOnly": "npm test"
+  }
+}

package/src/compile.js

@@ -0,0 +1,265 @@
+// compile(): trains a local model on your API's answers and certifies a cutoff.
+//
+//   1. Split rows into train / calib / test by group (or by normalized text), so repeats never leak.
+//   2. Train on train, quantize to int8. Every later number is measured on the int8 model you ship.
+//   3. On calib, certify the loosest margin cutoff that keeps agreement with the API ≥ target,
+//      with probability ≥ 1 − delta over the draw of calibration rows (Learn-Then-Test).
+//   4. On test, report what that cutoff actually did, with Wilson intervals.
+
+import { Featurizer, inputKey } from './features.js';
+import { hashString } from './hash.js';
+import { Model, quantize, softmax, topTwo } from './model.js';
+import { certify, localStart, minCalibration, wilson } from './stats.js';
+import { RECIPE, abortError, tick, train } from './train.js';
+
+export const DEFAULTS = Object.freeze({ target: 0.98, delta: 0.05, guarantee: 'overall', calib: 0.25, test: 0.1, seed: 1, audit: 0.02 });
+
+// Cutoffs on the logit margin. Fixed in advance, as Learn-Then-Test requires.
+const GRID = [0, ...Array.from({ length: 600 }, (_, i) => 0.01 * 6000 ** (i / 599))];
+const WHAT_IF = [0.9, 0.95, 0.97, 0.98, 0.99, 0.995];
+
+/**
+ * @param {Iterable<object>} records  { input, choice?, probs?, group? }; see README for accepted shapes
+ * @param {object} [opts]
+ * @returns {Promise<{ model: Model, report: object }>}
+ */
+export async function compile(records, opts = {}) {
+  const o = { ...DEFAULTS, ...opts };
+  for (const k of ['target', 'delta']) {
+    if (!(typeof o[k] === 'number' && o[k] > 0 && o[k] < 1)) throw new RangeError(`${k} must be a number between 0 and 1; got ${o[k]}`);
+  }
+  if (o.guarantee !== 'overall' && o.guarantee !== 'local') throw new RangeError(`guarantee must be "overall" or "local"; got ${o.guarantee}`);
+  const alpha = 1 - o.target;
+  const t0 = performance.now();
+  const onProgress = o.onProgress ?? (() => {});
+  const pause = async () => { await tick(); if (o.signal?.aborted) throw abortError(); };
+
+  const { labels, rows, skipped } = readRecords(records, o.labels);
+  const K = labels.length;
+  if (K < 2) throw new Error(`need at least two labels, saw ${K}`);
+
+  const split = { train: [], calib: [], test: [] };
+  const salt = 0x7f4a7c15 ^ o.seed;
+  for (const r of rows) {
+    const u = (hashString(r.group, salt) % 100_000) / 100_000;
+    const part = u < o.test ? 'test' : u < o.test + o.calib ? 'calib' : 'train';
+    if (r.trainOnly && part !== 'train') continue; // not an iid draw of traffic, so never certify on it
+    split[part].push(r);
+  }
+  if (split.train.length < 2 * K) throw new Error(`only ${split.train.length} training rows for ${K} labels`);
+
+  onProgress({ phase: 'features', done: 0 });
+  const fz = new Featurizer();
+  const trainRows = [];
+  for (const r of split.train) {
+    trainRows.push({ ...fz.copy(r.input), t: r.t });
+    if (trainRows.length % 2000 === 0) await pause();
+  }
+  const params = await train(trainRows, K, { ...pick(o, Object.keys(RECIPE)), seed: o.seed, onProgress, yieldMs: o.yieldMs, signal: o.signal });
+  const trainMs = performance.now() - t0;
+
+  await pause();
+  const draft = quantize({ labels, ...params });
+  const cal = score(draft, split.calib);
+  await pause();
+  const T = fitTemperature(cal);
+  await pause();
+  const cert = certify(cal.margin, cal.wrong, GRID, { alpha, delta: o.delta, guarantee: o.guarantee });
+  const whatIf = WHAT_IF.map((target) => {
+    const c = certify(cal.margin, cal.wrong, GRID, { alpha: 1 - target, delta: o.delta, guarantee: o.guarantee });
+    return { target, share: cal.n ? c.local / cal.n : 0 };
+  });
+
+  const certificate = {
+    target: o.target, delta: o.delta, guarantee: o.guarantee, n: cal.n,
+    local: cert.local, errors: cert.errors, pValue: cert.pValue, cutoff: cert.cutoff,
+  };
+  const calShare = cal.n ? cert.local / cal.n : 0;
+  const calLocalAgree = cert.local ? 1 - cert.errors / cert.local : null;
+  // Agreement on deferred calibration rows, overall and per guessed label (as a ratio to the model's
+  // confidence, shrunk toward 1 when rows are few). shadow() checks both live.
+  let dn = 0, dAgree = 0;
+  const seen = new Float64Array(K), expected = new Float64Array(K);
+  for (let i = 0; i < cal.n; i++) {
+    if (cal.margin[i] >= cert.cutoff) continue;
+    dn++;
+    if (!cal.wrong[i]) dAgree++;
+    const p = softmax(cal.Z[i], T), top = topTwo(cal.Z[i]).top;
+    expected[top] += p[top];
+    seen[top] += cal.wrong[i] ? 0 : 1;
+  }
+  const SHRINK = 10;
+  const ratio = Object.fromEntries(labels.map((l, k) => [l, Math.round(((seen[k] + SHRINK) / (expected[k] + SHRINK)) * 1000) / 1000]));
+  const meta = {
+    created: new Date().toISOString(), certificate, rows: { total: rows.length, train: split.train.length, calib: cal.n, test: split.test.length },
+    expected: { share: calShare, localAgreement: calLocalAgree, deferred: { n: dn, agreement: dn ? dAgree / dn : null, ratio } }, audit: o.audit,
+  };
+  const model = new Model({ ...draft, T, cutoff: cert.cutoff, meta });
+
+  await pause();
+  const test = split.test.length ? evaluate(model, split.test, params) : null;
+  await pause();
+  const latencyUs = timeDecide(model, (split.test.length ? split.test : split.calib).slice(0, 400));
+
+  const share = test ? test.share : calShare;
+  const minCal = o.guarantee === 'local' ? localStart(alpha, o.delta) : minCalibration(alpha, o.delta);
+  const verdict =
+    cal.n < minCal ? 'need-more-data' : calShare >= 0.25 ? 'ship' : calShare >= 0.05 ? 'marginal' : 'not-worth-it';
+  const report = {
+    verdict,
+    summary: summarize({ verdict, o, calShare, cal, minCal, whatIf }),
+    labels, target: o.target, delta: o.delta, guarantee: o.guarantee,
+    rows: { ...meta.rows, skipped },
+    features: params.keys.length, epochs: params.epochs,
+    certificate,
+    calib: { share: calShare, localAgreement: calLocalAgree, overallAgreement: cal.n ? 1 - cert.errors / cal.n : null, rawAgreement: cal.n ? 1 - cal.errors / cal.n : null },
+    test,
+    whatIf,
+    savings: { apiCallsAvoided: share * (1 - o.audit), auditRate: o.audit },
+    temperature: T,
+    bytes: model.toBytes().byteLength,
+    latencyUs,
+    ms: { train: Math.round(trainMs), total: Math.round(performance.now() - t0) },
+  };
+  model.meta.verdict = verdict;
+  onProgress({ phase: 'done', done: 1 });
+  return { model, report };
+}
+
+/** Normalizes answer records into { input, group, choice, t }. */
+export function readRecords(records, given) {
+  const list = Array.isArray(records) ? records : [...records];
+  let labels = given ? [...given] : null;
+  if (!labels) {
+    const seen = new Set();
+    let fileLabels = null;
+    for (const r of list) {
+      if (Array.isArray(r.labels)) fileLabels ??= r.labels;
+      const c = choiceOf(r, null);
+      if (typeof c === 'string') seen.add(c);
+      if (r.probs && !Array.isArray(r.probs)) for (const k of Object.keys(r.probs)) seen.add(k);
+    }
+    labels = fileLabels ?? [...seen].sort();
+  }
+  const at = new Map(labels.map((l, i) => [l, i]));
+  const K = labels.length;
+  const rows = [];
+  let skipped = 0;
+  for (const r of list) {
+    if (r.labels && !r.input && !('choice' in r) && !r.probs) continue; // a header line
+    const input = inputOf(r);
+    let t = null;
+    if (r.probs) {
+      t = new Float32Array(K);
+      if (Array.isArray(r.probs)) { if (r.probs.length !== K) { skipped++; continue; } r.probs.forEach((p, k) => (t[k] = Math.max(0, +p || 0))); }
+      else for (const [l, p] of Object.entries(r.probs)) { const k = at.get(l); if (k !== undefined) t[k] = Math.max(0, +p || 0); }
+      const s = t.reduce((a, b) => a + b, 0);
+      if (!(s > 0)) t = null; else for (let k = 0; k < K; k++) t[k] /= s;
+    }
+    let c = choiceOf(r, labels);
+    let y = typeof c === 'string' ? at.get(c) : undefined;
+    if (y === undefined && t) y = argmax(t);
+    if (y === undefined || input === undefined) { skipped++; continue; }
+    if (!t) { t = new Float32Array(K); t[y] = 1; }
+    rows.push({ input, group: r.group != null ? String(r.group) : inputKey(input), y, t, trainOnly: r.sample === false });
+  }
+  return { labels, rows, skipped };
+}
+
+function inputOf(r) {
+  if (r.input !== undefined) return r.input;
+  if (typeof r.a === 'string' && typeof r.b === 'string') return { a: r.a, b: r.b };
+  for (const k of ['text', 'state', 'content', 'message']) if (typeof r[k] === 'string') return r[k];
+  return undefined;
+}
+
+function choiceOf(r, labels) {
+  let c = r.choice ?? r.label ?? r.decision ?? r.answer;
+  if (c && typeof c === 'object') c = c.choice ?? c.label;
+  if (typeof c === 'number' && labels) c = labels[c];
+  return c;
+}
+
+function argmax(a) {
+  let m = 0;
+  for (let i = 1; i < a.length; i++) if (a[i] > a[m]) m = i;
+  return m;
+}
+
+function score(model, rows) {
+  const n = rows.length;
+  const margin = new Float64Array(n), wrong = new Uint8Array(n), Z = [], y = new Int32Array(n);
+  let errors = 0;
+  for (let i = 0; i < n; i++) {
+    const z = model.logits(rows[i].input);
+    const { top, second } = topTwo(z);
+    margin[i] = second < 0 ? Infinity : z[top] - z[second];
+    wrong[i] = top !== rows[i].y ? 1 : 0;
+    errors += wrong[i];
+    Z.push(Float32Array.from(z));
+    y[i] = rows[i].y;
+  }
+  return { n, margin, wrong, Z, y, errors };
+}
+
+/** Temperature that best explains the API's choices on calib. Only reported confidence uses it. */
+function fitTemperature({ Z, y, n }) {
+  if (!n) return 1;
+  const nll = (T) => {
+    let s = 0;
+    for (let i = 0; i < n; i++) s -= Math.log(Math.max(softmax(Z[i], T)[y[i]], 1e-12));
+    return s / n;
+  };
+  let lo = Math.log(0.05), hi = Math.log(20);
+  const g = (Math.sqrt(5) - 1) / 2;
+  let a = hi - g * (hi - lo), b = lo + g * (hi - lo), fa = nll(Math.exp(a)), fb = nll(Math.exp(b));
+  for (let it = 0; it < 40; it++) {
+    if (fa < fb) { hi = b; b = a; fb = fa; a = hi - g * (hi - lo); fa = nll(Math.exp(a)); }
+    else { lo = a; a = b; fa = fb; b = lo + g * (hi - lo); fb = nll(Math.exp(b)); }
+  }
+  return Math.exp((lo + hi) / 2);
+}
+
+function evaluate(model, rows, params) {
+  const n = rows.length;
+  const float = new Model({ ...model, q: params.E, scales: new Float32Array(params.keys.length).fill(1) });
+  let local = 0, localWrong = 0, rawWrong = 0, flips = 0;
+  for (const r of rows) {
+    const d = model.decide(r.input);
+    if (d.index !== r.y) rawWrong++;
+    if (d.local) { local++; if (d.index !== r.y) localWrong++; }
+    if (topTwo(float.logits(r.input)).top !== d.index) flips++;
+  }
+  return {
+    n, share: local / n,
+    overallAgreement: 1 - localWrong / n, overallCI: wilson(n - localWrong, n),
+    localAgreement: local ? 1 - localWrong / local : null, localCI: local ? wilson(local - localWrong, local) : null,
+    rawAgreement: 1 - rawWrong / n, int8Flips: flips,
+  };
+}
+
+function timeDecide(model, rows) {
+  if (!rows.length) return null;
+  for (const r of rows) model.decide(r.input);
+  const t = performance.now();
+  let reps = 0;
+  while (performance.now() - t < 50) { for (const r of rows) model.decide(r.input); reps++; }
+  return Math.round(((performance.now() - t) * 1000) / (reps * rows.length) * 10) / 10;
+}
+
+function summarize({ verdict, o, calShare, cal, minCal, whatIf }) {
+  const pct = (x) => `${Math.round(x * 1000) / 10}%`;
+  const scope = o.guarantee === 'local' ? 'agreement on the answers it gives' : 'overall agreement with your API';
+  if (verdict === 'need-more-data') return `Only ${cal.n} calibration rows; certifying ${pct(o.target)} needs at least ${minCal}. Keep shadowing and compile again.`;
+  const head = `Answers ${pct(calShare)} of calls locally while keeping ${scope} ≥ ${pct(o.target)} (${pct(1 - o.delta)} confidence).`;
+  if (verdict === 'ship') return head;
+  const looser = whatIf.filter((w) => w.target < o.target && w.share >= Math.max(0.25, calShare * 2)).at(-1);
+  const hint = looser ? ` At ${pct(looser.target)} it would answer ${pct(looser.share)}.` : '';
+  if (verdict === 'marginal') return `${head} Savings are small.${hint}`;
+  return `Not worth it: only ${pct(calShare)} of calls clear the cutoff. A word-level model can't copy this decision reliably; keep calling the API.${hint}`;
+}
+
+function pick(o, keys) {
+  return Object.fromEntries(keys.filter((k) => o[k] !== undefined).map((k) => [k, o[k]]));
+}
+

package/src/features.js

@@ -0,0 +1,128 @@
+// Text → hashed features. Two groups are kept apart because they pool separately in the model:
+//   words: word unigrams, word bigrams, number shapes, and (for pairs) side + overlap features
+//   chars: character 2–4 grams inside each word, with < > word boundaries
+// Han and kana characters are tokens of their own, so CJK text gets character unigrams and bigrams.
+
+import { fmix, hashString } from './hash.js';
+
+export const FEATURES_VERSION = 1;
+
+const TOKEN = /[\p{sc=Han}\p{sc=Hiragana}\p{sc=Katakana}]|[\p{L}\p{M}\p{N}]+|[^\s\p{L}\p{M}\p{N}]/gu;
+const DIGITS = /^\p{Nd}+$/u;
+const MAX_CHARS = 4000;
+const MAX_TOKENS = 400;
+const MAX_GRAM_TOKEN = 48;
+const MIN_N = 2;
+const MAX_N = 4;
+
+const SEED = {
+  word: 0x1b873593, bigram: 0xcc9e2d51, char: 0x85ebca77, shape: 0x27d4eb2f,
+  sideA: 0x165667b1, sideB: 0xd3a2646c, shared: 0xfd7046c5, onlyA: 0xb55a4f09, onlyB: 0x6c8e9cf5, jaccard: 0x9e3779b1,
+};
+
+/** Normalizes any supported input into { text } or { a, b }. */
+export function asInput(input) {
+  if (typeof input === 'string') return { text: input };
+  if (input == null) return { text: '' };
+  if (typeof input === 'object') {
+    if (typeof input.a === 'string' && typeof input.b === 'string') return { a: input.a, b: input.b };
+    for (const k of ['state', 'text', 'input', 'content', 'message']) if (typeof input[k] === 'string') return { text: input[k] };
+  }
+  return { text: stableString(input) };
+}
+
+/** A canonical text for an input, used for grouping and de-duplication. */
+export function inputKey(input) {
+  const x = asInput(input);
+  return x.text !== undefined ? normalize(x.text) : normalize(x.a) + '␞' + normalize(x.b);
+}
+
+export function normalize(s) {
+  return String(s).slice(0, MAX_CHARS).normalize('NFKC').toLowerCase();
+}
+
+function tokens(text) {
+  const out = [];
+  for (const m of normalize(text).matchAll(TOKEN)) {
+    out.push(m[0]);
+    if (out.length === MAX_TOKENS) break;
+  }
+  return out;
+}
+
+/** Growable uint32 buffer, reused across calls so the hot path does not allocate per feature. */
+class Buf {
+  constructor(n = 256) { this.a = new Uint32Array(n); this.n = 0; }
+  push(v) {
+    if (this.n === this.a.length) { const b = new Uint32Array(this.a.length * 2); b.set(this.a); this.a = b; }
+    this.a[this.n++] = v;
+  }
+  view() { return this.a.subarray(0, this.n); }
+}
+
+export class Featurizer {
+  constructor() { this.w = new Buf(); this.c = new Buf(); }
+
+  /** Returns { w, c } views into internal buffers; copy them if you keep them past the next call. */
+  run(input) {
+    const x = asInput(input);
+    this.w.n = 0; this.c.n = 0;
+    if (x.text !== undefined) {
+      this.#side(tokens(x.text), 0);
+    } else {
+      const ta = tokens(x.a), tb = tokens(x.b);
+      const ua = this.#side(ta, SEED.sideA), ub = this.#side(tb, SEED.sideB);
+      let shared = 0;
+      for (const h of ub) {
+        const inA = ua.has(h);
+        if (inA) shared++;
+        this.w.push(fmix(h ^ (inA ? SEED.shared : SEED.onlyB)));
+      }
+      for (const h of ua) if (!ub.has(h)) this.w.push(fmix(h ^ SEED.onlyA));
+      const union = ua.size + ub.size - shared;
+      const bucket = union ? Math.round((10 * shared) / union) : 10;
+      for (let i = 0; i < 4; i++) this.w.push(fmix(SEED.jaccard + bucket * 16 + i));
+    }
+    return { w: this.w.view(), c: this.c.view() };
+  }
+
+  /** Copies of the features for one input, safe to store. */
+  copy(input) {
+    const { w, c } = this.run(input);
+    return { w: w.slice(), c: c.slice() };
+  }
+
+  #side(toks, salt) {
+    const uni = salt ? new Set() : null; // only pairs compare their sides
+    let prev = 0;
+    for (let i = 0; i < toks.length; i++) {
+      const t = toks[i];
+      const h = hashString(t, SEED.word);
+      uni?.add(h);
+      this.w.push(salt ? fmix(h ^ salt) : h);
+      if (i > 0) this.w.push(fmix((Math.imul(prev, 0x9e3779b1) ^ h ^ SEED.bigram ^ salt) >>> 0));
+      prev = h;
+      if (DIGITS.test(t)) this.w.push(fmix(SEED.shape + Math.min(t.length, 12) * 31 + salt));
+      if (t.length > 1) this.#grams(t, salt);
+    }
+    return uni;
+  }
+
+  #grams(t, salt) {
+    const len = Math.min(t.length, MAX_GRAM_TOKEN) + 2;
+    const code = (j) => (j === 0 ? 60 : j === len - 1 ? 62 : t.charCodeAt(j - 1));
+    for (let i = 0; i < len - 1; i++) {
+      let h = SEED.char ^ salt;
+      for (let j = i, n = 1; j < len && n <= MAX_N; j++, n++) {
+        h = Math.imul(h ^ code(j), 0x01000193);
+        if (n >= MIN_N) this.c.push(fmix((h + n) >>> 0));
+      }
+    }
+  }
+}
+
+function stableString(v) {
+  if (v === null || typeof v !== 'object') return String(v);
+  if (Array.isArray(v)) return v.map(stableString).join(' ');
+  return Object.keys(v).sort().map((k) => `${k}: ${stableString(v[k])}`).join('\n');
+}

package/src/hash.js

@@ -0,0 +1,87 @@
+// 32-bit hashing shared by the featurizer, the trainer and the runtime. Everything is integer math on
+// UTF-16 code units, so a feature hashes identically in every JS engine.
+
+export const FNV_OFFSET = 0x811c9dc5;
+export const FNV_PRIME = 0x01000193;
+
+/** Murmur3 finalizer: spreads the bits of an FNV state so low bits are usable as table indexes. */
+export function fmix(h) {
+  h ^= h >>> 16; h = Math.imul(h, 0x85ebca6b);
+  h ^= h >>> 13; h = Math.imul(h, 0xc2b2ae35);
+  h ^= h >>> 16;
+  return h >>> 0;
+}
+
+/** FNV-1a over a string, seeded. */
+export function hashString(s, seed = FNV_OFFSET) {
+  let h = seed;
+  for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), FNV_PRIME);
+  return fmix(h);
+}
+
+/** Deterministic PRNG (mulberry32) so compiles are reproducible from a seed. */
+export function rng(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Open-addressing map from uint32 keys to int32 values (-1 = absent). Keys are already well mixed. */
+export class U32Map {
+  constructor(capacity = 1024) {
+    let cap = 16;
+    while (cap < capacity * 2) cap <<= 1;
+    this.mask = cap - 1;
+    this.keys = new Uint32Array(cap);
+    this.vals = new Int32Array(cap).fill(-1);
+    this.size = 0;
+  }
+
+  get(key) {
+    const { keys, vals, mask } = this;
+    for (let i = key & mask; ; i = (i + 1) & mask) {
+      const v = vals[i];
+      if (v === -1) return -1;
+      if (keys[i] === key) return v;
+    }
+  }
+
+  set(key, val) {
+    if ((this.size + 1) * 2 > this.mask + 1) this.#grow();
+    const { keys, vals, mask } = this;
+    for (let i = key & mask; ; i = (i + 1) & mask) {
+      if (vals[i] === -1) { keys[i] = key; vals[i] = val; this.size++; return; }
+      if (keys[i] === key) { vals[i] = val; return; }
+    }
+  }
+
+  /** Adds 1 to the value at key (absent counts as 0); returns the new count. */
+  inc(key) {
+    if ((this.size + 1) * 2 > this.mask + 1) this.#grow();
+    const { keys, vals, mask } = this;
+    for (let i = key & mask; ; i = (i + 1) & mask) {
+      if (vals[i] === -1) { keys[i] = key; vals[i] = 1; this.size++; return 1; }
+      if (keys[i] === key) return ++vals[i];
+    }
+  }
+
+  forEach(fn) {
+    const { keys, vals } = this;
+    for (let i = 0; i < vals.length; i++) if (vals[i] !== -1) fn(keys[i], vals[i]);
+  }
+
+  #grow() {
+    const { keys, vals } = this;
+    const cap = (this.mask + 1) * 2;
+    this.mask = cap - 1;
+    this.keys = new Uint32Array(cap);
+    this.vals = new Int32Array(cap).fill(-1);
+    this.size = 0;
+    for (let i = 0; i < vals.length; i++) if (vals[i] !== -1) this.set(keys[i], vals[i]);
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+// The public API. Everything here runs in browsers, workers and edge runtimes; Node gets ./node.js.
+export { shadow } from './shadow.js';
+export { compile } from './compile.js';
+export { Model } from './model.js';
+export { memoryStore } from './store.js';

package/src/log.js

@@ -0,0 +1,55 @@
+// One log line per lifecycle event (start, compile, guard, error), never per call.
+
+const pct = (x) => `${Math.round(x * 100)}%`;
+const int = (x) => x.toLocaleString('en-US');
+const UNTIL = 'Every call goes to your API until a model trained on its new answers certifies.';
+
+/** @returns {string | null} */
+export function describe(e) {
+  switch (e.type) {
+    case 'start':
+      if (e.mode === 'guarded') return `guarded since ${new Date(e.since).toISOString()}. ${UNTIL}`;
+      if (e.mode === 'local') return `loaded the saved model: it answers about ${pct(e.share)} of calls locally at ≥ ${pct(e.target)} agreement with your API.`;
+      return `learning from your API. First compile after ${int(e.min)} answers${e.logged ? ` (${int(e.logged)} logged so far)` : ''}.`;
+    case 'compile': {
+      const r = e.report;
+      const from = `compiled from ${int(r.rows.total)} answers${e.recovering ? ' since the change' : ''}`;
+      if (r.calib.share > 0) {
+        return `${from}: answers ${pct(r.calib.share)} of calls locally, with ≥ ${pct(r.target)} agreement with your API certified at ${pct(1 - r.delta)} confidence. ${(r.bytes / 1e6).toFixed(2)} MB, ${r.latencyUs} µs per call.`;
+      }
+      return `${from}. Nothing certified yet, so your API keeps every call. ${r.summary}`;
+    }
+    case 'guard':
+      if (e.reason === 'schema') return `your API returned a label the model has never seen ("${e.label}"). ${UNTIL}`;
+      if (e.slice === 'deferred' && e.label) return `your API's answers changed for "${e.label}": on calls the model leaned toward "${e.label}" but left to your API, they now agree ${pct(e.agreement)} of the time where the model expected ${pct(e.baseline)}. ${UNTIL}`;
+      if (e.slice === 'deferred') return `your API's answers changed: on calls it answered itself, the model now agrees ${pct(e.agreement)} of the time, down from ${pct(e.baseline)}. ${UNTIL}`;
+      return `your API's answers changed: the model agreed on only ${pct(e.agreement)} of ${int(e.sampled)} audited calls (target ${pct(e.target)}). ${UNTIL}`;
+    case 'unreadable':
+      return `could not find a label in your API's response ${e.preview}. Return a label string or an object with a "label" field, or pass choice: (response) => label. Calls still work; they just teach nothing.`;
+    case 'error':
+      return `${e.where} failed: ${e.error}`;
+    default:
+      return null;
+  }
+}
+
+/**
+ * @param {string | undefined} name
+ * @param {boolean | ((line: string, event: object) => void)} log
+ */
+export function logger(name, log) {
+  if (!log) return () => {};
+  const write = typeof log === 'function' ? log : (line) => console.info(line);
+  const prefix = `[tinydecide]${name ? ` ${name}:` : ''} `;
+  let last = '', lastAt = 0;
+  return (e) => {
+    const line = describe(e);
+    if (!line) return;
+    // A failure that repeats (a full disk, a store that is down) is logged once a minute, not per call.
+    if (e.type === 'error') {
+      if (line === last && Date.now() - lastAt < 60_000) return;
+      last = line; lastAt = Date.now();
+    }
+    try { write(prefix + line, e); } catch {}
+  };
+}