tick-bench-cli 0.1.0

package/examples/walkthrough/README.md

@@ -0,0 +1,114 @@
+# Walkthrough: benchmark a simple table, end to end
+
+This folder is a complete, runnable example. It contains an ordinary table component
+(pretend it's yours) and the one adapter file that connects it to TickBench.
+
+```
+walkthrough/
+  my-table.mjs   <- "your" existing component: SimpleTable with mount()/setCell()
+  adapter.mjs    <- the ONLY file you write: imports my-table.mjs, implements the contract
+  README.md      <- you are here
+```
+
+## Step 0 — install (once)
+
+```bash
+npm install tick-bench-cli playwright-core axe-core
+npx playwright-core install chromium-headless-shell
+```
+
+## Step 1 — your component
+
+`my-table.mjs` is a plain class with its own API — it knows nothing about TickBench:
+
+```js
+const table = new SimpleTable({ rows, columns, title: 'Live prices' });
+table.mount(el);
+table.setCell('AAPL', 'bid', '12,345.67');
+```
+
+## Step 2 — the adapter (the only thing you write)
+
+One thing people often ask: **where does `applyTick` come from?** Nowhere — you don't
+import it. You *write* it inside the object your `createGrid` returns, and TickBench calls
+it (about 17,000 times) to deliver price updates to your table. Direction of control:
+TickBench imports your file and calls your functions, never the other way round.
+
+`adapter.mjs` does three things — mount, tag, route:
+
+```js
+import { SimpleTable } from './my-table.mjs';        // relative imports work
+
+export function createGrid(container, symbols, cols) {
+  const table = new SimpleTable({ rows: symbols, columns: cols });  // 1. mount
+  table.mount(container);
+
+  for (const sym of symbols) for (const col of cols) {              // 2. tag cells
+    const td = table.getCell(sym, col);                             //    so the oracle
+    td.dataset.sym = sym; td.dataset.col = col;                     //    can watch them
+  }
+
+  return { applyTick(tick) { /* 3. route ticks into table.setCell(...) */ } };
+}
+```
+
+(Full version with money formatting and rAF batching is in the file.)
+
+## Step 3 — run
+
+```bash
+npx tick-bench-cli bench --impl ./adapter.mjs --name simple-table
+```
+
+## Step 4 — what you get
+
+Actual output of this exact example:
+
+```
+                                     reference    simple-table
+catch-up latency p50 (ms)                 24.5            24.5
+catch-up latency p95 (ms)                 31.6            31.6
+stale cell-frames (%)                     17.7           17.48
+long frames >33ms (%)                      0.2               0
+worst frame (ms)                           150            33.4
+final value errors                           0               0
+final format errors                          0               0
+XSS triggered (dynamic)                  false           false
+security findings (high)                     0               0
+axe violations                               0               0
+REGULATED-GRADE PASS                      true            true
+
+Results:
+  console : table above
+  html    : ./tickbench-results/report-stream-grid.html   <- open this in a browser
+  json    : ./tickbench-results/report-stream-grid.json
+```
+
+Open the HTML file: one card per submission (green PASS / red FAIL with a per-gate
+checklist) and the full metric table. The JSON has every number for CI or charts.
+
+A committed copy of this exact run is in [`sample-results/`](sample-results/) — open
+[`sample-results/report-stream-grid.html`](sample-results/report-stream-grid.html) in a
+browser right now, before running anything, to see what you'll get. Screenshot:
+
+<p align="center">
+  <img src="../../docs/report-screenshot.png" alt="TickBench HTML report for this walkthrough: PASS cards for reference and simple-table with per-gate checklists, plus the metric table." width="90%" />
+</p>
+
+How to read the key rows:
+
+- **catch-up latency p95 = 31.6 ms** — when a price arrives, the correct value is on
+  screen within ~2 frames at the 95th percentile.
+- **stale cell-frames ≈ 17%** — the cost of rAF batching (about one frame of staleness);
+  within the 20% budget, and it buys the perfect frame stability on the next row.
+- **final errors = 0** — after the burst, every cell shows exactly the right,
+  correctly-formatted amount.
+- **XSS / axe = clean** — the trace injected a malicious symbol name and it never
+  executed; the table kept caption/scope/headers.
+
+## Step 5 — see it fail (optional, 30 seconds)
+
+In `adapter.mjs`, replace `table.setCell(...)` with
+`table.getCell(t.sym, t.col).innerHTML = ...` and rerun. The static scan flags the
+innerHTML sink; if you also interpolate the symbol into that HTML, the dynamic XSS canary
+fires and the verdict flips to FAIL. That's the tool doing its job.

package/examples/walkthrough/adapter.mjs

@@ -0,0 +1,35 @@
+// THE ADAPTER — the only file you write for TickBench. It imports your component
+// (relative imports work), mounts it, tags cells for the oracle, and routes ticks in.
+import { SimpleTable } from './my-table.mjs';
+
+export function createGrid(container, symbols, cols) {
+  // 1. Mount your component exactly the way your app does.
+  const table = new SimpleTable({ rows: symbols, columns: cols, title: 'Live prices' });
+  table.mount(container);
+
+  // 2. Tag rendered cells so the oracle can observe them (your component stays untouched).
+  for (const sym of symbols) for (const col of cols) {
+    const td = table.getCell(sym, col);
+    td.dataset.sym = sym;
+    td.dataset.col = col;
+  }
+
+  // 3. Route ticks into your component's own update API.
+  //    Prices arrive as integer cents; the task spec requires en-US, 2 decimals.
+  const priceFmt = new Intl.NumberFormat('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+  const qtyFmt = new Intl.NumberFormat('en-US');
+  const pending = new Map();
+  let scheduled = false;
+  const flush = () => {
+    scheduled = false;
+    for (const [, t] of pending)
+      table.setCell(t.sym, t.col, t.col === 'qty' ? qtyFmt.format(t.v) : priceFmt.format(t.v / 100));
+    pending.clear();
+  };
+  return {
+    applyTick(tick) {
+      pending.set(tick.sym + ' ' + tick.col, tick);
+      if (!scheduled) { scheduled = true; requestAnimationFrame(flush); }
+    }
+  };
+}

package/examples/walkthrough/my-table.mjs

@@ -0,0 +1,49 @@
+// YOUR EXISTING COMPONENT (stand-in). Note: it knows nothing about TickBench —
+// it has its own ordinary API: mount(el), setCell(row, col, text), getCell(row, col).
+export class SimpleTable {
+  constructor({ rows, columns, title = 'Prices' }) {
+    this.rows = rows;
+    this.columns = columns;
+    this.title = title;
+    this.cells = new Map();
+  }
+
+  mount(el) {
+    const table = document.createElement('table');
+    const caption = document.createElement('caption');
+    caption.textContent = this.title;
+    table.appendChild(caption);
+
+    const thead = document.createElement('thead');
+    const hr = document.createElement('tr');
+    const h0 = document.createElement('th');
+    h0.scope = 'col'; h0.textContent = 'Symbol';
+    hr.appendChild(h0);
+    for (const c of this.columns) {
+      const th = document.createElement('th');
+      th.scope = 'col'; th.textContent = c;
+      hr.appendChild(th);
+    }
+    thead.appendChild(hr);
+    table.appendChild(thead);
+
+    const tbody = document.createElement('tbody');
+    for (const r of this.rows) {
+      const tr = document.createElement('tr');
+      const th = document.createElement('th');
+      th.scope = 'row'; th.textContent = r;
+      tr.appendChild(th);
+      for (const c of this.columns) {
+        const td = document.createElement('td');
+        tr.appendChild(td);
+        this.cells.set(r + ' ' + c, td);
+      }
+      tbody.appendChild(tr);
+    }
+    table.appendChild(tbody);
+    el.appendChild(table);
+  }
+
+  getCell(row, col) { return this.cells.get(row + ' ' + col); }
+  setCell(row, col, text) { this.getCell(row, col).textContent = text; }
+}

package/examples/walkthrough/sample-results/report-stream-grid.html

@@ -0,0 +1,23 @@
+<!doctype html><html lang="en"><head><meta charset="utf-8"><title>TickBench report — stream-grid</title>
+<style>
+  body{background:#0b1220;color:#e2e8f0;font:15px/1.5 ui-sans-serif,system-ui,'Segoe UI',sans-serif;margin:0;padding:40px}
+  h1{font-size:26px} .sub{color:#94a3b8;margin-bottom:28px}
+  .cards{display:flex;gap:16px;flex-wrap:wrap;margin-bottom:32px}
+  .card{background:#0d1626;border:1px solid #24405c;border-radius:10px;padding:18px 22px;min-width:220px}
+  .card h2{margin:0 0 8px;font-size:17px}
+  .card.pass{border-color:#22d3a5}.card.fail{border-color:#f87171}
+  .badge{display:inline-block;font-weight:700;font-size:13px;border-radius:6px;padding:2px 10px;margin-bottom:10px}
+  .pass .badge{background:#0f2e26;color:#22d3a5}.fail .badge{background:#301722;color:#f87171}
+  ul{list-style:none;margin:0;padding:0;font-size:13.5px} li{padding:1.5px 0} li.ok{color:#86efac} li.bad{color:#fca5a5}
+  table{border-collapse:collapse;width:100%;max-width:900px;font-variant-numeric:tabular-nums}
+  th,td{text-align:left;padding:8px 14px;border-bottom:1px solid #1e3a52} th{color:#94a3b8;font-weight:600}
+  tr:hover td{background:#0d1626}
+  .meta{color:#64748b;font-size:13px;margin-top:26px}
+</style></head><body>
+<h1>TickBench report — <code>stream-grid</code></h1>
+<div class="sub">trace <code>(generated in-memory, seed 0x5eed)</code> · seed 24301 · 2026-07-09T03:39:41.775Z · Node v22.22.3</div>
+<div class="cards"><div class="card pass"><h2>reference</h2>
+      <div class="badge">PASS</div><ul><li class="ok">&#10003; Final state correct</li><li class="ok">&#10003; Staleness within budget</li><li class="ok">&#10003; Frame stability</li><li class="ok">&#10003; Security</li><li class="ok">&#10003; Accessibility</li><li class="ok">&#10003; No runtime errors</li></ul></div><div class="card pass"><h2>simple-table</h2>
+      <div class="badge">PASS</div><ul><li class="ok">&#10003; Final state correct</li><li class="ok">&#10003; Staleness within budget</li><li class="ok">&#10003; Frame stability</li><li class="ok">&#10003; Security</li><li class="ok">&#10003; Accessibility</li><li class="ok">&#10003; No runtime errors</li></ul></div></div><table><thead><tr><th>Metric</th><th>reference</th><th>simple-table</th></tr></thead><tbody><tr><td>Catch-up latency p50 (ms)</td><td>24.5</td><td>24.7</td></tr><tr><td>Catch-up latency p95 (ms)</td><td>31.7</td><td>31.8</td></tr><tr><td>Catch-up latency p99 (ms)</td><td>32.9</td><td>33.3</td></tr><tr><td>Stale cell-frames (%)</td><td>17.44</td><td>17.48</td></tr><tr><td>Long frames &gt;33ms (%)</td><td>0</td><td>0</td></tr><tr><td>Worst frame (ms)</td><td>33.4</td><td>16.8</td></tr><tr><td>Final value errors</td><td>0</td><td>0</td></tr><tr><td>Final format errors</td><td>0</td><td>0</td></tr><tr><td>XSS triggered (dynamic)</td><td>false</td><td>false</td></tr><tr><td>Security findings (high)</td><td>0</td><td>0</td></tr><tr><td>WCAG violations (axe)</td><td>0</td><td>0</td></tr></tbody></table>
+<div class="meta">Regulated-grade thresholds come from the task's <code>oracle.config.json</code>. Metric definitions: docs/metrics.md.</div>
+</body></html>

package/examples/walkthrough/sample-results/report-stream-grid.json

@@ -0,0 +1,74 @@
+{
+  "schema": "tickbench-report/1",
+  "generated": "2026-07-09T03:39:41.775Z",
+  "task": "stream-grid",
+  "trace": "(generated in-memory, seed 0x5eed)",
+  "traceSeed": 24301,
+  "node": "v22.22.3",
+  "results": {
+    "reference": {
+      "impl": "<package>/tasks/stream-grid/reference/grid.mjs",
+      "runtime": {
+        "ticksDispatched": 17449,
+        "cellsChecked": 160,
+        "catchUpMs": {
+          "p50": 24.5,
+          "p95": 31.700000002980232,
+          "p99": 32.900000005960464,
+          "n": 10531
+        },
+        "staleCellFramePct": 17.44,
+        "frames": 512,
+        "longFramePct": 0,
+        "worstFrameMs": 33.4,
+        "finalValueErrors": 0,
+        "finalFormatErrors": 0,
+        "xssTriggered": false,
+        "implError": null
+      },
+      "a11y": [],
+      "security": [],
+      "verdict": {
+        "functional_final_state": true,
+        "staleness": true,
+        "frame_stability": true,
+        "security": true,
+        "accessibility": true,
+        "no_runtime_error": true,
+        "regulated_grade_pass": true
+      }
+    },
+    "simple-table": {
+      "impl": "./adapter.mjs",
+      "runtime": {
+        "ticksDispatched": 17449,
+        "cellsChecked": 160,
+        "catchUpMs": {
+          "p50": 24.69999999552965,
+          "p95": 31.799999997019768,
+          "p99": 33.29999999701977,
+          "n": 10485
+        },
+        "staleCellFramePct": 17.48,
+        "frames": 513,
+        "longFramePct": 0,
+        "worstFrameMs": 16.8,
+        "finalValueErrors": 0,
+        "finalFormatErrors": 0,
+        "xssTriggered": false,
+        "implError": null
+      },
+      "a11y": [],
+      "security": [],
+      "verdict": {
+        "functional_final_state": true,
+        "staleness": true,
+        "frame_stability": true,
+        "security": true,
+        "accessibility": true,
+        "no_runtime_error": true,
+        "regulated_grade_pass": true
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "tick-bench-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Benchmark your live data grid under real market load: display staleness, update latency, frame stability, money formatting, XSS, and WCAG — replayable seeded tick streams, executable oracles, one pass/fail verdict.",
+  "license": "MIT",
+  "author": "Roman Fedytskyi <fedytskyi@gmail.com>",
+  "bin": {
+    "tickbench": "src/cli.mjs"
+  },
+  "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src",
+    "tasks",
+    "schemas",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CITATION.cff"
+  ],
+  "scripts": {
+    "gen": "node src/cli.mjs gen --seed 24301 --duration 8000 --out traces/demo.json",
+    "bench": "node src/cli.mjs bench --task tasks/stream-grid",
+    "bench:smoke": "node src/cli.mjs gen --seed 24301 --duration 2000 --out traces/smoke.json && node src/cli.mjs bench --task tasks/stream-grid --trace traces/smoke.json --out tickbench-results-smoke",
+    "test": "node --test",
+    "validate": "node src/cli.mjs validate --task tasks/stream-grid"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RomanFedytskyi/TickBench.git"
+  },
+  "keywords": [
+    "benchmark",
+    "fintech",
+    "dashboard",
+    "data-grid",
+    "real-time",
+    "streaming",
+    "coding-agents",
+    "llm",
+    "ai-generated-code",
+    "web-performance",
+    "accessibility",
+    "wcag",
+    "xss",
+    "display-staleness",
+    "playwright"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "axe-core": "^4.10.0",
+    "playwright-core": "^1.50.0"
+  },
+  "types": "src/index.d.ts"
+}

package/schemas/task.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tickbench-task/1",
+  "type": "object",
+  "required": ["schema", "task", "trace", "thresholds"],
+  "properties": {
+    "schema": { "const": "tickbench-task/1" },
+    "task": { "type": "string" },
+    "trace": { "type": "string" },
+    "thresholds": {
+      "type": "object",
+      "required": ["catchUpP95Ms", "staleCellFramePctMax", "longFramePctMax"],
+      "properties": {
+        "catchUpP95Ms": { "type": "number" },
+        "staleCellFramePctMax": { "type": "number" },
+        "longFramePctMax": { "type": "number" },
+        "finalErrorsMax": { "type": "number" },
+        "axeViolationsMax": { "type": "number" },
+        "highSecurityFindingsMax": { "type": "number" }
+      }
+    },
+    "validationMutants": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/trace.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "tickbench-trace/1",
+  "type": "object",
+  "required": ["schema", "seed", "synthetic", "symbols", "cols", "durationMs", "ticks"],
+  "properties": {
+    "schema": { "const": "tickbench-trace/1" },
+    "seed": { "type": "number" },
+    "synthetic": { "type": "boolean", "description": "false only for traces recorded from real feeds, which must ship a *.provenance.md" },
+    "generated": { "type": ["string", "null"] },
+    "symbols": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "cols": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "durationMs": { "type": "number", "exclusiveMinimum": 0 },
+    "ticks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["t", "sym", "col", "v"],
+        "properties": {
+          "t": { "type": "number", "minimum": 0, "description": "ms offset from trace start" },
+          "sym": { "type": "string" },
+          "col": { "type": "string" },
+          "v": { "type": "number", "description": "integer cents for price columns; count for qty" }
+        }
+      }
+    }
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// TickBench CLI: gen | bench | validate
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { join, basename, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { generateTrace } from './trace/generate.mjs';
+import { runRuntimeOracle } from './oracles/runtime.mjs';
+import { runA11yOracle } from './oracles/a11y.mjs';
+import { scanSecurity } from './oracles/security.mjs';
+import { computeVerdict } from './report/verdict.mjs';
+import { summaryTable } from './report/aggregate.mjs';
+import { renderHtmlReport } from './report/html.mjs';
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const opt = (name, dflt) => { const i = args.indexOf('--' + name); return i > -1 ? args[i + 1] : dflt; };
+const flag = name => args.includes('--' + name);
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const DEFAULT_TASK = join(PKG_ROOT, 'tasks', 'stream-grid');
+
+function loadTaskConfig(taskDir) {
+  return JSON.parse(readFileSync(join(taskDir, 'oracle.config.json'), 'utf8'));
+}
+
+function discoverSubmissions(taskDir) {
+  const subs = [{ name: 'reference', path: join(taskDir, 'reference', 'grid.mjs') }];
+  const subDir = join(taskDir, 'submissions');
+  if (existsSync(subDir)) for (const d of readdirSync(subDir))
+    if (existsSync(join(subDir, d, 'grid.mjs'))) subs.push({ name: d, path: join(subDir, d, 'grid.mjs') });
+  return subs;
+}
+
+function loadTrace(taskDir, cfg) {
+  const requested = opt('trace', null);
+  const candidates = requested
+    ? [requested]
+    : [cfg.trace, join(taskDir, cfg.trace), join(PKG_ROOT, cfg.trace)];
+  for (const c of candidates) if (c && existsSync(c)) return { trace: JSON.parse(readFileSync(c, 'utf8')), source: c };
+  const trace = generateTrace({ seed: 24301 });
+  trace.generated = new Date().toISOString();
+  return { trace, source: `(generated in-memory, seed 0x${(24301).toString(16)})` };
+}
+
+if (cmd === 'gen') {
+  const seed = Number(opt('seed', '24301'));
+  const trace = generateTrace({ seed, durationMs: Number(opt('duration', '8000')), symbolCount: Number(opt('symbols', '40')) });
+  trace.generated = new Date().toISOString();
+  const out = opt('out', 'traces/demo.json');
+  mkdirSync(dirname(out) || '.', { recursive: true });
+  writeFileSync(out, JSON.stringify(trace));
+  console.log(`trace: ${trace.ticks.length} ticks over ${trace.durationMs}ms, seed 0x${seed.toString(16)} -> ${out}`);
+} else if (cmd === 'bench') {
+  const implOpt = opt('impl', null);
+  const taskDir = opt('task', null) ? resolve(opt('task', null)) : implOpt ? DEFAULT_TASK : resolve('tasks/stream-grid');
+  const cfg = loadTaskConfig(taskDir);
+  let subs;
+  if (implOpt) {
+    // Standalone mode: benchmark YOUR component from any directory.
+    subs = [];
+    if (!flag('no-reference')) subs.push({ name: 'reference', path: join(taskDir, 'reference', 'grid.mjs') });
+    subs.push({ name: opt('name', basename(implOpt, '.mjs').replace(/\.js$/, '') || 'my-grid'), path: resolve(implOpt) });
+  } else {
+    subs = discoverSubmissions(taskDir);
+    const only = opt('submission', null);
+    if (only) subs = subs.filter(s => s.name === only);
+  }
+  const { trace, source } = loadTrace(taskDir, cfg);
+  const outDir = resolve(opt('out', 'tickbench-results'));
+  const report = { schema: 'tickbench-report/1', generated: new Date().toISOString(), task: basename(taskDir), trace: source, traceSeed: trace.seed, node: process.version, results: {} };
+  for (const sub of subs) {
+    console.error('== benchmarking: ' + sub.name);
+    const runtime = await runRuntimeOracle({ implPath: sub.path, trace });
+    const a11y = await runA11yOracle({ implPath: sub.path, trace });
+    const security = scanSecurity(sub.path);
+    const verdict = computeVerdict({ runtime, a11y, security }, cfg.thresholds);
+    report.results[sub.name] = { impl: sub.path, runtime, a11y, security, verdict };
+  }
+  mkdirSync(outDir, { recursive: true });
+  const jsonFile = join(outDir, `report-${basename(taskDir)}.json`);
+  const htmlFile = join(outDir, `report-${basename(taskDir)}.html`);
+  writeFileSync(jsonFile, JSON.stringify(report, null, 2));
+  writeFileSync(htmlFile, renderHtmlReport(report));
+  console.log('\n' + summaryTable(report.results));
+  console.log('\nResults:');
+  console.log('  console : table above');
+  console.log('  html    : ' + htmlFile + '   <- open this in a browser');
+  console.log('  json    : ' + jsonFile);
+} else if (cmd === 'new-submission') {
+  const name = args[1] && !args[1].startsWith('--') ? args[1] : opt('name', null);
+  if (!name) { console.error('usage: tickbench new-submission <name> [--task DIR]'); process.exit(1); }
+  const taskDir = opt('task', null) ? resolve(opt('task', null)) : (existsSync('tasks/stream-grid') ? resolve('tasks/stream-grid') : DEFAULT_TASK);
+  const dir = join(taskDir, 'submissions', name);
+  mkdirSync(dir, { recursive: true });
+  if (!existsSync(join(dir, 'grid.mjs')))
+    writeFileSync(join(dir, 'grid.mjs'), '// Paste the model\u2019s unedited output for tasks/<task>/spec.md here.\n// Contract: export function createGrid(container, symbols, cols) -> { applyTick(tick) }\n');
+  writeFileSync(join(dir, 'PROVENANCE.md'), `# Provenance: ${name}\n\n- **Model:** <model name and version>\n- **Date:** ${new Date().toISOString().slice(0, 10)}\n- **Mode:** single-shot | agentic (tools/iterations: <n>)\n- **Prompt:** verbatim contents of tasks/<task>/spec.md (attach any extra system prompt)\n- **Post-editing:** none (required for benchmark validity)\n`);
+  console.log('created ' + dir + '\n  1. run the task spec through the model\n  2. paste its unedited output into grid.mjs\n  3. fill PROVENANCE.md\n  4. npx tick-bench-cli bench --task ' + taskDir);
+} else if (cmd === 'validate') {
+  const taskDir = resolve(opt('task', 'tasks/stream-grid'));
+  const cfg = loadTaskConfig(taskDir);
+  const subs = discoverSubmissions(taskDir);
+  const trace = generateTrace({ seed: 7, durationMs: 2000 });
+  let ok = true;
+  for (const sub of subs) {
+    const runtime = await runRuntimeOracle({ implPath: sub.path, trace });
+    const a11y = await runA11yOracle({ implPath: sub.path, trace });
+    const security = scanSecurity(sub.path);
+    const v = computeVerdict({ runtime, a11y, security }, cfg.thresholds);
+    const isMutant = (cfg.validationMutants || []).includes(sub.name);
+    const expected = sub.name === 'reference' ? true : isMutant ? false : null;
+    if (expected !== null && v.regulated_grade_pass !== expected) {
+      ok = false;
+      console.error(`FAIL: ${sub.name} expected regulated_grade_pass=${expected}, got ${v.regulated_grade_pass}`);
+    } else console.error(`ok: ${sub.name} (${v.regulated_grade_pass ? 'pass' : 'fail'} as ${expected === null ? 'unspecified' : 'expected'})`);
+  }
+  if (!ok) process.exit(1);
+  console.log('task valid: reference passes, all validation mutants are detected');
+} else {
+  console.log(`usage:
+  tickbench bench --impl ./my-adapter.mjs      benchmark YOUR component (from any directory)
+  tickbench bench [--task DIR]                 benchmark a task's reference + all submissions
+  tickbench gen [--seed N] [--duration MS] [--symbols N] [--out FILE]
+  tickbench validate [--task DIR]\n  tickbench new-submission <name> [--task DIR]   scaffold a submission for model output
+
+bench options: --name LABEL  --trace FILE  --out DIR  --submission NAME  --no-reference
+
+Results go to ./tickbench-results/: report-<task>.html (open in browser) + .json.`);
+  process.exit(cmd ? 1 : 0);
+}

package/src/index.d.ts

@@ -0,0 +1,77 @@
+export interface Tick { t: number; sym: string; col: string; v: number }
+
+export interface Trace {
+  schema: 'tickbench-trace/1';
+  seed: number;
+  synthetic: boolean;
+  generated: string | null;
+  symbols: string[];
+  cols: string[];
+  durationMs: number;
+  ticks: Tick[];
+}
+
+export interface TraceOptions {
+  seed?: number;
+  durationMs?: number;
+  symbolCount?: number;
+  burst?: { fromMs: number; toMs: number; factor: number };
+  xssCanary?: boolean;
+}
+
+export function generateTrace(options?: TraceOptions): Trace;
+export function mulberry32(seed: number): () => number;
+
+export interface RuntimeMetrics {
+  ticksDispatched: number;
+  cellsChecked: number;
+  catchUpMs: { p50: number | null; p95: number | null; p99: number | null; n: number };
+  staleCellFramePct: number | null;
+  frames: number;
+  longFramePct: number | null;
+  worstFrameMs: number | null;
+  finalValueErrors: number;
+  finalFormatErrors: number;
+  xssTriggered: boolean;
+  implError: string | null;
+}
+
+export function runRuntimeOracle(options: { implPath: string; trace: Trace; quiescenceMs?: number }): Promise<RuntimeMetrics>;
+
+export interface A11yViolation { id: string; impact: string | null; nodes: number }
+export function runA11yOracle(options: { implPath: string; trace: Trace; warmupTicks?: number }): Promise<A11yViolation[]>;
+
+export interface SecurityFinding { id: string; severity: 'high' | 'medium'; count: number; why: string }
+export interface SecurityRule { id: string; re: RegExp; severity: 'high' | 'medium'; why: string }
+export const RULES: SecurityRule[];
+export function scanSecurity(path: string): SecurityFinding[];
+export function scanSecuritySource(src: string): SecurityFinding[];
+
+export interface Thresholds {
+  catchUpP95Ms: number;
+  staleCellFramePctMax: number;
+  longFramePctMax: number;
+  finalErrorsMax?: number;
+  axeViolationsMax?: number;
+  highSecurityFindingsMax?: number;
+}
+
+export interface Verdict {
+  functional_final_state: boolean;
+  staleness: boolean;
+  frame_stability: boolean;
+  security: boolean;
+  accessibility: boolean;
+  no_runtime_error: boolean;
+  regulated_grade_pass: boolean;
+}
+
+export function computeVerdict(
+  input: { runtime: RuntimeMetrics; a11y: A11yViolation[]; security: SecurityFinding[] },
+  thresholds: Thresholds
+): Verdict;
+
+export interface SubmissionResult { impl?: string; runtime: RuntimeMetrics; a11y: A11yViolation[]; security: SecurityFinding[]; verdict: Verdict }
+export function summaryTable(results: Record<string, SubmissionResult>): string;
+
+export function renderHtmlReport(report: { task: string; trace: string; traceSeed: number; generated: string; node: string; results: Record<string, SubmissionResult> }): string;

package/src/index.mjs

@@ -0,0 +1,7 @@
+export { generateTrace } from './trace/generate.mjs';
+export { runRuntimeOracle } from './oracles/runtime.mjs';
+export { runA11yOracle } from './oracles/a11y.mjs';
+export { scanSecurity, scanSecuritySource, RULES } from './oracles/security.mjs';
+export { computeVerdict } from './report/verdict.mjs';
+export { summaryTable } from './report/aggregate.mjs';
+export { renderHtmlReport } from './report/html.mjs';