Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

13.5 KB
Raw Blame
import { expect, test } from 'bun:test';
import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { cellKind, cellUrl, cpuPercent, d41Verdict, displayRate, frameStats, gpuBusyMedian, hitchCounts, HUB_RULE, interleaveOrder, parseBattery, parseCell, parseLoadavg, parseNvidiaSmi, parseProcStat,
  parseThermalStatus, parseTop, parseWho, PC_RULE, TABLET_RULE, percentile, planRuns, quietVerdict, refreshShare, summarizeBlock, summarizeCell, tabletCool, type RunMetrics } from '../timing-ab';

test('percentile uses the pilot rule (ceil(n q)-th smallest) and frame stats keep count, fps and sampled time', () => {
  const values = [10, 1, 9, 2, 8, 3, 7, 4, 6, 5];
  expect([percentile(values, .5), percentile(values, .95), percentile(values, 1), percentile([], .5)]).toEqual([5, 10, 10, null]);
  const s = frameStats([8, 8, 8, 16]);
  expect([s.count, s.p50, s.p95, s.max, s.sampledMs, s.fps]).toEqual([4, 8, 16, 16, 40, 100]);
  expect(frameStats([NaN, 10]).count).toBe(1);
});

test('the display rate is the lower-quartile probe interval, robust to a throttled half window', () => {
  const r = displayRate([8.33, 8.34, 8.32, 16.67, 8.33]);
  expect(r.periodMs).toBe(8.33); expect(r.hz).toBeCloseTo(120.05, 1);
  expect(displayRate([]).periodMs).toBeNull();
  // The tablet case: an idle page at 60 Hz, then throttled to 30 Hz for most of the window.
  const throttled = [...Array(12).fill(16.6), ...Array(30).fill(33.3)];
  expect(displayRate(throttled).periodMs).toBe(16.6); // the median would read 33.3
  expect(displayRate([...Array(15).fill(16.6), ...Array(25).fill(33.3)]).periodMs).toBe(16.6);
});

test('refresh share counts frames within one (< 1.5 P) and within two (< 2.5 P) display periods', () => {
  const P = 1000 / 120;
  const intervals = [8.2, 8.4, 8.5, 12.4, 12.6, 16.7, 20.8, 21, 25, 33.4];
  // < 12.5: 8.2 8.4 8.5 12.4 → 4; < 20.83: plus 12.6 16.7 20.8 → 7.
  const s = refreshShare(intervals, P);
  expect(s.withinOne).toBe(.4); expect(s.withinTwo).toBe(.7); expect(s.frames).toBe(10);
  expect(refreshShare([], P).withinOne).toBeNull();
  expect(refreshShare([10], NaN).withinTwo).toBeNull();
  // A 60 Hz tablet: 16.7 is one refresh, 33.3 two, 50 three.
  expect(refreshShare([16.6, 16.8, 33.3, 50.1], 1000 / 60)).toMatchObject({ withinOne: .5, withinTwo: .75 });
});

test('hitch counts and the D-41 rule (desktop 0/0/<=50 ms; tablet <=2 over 50, 0 over 100; only on 60 s runs)', () => {
  const c = hitchCounts([8, 50, 50.1, 99, 100.5]);
  expect(c).toEqual({ over50: 3, over100: 1, longestMs: 100.5 });
  expect(d41Verdict(c, { row: 'desktop', seconds: 60 }).pass).toBe(false);
  expect(d41Verdict(hitchCounts([8, 33.4, 50]), { row: 'desktop', seconds: 60 }).pass).toBe(true);
  expect(d41Verdict(hitchCounts([8, 50.2]), { row: 'desktop', seconds: 60 }).pass).toBe(false);
  expect(d41Verdict(hitchCounts([8, 51, 70]), { row: 'tablet', seconds: 60 }).pass).toBe(true);
  expect(d41Verdict(hitchCounts([8, 51, 70, 60]), { row: 'tablet', seconds: 60 }).pass).toBe(false);
  expect(d41Verdict(hitchCounts([8, 101]), { row: 'tablet', seconds: 60 }).pass).toBe(false);
  const dry = d41Verdict(hitchCounts([8, 101]), { row: 'desktop', seconds: 10 });
  expect([dry.applies, dry.pass]).toEqual([false, null]);
  expect(hitchCounts([]).longestMs).toBeNull();
});

