@bongos/core 1.17.0

package/tests/live_sse.mjs

@@ -0,0 +1,122 @@
+// tests/live_sse.mjs
+//
+// Unit smoke for the hall's Server-Sent Events live endpoint
+// (src/bongos/routes/live.js — R55, task 1194 / ADR 0069), the transport that
+// replaced the Colyseus builders_hall room so the hall is live on a game-less
+// Cloud Bongos boot.
+//
+// Tests the pure SSE framing + the streamLive lifecycle WITHOUT standing up HTTP
+// or auth — a fake req/res plus an injected subscribe seam (mirrors the
+// _setClientFactory style in tests/live_channel.mjs). Covers:
+//   1. frameEvent emits valid SSE wire format.
+//   2. streamLive sets event-stream headers, opens with a comment, flushes.
+//   3. a relay nudge becomes a bare `nudge` event — the {table,op} is NOT leaked.
+//   4. closing the request unsubscribes and releases the per-IP slot.
+//   5. the per-IP concurrent-connection cap refuses (429) past the limit and
+//      frees a slot on close.
+//
+// Run:  node --test tests/live_sse.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { EventEmitter } from 'node:events';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const buildLiveRouter = require('../src/bongos/routes/live.js');
+const { frameEvent, streamLive, MAX_CONN_PER_IP, _connByIp } = buildLiveRouter;
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+function fakeRes() {
+  const res = new EventEmitter();
+  res.written = [];
+  res.headers = null;
+  res.statusCode = null;
+  res.jsonBody = undefined;
+  res.flushed = false;
+  res.writeHead = (status, headers) => { res.statusCode = status; res.headers = headers; return res; };
+  res.write = (chunk) => { res.written.push(String(chunk)); return true; };
+  res.flushHeaders = () => { res.flushed = true; };
+  res.status = (code) => { res.statusCode = code; return res; };
+  res.json = (obj) => { res.jsonBody = obj; return res; };
+  attachFail({}, res, () => {}); // install res.fail() as the router does (task 1991)
+  return res;
+}
+
+function fakeReq(ip = '1.2.3.4') {
+  const req = new EventEmitter();
+  req.ip = ip;
+  return req;
+}
+
+// Never let a stray heartbeat fire during a synchronous test.
+const NO_HEARTBEAT = 10_000_000;
+
+test('frameEvent emits valid SSE framing', () => {
+  assert.equal(frameEvent('nudge', '{}'), 'event: nudge\ndata: {}\n\n');
+});
+
+test('streamLive opens an event-stream, delivers a bare nudge, and cleans up', () => {
+  _connByIp.clear();
+  let captured = null;
+  let unsubscribed = false;
+  const subscribe = (fn) => { captured = fn; return () => { unsubscribed = true; }; };
+
+  const req = fakeReq('10.0.0.1');
+  const res = fakeRes();
+  streamLive(req, res, { subscribe, heartbeatMs: NO_HEARTBEAT });
+
+  // SSE headers + opening comment + immediate flush.
+  assert.equal(res.statusCode, 200);
+  assert.match(res.headers['Content-Type'], /text\/event-stream/);
+  assert.equal(res.headers['Cache-Control'], 'no-cache, no-transform');
+  assert.equal(res.headers['X-Accel-Buffering'], 'no');
+  assert.ok(res.written[0].startsWith(':'), 'stream opens with a comment line');
+  assert.equal(res.flushed, true);
+  assert.equal(_connByIp.get('10.0.0.1'), 1, 'connection counted for the IP');
+
+  // The relay hands the subscriber {table,op}; the route must forward ONLY the
+  // opaque nudge so internal table names never reach the wire (ADR 0030).
+  assert.equal(typeof captured, 'function', 'streamLive subscribed to the relay');
+  captured({ table: 'tasks', op: 'UPDATE' });
+  const nudge = res.written.find((w) => w.startsWith('event: nudge'));
+  assert.equal(nudge, 'event: nudge\ndata: {}\n\n', 'bare nudge — no table/op leaked');
+
+  // Closing the request tears down the subscription and frees the slot.
+  req.emit('close');
+  assert.equal(unsubscribed, true, 'unsubscribed from the relay on close');
+  assert.equal(_connByIp.has('10.0.0.1'), false, 'per-IP connection count released');
+});
+
+test('streamLive enforces a per-IP concurrent-connection cap', () => {
+  _connByIp.clear();
+  const subscribe = () => () => {};
+  const reqs = [];
+
+  // Saturate one IP up to the cap.
+  for (let i = 0; i < MAX_CONN_PER_IP; i++) {
+    const req = fakeReq('9.9.9.9');
+    streamLive(req, fakeRes(), { subscribe, heartbeatMs: NO_HEARTBEAT });
+    reqs.push(req);
+  }
+  assert.equal(_connByIp.get('9.9.9.9'), MAX_CONN_PER_IP);
+
+  // One past the cap is refused with 429 and never streams.
+  const overflow = fakeRes();
+  streamLive(fakeReq('9.9.9.9'), overflow, { subscribe, heartbeatMs: NO_HEARTBEAT });
+  assert.equal(overflow.statusCode, 429);
+  assert.deepEqual(overflow.jsonBody, { error: { code: 'too_many_live_connections', message: 'too_many_live_connections' } });
+  assert.equal(overflow.written.length, 0, 'a refused connection writes nothing');
+
+  // Closing one frees a slot for a fresh stream.
+  reqs[0].emit('close');
+  assert.equal(_connByIp.get('9.9.9.9'), MAX_CONN_PER_IP - 1);
+  const ok = fakeRes();
+  const okReq = fakeReq('9.9.9.9');
+  streamLive(okReq, ok, { subscribe, heartbeatMs: NO_HEARTBEAT });
+  assert.equal(ok.statusCode, 200, 'slot freed → new stream accepted');
+
+  // Release everything so no unref'd interval lingers.
+  for (const r of reqs.slice(1)) r.emit('close');
+  okReq.emit('close');
+});

