@bongos/core 1.17.0

package/tests/discord_role_sync.mjs

@@ -0,0 +1,151 @@
+// tests/discord_role_sync.mjs
+//
+// Unit tests for Discord role-sync (Phase 3 F5, ADR 0033 §4). Pure logic +
+// orchestration via injected fakes — no Discord, no DB:
+//   - rankToRoleId: only the 3 live ranks map; the unused ladder maps to null.
+//   - computeRoleChange: minimal idempotent add/remove over ONLY the 3 managed
+//     rank roles — never touches unrelated roles.
+//   - loadRoleMap: env parsing.
+//   - syncBuilderRole: resolves link + live rank, applies the change, best-effort.
+//
+// One-way invariant (GDS→Discord) is structural: this module only READS the GDS
+// and WRITES Discord; there is no path back. Live verification (real role
+// assignment) needs the bot on + Manage Roles and is deferred to go-live.
+//
+// Run:  node tests/discord_role_sync.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const rs = require('../modules/discord/discord-role-sync.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  return Promise.resolve().then(fn)
+    .then(() => { passed++; console.log(`  PASS  ${name}`); })
+    .catch((e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); });
+}
+
+const MAP = { xenos: 'R_X', thetes: 'R_T', metic: 'R_M', archon: 'R_A' };
+
+console.log('Discord role-sync (Phase 3 F5):');
+
+// ---- rankToRoleId ----------------------------------------------------------
+await t('rankToRoleId maps the 4 live ranks (incl. thetes), null for the unused ladder', () => {
+  assert.equal(rs.rankToRoleId('xenos', MAP), 'R_X');
+  assert.equal(rs.rankToRoleId('thetes', MAP), 'R_T');
+  assert.equal(rs.rankToRoleId('metic', MAP), 'R_M');
+  assert.equal(rs.rankToRoleId('archon', MAP), 'R_A');
+  for (const r of ['helot', 'olympian', 'strategos', 'doulos', '', null, undefined]) {
+    assert.equal(rs.rankToRoleId(r, MAP), null, `non-managed ${String(r)} → null`);
+  }
+});
+await t('rankToRoleId returns null for a managed rank with no mapping', () => {
+  assert.equal(rs.rankToRoleId('archon', { xenos: 'R_X' }), null);
+});
+
+// ---- computeRoleChange -----------------------------------------------------
+await t('computeRoleChange: no roles + metic → add metic, remove none', () => {
+  assert.deepEqual(rs.computeRoleChange([], 'metic', MAP), { add: 'R_M', remove: [] });
+});
+await t('computeRoleChange: had xenos, now metic → add metic, remove xenos', () => {
+  assert.deepEqual(rs.computeRoleChange(['R_X'], 'metic', MAP), { add: 'R_M', remove: ['R_X'] });
+});
+await t('computeRoleChange: already correct → noop', () => {
+  assert.deepEqual(rs.computeRoleChange(['R_M'], 'metic', MAP), { add: null, remove: [] });
+});
+await t('computeRoleChange: had two managed roles, now xenos → add xenos, remove the other two', () => {
+  const { add, remove } = rs.computeRoleChange(['R_A', 'R_M'], 'xenos', MAP);
+  assert.equal(add, 'R_X');
+  assert.deepEqual(remove.sort(), ['R_A', 'R_M']);
+});
+await t('computeRoleChange: never touches unrelated roles', () => {
+  // member has an unrelated role + already the right rank role → nothing to do
+  assert.deepEqual(rs.computeRoleChange(['R_M', 'UNRELATED'], 'metic', MAP), { add: null, remove: [] });
+});
+await t('computeRoleChange: non-managed rank strips managed roles, adds none', () => {
+  assert.deepEqual(rs.computeRoleChange(['R_M'], 'helot', MAP), { add: null, remove: ['R_M'] });
+});
+
+// ---- loadRoleMap (env) -----------------------------------------------------
+await t('loadRoleMap reads the env role ids (incl. thetes)', () => {
+  const env = { DISCORD_ROLE_XENOS: '1', DISCORD_ROLE_THETES: '4', DISCORD_ROLE_METIC: '2', DISCORD_ROLE_ARCHON: '3' };
+  assert.deepEqual(rs.loadRoleMap(env), { xenos: '1', thetes: '4', metic: '2', archon: '3' });
+});
+await t('loadRoleMap: thetes missing from env → omitted from map (partial config ok)', () => {
+  const env = { DISCORD_ROLE_XENOS: '1', DISCORD_ROLE_METIC: '2', DISCORD_ROLE_ARCHON: '3' };
+  assert.deepEqual(rs.loadRoleMap(env), { xenos: '1', metic: '2', archon: '3' });
+});
+await t('computeRoleChange: thetes → add thetes role, remove xenos if held', () => {
+  assert.deepEqual(rs.computeRoleChange(['R_X'], 'thetes', MAP), { add: 'R_T', remove: ['R_X'] });
+});
+
+// ---- syncBuilderRole (fakes) ----------------------------------------------
+function fakeMember(currentRoles) {
+  const calls = { add: [], remove: [] };
+  const member = {
+    roles: {
+      cache: new Map(currentRoles.map((r) => [r, r])),
+      add: async (id) => { calls.add.push(id); },
+      remove: async (ids) => { calls.remove.push(ids); },
+    },
+  };
+  return { member, calls };
+}
+function makeDeps(over = {}) {
+  const { member, calls } = fakeMember(over.currentRoles || []);
+  const deps = {
+    getDiscordLink: async () => (over.link === undefined ? { discord_user_id: '123' } : over.link),
+    getBuilderById: async () => (over.builder === undefined ? { id: 5, rank: 'metic' } : over.builder),
+    loadRoleMap: () => (over.roleMap === undefined ? MAP : over.roleMap),
+    getGuild: () => (over.guild === undefined
+      ? { members: { fetch: async () => (over.memberFound === false ? null : member) } }
+      : over.guild),
+  };
+  return { deps, calls };
+}
+
+await t('syncBuilderRole: linked metic with stale xenos role → removes xenos, adds metic', async () => {
+  const { deps, calls } = makeDeps({ currentRoles: ['R_X'], builder: { id: 5, rank: 'metic' } });
+  const r = await rs.syncBuilderRole(5, deps);
+  assert.equal(r.ok, true);
+  assert.deepEqual(calls.remove, [['R_X']]);
+  assert.deepEqual(calls.add, ['R_M']);
+});
+await t('syncBuilderRole: not linked → {ok:false, not_linked}, no role writes', async () => {
+  const { deps, calls } = makeDeps({ link: null });
+  const r = await rs.syncBuilderRole(5, deps);
+  assert.equal(r.ok, false); assert.equal(r.reason, 'not_linked');
+  assert.equal(calls.add.length + calls.remove.length, 0);
+});
+await t('syncBuilderRole: no role map configured → inert', async () => {
+  const r = await rs.syncBuilderRole(5, makeDeps({ roleMap: {} }).deps);
+  assert.equal(r.reason, 'no_role_map');
+});
+await t('syncBuilderRole: bot not in a guild → {ok:false, no_guild}', async () => {
+  const r = await rs.syncBuilderRole(5, makeDeps({ guild: null }).deps);
+  assert.equal(r.reason, 'no_guild');
+});
+await t('syncBuilderRole: member left the guild → {ok:false, member_not_found}', async () => {
+  const r = await rs.syncBuilderRole(5, makeDeps({ memberFound: false }).deps);
+  assert.equal(r.reason, 'member_not_found');
+});
+await t('syncBuilderRole: already correct → noop, no writes', async () => {
+  const { deps, calls } = makeDeps({ currentRoles: ['R_M'], builder: { id: 5, rank: 'metic' } });
+  const r = await rs.syncBuilderRole(5, deps);
+  assert.equal(r.ok, true); assert.equal(r.noop, true);
+  assert.equal(calls.add.length + calls.remove.length, 0);
+});
+await t('syncBuilderRole: never throws on a Discord error', async () => {
+  const deps = {
+    getDiscordLink: async () => ({ discord_user_id: '123' }),
+    getBuilderById: async () => ({ id: 5, rank: 'metic' }),
+    loadRoleMap: () => MAP,
+    getGuild: () => ({ members: { fetch: async () => { throw new Error('discord 500'); } } }),
+  };
+  const r = await rs.syncBuilderRole(5, deps);
+  assert.equal(r.ok, false);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/display_name.mjs

@@ -0,0 +1,123 @@
+// tests/display_name.mjs
+//
+// Unit smoke for modules/builder-settings/display-name.js (task 1669) — the pure
+// validator behind GET/PATCH /me/display-name (the self-service display-name
+// editor). Covers the rules the route enforces: trim, reject empty /
+// whitespace-only, the length ceiling, and control-character rejection. The DB
+// write + route plumbing are exercised by the prod smoke; here we cover the
+// pure logic without touching pg.
+//
+// Run:  node tests/display_name.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const d = require('../modules/builder-settings/display-name.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// Control characters, built from code points so the source stays clean text.
+const NUL = String.fromCharCode(0x00); // C0
+const BEL = String.fromCharCode(0x07); // C0
+const TAB = String.fromCharCode(0x09); // C0
+const NL  = String.fromCharCode(0x0a); // C0
+const DEL = String.fromCharCode(0x7f); // DEL
+const C1  = String.fromCharCode(0x85); // C1 block (NEL)
+
+console.log('display-name constants:');
+
+t('MAX_LENGTH is a sensible positive ceiling', () => {
+  assert.equal(typeof d.MAX_LENGTH, 'number');
+  assert.ok(d.MAX_LENGTH > 0 && d.MAX_LENGTH <= 255);
+});
+
+console.log('\nvalid names:');
+
+t('accepts a normal name and returns it trimmed', () => {
+  const r = d.validate('Ada Lovelace');
+  assert.equal(r.ok, true);
+  assert.equal(r.value, 'Ada Lovelace');
+});
+
+t('trims leading/trailing whitespace from the stored value', () => {
+  const r = d.validate('   Jaxri   ');
+  assert.equal(r.ok, true);
+  assert.equal(r.value, 'Jaxri');
+});
+
+t('keeps interior spaces and unicode (emoji, accents) intact', () => {
+  const r = d.validate('Renée 🛠 the Builder');
+  assert.equal(r.ok, true);
+  assert.equal(r.value, 'Renée 🛠 the Builder');
+});
+
+t('accepts a name exactly at the length ceiling', () => {
+  const name = 'x'.repeat(d.MAX_LENGTH);
+  const r = d.validate(name);
+  assert.equal(r.ok, true);
+  assert.equal(r.value, name);
+});
+
+console.log('\nrejected names:');
+
+t('rejects a non-string body value', () => {
+  for (const bad of [undefined, null, 7, true, {}, ['x']]) {
+    const r = d.validate(bad);
+    assert.equal(r.ok, false, `reject ${JSON.stringify(bad)}`);
+    assert.equal(r.errors[0].error, 'must_be_string');
+  }
+});
+
+t('rejects empty and whitespace-only names', () => {
+  for (const bad of ['', '   ', TAB, NL + '  ' + NL]) {
+    const r = d.validate(bad);
+    assert.equal(r.ok, false, `reject ${JSON.stringify(bad)}`);
+    assert.equal(r.errors[0].error, 'empty');
+  }
+});
+
+t('rejects a name longer than the ceiling (counted in code points)', () => {
+  const r = d.validate('x'.repeat(d.MAX_LENGTH + 1));
+  assert.equal(r.ok, false);
+  assert.equal(r.errors[0].error, 'too_long');
+  assert.equal(r.errors[0].max, d.MAX_LENGTH);
+});
+
+t('length is counted AFTER trimming (trailing spaces do not push over)', () => {
+  const r = d.validate('x'.repeat(d.MAX_LENGTH) + '     ');
+  assert.equal(r.ok, true);
+  assert.equal(d.codePointLength(r.value), d.MAX_LENGTH);
+});
+
+t('rejects interior control characters: C0, DEL, tab, newline, C1', () => {
+  const cases = [`Na${NUL}me`, `Na${BEL}me`, `Tab${TAB}Name`, `Line${NL}Break`, `Del${DEL}ete`, `C1${C1}here`];
+  for (const bad of cases) {
+    const r = d.validate(bad);
+    assert.equal(r.ok, false, `reject ${JSON.stringify(bad)}`);
+    // none of these trim to empty, so the error must be control_char.
+    assert.equal(r.errors[0].error, 'control_char', `for ${JSON.stringify(bad)}`);
+  }
+});
+
+console.log('\nhelpers:');
+
+t('codePointLength counts astral characters as one', () => {
+  assert.equal(d.codePointLength('ab'), 2);
+  assert.equal(d.codePointLength('🛠'), 1); // one astral code point (2 UTF-16 units)
+  assert.equal(d.codePointLength('é'), 1);
+});
+
+t('hasControlChar detects control chars and clears normal text', () => {
+  assert.equal(d.hasControlChar('plain text 123'), false);
+  assert.equal(d.hasControlChar(`with${TAB}tab`), true);
+  assert.equal(d.hasControlChar(`with${BEL}bell`), true);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/dns_preflight.mjs

@@ -0,0 +1,74 @@
+// tests/dns_preflight.mjs — DB-free unit tests for the DNS token-scope preflight
+// (scripts/gds/provision.js classifyZoneScope + checkDnsTokenScope, task 1980).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const prov = require('../scripts/gds/provision.js');
+
+test('classifyZoneScope: a token that sees the zone is reachable', () => {
+  const r = prov.classifyZoneScope({ status: 200, body: { success: true, result: [{ name: 'example.com', id: 'z1' }] }, zone: 'example.com' });
+  assert.equal(r.reachable, true);
+  assert.equal(r.zoneId, 'z1');
+});
+
+test('classifyZoneScope: authenticated but zone NOT in scope → not reachable + widen guidance (the standup failure)', () => {
+  const r = prov.classifyZoneScope({ status: 200, body: { success: true, result: [] }, zone: 'newproject.com' });
+  assert.equal(r.reachable, false);
+  assert.match(r.reason, /not in its scope/i);
+  assert.match(r.guidance, /widen|include/i);
+  assert.match(r.guidance, /newproject\.com/);
+});
+
+test('classifyZoneScope: result lists a DIFFERENT zone → not reachable', () => {
+  const r = prov.classifyZoneScope({ status: 200, body: { success: true, result: [{ name: 'other.com', id: 'z9' }] }, zone: 'example.com' });
+  assert.equal(r.reachable, false);
+});
+
+test('classifyZoneScope: 403 → not reachable + token-scope guidance', () => {
+  const r = prov.classifyZoneScope({ status: 403, body: { success: false, errors: [{ message: 'Invalid token' }] }, zone: 'example.com' });
+  assert.equal(r.reachable, false);
+  assert.match(r.reason, /rejected the token/i);
+  assert.match(r.guidance, /CLOUDFLARE_API_TOKEN/);
+});
+
+test('classifyZoneScope: non-200 / success:false → not reachable', () => {
+  assert.equal(prov.classifyZoneScope({ status: 500, body: null, zone: 'x.com' }).reachable, false);
+  assert.equal(prov.classifyZoneScope({ status: 200, body: { success: false, errors: [{ message: 'oops' }] }, zone: 'x.com' }).reachable, false);
+});
+
+test('checkDnsTokenScope: derives the zone + reports reachable via an injected fetch', async () => {
+  const calls = [];
+  const fakeFetch = async (url, opts) => {
+    calls.push({ url, auth: opts.headers.Authorization });
+    return { status: 200, json: async () => ({ success: true, result: [{ name: 'example.com', id: 'zX' }] }) };
+  };
+  const r = await prov.checkDnsTokenScope('mercury.example.com', { token: 'tok_123', fetchImpl: fakeFetch });
+  assert.equal(r.zone, 'example.com');            // derived from the sub-domain
+  assert.equal(r.reachable, true);
+  assert.match(calls[0].url, /zones\?name=example\.com/);
+  assert.equal(calls[0].auth, 'Bearer tok_123');
+});
+
+test('checkDnsTokenScope: empty result → not reachable (guides widening)', async () => {
+  const fakeFetch = async () => ({ status: 200, json: async () => ({ success: true, result: [] }) });
+  const r = await prov.checkDnsTokenScope('app.newproject.com', { token: 'tok', fetchImpl: fakeFetch });
+  assert.equal(r.reachable, false);
+  assert.match(r.guidance, /widen|include/i);
+});
+
+test('checkDnsTokenScope: no token configured → not reachable, no network call', async () => {
+  let called = false;
+  const fakeFetch = async () => { called = true; return { status: 200, json: async () => ({}) }; };
+  const r = await prov.checkDnsTokenScope('example.com', { token: '', fetchImpl: fakeFetch });
+  assert.equal(r.reachable, false);
+  assert.match(r.reason, /no CLOUDFLARE_API_TOKEN/);
+  assert.equal(called, false);
+});
+
+test('checkDnsTokenScope: a thrown fetch is caught → not reachable', async () => {
+  const fakeFetch = async () => { throw new Error('ENETUNREACH'); };
+  const r = await prov.checkDnsTokenScope('example.com', { token: 'tok', fetchImpl: fakeFetch });
+  assert.equal(r.reachable, false);
+  assert.match(r.reason, /request failed/i);
+});

package/tests/event_sound_prefs.mjs

@@ -0,0 +1,194 @@
+// tests/event_sound_prefs.mjs
+//
+// Unit smoke for modules/builder-settings/event-sound-prefs.js (task 1495) —
+// the per-builder per-event sound-VARIANT selection (migration 164). The five
+// pure shapers turn a raw event_sound_prefs jsonb blob into effective values:
+//   resolveVariant / resolveWav — pick the variant (or its backing .wav) for an
+//     event, honouring a stored override only when it's a known variant id;
+//   listEffective / effectiveWavMap — the /me + offline-hook payloads;
+//   validatePatch / applyPatch — the PATCH-body validator + the merge that
+//     honours the null clear-sentinel.
+// All deterministic, zero DB/network — DB plumbing lives in routes/settings.js +
+// the prod smoke. Run:  node tests/event_sound_prefs.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const e = require('../modules/builder-settings/event-sound-prefs.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL  ${name}\n        ${err.message}`); }
+}
+
+console.log('constants / shape:');
+
+t('EVENTS lists the 5 build events in UI order', () => {
+  assert.deepEqual(
+    e.EVENTS.map((ev) => ev.id),
+    ['user-input', 'task-shipped', 'credits-awarded', 'rank-promoted', 'achievement'],
+  );
+});
+
+t('every event has exactly one default variant', () => {
+  for (const ev of e.EVENTS) {
+    const defaults = ev.variants.filter((v) => v.isDefault);
+    assert.equal(defaults.length, 1, `${ev.id} has one default`);
+  }
+});
+
+t('EVENT_DEFAULT maps each event to its default variant id', () => {
+  assert.equal(e.EVENT_DEFAULT['user-input'], 'lyre-pluck');
+  assert.equal(e.EVENT_DEFAULT['task-shipped'], 'bronze-fanfare');
+  assert.equal(e.EVENT_DEFAULT['credits-awarded'], 'coin-clink');
+  assert.equal(e.EVENT_DEFAULT['rank-promoted'], 'herald-call');
+  assert.equal(e.EVENT_DEFAULT['achievement'], 'harp-flourish');
+});
+
+t('VARIANT_WAV backs each variant id with an existing .wav name', () => {
+  assert.equal(e.VARIANT_WAV['lyre-pluck'], 'alert');
+  assert.equal(e.VARIANT_WAV['triumph-call'], 'triumph');
+  assert.equal(e.VARIANT_WAV['herald-call'], 'fanfare');
+});
+
+t('KNOWN_*_IDS membership sets are correct', () => {
+  assert.ok(e.KNOWN_EVENT_IDS.has('rank-promoted'));
+  assert.ok(!e.KNOWN_EVENT_IDS.has('nope'));
+  assert.ok(e.KNOWN_VARIANT_IDS.has('chime-soft'));
+  assert.ok(!e.KNOWN_VARIANT_IDS.has('nope'));
+});
+
+console.log('\nresolveVariant (the chosen variant id):');
+
+t('falls back to the default when prefs are empty / null / undefined', () => {
+  assert.equal(e.resolveVariant('task-shipped', {}), 'bronze-fanfare');
+  assert.equal(e.resolveVariant('task-shipped', null), 'bronze-fanfare');
+  assert.equal(e.resolveVariant('task-shipped', undefined), 'bronze-fanfare');
+});
+
+t('honours a stored override that is a known variant id', () => {
+  assert.equal(e.resolveVariant('task-shipped', { 'task-shipped': 'triumph-call' }), 'triumph-call');
+});
+
+t('ignores a stored value that is not a known variant id', () => {
+  assert.equal(e.resolveVariant('task-shipped', { 'task-shipped': 'bogus' }), 'bronze-fanfare');
+  assert.equal(e.resolveVariant('task-shipped', { 'task-shipped': 42 }), 'bronze-fanfare');
+  assert.equal(e.resolveVariant('task-shipped', { 'task-shipped': null }), 'bronze-fanfare');
+});
+
+t('does NOT cross-check the variant belongs to the event (resolve trusts KNOWN_VARIANT_IDS only)', () => {
+  // a variant valid for a DIFFERENT event is still accepted by resolveVariant —
+  // documents the real behaviour: only validatePatch enforces event↔variant.
+  assert.equal(e.resolveVariant('task-shipped', { 'task-shipped': 'lyre-pluck' }), 'lyre-pluck');
+});
+
+console.log('\nresolveWav (the .wav the hook plays):');
+
+t('resolves a variant to its backing .wav', () => {
+  assert.equal(e.resolveWav('task-shipped', {}), 'ship');
+  assert.equal(e.resolveWav('task-shipped', { 'task-shipped': 'triumph-call' }), 'triumph');
+});
+
+t('unknown event id falls back to the "chime" safety default', () => {
+  assert.equal(e.resolveWav('no-such-event', {}), 'chime');
+});
+
+console.log('\nlistEffective / effectiveWavMap (the payloads):');
+
+t('listEffective returns one entry per event with selected + wav', () => {
+  const list = e.listEffective({ 'task-shipped': 'triumph-call' });
+  assert.equal(list.length, e.EVENTS.length);
+  const shipped = list.find((row) => row.event === 'task-shipped');
+  assert.equal(shipped.selected, 'triumph-call');
+  assert.equal(shipped.wav, 'triumph');
+  assert.equal(shipped.label, 'Task Shipped');
+  assert.equal(shipped.variants[0].is_default, true);
+});
+
+t('effectiveWavMap maps every event id to its resolved wav', () => {
+  const m = e.effectiveWavMap({});
+  assert.deepEqual(Object.keys(m).sort(), e.EVENTS.map((ev) => ev.id).sort());
+  assert.equal(m['task-shipped'], 'ship');
+  const overridden = e.effectiveWavMap({ 'task-shipped': 'triumph-call' });
+  assert.equal(overridden['task-shipped'], 'triumph');
+});
+
+console.log('\nvalidatePatch:');
+
+t('rejects non-object bodies', () => {
+  for (const bad of [null, undefined, 'x', 7, [true]]) {
+    const v = e.validatePatch(bad);
+    assert.equal(v.ok, false, `reject ${JSON.stringify(bad)}`);
+    assert.equal(v.errors[0].error, 'body_must_be_object');
+  }
+});
+
+t('accepts an empty body (no-op patch)', () => {
+  const v = e.validatePatch({});
+  assert.equal(v.ok, true);
+  assert.deepEqual(v.patch, {});
+});
+
+t('accepts a valid event→variant pair', () => {
+  const v = e.validatePatch({ 'task-shipped': 'triumph-call' });
+  assert.equal(v.ok, true);
+  assert.equal(v.patch['task-shipped'], 'triumph-call');
+});
+
+t('accepts the null clear-sentinel', () => {
+  const v = e.validatePatch({ 'task-shipped': null });
+  assert.equal(v.ok, true);
+  assert.equal(v.patch['task-shipped'], null);
+});
+
+t('rejects an unknown event id', () => {
+  const v = e.validatePatch({ 'no-such-event': 'lyre-pluck' });
+  assert.equal(v.ok, false);
+  assert.equal(v.errors[0].error, 'unknown_event');
+});
+
+t('rejects a non-string, non-null variant value', () => {
+  const v = e.validatePatch({ 'task-shipped': 42 });
+  assert.equal(v.ok, false);
+  assert.equal(v.errors[0].error, 'variant_must_be_string_or_null');
+});
+
+t('rejects a variant that exists but belongs to a DIFFERENT event', () => {
+  // lyre-pluck is a real variant id, but only for user-input — not task-shipped.
+  const v = e.validatePatch({ 'task-shipped': 'lyre-pluck' });
+  assert.equal(v.ok, false);
+  assert.equal(v.errors[0].error, 'variant_not_for_event');
+});
+
+t('collects MULTIPLE errors and emits no patch when any field is bad', () => {
+  const v = e.validatePatch({ 'no-such-event': 'x', 'task-shipped': 99 });
+  assert.equal(v.ok, false);
+  assert.equal(v.errors.length, 2);
+  assert.ok(!('patch' in v)); // a failed validation returns no patch
+});
+
+console.log('\napplyPatch:');
+
+t('sets a value onto an empty/undefined existing blob', () => {
+  assert.equal(e.applyPatch({}, { 'task-shipped': 'triumph-call' })['task-shipped'], 'triumph-call');
+  assert.equal(e.applyPatch(undefined, { 'task-shipped': 'triumph-call' })['task-shipped'], 'triumph-call');
+});
+
+t('null clears the override key entirely', () => {
+  const next = e.applyPatch({ 'task-shipped': 'triumph-call' }, { 'task-shipped': null });
+  assert.ok(!('task-shipped' in next));
+});
+
+t('leaves sibling event keys untouched and does not mutate the input', () => {
+  const existing = { 'user-input': 'chime-soft' };
+  const next = e.applyPatch(existing, { 'task-shipped': 'triumph-call' });
+  assert.equal(next['user-input'], 'chime-soft', 'sibling preserved');
+  assert.equal(next['task-shipped'], 'triumph-call');
+  assert.ok(!('task-shipped' in existing), 'input not mutated');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);