test('interleave order alternates which side runs first in each pair', () => {
  expect(interleaveOrder(1)).toEqual(['A', 'B']);
  expect(interleaveOrder(3)).toEqual(['A', 'B', 'B', 'A', 'A', 'B']);
  expect(() => interleaveOrder(0)).toThrow();
  const plan = planRuns([parseCell('farm:high:hero'), parseCell('golden-gate:minimal:arrival')], 2);
  expect(plan.map(p => `${p.cell.scene}/${p.pair}/${p.side}`)).toEqual(['farm/1/A', 'farm/1/B', 'farm/2/B', 'farm/2/A', 'golden-gate/1/A', 'golden-gate/1/B', 'golden-gate/2/B', 'golden-gate/2/A']);
  expect(plan.map(p => p.position)).toEqual([1, 2, 3, 4, 1, 2, 3, 4]);
});

test('cells parse as scene:tier:name and resolve to the scene own views and workloads', () => {
  expect(parseCell('foundry-floor:high:campus')).toEqual({ scene: 'foundry-floor', tier: 'high', name: 'campus' });
  expect(() => parseCell('farm:ultra:hero')).toThrow(); expect(() => parseCell('mill:high:hero')).toThrow(); expect(() => parseCell('farm:high')).toThrow();
  expect(cellKind(parseCell('farm:high:hero'))).toBe('view');
  expect(cellKind(parseCell('farm:economy:tractor-drive'))).toBe('workload');
  expect(cellKind(parseCell('golden-gate:minimal:drive'))).toBe('workload');
  expect(cellKind(parseCell('foundry-floor:high:fab-overview'))).toBe('view');
  expect(() => cellKind(parseCell('golden-gate:high:hero'))).toThrow(/no view or workload/);
  // The clock is never frozen: no freeze or time parameter; tier and A/B extras are added.
  const url = new URL(cellUrl('http://127.0.0.1:4400/', parseCell('golden-gate:minimal:arrival'), { msaa: 'store' }));
  expect(Object.fromEntries(url.searchParams)).toEqual({ capture: '1', hud: '0', preset: 'day', cam: 'arrival', tier: 'minimal', msaa: 'store' });
  expect(new URL(cellUrl('http://x', parseCell('farm:high:hero'))).search).toBe('?view=hero&tier=high');
  expect(new URL(cellUrl('http://x', parseCell('foundry-floor:economy:drive'))).search).toBe('?capture=1&tier=economy');
});

test('quiet-check parsing: loadavg, /proc/stat, nvidia-smi, who and top', () => {
  expect(parseLoadavg('0.37 0.40 0.37 1/589 1685215\n')).toEqual({ one: .37, five: .4, fifteen: .37, running: 1, total: 589 });
  const a = parseProcStat('cpu  100 0 50 1000 50 0 0 0 0 0\ncpu0 1 2 3'), b = parseProcStat('cpu  110 0 60 1170 50 0 0 0 0 0\n');
  expect(a).toEqual({ total: 1200, idle: 1050 }); expect(cpuPercent(a, b)).toBeCloseTo(100 * 20 / 190, 6);
  expect(cpuPercent(a, a)).toBeNull();
  expect(parseNvidiaSmi('0, 39, 300, 5, P8\n', ['utilization.gpu', 'temperature.gpu', 'clocks.gr', 'memory.used', 'pstate'])).toEqual([{ 'utilization.gpu': 0, 'temperature.gpu': 39, 'clocks.gr': 300, 'memory.used': 5, pstate: 'P8' }]);
  expect(parseNvidiaSmi('[N/A], 40\n', ['a', 'b'])[0]).toEqual({ a: null, b: 40 });
  expect(parseWho('\n')).toEqual([]); expect(parseWho('matthewk tty2 2026-09-30 01:00\n')).toHaveLength(1);
  const top = `top - 01:19:44 up 6 days, 16:51,  3 users,  load average: 0.37, 0.40, 0.37
Tasks: 300 total,   1 running, 299 sleeping,   0 stopped,   0 zombie

    PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
   1234 matthewk  20   0 3400000 200000  90000 S   6.2   1.3   1:23.45 kwin_wayland --xwayland
      1 root      20   0   22000  12000   9000 S   0.0   0.1   0:05.00 systemd
`;
  expect(parseTop(top)).toEqual([{ pid: 1234, user: 'matthewk', cpuPercent: 6.2, memPercent: 1.3, command: 'kwin_wayland --xwayland' }, { pid: 1, user: 'root', cpuPercent: 0, memPercent: .1, command: 'systemd' }]);
  expect(parseTop('no header')).toEqual([]);
});

