@bongos/core 1.22.2 → 1.23.2

package/tests/module_store_subcategories.mjs

@@ -0,0 +1,364 @@
+// tests/module_store_subcategories.mjs — the sub-category approval queue (task
+// 1004355, ADR 0342 D3): a publish proposes a sub-category the store has not seen,
+// a Metic+ person approves (optionally renamed) or merges it, a merge moves its
+// modules, and near-duplicate names sit beside each proposal. DB-free: an in-memory
+// fake of the two core_278 tables, matched by SQL shape.
+//
+// Run:  node tests/module_store_subcategories.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+
+const require = createRequire(import.meta.url);
+
+// The routes reach the database through pool.js; point it at whichever fake the
+// route test below installs (the module_store_reassess.mjs harness).
+let routeDb = null;
+const poolPath = require.resolve('../src/bongos/pool.js');
+const poolProxy = { query: (...a) => routeDb.query(...a), connect: (...a) => routeDb.connect(...a) };
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: poolProxy } };
+const {
+  isNear, recordPublishCategory, listSubcategories, reviewQueue, readModuleCategories,
+  approveSubcategory, mergeSubcategory,
+} = require('../src/bongos/module-subcategories.js');
+const subs = { isNear, recordPublishCategory, listSubcategories, reviewQueue, readModuleCategories, approveSubcategory, mergeSubcategory };
+const { checkRouteRanks } = require('../src/bongos/route-rank-check.js');
+const catalog = require('../modules/government/catalog.js');
+
+// ---- an in-memory store_subcategories + store_module_categories ----------------
+
+function fakeDb() {
+  const state = { subs: [], cats: new Map(), nextId: 1, log: [] };
+  const query = async (sql, p = []) => {
+    const q = sql.replace(/\s+/g, ' ').trim();
+    state.log.push(q);
+    if (/^(BEGIN|COMMIT|ROLLBACK)$/.test(q)) return { rows: [] };
+    if (q.startsWith('INSERT INTO store_subcategories')) {
+      if (!state.subs.some((s) => s.parent === p[0] && s.sub_key === p[1])) {
+        state.subs.push({ id: String(state.nextId++), parent: p[0], sub_key: p[1], label: p[2], status: 'proposed', proposed_by: p[3], decided_by: null, decided_at: null, merged_into: null, created_at: new Date(state.nextId) });
+      }
+      return { rows: [] };
+    }
+    if (/FROM store_subcategories WHERE parent = \$1 AND sub_key = \$2/.test(q)) {
+      return { rows: state.subs.filter((s) => s.parent === p[0] && s.sub_key === p[1]).map((s) => ({ ...s })) };
+    }
+    if (/FROM store_subcategories WHERE id = ANY\(\$1\) ORDER BY id FOR UPDATE/.test(q)) {
+      const ids = p[0].map((x) => String(BigInt(x)));
+      return { rows: state.subs.filter((s) => ids.includes(s.id)).map((s) => ({ ...s })) };
+    }
+    if (/FROM store_subcategories WHERE id = \$1/.test(q)) return { rows: state.subs.filter((s) => s.id === String(p[0])).map((s) => ({ ...s })) };
+    if (/FROM store_subcategories WHERE status = 'approved'/.test(q)) return { rows: state.subs.filter((s) => s.status === 'approved') };
+    if (/FROM store_subcategories WHERE status <> 'merged'/.test(q)) return { rows: state.subs.filter((s) => s.status !== 'merged') };
+    if (q.startsWith('INSERT INTO store_module_categories')) {
+      state.cats.set(p[0], { module_key: p[0], parent: p[1], subcategory_id: p[2] == null ? null : String(p[2]) });
+      return { rows: [] };
+    }
+    if (/FROM store_module_categories WHERE subcategory_id = ANY/.test(q)) {
+      const ids = p[0].map(String);
+      return { rows: [...state.cats.values()].filter((c) => ids.includes(c.subcategory_id)) };
+    }
+    if (/FROM store_module_categories c LEFT JOIN/.test(q)) {
+      return { rows: [...state.cats.values()].filter((c) => p[0].includes(c.module_key)).map((c) => {
+        const s = state.subs.find((x) => x.id === c.subcategory_id);
+        return { module_key: c.module_key, parent: c.parent, sub_key: s ? s.sub_key : null, label: s ? s.label : null, status: s ? s.status : null };
+      }) };
+    }
+    if (q.startsWith("UPDATE store_subcategories SET status = 'approved'")) {
+      const s = state.subs.find((x) => x.id === String(p[0]));
+      Object.assign(s, { status: 'approved', label: p[1], sub_key: p[2], decided_by: p[3], decided_at: new Date() });
+      return { rows: [s] };
+    }
+    if (q.startsWith("UPDATE store_subcategories SET status = 'merged'")) {
+      const s = state.subs.find((x) => x.id === String(p[0]));
+      Object.assign(s, { status: 'merged', merged_into: String(p[1]), decided_by: p[2], decided_at: new Date() });
+      return { rows: [] };
+    }
+    if (q.startsWith('UPDATE store_subcategories SET merged_into')) {
+      for (const s of state.subs) if (s.merged_into === String(p[0])) s.merged_into = String(p[1]);
+      return { rows: [] };
+    }
+    if (q.startsWith('UPDATE store_module_categories')) {
+      const moved = [];
+      for (const c of state.cats.values()) {
+        if (c.subcategory_id === String(p[0])) { c.subcategory_id = String(p[1]); c.parent = p[2]; moved.push({ module_key: c.module_key }); }
+      }
+      return { rows: moved };
+    }
+    throw new Error(`fake db: unexpected SQL: ${q}`);
+  };
+  const client = { query, release() {} };
+  return { state, query, connect: async () => client, client };
+}
+
+const publish = (db, key, category, builderId = '7') => subs.recordPublishCategory(db.client, { key, category, builderId });
+
+// ---- publish proposes ------------------------------------------------------------
+
+test('publish: an unseen sub-category is proposed, not live, labelled from its key', async () => {
+  const db = fakeDb();
+  const out = await publish(db, 'pay-a', { parent: 'money', sub: 'stripe-payments' });
+  assert.equal(out.status, 'proposed');
+  assert.equal(out.live, false);
+  assert.equal(out.label, 'Stripe payments');
+  assert.equal(db.state.subs.length, 1);
+  assert.equal(db.state.cats.get('pay-a').subcategory_id, db.state.subs[0].id);
+});
+
+test('publish: a second module naming the same key joins the one proposal', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'pay-b', { parent: 'money', sub: 'stripe' }, '8');
+  assert.equal(db.state.subs.length, 1);
+  const { proposals } = await subs.reviewQueue({ db });
+  assert.deepEqual(proposals[0].modules, ['pay-a', 'pay-b']);
+});
+
+test('publish: a parent with no sub sits under the parent only; no category leaves nothing written', async () => {
+  const db = fakeDb();
+  const out = await publish(db, 'chat', { parent: 'communication' });
+  assert.deepEqual(out, { parent: 'communication', sub: null, status: null, live: false });
+  assert.equal(db.state.cats.get('chat').subcategory_id, null);
+  assert.equal(await publish(db, 'other', undefined), null);
+  assert.equal(db.state.cats.has('other'), false);
+});
+
+test('publish: naming an approved sub-category is live at once', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe' });
+  await subs.approveSubcategory(db.state.subs[0].id, { builderId: '1' }, { db });
+  const out = await publish(db, 'pay-b', { parent: 'money', sub: 'stripe' });
+  assert.equal(out.live, true);
+  assert.equal(out.status, 'approved');
+});
+
+// ---- approve / rename ------------------------------------------------------------
+
+test('approve: makes a proposal live and records who decided', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe' });
+  const r = await subs.approveSubcategory(db.state.subs[0].id, { builderId: '1' }, { db });
+  assert.equal(r.ok, true);
+  assert.equal(r.renamed, false);
+  assert.equal(r.subcategory.status, 'approved');
+  assert.equal(r.subcategory.decided_by, '1');
+  const cats = await subs.readModuleCategories(['pay-a'], { db });
+  assert.equal(cats.get('pay-a').live, true);
+  const listed = await subs.listSubcategories({ db });
+  assert.equal(listed.parents.length, 8);
+  assert.deepEqual(listed.parents.find((x) => x.parent === 'money').subcategories.map((s) => s.sub_key), ['stripe']);
+});
+
+test('approve: a rename takes a new label and derives its key; the module stays put', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'payments-stripe' });
+  const r = await subs.approveSubcategory(db.state.subs[0].id, { label: 'Stripe payments', builderId: '1' }, { db });
+  assert.equal(r.renamed, true);
+  assert.equal(r.subcategory.sub_key, 'stripe-payments');
+  assert.equal((await subs.readModuleCategories(['pay-a'], { db })).get('pay-a').sub, 'stripe-payments');
+});
+
+test('approve: refuses a rename onto an existing key (that is a merge), and a decided row', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'pay-b', { parent: 'money', sub: 'stripe-pay' });
+  const [a, b] = db.state.subs;
+  await subs.approveSubcategory(a.id, { builderId: '1' }, { db });
+  const clash = await subs.approveSubcategory(b.id, { subKey: 'stripe', builderId: '1' }, { db });
+  assert.equal(clash.code, 'subcategory_exists');
+  assert.match(clash.message, /merge/);
+  assert.equal((await subs.approveSubcategory(a.id, { builderId: '1' }, { db })).code, 'subcategory_decided');
+  assert.equal((await subs.approveSubcategory('99', { builderId: '1' }, { db })).code, 'subcategory_not_found');
+  assert.equal((await subs.approveSubcategory(b.id, { subKey: 'Bad Key', builderId: '1' }, { db })).code, 'bad_sub_key');
+});
+
+// ---- merge -----------------------------------------------------------------------
+
+test('merge: moves every module of the merged name to the target, parent included', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe-payments' });
+  await publish(db, 'pay-b', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'pay-c', { parent: 'work', sub: 'stripe' });
+  const [target, money, work] = db.state.subs;
+  await subs.approveSubcategory(target.id, { builderId: '1' }, { db });
+  const r1 = await subs.mergeSubcategory(money.id, { into: target.id, builderId: '1' }, { db });
+  assert.deepEqual(r1.moved, ['pay-b']);
+  const r2 = await subs.mergeSubcategory(work.id, { into: target.id, builderId: '1' }, { db });
+  assert.deepEqual(r2.moved, ['pay-c']);
+  const cats = await subs.readModuleCategories(['pay-b', 'pay-c'], { db });
+  assert.equal(cats.get('pay-b').sub, 'stripe-payments');
+  assert.equal(cats.get('pay-c').parent, 'money');
+  assert.equal(cats.get('pay-c').live, true);
+});
+
+test('merge: a later publish naming the merged key lands on the target, not a new proposal', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe-payments' });
+  await publish(db, 'pay-b', { parent: 'money', sub: 'stripe' });
+  const [target, dup] = db.state.subs;
+  await subs.approveSubcategory(target.id, { builderId: '1' }, { db });
+  await subs.mergeSubcategory(dup.id, { into: target.id, builderId: '1' }, { db });
+  const out = await publish(db, 'pay-d', { parent: 'money', sub: 'stripe' });
+  assert.equal(out.sub, 'stripe-payments');
+  assert.equal(out.live, true);
+  assert.equal(out.named, 'stripe');
+  assert.equal(db.state.subs.length, 2);
+});
+
+test('merge: an approved duplicate can be folded too, and earlier merges into it are re-pointed', async () => {
+  const db = fakeDb();
+  await publish(db, 'a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'b', { parent: 'money', sub: 'stripe-pay' });
+  await publish(db, 'c', { parent: 'money', sub: 'stripe-payments' });
+  const [s1, s2, s3] = db.state.subs;
+  await subs.approveSubcategory(s1.id, { builderId: '1' }, { db });
+  await subs.mergeSubcategory(s2.id, { into: s1.id, builderId: '1' }, { db });
+  await subs.approveSubcategory(s3.id, { builderId: '1' }, { db });
+  const r = await subs.mergeSubcategory(s1.id, { into: s3.id, builderId: '1' }, { db });
+  assert.deepEqual(r.moved, ['a', 'b']);
+  assert.equal(db.state.subs.find((s) => s.id === s2.id).merged_into, s3.id);
+});
+
+test('merge: refuses self, an unapproved target, a missing row and an already-merged one', async () => {
+  const db = fakeDb();
+  await publish(db, 'a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'b', { parent: 'money', sub: 'paypal' });
+  const [s1, s2] = db.state.subs;
+  assert.equal((await subs.mergeSubcategory(s1.id, { into: s1.id, builderId: '1' }, { db })).code, 'merge_into_self');
+  assert.equal((await subs.mergeSubcategory(s1.id, { into: s2.id, builderId: '1' }, { db })).code, 'merge_target_not_approved');
+  assert.equal((await subs.mergeSubcategory('99', { into: s2.id, builderId: '1' }, { db })).code, 'subcategory_not_found');
+  await subs.approveSubcategory(s2.id, { builderId: '1' }, { db });
+  await subs.mergeSubcategory(s1.id, { into: s2.id, builderId: '1' }, { db });
+  assert.equal((await subs.mergeSubcategory(s1.id, { into: s2.id, builderId: '1' }, { db })).code, 'subcategory_decided');
+  assert.ok(db.state.log.includes('ROLLBACK'));
+});
+
+// ---- near-duplicates ---------------------------------------------------------------
+
+test('near: "Stripe", "Stripe payments" and "Payments (Stripe)" sit beside each other; unrelated names do not', () => {
+  assert.ok(subs.isNear('Stripe', 'Stripe payments'));
+  assert.ok(subs.isNear('Stripe payments', 'Payments (Stripe)'));
+  assert.ok(subs.isNear('stripe-payment', 'Stripe payments'));
+  assert.ok(subs.isNear('stirpe', 'stripe'));
+  assert.ok(!subs.isNear('Stripe', 'Discord bots'));
+  assert.ok(!subs.isNear('Weather', 'Whether forecasts'));
+});
+
+test('queue: each proposal carries its near-duplicates across parents, never itself or a merged row', async () => {
+  const db = fakeDb();
+  await publish(db, 'a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'b', { parent: 'money', sub: 'stripe-payments' });
+  await publish(db, 'c', { parent: 'work', sub: 'payments-stripe' });
+  await publish(db, 'd', { parent: 'communication', sub: 'discord-bots' });
+  const { proposals } = await subs.reviewQueue({ db });
+  const byKey = Object.fromEntries(proposals.map((p) => [`${p.parent}/${p.sub_key}`, p]));
+  assert.deepEqual(byKey['money/stripe'].near.map((n) => n.sub_key).sort(), ['payments-stripe', 'stripe-payments']);
+  assert.deepEqual(byKey['communication/discord-bots'].near, []);
+  assert.equal(byKey['money/stripe'].parent_title, 'Money');
+});
+
+// ---- authority ---------------------------------------------------------------------
+
+test('authority: the review routes are pinned to their own Metic+ atom, granted to metic and archon', () => {
+  const entry = catalog.byKey('module.subcategory.review');
+  assert.ok(entry, 'catalog defines module.subcategory.review');
+  assert.equal(entry.floor, 'metic');
+  assert.equal(entry.system, false);
+  const sql = fs.readFileSync(new URL('../modules/government/migrations/government_034_module_subcategory_review.sql', import.meta.url), 'utf8');
+  for (const rank of ['metic', 'archon']) assert.match(sql, new RegExp(`SELECT '${rank}', unnest\\(ARRAY\\[\\s*'module\\.subcategory\\.review'`));
+  const res = checkRouteRanks();
+  assert.equal(res.ok, true);
+  assert.deepEqual((res.findings || []).filter((f) => /subcategor/.test(JSON.stringify(f))), []);
+});
+
+test('merge: both rows are locked in one statement, in id order (no deadlock between opposite merges)', async () => {
+  const db = fakeDb();
+  await publish(db, 'a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'b', { parent: 'money', sub: 'paypal' });
+  const [s1, s2] = db.state.subs;
+  await subs.approveSubcategory(s1.id, { builderId: '1' }, { db });
+  db.state.log.length = 0;
+  await subs.mergeSubcategory(s2.id, { into: s1.id, builderId: '1' }, { db });
+  const locks = db.state.log.filter((q) => /FOR UPDATE/.test(q));
+  assert.equal(locks.length, 1);
+  assert.match(locks[0], /WHERE id = ANY\(\$1\) ORDER BY id FOR UPDATE/);
+});
+
+test('queue: bounded to the oldest hundred proposals, and says how many wait', async () => {
+  const db = fakeDb();
+  for (let i = 0; i < 105; i++) await publish(db, `m${i}`, { parent: 'work', sub: `kind-${i}` });
+  const q = await subs.reviewQueue({ db });
+  assert.equal(q.proposals.length, 100);
+  assert.equal(q.total, 105);
+  assert.equal(q.more, true);
+  assert.equal(q.proposals[0].sub_key, 'kind-0');
+});
+
+// ---- the HTTP routes, through the real router ------------------------------------
+
+const buildModulesRouter = require('../src/bongos/routes/modules.js');
+const router = buildModulesRouter();
+function route(method, p) {
+  const layer = router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]);
+  assert.ok(layer, `no ${method.toUpperCase()} ${p} on the router`);
+  return layer.route.stack;
+}
+async function call(method, p, { params = {}, body = {} } = {}) {
+  const stack = route(method, p);
+  const res = {
+    statusCode: 200, body: undefined, headers: {},
+    json(b) { this.body = b; return this; },
+    status(c) { this.statusCode = c; return this; },
+    set(k, v) { this.headers[k] = v; return this; },
+    fail(code, opts, details) { const o = typeof opts === 'number' ? { status: opts, details } : (opts || {}); this.statusCode = o.status; this.body = { error: code, ...o }; return this; },
+  };
+  let err = null;
+  await stack[stack.length - 1].handle({ params, body, query: {}, builder: { id: 3 } }, res, (e) => { err = e; });
+  if (err) throw err;
+  return res;
+}
+
+test('routes: the three review routes sit behind requireBuilder + the module.subcategory.review atom; the list behind requireBuilder only', () => {
+  const src = fs.readFileSync(new URL('../src/bongos/routes/modules.js', import.meta.url), 'utf8');
+  for (const decl of [
+    "router.get('/store/subcategories/queue'",
+    "router.post('/store/subcategories/:id/approve'",
+    "router.post('/store/subcategories/:id/merge'",
+  ]) {
+    assert.ok(src.includes(`${decl}, auth.requireBuilder, auth.requirePermission('module.subcategory.review')`), decl);
+  }
+  assert.equal(route('get', '/store/subcategories/queue').length, 3);
+  assert.equal(route('get', '/store/subcategories').length, 2);
+});
+
+test('routes: list, queue, approve and merge end to end, refusals mapped to their status', async () => {
+  routeDb = fakeDb();
+  await publish(routeDb, 'pay-a', { parent: 'money', sub: 'stripe-payments' });
+  await publish(routeDb, 'pay-b', { parent: 'money', sub: 'stripe' });
+  const [target, dup] = routeDb.state.subs;
+
+  const queue = await call('get', '/store/subcategories/queue');
+  assert.equal(queue.statusCode, 200);
+  assert.equal(queue.body.proposals.length, 2);
+  assert.equal(queue.body.proposals[0].near[0].sub_key, 'stripe');
+
+  assert.equal((await call('post', '/store/subcategories/:id/approve', { params: { id: 'x1' } })).statusCode, 400);
+  assert.equal((await call('post', '/store/subcategories/:id/approve', { params: { id: target.id }, body: { label: 5 } })).statusCode, 400);
+  assert.equal((await call('post', '/store/subcategories/:id/approve', { params: { id: '999' } })).statusCode, 404);
+  const ok = await call('post', '/store/subcategories/:id/approve', { params: { id: target.id }, body: { label: 'Stripe payments' } });
+  assert.equal(ok.statusCode, 200);
+  assert.equal(ok.body.subcategory.status, 'approved');
+  assert.equal((await call('post', '/store/subcategories/:id/approve', { params: { id: target.id } })).statusCode, 409);
+
+  const listed = await call('get', '/store/subcategories');
+  assert.equal(listed.statusCode, 200);
+  assert.deepEqual(listed.body.parents.find((x) => x.parent === 'money').subcategories.map((x) => x.sub_key), ['stripe-payments']);
+
+  assert.equal((await call('post', '/store/subcategories/:id/merge', { params: { id: dup.id }, body: {} })).statusCode, 400);
+  assert.equal((await call('post', '/store/subcategories/:id/merge', { params: { id: dup.id }, body: { into: '0' + dup.id } })).statusCode, 400);
+  const merged = await call('post', '/store/subcategories/:id/merge', { params: { id: dup.id }, body: { into: Number(target.id) } });
+  assert.equal(merged.statusCode, 200);
+  assert.deepEqual(merged.body.moved, ['pay-b']);
+  assert.equal((await call('post', '/store/subcategories/:id/merge', { params: { id: dup.id }, body: { into: target.id } })).statusCode, 409);
+});

package/tests/sleep_helper.mjs

@@ -0,0 +1,99 @@
+// tests/sleep_helper.mjs — ONE "wait N milliseconds" helper per side (task 1004893, goal 1000135).
+//
+// ~27 files each hand-rolled `new Promise((r) => setTimeout(r, ms))`. They were
+// collapsed onto two: window.OTB.sleep (modules/hall-ui/public/dom-utils.js) in
+// the browser and sleep (src/sleep.js, re-exported by the module doorway as
+// api.sleep) on the server. The two blocking Atomics.wait sleeps
+// (modules/lifecycle/merge-lock.js, scripts/bongos/rename-ledger-prose.js) are a
+// different thing — they freeze the thread on purpose — and stay local. These
+// tests pin:
+//   1. the server sleep waits about as long as asked, and resolves to undefined;
+//   2. the module doorway hands modules the very same function;
+//   3. the browser twin exists on window.OTB and waits too;
+//   4. the fitness check goes red on a new hand-rolled copy and stays green on
+//      the repo, the two shared helpers and a blocking sleep.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import vm from 'node:vm';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PUB = path.join(ROOT, 'modules', 'hall-ui', 'public');
+
+const { sleep } = require('../src/sleep.js');
+const guard = require('../scripts/bongos/sleep-helper-guard.js');
+
+test('server sleep waits roughly the time asked and resolves to undefined', async () => {
+  const t0 = Date.now();
+  const v = await sleep(30);
+  assert.equal(v, undefined);
+  assert.ok(Date.now() - t0 >= 25, 'waited at least ~30ms');
+});
+
+test('server sleep keeps setTimeout\'s forgiving inputs (null, a numeric string) instead of throwing', async () => {
+  // node:timers/promises throws ERR_INVALID_ARG_TYPE on these; the hand-rolled copies never did.
+  await sleep(null);
+  await sleep('1');
+});
+
+test('the module doorway exports the shared server sleep', () => {
+  const api = require('../src/module-api.js');
+  assert.equal(api.sleep, sleep);
+});
+
+test('the browser twin is window.OTB.sleep and waits', async () => {
+  const sandbox = { window: {}, document: { querySelector: () => null }, setTimeout, Promise };
+  vm.createContext(sandbox);
+  vm.runInContext(fs.readFileSync(path.join(PUB, 'dom-utils.js'), 'utf8'), sandbox, { filename: 'dom-utils.js' });
+  const OTB = sandbox.window.OTB;
+  assert.equal(typeof OTB.sleep, 'function');
+  const t0 = Date.now();
+  await OTB.sleep(20);
+  assert.ok(Date.now() - t0 >= 15);
+});
+
+test('fitness: the repo holds no hand-rolled sleep outside the two shared helpers', () => {
+  const r = guard.checkOneSleepHelper();
+  assert.equal(r.ok, true, r.violations.join('\n'));
+});
+
+test('fitness: finds every shape of a hand-rolled sleep', () => {
+  const shapes = [
+    'const sleep = (ms) => new Promise((r) => setTimeout(r, ms));',
+    'const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));',
+    '    await new Promise(resolve => setTimeout(resolve, 3_000));',
+    '  sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now,',
+    'await Promise.race([a, new Promise((r) => setTimeout(r, 2000))]);',
+    'function sleep(ms) { return new Promise(function (res) { setTimeout(res, ms); }); }',
+  ];
+  for (const s of shapes) assert.deepEqual(guard.findHandRolledSleeps(s), [1], s);
+});
+
+test('fitness: a blocking Atomics.wait sleep and a timer that does real work are not flagged', () => {
+  assert.deepEqual(guard.findHandRolledSleeps('function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }'), []);
+  assert.deepEqual(guard.findHandRolledSleeps('new Promise((r) => setTimeout(() => r(compute()), 10))'), []);
+  assert.deepEqual(guard.findHandRolledSleeps('const t = setTimeout(resolve, ms); t.unref();'), []);
+});
+
+test('fitness: goes red on a planted copy, green once it is gone', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 't1004893-'));
+  try {
+    fs.mkdirSync(path.join(tmp, 'scripts', 'bongos'), { recursive: true });
+    const f = path.join(tmp, 'scripts', 'bongos', 'x.js');
+    fs.writeFileSync(f, "const sleep = (ms) => new Promise((r) => setTimeout(r, ms));\n");
+    let r = guard.checkOneSleepHelper({ root: tmp });
+    assert.equal(r.ok, false);
+    assert.match(r.violations[0], /scripts\/bongos\/x\.js:1/);
+    fs.writeFileSync(f, "const { sleep } = require('../../src/sleep');\n");
+    r = guard.checkOneSleepHelper({ root: tmp });
+    assert.equal(r.ok, true, r.violations.join('\n'));
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});