@bongos/core 1.19.773 → 1.19.774

package/tests/provisioning_capacity_gate.mjs

@@ -0,0 +1,192 @@
+// tests/provisioning_capacity_gate.mjs
+//
+// A full box refused at the create route (task 1003938, ADR 0285).
+//
+// Task 1003927 put the ceiling in the RUNNER: a project that does not fit is refused at
+// placement, retried, then retired with the reason on the card — minutes after the wizard
+// said "requested". This gate answers the same ceiling up front, as a 409 `box_full`
+// naming N of M, before any row or intent exists.
+//
+// What these tests pin: the refusal lands before createInstance; a box the web tier cannot
+// count (dedicated, a remote co-host) is never refused here; a re-request of a row that
+// already holds its slot stays idempotent, while a revive (which takes a slot) is counted;
+// the live-memory floor stays the runner's; and a capacity read that fails ADMITS, because
+// the runner remains the wall.
+//
+// Hermetic: capacity.fleetCapacity is re-pointed at the real arithmetic over a fake count
+// and a fixed meminfo; the route's data access is stubbed; auth is faked. No Postgres.
+//
+// Run:  node tests/provisioning_capacity_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+
+let passed = 0, failed = 0;
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// The live control plane on 2026-09-16: 1968 MiB total → a measured ceiling of 15.
+const MEMINFO_2GB = 'MemTotal:        2015216 kB\nMemAvailable:    1135180 kB\n';
+const MEMINFO_TIGHT = 'MemTotal:        2015216 kB\nMemAvailable:      120000 kB\n';   // under the 256 MB floor
+
+const capacity = require('../modules/provisioning/capacity.js');
+const realFleetCapacity = capacity.fleetCapacity;
+let placed = 0, meminfo = MEMINFO_2GB, capacityReads = 0, capacityFails = false;
+capacity.fleetCapacity = async () => {
+  capacityReads++;
+  if (capacityFails) throw new Error('count unavailable');
+  const db = { query: async () => ({ rows: [{ n: placed }] }) };
+  return realFleetCapacity(db, { meminfo, remoteHost: null });
+};
+
+// ── stubs: the route's data access + auth ────────────────────────────────────────
+const provisioning = require('../modules/provisioning/provisioning.js');
+let existing = null, lastCreateArgs = null;
+provisioning.getInstanceBySlug = async () => existing;
+provisioning.createInstance = async (_db, args) => {
+  lastCreateArgs = args;
+  if (existing) return { instance: existing, created: false };
+  return { instance: { id: 42, owner_builder_id: 7, slug: args.slug, hosting_shape: args.hostingShape, status: 'requested' }, created: true };
+};
+provisioning.enqueueIntent = async () => ({ intent: { id: 1, state: 'pending' }, created: true });
+provisioning.getOpenIntent = async () => null;
+provisioning.recordEvent = async () => {};
+
+const api = require('../src/module-api.js');
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner' }; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+
+const express = require('express');
+const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    res.status(status).json({ error: { code, ...(details || (typeof opts === 'object' ? opts : {})) } });
+  };
+  next();
+});
+app.use('/api/bongos', provisioningRoutes());
+
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function post(body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`${base}/provisioning/instances`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+function reset({ count = 0, row = null, mem = MEMINFO_2GB, fails = false } = {}) {
+  placed = count; existing = row; meminfo = mem; capacityFails = fails;
+  capacityReads = 0; lastCreateArgs = null;
+  delete process.env.PROVISION_REMOTE_HOST;
+}
+
+const WIZARD = { slug: 'lantern', hosting_shape: 'standalone', no_address: true };
+
+// ── the wall ──────────────────────────────────────────────────────────────────────
+
+await ta('a full box answers 409 box_full naming N of M, and no row is created', async () => {
+  reset({ count: 15 });
+  const res = await post(WIZARD);
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'box_full');
+  assert.match(res.body.error.message, /15 of 15 project slots/);
+  assert.equal(res.body.error.details.placed, 15);
+  assert.equal(res.body.error.details.ceiling, 15);
+  assert.equal(lastCreateArgs, null, 'the refusal lands before createInstance');
+});
+
+await ta('a box with one slot left admits the create', async () => {
+  reset({ count: 14 });
+  const res = await post(WIZARD);
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(lastCreateArgs && lastCreateArgs.slug, 'lantern');
+});
+
+await ta('an absent shape (the co-tenant default) on a local box is counted too', async () => {
+  reset({ count: 15 });
+  const res = await post({ slug: 'lantern', no_address: true });
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'box_full');
+});
+
+// ── boxes the web tier cannot count are the runner's ──────────────────────────────
+
+await ta('dedicated is its own box: never refused here, and the count is never read', async () => {
+  reset({ count: 15 });
+  const res = await post({ slug: 'lantern', hosting_shape: 'dedicated', no_address: true });
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(capacityReads, 0);
+});
+
+await ta('a co-tenant under remote-exec lands on a box this host cannot measure: admitted', async () => {
+  reset({ count: 15 });
+  process.env.PROVISION_REMOTE_HOST = 'overflow.example';
+  const res = await post({ slug: 'lantern', hosting_shape: 'co-tenant', no_address: true });
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(capacityReads, 0);
+  delete process.env.PROVISION_REMOTE_HOST;
+});
+
+await ta('the live-memory floor is left to the runner: slots free + memory tight still admits', async () => {
+  reset({ count: 3, mem: MEMINFO_TIGHT });
+  const res = await post(WIZARD);
+  assert.equal(res.status, 201, res.raw);
+});
+
+// ── re-requests ───────────────────────────────────────────────────────────────────
+
+await ta('a re-request of the owner\'s ACTIVE project on a full box stays idempotent (no box_full)', async () => {
+  reset({ count: 15, row: { id: 42, owner_builder_id: 7, slug: 'lantern', hosting_shape: 'standalone', status: 'active' } });
+  const res = await post(WIZARD);
+  assert.notEqual(res.status, 409, res.raw);
+  assert.ok(res.status < 300, res.raw);
+});
+
+await ta('a revive of a torn-down project takes a slot, so a full box refuses it', async () => {
+  reset({ count: 15, row: { id: 42, owner_builder_id: 7, slug: 'lantern', hosting_shape: 'standalone', status: 'torn_down' } });
+  const res = await post(WIZARD);
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'box_full');
+  assert.equal(lastCreateArgs, null);
+});
+
+// ── the gate is an early answer, not the enforcement ──────────────────────────────
+
+await ta('a capacity read that fails ADMITS — the runner remains the wall', async () => {
+  reset({ count: 15, fails: true });
+  const res = await post(WIZARD);
+  assert.equal(res.status, 201, res.raw);
+});
+
+await ta('a malformed slug or shape gets the handler\'s 400, not box_full', async () => {
+  for (const body of [{ slug: 'Bad Slug!', hosting_shape: 'standalone' }, { slug: 'lantern', hosting_shape: 'giant' }]) {
+    reset({ count: 15 });
+    const res = await post(body);
+    assert.equal(res.status, 400, `${JSON.stringify(body)} → ${res.raw}`);
+  }
+});
+
+capacity.fleetCapacity = realFleetCapacity;
+server.close();
+console.log(`\nprovisioning_capacity_gate: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/provisioning_disconnect.mjs

@@ -0,0 +1,231 @@
+// tests/provisioning_disconnect.mjs
+//
+// "Disconnect from Bongos entirely" — the web tier (task 1003249, ADR 0290).
+//
+// "Take it offline" only tears a project down: the database, backups and address stay
+// reserved (ADR 0181). The owner asked for a separate, truer delete. The web tier's half
+// is the same shape as every other provisioning action — it only ENQUEUES; the runner does
+// the destruction (scripts/gds/provision-disconnect.js, tests/provision_disconnect.mjs).
+//
+// What these tests pin:
+//   • the schema: a 'disconnect' intent action, admitted by migration provisioning_016,
+//     which (as the NEWEST action migration) owns the strict INTENT_ACTIONS set equality
+//   • the queue: a disconnect is refused while ANY other intent is open (never superseded —
+//     a destructive run must not race a standup), and is idempotent against itself
+//   • the route: own-scoped (404 for anyone else) with the archon override, a server-side
+//     typed-name confirm, a 409 naming the blocking run, an audit event, and copy that makes
+//     no wall-clock promise
+//
+// DB-free: data access is stubbed on the cached module objects; auth is faked.
+//
+// Run:  node tests/provisioning_disconnect.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const provisioning = require('../modules/provisioning/provisioning.js');
+const disconnect = require('../modules/provisioning/disconnect.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.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const PROMISE = /shortly|briefly|minute|second|soon\b/i;
+
+console.log('the schema:');
+
+t("INTENT_ACTIONS includes 'disconnect', in strict lockstep with the provisioning_016 CHECK (the newest action migration)", () => {
+  assert.ok(provisioning.INTENT_ACTIONS.includes('disconnect'));
+  const sql = readFileSync(new URL('../modules/provisioning/migrations/provisioning_016_disconnect.sql', import.meta.url), 'utf8');
+  const m = /CHECK \(action IN \(([^)]*)\)\)/.exec(sql);
+  assert.ok(m, 'the migration widens the action CHECK');
+  const inSql = m[1].split(',').map((s) => s.trim().replace(/^'|'$/g, '')).sort();
+  assert.deepEqual(inSql, [...provisioning.INTENT_ACTIONS].sort(), 'the CHECK a live DB ends with and INTENT_ACTIONS carry the same set');
+  assert.match(sql, /INSERT INTO schema_migrations \(version\) VALUES \('provisioning_016_disconnect'\)/, 'self-registers');
+});
+
+console.log('\nthe queue:');
+
+// A fake db over one open-intent slot, mirroring ux_provisioning_intents_open.
+function queueDb({ open = null } = {}) {
+  const inserts = [], deletes = [];
+  return {
+    inserts, deletes,
+    query: async (sql, params) => {
+      if (/SELECT \* FROM provisioning_intents/.test(sql)) return { rows: open ? [open] : [] };
+      if (/INSERT INTO provisioning_intents/.test(sql)) {
+        if (open) { const e = new Error('dup'); e.code = '23505'; throw e; }
+        inserts.push(params);
+        return { rows: [{ id: 99, instance_id: params[0], action: params[1], requested_by: params[2], state: 'pending' }] };
+      }
+      if (/DELETE FROM provisioning_instances/.test(sql)) { deletes.push(params); return { rowCount: 1, rows: [] }; }
+      throw new Error(`unexpected SQL: ${sql}`);
+    },
+  };
+}
+
+await ta('an idle project queues a disconnect intent', async () => {
+  const db = queueDb();
+  const r = await disconnect.enqueueDisconnect(db, 7, 'api:self');
+  assert.equal(r.created, true);
+  assert.deepEqual(db.inserts, [[7, 'disconnect', 'api:self']]);
+});
+
+for (const [action, state] of [['provision', 'pending'], ['provision', 'running'], ['teardown', 'running'], ['restart', 'pending']]) {
+  await ta(`a ${state} '${action}' run REFUSES the disconnect — it is never superseded`, async () => {
+    const db = queueDb({ open: { id: 5, action, state } });
+    const r = await disconnect.enqueueDisconnect(db, 7, 'api:self');
+    assert.equal(r.conflict, 'open_intent');
+    assert.equal(r.intent.action, action);
+    assert.equal(db.inserts.length, 0);
+  });
+}
+
+await ta('an open disconnect makes a second request idempotent, not a conflict', async () => {
+  const db = queueDb({ open: { id: 5, action: 'disconnect', state: 'pending' } });
+  const r = await disconnect.enqueueDisconnect(db, 7, 'api:self');
+  assert.equal(r.created, false);
+  assert.equal(r.conflict, undefined);
+});
+
+await ta('deleteInstance removes the row by id (its intents, events and manifests cascade)', async () => {
+  const db = queueDb();
+  assert.equal(await disconnect.deleteInstance(db, 7), 1);
+  assert.deepEqual(db.deletes, [[7]]);
+});
+
+console.log('\nthe route:');
+
+let instance = null, enqueued = [], events = [], enqueueResult = null;
+provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+provisioning.recordEvent = async (_db, e) => { events.push(e); };
+disconnect.enqueueDisconnect = async (_db, id, requestedBy) => { enqueued.push([id, requestedBy]); return enqueueResult; };
+
+const api = require('../src/module-api.js');
+let builder = { id: 7, rank: 'xenos', github_login: 'owner' };
+api.requireBuilder = (req, _res, next) => { req.builder = builder; next(); };
+
+const express = require('express');
+const disconnectRoutes = require('../modules/provisioning/routes/disconnect.js');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    const extra = typeof opts === 'object' ? opts : {};
+    res.status(status).json({ error: { code, message: extra.message || code, details: details || extra.details } });
+  };
+  next();
+});
+app.use('/api/bongos', disconnectRoutes());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function post(path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`${base}${path}`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+function reset({ inst = { owner_builder_id: 7, slug: 'lantern', status: 'active' }, who = { id: 7, rank: 'xenos', github_login: 'owner' }, result = { intent: { id: 1, action: 'disconnect', state: 'pending' }, created: true } } = {}) {
+  instance = inst; builder = who; enqueueResult = result; enqueued = []; events = [];
+}
+const URL_ = '/provisioning/instances/40/disconnect';
+
+await ta('the owner, typing the name, queues it — with an audit event and no wall-clock promise', async () => {
+  reset();
+  const res = await post(URL_, { confirm_slug: 'lantern' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.queued, true);
+  assert.equal(res.body.action, 'disconnect');
+  assert.doesNotMatch(res.body.message, PROMISE);
+  assert.deepEqual(enqueued, [[40, 'api:self']]);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].event, 'disconnect');
+  assert.equal(events[0].actor, 'api:self');
+});
+
+for (const state of ['requested', 'active', 'error', 'torn_down']) {
+  await ta(`reachable from '${state}' — the state machine is the queue's job, not a status gate`, async () => {
+    reset({ inst: { owner_builder_id: 7, slug: 'lantern', status: state } });
+    const res = await post(URL_, { confirm_slug: 'lantern' });
+    assert.equal(res.status, 200, res.raw);
+  });
+}
+
+await ta('the typed name is checked on the SERVER: a wrong or missing name is refused and nothing is queued', async () => {
+  // A missing name fails validation outright — it is never stringified and compared, so a
+  // project literally named `undefined` cannot be disconnected by omitting the field.
+  for (const [body, code] of [[{ confirm_slug: 'lanterns' }, 'confirm_mismatch'], [{ confirm_slug: '' }, 'confirm_mismatch'], [{}, 'validation_failed']]) {
+    reset();
+    const res = await post(URL_, body);
+    assert.equal(res.status, 400, `${JSON.stringify(body)} → ${res.raw}`);
+    assert.equal(res.body.error.code, code, `${JSON.stringify(body)} → ${res.raw}`);
+    assert.equal(enqueued.length, 0);
+  }
+  reset();
+  const ok = await post(URL_, { confirm_slug: '  Lantern ' });
+  assert.equal(ok.status, 200, 'case and surrounding space are forgiven, the name is not');
+});
+
+await ta('someone else\'s project is a 404 — it does not leak that the id exists', async () => {
+  reset({ who: { id: 8, rank: 'metic', github_login: 'other' } });
+  const res = await post(URL_, { confirm_slug: 'lantern' });
+  assert.equal(res.status, 404, res.raw);
+  assert.equal(enqueued.length, 0);
+});
+
+await ta('an archon may disconnect any project, and the event names WHICH archon', async () => {
+  reset({ who: { id: 3, rank: 'archon', github_login: 'arch' } });
+  const res = await post(URL_, { confirm_slug: 'lantern' });
+  assert.equal(res.status, 200, res.raw);
+  assert.deepEqual(enqueued, [[40, 'api:archon:3']]);
+  assert.equal(events[0].actor, 'api:archon:3');
+});
+
+await ta('an open run answers 409 naming it, and records nothing', async () => {
+  reset({ result: { intent: { id: 5, action: 'provision', state: 'running' }, created: false, conflict: 'open_intent' } });
+  const res = await post(URL_, { confirm_slug: 'lantern' });
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'intent_conflict');
+  assert.match(res.body.error.message, /provision/);
+  assert.doesNotMatch(res.body.error.message, PROMISE);
+  assert.equal(events.length, 0);
+});
+
+await ta('a repeated request while the disconnect is queued says so, and writes no second event', async () => {
+  reset({ result: { intent: { id: 1, action: 'disconnect', state: 'running' }, created: false } });
+  const res = await post(URL_, { confirm_slug: 'lantern' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.queued, false);
+  assert.equal(events.length, 0);
+});
+
+await ta('a missing project is a 404', async () => {
+  reset({ inst: null });
+  const res = await post(URL_, { confirm_slug: 'lantern' });
+  assert.equal(res.status, 404, res.raw);
+});
+
+server.close();
+console.log(`\nprovisioning_disconnect: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/provisioning_restart.mjs

@@ -56,11 +56,11 @@ t("INTENT_ACTIONS includes 'restart', in lockstep with the provisioning_011 CHEC
   const sql = readFileSync(new URL('../modules/provisioning/migrations/provisioning_011_restart.sql', import.meta.url), 'utf8');
   const m = /CHECK \(action IN \(([^)]*)\)\)/.exec(sql);
   assert.ok(m, 'the migration widens the action CHECK');
-  const inSql = m[1].split(',').map((s) => s.trim().replace(/^'|'$/g, '')).sort();
-  // The NEWEST migration owns the strict set equality — the CHECK a live DB
-  // ends up with is the last one applied, so this is the assertion that would
-  // catch an action added in code but never admitted by the schema.
-  assert.deepEqual(inSql, [...provisioning.INTENT_ACTIONS].sort(), 'the CHECK and INTENT_ACTIONS carry the same set');
+  const inSql = m[1].split(',').map((s) => s.trim().replace(/^'|'$/g, ''));
+  assert.ok(inSql.includes('restart'), 'this migration is the one that admitted it');
+  // The NEWEST action migration owns the strict set equality (provisioning_016,
+  // tests/provisioning_disconnect.mjs); an older one is a prefix of the set.
+  for (const a of inSql) assert.ok(provisioning.INTENT_ACTIONS.includes(a), `${a} is still an INTENT_ACTION`);
   assert.match(sql, /INSERT INTO schema_migrations \(version\) VALUES \('provisioning_011_restart'\)/, 'self-registers');
 });
 

package/tests/public_landing_projects.mjs

@@ -138,7 +138,8 @@ test('the delete section is served live, and never claims to erase (task 1003042
   assert.match(body, /id="mDelWhat"/, 'the teardown-vs-delete fold is served');
   assert.match(body, /does <b>not<\/b> erase the project/i,
     'the distinction survives to the wire, not just the source');
-  assert.match(body, /no permanent-delete button/i, 'the absent capability is admitted');
+  assert.match(body, /use <b>Disconnect from Bongos entirely<\/b> below/, 'the true delete is its own card (task 1003249), and the fold says where');
+  assert.match(body, /id="mDisconnect"/, 'and that card is served');
   // the confirmation asks for the project's own name — the heaviest gate on the page
   assert.match(body, /Type the project’s name to confirm/, 'the typed confirmation is served');
   assert.match(body, /data-del-yes disabled/, 'and the act starts unreachable');
@@ -146,8 +147,8 @@ test('the delete section is served live, and never claims to erase (task 1003042
 
 test('the served teardown copy no longer claims the address goes quiet (task 1003042)', async () => {
   const { body } = await request('/projects', 'game.test.local');
-  // teardown has no DNS or Caddy leg: the hostname keeps resolving and 502s, so
-  // this sentence was false on the wire. Task 1002897 owns actually releasing it.
+  // teardown parks the hostname and removes its Caddy block (task 1002897) but
+  // keeps the address for a revive, so "reserved" stays and "goes quiet" never did.
   assert.doesNotMatch(body, /the address stops answering/,
     'no served copy may promise a silence the runner does not deliver');
   assert.match(body, /stays reserved for this project/,

package/tests/render_prefs.mjs

@@ -118,5 +118,157 @@ t('describeForApi reflects an explicit OFF override', () => {
   assert.equal(d.override, false);
 });
 
+// ---- the card-richness ladder (task 1002518) --------------------------------
+// The boolean became four rungs, and the rung a builder gets with no override is
+// DERIVED from their interaction profile. These pin both halves, plus the
+// compatibility surface every pinned CLI still reads.
+
+console.log('\nthe ladder:');
+
+t('LEVELS is ordered least → most rich, and rank follows the order', () => {
+  assert.deepEqual(r.LEVELS, ['minimal', 'text', 'standard', 'rich']);
+  assert.ok(r.levelRank('minimal') < r.levelRank('text'));
+  assert.ok(r.levelRank('text') < r.levelRank('standard'));
+  assert.ok(r.levelRank('standard') < r.levelRank('rich'));
+});
+
+t('the predicates say what each rung draws', () => {
+  // minimal: nothing but the confirmation line.
+  assert.equal(r.showsCard('minimal'), false);
+  assert.equal(r.showsWidget('minimal'), false);
+  // text: the monospace card, no HTML.
+  assert.equal(r.showsCard('text'), true);
+  assert.equal(r.showsWidget('text'), false);
+  // standard: the widget, summary folded.
+  assert.equal(r.showsWidget('standard'), true);
+  assert.equal(r.widgetExpanded('standard'), false);
+  // rich: the widget, summary open.
+  assert.equal(r.showsWidget('rich'), true);
+  assert.equal(r.widgetExpanded('rich'), true);
+});
+
+t('cardFlags bundles the three answers a card emitter needs', () => {
+  assert.deepEqual(r.cardFlags('rich'), { level: 'rich', showCard: true, showWidget: true, expanded: true });
+  assert.deepEqual(r.cardFlags('minimal'), { level: 'minimal', showCard: false, showWidget: false, expanded: false });
+});
+
+t('an unknown level rank-resolves to standard rather than throwing', () => {
+  // Defensive: a level string from an instance ahead of this code must degrade,
+  // not crash a ship. standard is the historical default rendering.
+  assert.equal(r.levelRank('nonsense'), r.levelRank('standard'));
+});
+
+console.log('\nderivation from the interaction profile:');
+
+const withProfile = (interaction) => ({ interaction });
+
+t('the DEFAULT builder (non-technical, concise) derives the RICHEST card', () => {
+  // The point of the task: the reader who most needs explanation, and who by
+  // definition never opened Settings, must not get the terser card.
+  assert.equal(r.derivedLevel({}), 'rich');
+  assert.equal(r.derivedLevel(null), 'rich');
+  assert.equal(r.resolveLevel({}), 'rich');
+});
+
+t('technical_level is the primary axis', () => {
+  assert.equal(r.derivedLevel(withProfile({ technical_level: 'non_technical' })), 'rich');
+  assert.equal(r.derivedLevel(withProfile({ technical_level: 'mixed' })), 'standard');
+  assert.equal(r.derivedLevel(withProfile({ technical_level: 'engineer' })), 'text');
+});
+
+t('machinery:quiet drops a rung — an expert who asked for less gets terse or none', () => {
+  assert.equal(r.derivedLevel(withProfile({ technical_level: 'engineer', machinery: 'quiet' })), 'minimal');
+  assert.equal(r.derivedLevel(withProfile({ technical_level: 'non_technical', machinery: 'quiet' })), 'standard');
+});
+
+t('verbosity:detailed raises a rung', () => {
+  assert.equal(r.derivedLevel(withProfile({ technical_level: 'engineer', verbosity: 'detailed' })), 'standard');
+});
+
+t('verbosity:concise does NOT drop a rung (it is the default — see the derivation note)', () => {
+  // Taxing the default would push the accessible-by-default builder from rich
+  // down to standard, inverting the whole point of deriving from the profile.
+  assert.equal(
+    r.derivedLevel(withProfile({ technical_level: 'non_technical', verbosity: 'concise' })),
+    r.derivedLevel(withProfile({ technical_level: 'non_technical' })),
+  );
+});
+
+t('the ladder clamps at both ends', () => {
+  // non_technical (rich) + detailed would be rank 4; engineer (text) + quiet
+  // twice over would go below 0. Neither may fall off the ladder.
+  assert.equal(r.derivedLevel(withProfile({ technical_level: 'non_technical', verbosity: 'detailed' })), 'rich');
+  assert.equal(r.derivedLevel(withProfile({ technical_level: 'engineer', machinery: 'quiet', verbosity: 'concise' })), 'minimal');
+});
+
+t('derivedReason names the fields that actually moved the level', () => {
+  const plain = r.derivedReason({});
+  assert.match(plain, /technical level: non-technical/);
+  assert.ok(!/machinery/.test(plain), 'a default field is not listed as a reason');
+  const quiet = r.derivedReason(withProfile({ technical_level: 'engineer', machinery: 'quiet' }));
+  assert.match(quiet, /machinery: quiet/);
+});
+
+console.log('\noverrides beat derivation:');
+
+t('an explicit level override wins over the profile', () => {
+  const eng = { interaction: { technical_level: 'engineer' }, widgets: 'rich' };
+  assert.equal(r.derivedLevel(eng), 'text', 'the profile would have said text');
+  assert.equal(r.resolveLevel(eng), 'rich', 'the override wins');
+  assert.equal(r.overrideLevel(eng), 'rich');
+});
+
+t('clearing the override falls back to the derived level', () => {
+  const cleared = r.applyPatch({ widgets: 'minimal', interaction: { technical_level: 'mixed' } }, { widgets: null });
+  assert.ok(!('widgets' in cleared));
+  assert.equal(r.resolveLevel(cleared), 'standard', 'back to what the profile says');
+  assert.equal(r.overrideLevel(cleared), null);
+});
+
+console.log('\nlegacy boolean compatibility (a pinned CLI / an older hall build):');
+
+t('a stored legacy boolean keeps the exact card it always meant', () => {
+  assert.equal(r.overrideLevel({ widgets: true }), 'standard');
+  assert.equal(r.overrideLevel({ widgets: false }), 'text');
+  // And it still beats the profile, because it IS an explicit choice.
+  assert.equal(r.resolveLevel({ widgets: false, interaction: { technical_level: 'non_technical' } }), 'text');
+});
+
+t('validatePatch still accepts booleans, normalising them to a level on the way in', () => {
+  assert.equal(r.validatePatch({ widgets: true }).patch.widgets, 'standard');
+  assert.equal(r.validatePatch({ widgets: false }).patch.widgets, 'text');
+});
+
+t('validatePatch accepts every level and rejects a non-level string', () => {
+  for (const lvl of r.LEVELS) {
+    assert.equal(r.validatePatch({ widgets: lvl }).ok, true, `accept ${lvl}`);
+  }
+  const bad = r.validatePatch({ widgets: 'verbose' });
+  assert.equal(bad.ok, false);
+  assert.equal(bad.errors[0].error, 'invalid_value');
+});
+
+t('widgetsEnabled — the boolean every pinned CLI reads — tracks the ladder', () => {
+  assert.equal(r.widgetsEnabled({ widgets: 'minimal' }), false);
+  assert.equal(r.widgetsEnabled({ widgets: 'text' }), false);
+  assert.equal(r.widgetsEnabled({ widgets: 'standard' }), true);
+  assert.equal(r.widgetsEnabled({ widgets: 'rich' }), true);
+});
+
+t('describeForApi keeps the legacy keys AND adds the ladder', () => {
+  const d = r.describeForApi({ interaction: { technical_level: 'engineer' } });
+  // legacy half — an older CLI reads only these and is correct
+  assert.equal(d.widgets_enabled, false, 'engineer derives text, so no widget');
+  assert.equal(d.default_enabled, true);
+  assert.equal(d.override, null, 'derived, not chosen');
+  // ladder half
+  assert.equal(d.level, 'text');
+  assert.equal(d.derived_level, 'text');
+  assert.equal(d.override_level, null);
+  assert.match(d.derived_reason, /technical level: engineer/);
+  assert.deepEqual(d.levels.map((l) => l.value), r.LEVELS);
+  assert.ok(d.levels.every((l) => l.label && l.blurb), 'every rung is labelled for the UI');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);