test('quiet verdicts: the hub pilot rule and this PC rule', () => {
  const calm = { cpu: [1, 1.5, .8, 2, 1, 1, 1, 1], gpu: [0, 0, 1, 0, 0, 0, 0, 0], screenLocked: false };
  expect(quietVerdict(calm, HUB_RULE).quiet).toBe(true);
  expect(quietVerdict({ ...calm, gpu: [0, 0, 4, 0, 0, 0, 0, 0] }, HUB_RULE).reasons).toEqual(['GPU max 4 % > 3 %']);
  expect(quietVerdict({ ...calm, cpu: [1, 1, 1, 13, 1, 1, 1, 1] }, HUB_RULE).reasons[0]).toMatch(/CPU max 13/);
  expect(quietVerdict({ ...calm, screenLocked: true }, HUB_RULE).quiet).toBe(false);
  expect(quietVerdict({ cpu: [1, 1], gpu: [], screenLocked: false }, HUB_RULE).reasons).toEqual(['2 of 8 CPU samples', '0 of 8 readable GPU samples in [0, 100]']);
  const busyPc = { cpu: [35, 40, 38, 36, 37, 39, 41, 36], gpu: [22, 25, 24, 23, 22, 21, 20, 25], screenLocked: false };
  expect(quietVerdict(busyPc, PC_RULE).reasons).toEqual(['CPU mean 37.75 % >= 20 %', 'GPU max 25 % > 9.999 %']);
  expect(quietVerdict({ cpu: [10, 12, 15, 11, 9, 14, 13, 12], gpu: [5, 5, 5, 5, 5, 5, 5, 9], screenLocked: false }, PC_RULE).quiet).toBe(true);
});

test('a quiet proof requires a complete readable bounded GPU window on every host policy', () => {
  for (const rule of [HUB_RULE, PC_RULE, TABLET_RULE]) {
    const cpu = Array(rule.samples).fill(1), calm = Array(rule.samples).fill(0);
    for (const bad of [null, NaN, Infinity, -1, 101]) {
      const gpu = [...calm]; gpu[3] = bad;
      const result = quietVerdict({ cpu, gpu, screenLocked: false }, rule);
      expect(result.quiet).toBe(false);
      expect(result.reasons.some(reason => reason.includes('GPU samples'))).toBe(true);
      // Extra valid samples must not conceal a bad reading in the observed window.
      expect(quietVerdict({ cpu, gpu: [...gpu, 0], screenLocked: false }, rule).quiet).toBe(false);
    }
    expect(quietVerdict({ cpu, gpu: calm.slice(1), screenLocked: false }, rule).quiet).toBe(false);
    expect(quietVerdict({ cpu, gpu: Array(rule.samples).fill(null), screenLocked: false }, rule)).toMatchObject({ quiet: false, gpuMax: null });
    expect(quietVerdict({ cpu, gpu: calm, screenLocked: false }, rule).quiet).toBe(true);
    expect(quietVerdict({ cpu, gpu: [...calm.slice(1), rule.gpuMaxAtMost], screenLocked: false }, rule).quiet).toBe(true);
    expect(quietVerdict({ cpu, gpu: [...calm.slice(1), rule.gpuMaxAtMost + .01], screenLocked: false }, rule).quiet).toBe(false);
  }
});

test('tablet readings and the cool rule (thermal none or light, battery at most 35 C)', () => {
  const battery = `Current Battery Service state:
  AC powered: false
  USB powered: true
  status: 5
  level: 100
  temperature: 240
09-30 02:00:19.688  Sending ACTION_BATTERY_CHANGED: level:100, temperature:228`;
  expect(parseBattery(battery)).toEqual({ level: 100, temperatureC: 24, status: 5, usbPowered: true, acPowered: false });
  expect(parseThermalStatus('IsStatusOverride: false\nThermal Status: 1\n')).toBe(1);
  expect(parseThermalStatus('nothing')).toBeNull();
  expect(tabletCool({ thermalStatus: 1, batteryC: 34.9 }).cool).toBe(true);
  expect(tabletCool({ thermalStatus: 2, batteryC: 30 }).reasons).toEqual(['thermal status moderate (2) above light']);
  expect(tabletCool({ thermalStatus: 0, batteryC: 35.2 }).reasons).toEqual(['battery 35.2 C above 35 C']);
  expect(tabletCool({ thermalStatus: null, batteryC: null }).reasons).toHaveLength(2);
});