package/tests/llm-cache-route.mjs

@@ -0,0 +1,110 @@
+// tests/llm-cache-route.mjs — System 5 transport route (task 1381). DB-free:
+// the llm-cache DB helpers are stubbed, and the route handlers are pulled out of
+// the express Router and driven with fake req/res. Tests the VALIDATION + TRUST
+// logic (hex key, known task_type, cost clamp, owner pinning, never-500). The
+// rank gate itself is asserted mechanically by scripts/gds/route-rank-check.js.
+// Run: node tests/llm-cache-route.mjs
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+
+// Stub the cache DB helpers BEFORE the route requires the module (same cached
+// object reference → the route sees these stubs).
+const cache = require('../src/bongos/llm-cache.js');
+let storeArgs = null, lookupShouldThrow = false;
+cache.store = async (spec, opts) => { storeArgs = { spec, opts }; return true; };
+cache.lookup = async () => { if (lookupShouldThrow) throw new Error('db blip'); return null; };
+
+const buildLlmCacheRouter = require('../src/bongos/routes/llm-cache.js');
+const router = buildLlmCacheRouter();
+
+// Pull the terminal handler for a route path out of the router stack.
+function handlerFor(path) {
+  const layer = router.stack.find((l) => l.route && l.route.path === path);
+  if (!layer) throw new Error(`no route ${path}`);
+  const chain = layer.route.stack;
+  return chain[chain.length - 1].handle; // last = the actual handler (after auth + parser)
+}
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const fakeRes = () => {
+  const res = {
+    statusCode: 200, body: null,
+    status(c) { this.statusCode = c; return this; },
+    json(o) { this.body = o; return this; },
+  };
+  attachFail({}, res, () => {}); // install res.fail() as the router does (task 1991)
+  return res;
+};
+const storeHandler = handlerFor('/llm-cache/store');
+const lookupHandler = handlerFor('/llm-cache/lookup');
+const HEX = 'a'.repeat(64);
+
+let passed = 0, failed = 0;
+const run = async (name, fn) => {
+  try { await fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (e) { console.error(`  FAIL ${name}\n    ${e && e.message}`); failed++; }
+};
+
+await run('/store: rejects a non-hex cache_key (400, store never called)', async () => {
+  storeArgs = null;
+  const res = fakeRes();
+  await storeHandler({ body: { spec: { key: 'not-hex', task_type: 'architect-audit' }, result_stdout: 'x' }, builder: { id: 1 } }, res);
+  assert.equal(res.statusCode, 400);
+  assert.equal(res.body.error.code, 'bad_cache_key');
+  assert.equal(storeArgs, null);
+});
+
+await run('/store: rejects an unknown task_type (400)', async () => {
+  const res = fakeRes();
+  await storeHandler({ body: { spec: { key: HEX, task_type: 'totally-made-up' }, result_stdout: 'x' }, builder: { id: 1 } }, res);
+  assert.equal(res.statusCode, 400);
+  assert.equal(res.body.error.code, 'unknown_task_type');
+});
+
+await run('/store: rejects empty result_stdout (400)', async () => {
+  const res = fakeRes();
+  await storeHandler({ body: { spec: { key: HEX, task_type: 'architect-audit' }, result_stdout: '' }, builder: { id: 1 } }, res);
+  assert.equal(res.statusCode, 400);
+  assert.equal(res.body.error.code, 'result_stdout_required');
+});
+
+await run('/store: clamps an inflated result_cost_usd to the ceiling; floors negatives at 0', async () => {
+  let res = fakeRes();
+  await storeHandler({ body: { spec: { key: HEX, task_type: 'architect-audit' }, result_stdout: 'x', result_cost_usd: 999999 }, builder: { id: 1 } }, res);
+  assert.equal(res.body.stored, true);
+  assert.equal(storeArgs.opts.resultCostUsd, 10); // MAX_CACHED_COST_USD default
+  res = fakeRes();
+  await storeHandler({ body: { spec: { key: HEX, task_type: 'architect-audit' }, result_stdout: 'x', result_cost_usd: -5 }, builder: { id: 1 } }, res);
+  assert.equal(storeArgs.opts.resultCostUsd, 0);
+});
+
+await run('/store: pins owner_builder_id to the CALLER, ignoring the client value', async () => {
+  const res = fakeRes();
+  await storeHandler({ body: { spec: { key: HEX, task_type: 'architect-audit', owner_builder_id: 999 }, result_stdout: 'x' }, builder: { id: 42 } }, res);
+  assert.equal(storeArgs.spec.owner_builder_id, 42);
+});
+
+await run('/store: accepts a non-hex scope_sha (onboarding-analyze uses a session id)', async () => {
+  const res = fakeRes();
+  await storeHandler({ body: { spec: { key: HEX, task_type: 'onboarding-analyze', scope_sha: 'session-abc-123' }, result_stdout: 'x' }, builder: { id: 1 } }, res);
+  assert.equal(res.body.stored, true);
+  assert.equal(storeArgs.spec.scope_sha, 'session-abc-123');
+});
+
+await run('/lookup: rejects a non-hex cache_key (400)', async () => {
+  const res = fakeRes();
+  await lookupHandler({ body: { cache_key: 'xyz' }, builder: { id: 1 } }, res);
+  assert.equal(res.statusCode, 400);
+});
+
+await run('/lookup: reports a miss (never 500) when the helper throws', async () => {
+  lookupShouldThrow = true;
+  const res = fakeRes();
+  await lookupHandler({ body: { cache_key: HEX }, builder: { id: 1 } }, res);
+  assert.equal(res.statusCode, 200);
+  assert.deepEqual(res.body, { hit: false, result: null });
+  lookupShouldThrow = false;
+});
+
+console.log(`\nllm-cache-route: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/llm-cache.mjs

@@ -0,0 +1,140 @@
+// tests/llm-cache.mjs — System 5 (task 1359). Pure helpers of the content-
+// addressed LLM cache: sha256, the per-task-type normalizers, computeCacheKey,
+// makeCacheSpec, scopeShaFor (with an injected git runner). DB-free — the
+// lookup/store/withCache paths are best-effort Postgres and live in the
+// integration surface, not this unit gate. Run: node tests/llm-cache.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const c = require('../src/bongos/llm-cache.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+test('sha256 is stable + 64 hex chars', () => {
+  assert.equal(c.sha256('x'), c.sha256('x'));
+  assert.match(c.sha256('x'), /^[0-9a-f]{64}$/);
+  assert.notEqual(c.sha256('a'), c.sha256('b'));
+});
+
+test('stripVolatile removes timestamps / version= / run-id lines', () => {
+  const out = c.stripVolatile('keep this\nversion=abc123\n2026-06-20T10:00 ran\nrun_id: 99\nalso keep');
+  assert.equal(out, 'keep this\nalso keep');
+});
+
+test('architect-audit + onboarding-analyze normalizers strip volatile; default trims', () => {
+  assert.equal(c.normalize('architect-audit', 'core\nversion=9\n'), 'core');
+  assert.equal(c.normalize('onboarding-analyze', '  generated at noon\nbody '), 'body');
+  assert.equal(c.normalize('unknown-type', '  x  '), 'x');
+});
+
+test('computeCacheKey: identical logical input → identical key (volatile lines ignored)', () => {
+  const a = c.computeCacheKey({ prompt: 'audit\nversion=1', model: 'opus', task_type: 'architect-audit', scope_sha: 'deadbeef' });
+  const b = c.computeCacheKey({ prompt: 'audit\nversion=2', model: 'opus', task_type: 'architect-audit', scope_sha: 'deadbeef' });
+  assert.equal(a, b, 'version= echo must not change the key');
+});
+
+test('computeCacheKey: a different scope_sha (tree changed) → different key', () => {
+  const a = c.computeCacheKey({ prompt: 'audit', model: 'opus', task_type: 'architect-audit', scope_sha: 'sha-A' });
+  const b = c.computeCacheKey({ prompt: 'audit', model: 'opus', task_type: 'architect-audit', scope_sha: 'sha-B' });
+  assert.notEqual(a, b);
+});
+
+test('computeCacheKey: a different model → different key', () => {
+  const a = c.computeCacheKey({ prompt: 'p', model: 'opus', task_type: 't', scope_sha: 's' });
+  const b = c.computeCacheKey({ prompt: 'p', model: 'haiku', task_type: 't', scope_sha: 's' });
+  assert.notEqual(a, b);
+});
+
+test('makeCacheSpec returns key + prompt_hash + dimensions', () => {
+  const spec = c.makeCacheSpec({ prompt: 'p\nversion=x', model: 'opus', task_type: 'architect-audit', scope_sha: 's', owner_builder_id: '7' });
+  assert.equal(spec.key, c.computeCacheKey({ prompt: 'p', model: 'opus', task_type: 'architect-audit', scope_sha: 's' }));
+  assert.equal(spec.prompt_hash, c.sha256('p')); // normalized
+  assert.equal(spec.owner_builder_id, 7);
+  assert.equal(spec.model, 'opus');
+});
+
+test('scopeShaFor: composes injected git rev-parse output; tree change → new sha', () => {
+  const runner1 = () => 'tree-aaa';
+  const runner2 = () => 'tree-bbb';
+  const s1 = c.scopeShaFor(['src/bongos'], { runner: runner1 });
+  const s2 = c.scopeShaFor(['src/bongos'], { runner: runner2 });
+  assert.match(s1, /^[0-9a-f]{64}$/);
+  assert.notEqual(s1, s2);
+});
+
+test('scopeShaFor: a path that errors in git → MISSING (no crash, distinct sha)', () => {
+  const ok = c.scopeShaFor(['a'], { runner: () => 'sha' });
+  const missing = c.scopeShaFor(['a'], { runner: () => { throw new Error('not in HEAD'); } });
+  assert.notEqual(ok, missing);
+});
+
+// --- transport fallback (task 1381). DB-free: no pool here, so poolReachable()
+// resolves false and the injected apiCall path is exercised deterministically. ---
+async function arun(name, fn) {
+  try { await fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+const KEY = 'a'.repeat(64);
+
+await arun('lookup: routes to apiCall on a HIT (right method/path/args)', async () => {
+  c._resetTransportForTests();
+  const calls = [];
+  c.setApiFallback(async (...args) => { calls.push(args); return { ok: true, data: { hit: true, result: { result_stdout: 'X', result_cost_usd: 0.4 } } }; });
+  const r = await c.lookup(KEY, { tokensSavedEst: 12 });
+  assert.equal(r.result_stdout, 'X');
+  assert.equal(calls[0][0], 'POST');
+  assert.equal(calls[0][1], '/api/gds/llm-cache/lookup');
+  assert.deepEqual(calls[0][2], { cache_key: KEY, tokens_saved_est: 12 });
+  assert.deepEqual(calls[0][3], { allowUnauthenticated: true });
+});
+
+await arun('lookup: miss on {hit:false} and on a thrown apiCall (best-effort)', async () => {
+  c._resetTransportForTests();
+  c.setApiFallback(async () => ({ ok: true, data: { hit: false, result: null } }));
+  assert.equal(await c.lookup(KEY), null);
+  c.setApiFallback(async () => { throw new Error('network down'); });
+  assert.equal(await c.lookup(KEY), null); // swallowed, never throws
+});
+
+await arun('lookup: null when no fallback set + pool unreachable (never throws)', async () => {
+  c._resetTransportForTests();
+  assert.equal(await c.lookup(KEY), null);
+});
+
+await arun('store: posts {spec, result_stdout, result_cost_usd}; true/false on result', async () => {
+  c._resetTransportForTests();
+  let body = null;
+  c.setApiFallback(async (m, p, b) => { body = b; return { ok: true, data: { stored: true } }; });
+  const spec = c.makeCacheSpec({ prompt: 'p', model: 'opus', task_type: 'architect-audit', scope_sha: 's' });
+  assert.equal(await c.store(spec, { resultStdout: 'OUT', resultCostUsd: 1.5 }), true);
+  assert.equal(body.spec.key, spec.key);
+  assert.equal(body.result_stdout, 'OUT');
+  assert.equal(body.result_cost_usd, 1.5);
+  c.setApiFallback(async () => ({ ok: false, status: 403 }));
+  assert.equal(await c.store(spec, { resultStdout: 'OUT' }), false);
+  c.setApiFallback(async () => { throw new Error('boom'); });
+  assert.equal(await c.store(spec, { resultStdout: 'OUT' }), false); // swallowed
+});
+
+await arun('recordSaving: pool-only, no API fallback — never calls apiCall, never throws', async () => {
+  c._resetTransportForTests();
+  let called = false;
+  c.setApiFallback(async () => { called = true; return { ok: true, data: {} }; });
+  const spec = c.makeCacheSpec({ prompt: 'p', model: 'opus', task_type: 'architect-audit', scope_sha: 's' });
+  await c.recordSaving(spec, { resultCostUsd: 2, hitCount: 1 }); // pool unreachable → early return
+  assert.equal(called, false, 'recordSaving must never book via the API (contract: server-priced only)');
+});
+
+await arun('setApiFallback(nonFn) is a no-op → lookup falls back to pool-only miss', async () => {
+  c._resetTransportForTests();
+  c.setApiFallback('not a function');
+  assert.equal(await c.lookup(KEY), null);
+});
+
+console.log(`\nllm-cache: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/llm-pricing.mjs

@@ -0,0 +1,152 @@
+// tests/llm-pricing.mjs — ADR 0028 path 2 (#560). Pure pricing-table tests.
+// Prices VERIFIED 2026-06-20 against the live Anthropic models/pricing page
+// (GDS-V4 task 1343): opus (4.8/4.7) $5/$25, sonnet (4.6) $3/$15, haiku (4.5)
+// $1/$5; flat across the 1M window (no long-context premium).
+// Run:  node tests/llm-pricing.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { priceUsage, familyFor, PRICES, canonicalizeModelId, priceModelUsage } = require('../src/bongos/llm-pricing.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+const M = 1_000_000;
+const near = (a, b) => Math.abs(a - b) < 1e-6;
+
+test('familyFor matches by substring; unknown → null', () => {
+  assert.equal(familyFor('claude-opus-4-8'), 'opus');
+  assert.equal(familyFor('claude-sonnet-4-6'), 'sonnet');
+  assert.equal(familyFor('claude-haiku-4-5'), 'haiku');
+  assert.equal(familyFor('gpt-4o'), null);
+  assert.equal(familyFor(''), null);
+  assert.equal(familyFor(undefined), null);
+});
+
+test('opus 4.8: 1M input + 1M output = $5 + $25 = $30', () => {
+  const r = priceUsage('claude-opus-4-8', { input_tokens: M, output_tokens: M });
+  assert.ok(near(r.usd, 30), `got ${r.usd}`);
+  assert.equal(r.unknown_model, false);
+  assert.equal(r.family, 'opus');
+});
+
+test('sonnet input ($3) vs haiku output ($5) use their own rates', () => {
+  assert.ok(near(priceUsage('claude-sonnet-4-6', { input_tokens: M }).usd, 3));
+  assert.ok(near(priceUsage('claude-haiku-4-5', { output_tokens: M }).usd, 5));
+});
+
+test('cache read is 0.1× input (opus $0.50 / 1M)', () => {
+  const r = priceUsage('claude-opus-4-8', { cache_read_input_tokens: M });
+  assert.ok(near(r.usd, 0.5), `got ${r.usd}`);
+});
+
+test('cache-creation breakdown: 1h priced at 2× input ($10/1M opus)', () => {
+  const r = priceUsage('claude-opus-4-8', {
+    cache_creation_input_tokens: M,
+    cache_creation: { ephemeral_5m_input_tokens: 0, ephemeral_1h_input_tokens: M },
+  });
+  assert.ok(near(r.usd, 10), `got ${r.usd}`);
+});
+
+test('cache-creation 5m breakdown priced at 1.25× input ($6.25/1M opus)', () => {
+  const r = priceUsage('claude-opus-4-8', {
+    cache_creation_input_tokens: M,
+    cache_creation: { ephemeral_5m_input_tokens: M, ephemeral_1h_input_tokens: 0 },
+  });
+  assert.ok(near(r.usd, 6.25), `got ${r.usd}`);
+});
+
+test('cache-creation lump WITHOUT breakdown → priced as 5m ($6.25)', () => {
+  const r = priceUsage('claude-opus-4-8', { cache_creation_input_tokens: M }); // no cache_creation obj
+  assert.ok(near(r.usd, 6.25), `got ${r.usd}`);
+});
+
+test('cache-creation breakdown remainder folded into 5m (not dropped) [regression]', () => {
+  // The 5m/1h breakdown may not enumerate every creation token. The authoritative
+  // total is cache_creation_input_tokens; any remainder must still be priced.
+  const r = priceUsage('claude-opus-4-8', {
+    cache_creation_input_tokens: M,
+    cache_creation: { ephemeral_5m_input_tokens: 400_000 }, // only 400k of the 1M enumerated
+  });
+  assert.equal(r.components.cache_write_5m.tokens, M, 'remainder folded into 5m');
+  assert.ok(near(r.usd, 6.25), `got ${r.usd}`); // full 1M @ 1.25× = $6.25, nothing dropped
+});
+
+test('component split: per-tier tokens + usd, summing to usd', () => {
+  const r = priceUsage('claude-opus-4-8', {
+    input_tokens: M, output_tokens: M,
+    cache_read_input_tokens: M, cache_creation_input_tokens: M,
+  });
+  assert.ok(near(r.components.input.usd, 5));
+  assert.ok(near(r.components.output.usd, 25));
+  assert.ok(near(r.components.cache_read.usd, 0.5));
+  assert.ok(near(r.components.cache_write_5m.usd, 6.25)); // lump → 5m
+  assert.equal(r.components.cache_read.tokens, M);
+  const sum = r.components.input.usd + r.components.output.usd + r.components.cache_read.usd
+            + r.components.cache_write_5m.usd + r.components.cache_write_1h.usd;
+  assert.ok(near(r.usd, sum), `usd ${r.usd} != component sum ${sum}`);
+});
+
+test('unknown model → priced as opus AND flagged', () => {
+  const r = priceUsage('gpt-4o', { input_tokens: M });
+  assert.ok(near(r.usd, 5), `got ${r.usd}`);
+  assert.equal(r.unknown_model, true);
+  assert.equal(r.family, 'opus');
+});
+
+test('empty/missing usage → $0, no throw', () => {
+  assert.equal(priceUsage('claude-opus-4-8', {}).usd, 0);
+  assert.equal(priceUsage('claude-opus-4-8', null).usd, 0);
+});
+
+test('realistic mixed turn (the verified machine sample shape)', () => {
+  // input 24375, cache_create 22843 (1h), cache_read 15611, output 171 — opus
+  const r = priceUsage('claude-opus-4-8', {
+    input_tokens: 24375, output_tokens: 171,
+    cache_read_input_tokens: 15611, cache_creation_input_tokens: 22843,
+    cache_creation: { ephemeral_5m_input_tokens: 0, ephemeral_1h_input_tokens: 22843 },
+  });
+  const expected = (24375 * 5 + 171 * 25 + 15611 * 0.5 + 22843 * 10) / 1e6;
+  assert.ok(near(r.usd, expected), `got ${r.usd}, expected ${expected}`);
+});
+
+// ---------- priceModelUsage + canonicalizeModelId (task 1005, ADR 0054) ----------
+
+test('priceModelUsage: opus 1M in + 1M out = $30; + haiku 1M out = $35', () => {
+  const a = priceModelUsage({ 'claude-opus-4-8': { input: M, output: M } });
+  assert.ok(near(a.true_cost_usd, 30), `got ${a.true_cost_usd}`);
+  const b = priceModelUsage({
+    'claude-opus-4-8': { input: M, output: M },
+    'claude-haiku-4-5': { output: M },
+  });
+  assert.ok(near(b.true_cost_usd, 35), `got ${b.true_cost_usd}`);
+});
+
+test('priceModelUsage: cache_creation lump priced at the 5m write rate (opus $6.25 / 1M)', () => {
+  const r = priceModelUsage({ 'claude-opus-4-8': { cache_creation: M } });
+  assert.ok(near(r.true_cost_usd, 6.25), `got ${r.true_cost_usd}`);
+});
+
+test('canonicalizeModelId strips [1m]/-fast/date; per-model keeps raw rows, total is the sum', () => {
+  assert.equal(canonicalizeModelId('claude-opus-4-8[1m]'), 'claude-opus-4-8');
+  assert.equal(canonicalizeModelId('claude-opus-4-8-fast'), 'claude-opus-4-8');
+  assert.equal(canonicalizeModelId('claude-haiku-4-5-20251001'), 'claude-haiku-4-5');
+  const r = priceModelUsage({
+    'claude-opus-4-8': { input: M },
+    'claude-opus-4-8[1m]': { input: M },
+  });
+  assert.equal(r.per_model.length, 2, 'raw keys kept as separate breakdown rows');
+  assert.ok(near(r.true_cost_usd, 10), `got ${r.true_cost_usd}`); // 5 + 5, pricing unaffected
+});
+
+test('priceModelUsage: unknown model still priced (opus rate) AND flagged loudly', () => {
+  const r = priceModelUsage({ 'gpt-4o': { input: M } });
+  assert.ok(near(r.true_cost_usd, 5), `got ${r.true_cost_usd}`);
+  assert.ok(r.unknown_models.includes('gpt-4o'), 'unknown model surfaced, never silent $0');
+});
+
+console.log(`\nllm-pricing tests: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/local_preview.mjs

@@ -0,0 +1,136 @@
+// tests/local_preview.mjs — hermetic unit smoke for scripts/gds/local-preview-lib.js
+// (the LOCAL sandbox launcher, task 1056). NO real spawn, NO network, NO fs
+// writes: fs / spawn / kill / fetchImpl / env are all injected.
+//
+// Run:  node tests/local_preview.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const lib = require('../scripts/gds/local-preview-lib.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+
+// ---------- port + url derivation ----------
+t('previewPort: default 3100, env override, invalid falls back', () => {
+  assert.equal(lib.previewPort({ env: {} }), 3100);
+  assert.equal(lib.previewPort({ env: { OTB_PREVIEW_PORT: '4200' } }), 4200);
+  assert.equal(lib.previewPort({ env: { OTB_PREVIEW_PORT: 'nope' } }), 3100);
+  assert.equal(lib.previewPort({ env: { OTB_PREVIEW_PORT: '0' } }), 3100);
+  assert.equal(lib.previewPort({ env: { OTB_PREVIEW_PORT: '70000' } }), 3100);
+});
+
+t('localUrl / healthUrl track the port (health on the loopback literal)', () => {
+  assert.equal(lib.localUrl({ env: {} }), 'http://localhost:3100');
+  assert.equal(lib.healthUrl({ env: {} }), 'http://127.0.0.1:3100/healthz');
+  assert.equal(lib.localUrl({ env: { OTB_PREVIEW_PORT: '4200' } }), 'http://localhost:4200');
+});
+
+// ---------- presence + pid probing ----------
+t('hasGameEntry: keyed on the preview entry file', () => {
+  assert.equal(lib.hasGameEntry({ fs: { existsSync: () => true } }), true);
+  assert.equal(lib.hasGameEntry({ fs: { existsSync: () => false } }), false);
+});
+
+t('onBox: any box marker ⇒ true; none ⇒ false (keeps the localhost path off a box, task 1443)', () => {
+  const only = (target) => ({ fs: { existsSync: (p) => p === target } });
+  assert.equal(lib.onBox(only('/etc/otb/box.env')), true, 'box.env');
+  assert.equal(lib.onBox(only('/usr/local/bin/box-preview')), true, 'box-preview wrapper');
+  assert.equal(lib.onBox(only('/etc/systemd/system/box-game-preview.service')), true, 'box-game-preview unit');
+  assert.equal(lib.onBox({ fs: { existsSync: () => false } }), false, 'a laptop has none of them');
+  // honors the dep names sandbox-stage.js injects, and a throwing existsSync is swallowed → false
+  assert.equal(lib.onBox({ boxEnvPath: '/custom/box.env', fs: { existsSync: (p) => p === '/custom/box.env' } }), true);
+  assert.equal(lib.onBox({ previewWrapper: '/custom/box-preview', fs: { existsSync: (p) => p === '/custom/box-preview' } }), true);
+  assert.equal(lib.onBox({ fs: { existsSync: () => { throw new Error('EACCES'); } } }), false, 'throwing existsSync → false, not a crash');
+});
+
+t('readPid: parses a pidfile; null on garbage/missing', () => {
+  assert.equal(lib.readPid({ fs: { readFileSync: () => '12345\n' } }), 12345);
+  assert.equal(lib.readPid({ fs: { readFileSync: () => 'garbage' } }), null);
+  assert.equal(lib.readPid({ fs: { readFileSync: () => { throw new Error('ENOENT'); } } }), null);
+});
+
+t('pidAlive: signal-0 probe (ESRCH=dead, EPERM=alive)', () => {
+  assert.equal(lib.pidAlive(123, { kill: () => true }), true);
+  assert.equal(lib.pidAlive(123, { kill: () => { const e = new Error('no'); e.code = 'ESRCH'; throw e; } }), false);
+  assert.equal(lib.pidAlive(123, { kill: () => { const e = new Error('perm'); e.code = 'EPERM'; throw e; } }), true);
+  assert.equal(lib.pidAlive(0), false);
+});
+
+// ---------- start / stop ----------
+t('start: refuses when the game entry is absent', () => {
+  const r = lib.start({ fs: { existsSync: () => false } });
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /doesn't carry the game/);
+});
+
+t('start: idempotent — no-op when already running', () => {
+  const r = lib.start({
+    fs: { existsSync: () => true, readFileSync: () => '999\n' },
+    kill: () => true, // pid 999 answers signal-0 → alive
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.already, true);
+  assert.equal(r.pid, 999);
+});
+
+t('start: spawns node with the preview entry, detached, PORT/HOST set; writes pidfile', () => {
+  let spawned = null, wrotePid = null;
+  const r = lib.start({
+    env: {},
+    fs: {
+      existsSync: (p) => /preview-server\.js$/.test(String(p)), // game entry yes
+      readFileSync: () => { throw new Error('ENOENT'); },        // not running
+      openSync: () => 'ignore',
+      writeFileSync: (p, d) => { wrotePid = { p, d }; },
+    },
+    spawn: (cmd, argv, opts) => { spawned = { cmd, argv, opts }; return { pid: 4242, unref() {} }; },
+    nodePath: '/usr/bin/node',
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.already, false);
+  assert.equal(r.pid, 4242);
+  assert.equal(spawned.cmd, '/usr/bin/node');
+  assert.match(String(spawned.argv[0]), /preview-server\.js$/);
+  assert.equal(spawned.opts.detached, true);
+  assert.equal(spawned.opts.env.PORT, '3100');
+  assert.equal(spawned.opts.env.HOST, '127.0.0.1');
+  assert.match(String(wrotePid.d), /4242/);
+});
+
+t('stop: kills the pid + clears the pidfile', () => {
+  let killed = null, removed = false;
+  const r = lib.stop({
+    fs: { readFileSync: () => '777\n', rmSync: () => { removed = true; } },
+    kill: (pid, sig) => { if (sig === 0) return true; killed = pid; },
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.wasRunning, true);
+  assert.equal(killed, 777);
+  assert.equal(removed, true);
+});
+
+t('stop: no-op when not running', () => {
+  const r = lib.stop({ fs: { readFileSync: () => { throw new Error('ENOENT'); }, rmSync: () => {} } });
+  assert.equal(r.ok, true);
+  assert.equal(r.wasRunning, false);
+});
+
+// ---------- health ----------
+await ta('health: <500 → true, 5xx/throw → false', async () => {
+  assert.equal(await lib.health({ env: {}, fetchImpl: async () => ({ status: 200 }) }), true);
+  assert.equal(await lib.health({ env: {}, fetchImpl: async () => ({ status: 500 }) }), false);
+  assert.equal(await lib.health({ env: {}, fetchImpl: async () => { throw new Error('refused'); } }), false);
+});
+
+console.log(`\nlocal_preview: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);