test('a cell summary gives per-side medians over valid runs and paired B - A differences', () => {
  const m = (p50: number, p95: number, withinOne: number, over50 = 0): RunMetrics => ({ p50, p95, p99: p95, max: p95, fps: 1000 / p50, withinOne, withinTwo: 1, over50, over100: 0, longestMs: p95, cpuRenderP50: p50 / 2, cpuRenderP95: p95 / 2, drawsMedian: 583, trianglesMedian: 2e6, gpuBusy: p50 * 4 });
  const runs = [
    { side: 'A' as const, pair: 1, valid: true, metrics: m(10, 20, .9) }, { side: 'B' as const, pair: 1, valid: true, metrics: m(9, 18, .95) },
    { side: 'B' as const, pair: 2, valid: true, metrics: m(9.5, 19, .94) }, { side: 'A' as const, pair: 2, valid: true, metrics: m(10.5, 21, .9) },
    { side: 'A' as const, pair: 3, valid: true, metrics: m(11, 22, .88, 1) }, { side: 'B' as const, pair: 3, valid: false, metrics: m(30, 60, .1, 9) },
  ];
  const s = summarizeCell(runs);
  expect([s.A.valid, s.B.valid, s.A.runs, s.B.runs]).toEqual([3, 2, 3, 3]);
  expect(s.A.p50).toEqual({ median: 10.5, min: 10, max: 11 });
  expect(s.B.p95?.max).toBe(19); // the invalid run is left out
  expect(s.pairs).toBe(2);
  expect(s.paired.map(p => p.p95)).toEqual([-2, -2]);
  expect(s.deltas.p50).toEqual({ medianDelta: -1, bLower: 2, bHigher: 0, equal: 0 });
  expect(s.deltas.drawsMedian).toEqual({ medianDelta: 0, bLower: 0, bHigher: 0, equal: 2 });
  expect(s.ratios.p95).toBeCloseTo(18 / 21, 6);
  expect(s.deltas.gpuBusy?.medianDelta).toBe(-4);
});

test('GPU busy during a run is the median of nvidia-smi or Mali gpu_busy samples', () => {
  expect(gpuBusyMedian([{ gpu: { 'utilization.gpu': 50 } }, { gpu: { 'utilization.gpu': 40 } }, { gpu: null }, { gpu: { 'utilization.gpu': 60 } }])).toBe(50);
  expect(gpuBusyMedian([{ gpuBusyPercent: 31 }, { batteryC: 25, gpuBusyPercent: 29 }, { gpuBusyPercent: null }])).toBe(29);
  expect(gpuBusyMedian([])).toBeNull();
});

test('persisted timing summary derives GPU units and tablet acceptance from raw samples, not cached scalar claims', async () => {
  const directory = await mkdtemp(join(tmpdir(), 'kiln-timing-summary-'));
  try {
    await mkdir(join(directory, 'runs'));
    await writeFile(join(directory, 'block.json'), JSON.stringify({ device: 'tablet', block: 'fixture' }));
    const record = (pair: number, side: 'A' | 'B') => ({ pair, side, valid: true, seconds: 60,
      cell: { scene: 'farm', tier: 'minimal', name: 'hero', kind: 'view' },
      metrics: { p50: 16, p95: 17, withinOne: .99, withinTwo: 1, over50: 0, over100: 0, gpuClockMHz: 999, gpuBusyClockMHz: 999 },
      loadDuring: Array.from({ length: 30 }, () => ({ gpuBusyPercent: 20, gpuClockKHz: 500000 })) });
    for (const pair of [1, 2, 3]) for (const side of ['A', 'B'] as const) await writeFile(join(directory, 'runs', `${pair}-${side}.json`), JSON.stringify(record(pair, side)));
    const qualified = await summarizeBlock(directory), cell = qualified.cells[0]!;
    expect(cell.A.gpuClockMHz?.median).toBe(500);
    expect(cell.B.gpuBusyClockMHz?.median).toBe(100);
    expect(cell.tabletAdoption?.pass).toBe(true);
    expect(await readFile(join(directory, 'summary.md'), 'utf8')).toContain('Busy × MHz');
    const missing = record(1, 'B'); missing.loadDuring = [];
    await writeFile(join(directory, 'runs', '1-B.json'), JSON.stringify(missing));
    expect((await summarizeBlock(directory)).cells[0]!.tabletAdoption?.pass).toBeNull();
  } finally { await rm(directory, { recursive: true, force: true }); }
});