@bongos/core 1.17.0

package/tests/discord_bugs.mjs

@@ -0,0 +1,297 @@
+// tests/discord_bugs.mjs
+//
+// Unit tests for Discord #bugs → GDS tasks (kind='bug') (Phase 3 F8, ADR 0047).
+// Pure screening/landing + orchestration via injected fakes — no Discord, no DB:
+//   - screenBug: message → { ok, title, bodyMd }; blank/short/text-free rejected.
+//   - decideBugLanding: Metic+ → 'ready'; everyone else linked → 'backlog'.
+//   - recordInboundBug: files via createTask under the anti-abuse guard —
+//     linked-only (unlinked rejected), rank-aware landing, per-builder
+//     rate-limit, body screen; audits surface='discord_bot'; never throws.
+//
+// Run:  node tests/discord_bugs.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const bg = require('../modules/discord/discord-bugs.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 GOOD_ID = '123456789012345678';
+const CFG = { rateLimitPerHour: 5, versionId: 'GDS-V3', credits: 10 };
+
+console.log('Discord #bugs → GDS tasks (Phase 3 F8):');
+
+// ---- screenBug -------------------------------------------------------------
+await t('screenBug: first line is the title, full text is the body', () => {
+  const s = bg.screenBug('Vendor dialog crashes\n\nhappens when you press B twice');
+  assert.equal(s.ok, true);
+  assert.equal(s.title, 'Vendor dialog crashes');
+  assert.equal(s.bodyMd, 'Vendor dialog crashes\n\nhappens when you press B twice');
+});
+await t('screenBug: blank / non-string → empty', () => {
+  for (const c of ['', '   ', '\n\n', null, undefined, 42]) {
+    assert.equal(bg.screenBug(c).reason, 'empty');
+  }
+});
+await t('screenBug: too-short → too_short', () => {
+  assert.equal(bg.screenBug('broke').reason, 'too_short');
+});
+await t('screenBug: text-free (no letters) → no_text', () => {
+  assert.equal(bg.screenBug('1234567890 !!!').reason, 'no_text');
+});
+await t('screenBug: long first line is capped (≤200, ellipsis)', () => {
+  const s = bg.screenBug('x'.repeat(300));
+  assert.ok(s.title.length <= 200, `title len ${s.title.length}`);
+  assert.ok(s.title.endsWith('…'));
+});
+
+// ---- decideBugLanding ------------------------------------------------------
+await t('decideBugLanding: Metic+ → ready', () => {
+  assert.equal(bg.decideBugLanding('metic'), 'ready');
+  assert.equal(bg.decideBugLanding('archon'), 'ready');
+  assert.equal(bg.decideBugLanding('ARCHON'), 'ready');
+});
+await t('decideBugLanding: Xenos/Thetes/unknown → backlog', () => {
+  for (const r of ['xenos', 'thetes', 'periokoi', '', null, undefined]) {
+    assert.equal(bg.decideBugLanding(r), 'backlog');
+  }
+});
+
+// ---- recordInboundBug (fakes) ---------------------------------------------
+function makeDeps(over = {}) {
+  const calls = { create: [], audit: [], count: [], persist: [] };
+  const deps = {
+    getBuilderByDiscordUserId: async () => (over.builder === undefined ? null : over.builder),
+    countRecentDiscordBugFilings: async (id, since) => {
+      calls.count.push({ id, since });
+      if (over.countThrows) throw new Error('count boom');
+      return over.recent ?? 0;
+    },
+    createTask: async (a) => { calls.create.push(a); if (over.createThrows) throw new Error('db boom'); return { id: over.taskId ?? 555 }; },
+    insertAuditLog: async (a) => { calls.audit.push(a); if (over.auditThrows) throw new Error('audit boom'); return { id: 1 }; },
+    persistImages: async (urls, opts) => {
+      calls.persist.push({ urls, opts });
+      if (over.persistThrows) throw new Error('persist boom');
+      // default: echo each url back as a stored ref unless overridden
+      return over.stored ?? urls.map((u, i) => ({ file: `bug-x-${i}.png`, url: `/api/gds/bug-attachments/bug-x-${i}.png` }));
+    },
+  };
+  return { deps, calls };
+}
+
+await t('recordInboundBug: linked Metic → filed at ready, kind=bug, attributed + audited', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' } });
+  const r = await bg.recordInboundBug({ discordUserId: GOOD_ID, content: 'Boats vanish at the dock', messageId: 'm1' }, deps, CFG);
+  assert.equal(r.outcome, 'filed');
+  assert.equal(r.taskId, 555);
+  assert.equal(r.status, 'ready');
+  assert.equal(calls.create[0].kind, 'bug');
+  assert.equal(calls.create[0].status, 'ready');
+  assert.equal(calls.create[0].source, 'discord:bugs');
+  assert.equal(calls.create[0].sourceRef, 'discord:m1');
+  assert.equal(calls.create[0].versionId, 'GDS-V3');
+  assert.match(calls.create[0].description, /reported from Discord #bugs by mona/);
+  assert.equal(calls.audit[0].surface, 'discord_bot');
+  assert.equal(calls.audit[0].responseStatus, 201);
+  assert.equal(calls.audit[0].builderId, 9);
+});
+
+await t('recordInboundBug: linked Xenos → filed at backlog (needs confirm)', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 4, github_login: 'newbie', rank: 'xenos' } });
+  const r = await bg.recordInboundBug({ discordUserId: GOOD_ID, content: 'Typo on the welcome sign', messageId: 'm2' }, deps, CFG);
+  assert.equal(r.outcome, 'filed');
+  assert.equal(r.status, 'backlog');
+  assert.equal(calls.create[0].status, 'backlog');
+});
+
+await t('recordInboundBug: UNLINKED author → ignored, nothing created', async () => {
+  const { deps, calls } = makeDeps({ builder: null });
+  const r = await bg.recordInboundBug({ discordUserId: GOOD_ID, content: 'something is broken here', messageId: 'm3' }, deps, CFG);
+  assert.equal(r.outcome, 'ignored');
+  assert.equal(r.reason, 'unlinked');
+  assert.equal(calls.create.length, 0);
+});
+
+await t('recordInboundBug: over rate-limit → ignored + audited 429, nothing created', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' }, recent: 5 });
+  const r = await bg.recordInboundBug({ discordUserId: GOOD_ID, content: 'yet another bug report', messageId: 'm4' }, deps, CFG);
+  assert.equal(r.outcome, 'ignored');
+  assert.equal(r.reason, 'rate_limited');
+  assert.equal(calls.create.length, 0);
+  assert.equal(calls.audit[0].responseStatus, 429);
+  assert.equal(calls.audit[0].surface, 'discord_bot');
+});
+
+await t('recordInboundBug: under rate-limit (recent < cap) → filed', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' }, recent: 4 });
+  const r = await bg.recordInboundBug({ discordUserId: GOOD_ID, content: 'one more valid bug', messageId: 'm5' }, deps, CFG);
+  assert.equal(r.outcome, 'filed');
+  assert.equal(calls.create.length, 1);
+});
+
+await t('recordInboundBug: rate-limit count failure → fails CLOSED (denied + 429 audited, nothing created) [L4 #999]', async () => {
+  // The old behaviour failed OPEN (filed anyway) — a DB error could be used to
+  // slip past the per-builder limit. Now a count error denies the request.
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' }, countThrows: true });
+  const r = await bg.recordInboundBug({ discordUserId: GOOD_ID, content: 'count is broken so deny it', messageId: 'm6' }, deps, CFG);
+  assert.equal(r.outcome, 'ignored');
+  assert.equal(r.reason, 'rate_limit_count_error', 'a count error is a distinct, forensically-visible reason');
+  assert.equal(calls.create.length, 0, 'must not file when the limit could not be verified');
+  assert.equal(calls.audit[0].responseStatus, 429);
+  assert.equal(calls.audit[0].surface, 'discord_bot');
+});
+
+await t('recordInboundBug: bad discord id → ignored, no builder lookup', async () => {
+  const { deps, calls } = makeDeps();
+  const r = await bg.recordInboundBug({ discordUserId: 'nope', content: 'a real bug body', messageId: 'm' }, deps, CFG);
+  assert.equal(r.outcome, 'ignored');
+  assert.equal(r.reason, 'bad_discord_user_id');
+  assert.equal(calls.create.length, 0);
+});
+
+await t('recordInboundBug: too-short body → ignored before any lookup', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' } });
+  const r = await bg.recordInboundBug({ discordUserId: GOOD_ID, content: 'broke', messageId: 'm' }, deps, CFG);
+  assert.equal(r.outcome, 'ignored');
+  assert.equal(r.reason, 'too_short');
+  assert.equal(calls.create.length, 0);
+});
+
+await t('recordInboundBug: audit failure does NOT undo the filing', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' }, auditThrows: true });
+  const r = await bg.recordInboundBug({ discordUserId: GOOD_ID, content: 'valid bug, broken audit', messageId: 'm' }, deps, CFG);
+  assert.equal(r.outcome, 'filed');
+  assert.equal(calls.create.length, 1);
+});
+
+await t('recordInboundBug: createTask error → {error}, never throws', async () => {
+  const { deps } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' }, createThrows: true });
+  const r = await bg.recordInboundBug({ discordUserId: GOOD_ID, content: 'valid bug body here', messageId: 'm' }, deps, CFG);
+  assert.equal(r.outcome, 'error');
+});
+
+// ---- images (task #936) ----------------------------------------------------
+await t('screenBug: image-only (no text) → ok with default screenshot title', () => {
+  const s = bg.screenBug('', { hasImages: true });
+  assert.equal(s.ok, true);
+  assert.equal(s.title, 'Bug report (screenshot)');
+  assert.equal(s.bodyMd, '');
+});
+await t('screenBug: short text + image → ok, keeps the short text as title', () => {
+  const s = bg.screenBug('oops', { hasImages: true });
+  assert.equal(s.ok, true);
+  assert.equal(s.title, 'oops');
+});
+await t('screenBug: no text AND no images → still rejected', () => {
+  assert.equal(bg.screenBug('', { hasImages: false }).ok, false);
+});
+
+await t('recordInboundBug: text + images → persists images + embeds durable links', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' } });
+  const r = await bg.recordInboundBug(
+    { discordUserId: GOOD_ID, content: 'Vendor sprite is pink', imageUrls: ['https://cdn.discordapp.com/a.png'], messageId: 'm9' },
+    deps, CFG
+  );
+  assert.equal(r.outcome, 'filed');
+  assert.equal(r.images, 1);
+  assert.equal(calls.persist.length, 1);
+  assert.deepEqual(calls.persist[0].urls, ['https://cdn.discordapp.com/a.png']);
+  assert.match(calls.create[0].description, /Attachments \(1\)/);
+  assert.match(calls.create[0].description, /!\[attachment 1\]\(\/api\/gds\/bug-attachments\//);
+});
+
+await t('recordInboundBug: image-only (empty text) → filed with screenshot title', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' } });
+  const r = await bg.recordInboundBug(
+    { discordUserId: GOOD_ID, content: '', imageUrls: ['https://cdn.discordapp.com/b.png'], messageId: 'm10' },
+    deps, CFG
+  );
+  assert.equal(r.outcome, 'filed');
+  assert.equal(calls.create[0].title, 'Bug report (screenshot)');
+  assert.equal(r.images, 1);
+});
+
+await t('recordInboundBug: image persist failure → still files (without images)', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' }, persistThrows: true });
+  const r = await bg.recordInboundBug(
+    { discordUserId: GOOD_ID, content: 'a real bug with a broken upload', imageUrls: ['https://cdn.discordapp.com/c.png'], messageId: 'm11' },
+    deps, CFG
+  );
+  assert.equal(r.outcome, 'filed');
+  assert.equal(r.images, 0);
+  assert.doesNotMatch(calls.create[0].description, /Attachments/);
+});
+
+await t('recordInboundBug: all images refused (stored empty) → filed, no Attachments block', async () => {
+  const { deps, calls } = makeDeps({ builder: { id: 9, github_login: 'mona', rank: 'metic' }, stored: [] });
+  const r = await bg.recordInboundBug(
+    { discordUserId: GOOD_ID, content: 'bug text here', imageUrls: ['https://evil.example/x.png'], messageId: 'm12' },
+    deps, CFG
+  );
+  assert.equal(r.outcome, 'filed');
+  assert.equal(r.images, 0);
+  assert.doesNotMatch(calls.create[0].description, /Attachments/);
+});
+
+// ---- combineParts ----------------------------------------------------------
+await t('combineParts: joins text + concatenates images, anchors on first message', () => {
+  const c = bg.combineParts([
+    { content: '', imageUrls: ['i1'], messageId: 'first' },
+    { content: 'here is what happened', imageUrls: ['i2'], messageId: 'second' },
+  ]);
+  assert.equal(c.content, 'here is what happened');
+  assert.deepEqual(c.imageUrls, ['i1', 'i2']);
+  assert.equal(c.messageId, 'first');
+});
+await t('combineParts: two text parts → blank-line joined', () => {
+  const c = bg.combineParts([
+    { content: 'line one', imageUrls: [], messageId: 'a' },
+    { content: 'line two', imageUrls: [], messageId: 'b' },
+  ]);
+  assert.equal(c.content, 'line one\n\nline two');
+});
+
+// ---- createBugAggregator (fake timers) ------------------------------------
+function fakeTimers() {
+  let seq = 0; const jobs = new Map();
+  return {
+    setTimeout: (fn) => { const id = ++seq; jobs.set(id, fn); return { id }; },
+    clearTimeout: (h) => { if (h && jobs.has(h.id)) jobs.delete(h.id); },
+    runAll: () => { for (const [, fn] of jobs) fn(); jobs.clear(); },
+    size: () => jobs.size,
+  };
+}
+
+await t('createBugAggregator: a burst from one author flushes as ONE combined bug', async () => {
+  const flushed = [];
+  const timers = fakeTimers();
+  const agg = bg.createBugAggregator({ onFlush: async (c) => { flushed.push(c); }, windowMs: 1000, timers });
+  agg.enqueue({ discordUserId: GOOD_ID, content: 'screenshot incoming', imageUrls: ['i1'], messageId: 'm1' });
+  agg.enqueue({ discordUserId: GOOD_ID, content: '', imageUrls: ['i2'], messageId: 'm2' });
+  assert.equal(flushed.length, 0, 'nothing files until the window elapses');
+  timers.runAll();
+  await new Promise((r) => setImmediate(r));
+  assert.equal(flushed.length, 1);
+  assert.equal(flushed[0].content, 'screenshot incoming');
+  assert.deepEqual(flushed[0].imageUrls, ['i1', 'i2']);
+});
+
+await t('createBugAggregator: two authors flush independently', async () => {
+  const flushed = [];
+  const timers = fakeTimers();
+  const agg = bg.createBugAggregator({ onFlush: async (c) => { flushed.push(c); }, windowMs: 1000, timers });
+  agg.enqueue({ discordUserId: '111111111111111111', content: 'bug A', imageUrls: [], messageId: 'a' });
+  agg.enqueue({ discordUserId: '222222222222222222', content: 'bug B', imageUrls: [], messageId: 'b' });
+  agg.flushAll();
+  await new Promise((r) => setImmediate(r));
+  assert.equal(flushed.length, 2);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/discord_channels.mjs

@@ -0,0 +1,337 @@
+// tests/discord_channels.mjs
+//
+// Unit tests for bot-managed Discord channels (ADR 0037, task #727). Pure
+// logic only — no Discord, no DB:
+//   - slugify: emoji + separators stripped to a stable match key.
+//   - resolveViewRoles: "everyone" vs a rank -> that rank and every rank above.
+//   - mergeViewOverwrites: VIEW bit set/cleared while non-VIEW bits + unmanaged
+//     ids are preserved.
+//   - viewOverwritesEqual: compares ONLY the managed VIEW decisions (idempotency).
+//   - planChannelReconcile: create-missing, edit-on-drift, no-op when in sync,
+//     never deletes, warns on a missing role id.
+//
+// One-way invariant (config -> Discord) is structural: this module only READS
+// the repo config and WRITES Discord. Live verification (real channel edits)
+// needs the bot on + Manage Channels and is deferred to go-live.
+//
+// Apply-layer note (#733): reconcileChannels writes an edit-channel as TWO
+// best-effort PATCHes — topic+parent (Manage Channels) separate from
+// permission_overwrites (Manage Permissions) — so a description still lands on
+// a private channel where the bot lacks Manage Permissions. That split lives in
+// the IO layer (raw Discord REST, not injectable here) and is verified live;
+// the pure planner below is unchanged.
+//
+// Run:  node tests/discord_channels.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const ch = require('../modules/discord/discord-channels.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 EVERYONE = '999000'; // guild id == @everyone role id
+const ROLE_MAP = { xenos: 'R_XEN', thetes: 'R_THE', metic: 'R_MET', archon: 'R_ARC' };
+const CTX = { everyoneId: EVERYONE, roleMap: ROLE_MAP };
+const VIEW = ch.VIEW_CHANNEL; // 1024n
+
+// Helper: does an overwrite list ALLOW view for an id?
+function allowsView(list, id) {
+  const o = list.find((x) => String(x.id) === String(id));
+  return !!o && (BigInt(o.allow) & VIEW) === VIEW;
+}
+function deniesView(list, id) {
+  const o = list.find((x) => String(x.id) === String(id));
+  return !!o && (BigInt(o.deny) & VIEW) === VIEW;
+}
+
+await t('slugify strips emoji and separators', () => {
+  assert.equal(ch.slugify('📯-ship-news'), 'ship-news');
+  assert.equal(ch.slugify('👋-welcome-and-start'), 'welcome-and-start');
+  assert.equal(ch.slugify('🛠️-ship-feed'), 'ship-feed');
+  assert.equal(ch.slugify('BUILDERS'), 'builders');
+});
+
+await t('resolveViewRoles everyone = @everyone, no rank roles', () => {
+  const r = ch.resolveViewRoles('everyone', ROLE_MAP);
+  assert.equal(r.everyone, true);
+  assert.deepEqual(r.allowRoleIds, []);
+});
+
+await t('resolveViewRoles metic = metic + archon, @everyone denied', () => {
+  const r = ch.resolveViewRoles('metic', ROLE_MAP);
+  assert.equal(r.everyone, false);
+  assert.deepEqual(r.allowRoleIds.sort(), ['R_ARC', 'R_MET'].sort());
+});
+
+await t('resolveViewRoles archon = archon only', () => {
+  const r = ch.resolveViewRoles('archon', ROLE_MAP);
+  assert.deepEqual(r.allowRoleIds, ['R_ARC']);
+});
+
+await t('resolveViewRoles reports missing role ids', () => {
+  const r = ch.resolveViewRoles('metic', { archon: 'R_ARC' }); // metic id absent
+  assert.deepEqual(r.missing, ['metic']);
+  assert.deepEqual(r.allowRoleIds, ['R_ARC']);
+});
+
+await t('mergeViewOverwrites everyone: @everyone allowed', () => {
+  const out = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX);
+  assert.ok(allowsView(out, EVERYONE));
+});
+
+await t('mergeViewOverwrites metic: @everyone denied, metic+archon allowed', () => {
+  const out = ch.mergeViewOverwrites([], ch.resolveViewRoles('metic', ROLE_MAP), CTX);
+  assert.ok(deniesView(out, EVERYONE));
+  assert.ok(allowsView(out, 'R_MET'));
+  assert.ok(allowsView(out, 'R_ARC'));
+  // xenos / thetes not granted
+  assert.ok(!allowsView(out, 'R_XEN'));
+  assert.ok(!allowsView(out, 'R_THE'));
+});
+
+await t('mergeViewOverwrites preserves non-VIEW bits on an unmanaged id', () => {
+  const SEND = 2048n; // some other permission bit
+  const current = [{ id: 'BOTROLE', type: 0, allow: SEND.toString(), deny: '0' }];
+  const out = ch.mergeViewOverwrites(current, ch.resolveViewRoles('metic', ROLE_MAP), CTX);
+  const bot = out.find((x) => x.id === 'BOTROLE');
+  assert.ok(bot, 'unmanaged overwrite kept');
+  assert.equal(BigInt(bot.allow), SEND, 'non-VIEW bit preserved');
+});
+
+await t('mergeViewOverwrites revokes a rank that drops out of the allow set', () => {
+  // Channel was metic-visible (metic had VIEW allowed); tighten to archon-only.
+  const current = [
+    { id: EVERYONE, type: 0, allow: '0', deny: VIEW.toString() },
+    { id: 'R_MET', type: 0, allow: VIEW.toString(), deny: '0' },
+    { id: 'R_ARC', type: 0, allow: VIEW.toString(), deny: '0' },
+  ];
+  const out = ch.mergeViewOverwrites(current, ch.resolveViewRoles('archon', ROLE_MAP), CTX);
+  assert.ok(allowsView(out, 'R_ARC'));
+  assert.ok(!allowsView(out, 'R_MET'), 'metic VIEW cleared on downgrade');
+});
+
+await t('viewOverwritesEqual is true for identical VIEW decisions, ignores other bits', () => {
+  const a = [{ id: EVERYONE, type: 0, allow: VIEW.toString(), deny: '0' }];
+  const b = [{ id: EVERYONE, type: 0, allow: (VIEW | 4096n).toString(), deny: '0' }];
+  assert.equal(ch.viewOverwritesEqual(a, b, CTX), true);
+});
+
+const CONFIG = {
+  categories: [
+    { name: 'PUBLIC', view: 'everyone', channels: [
+      { key: 'ship-news', name: '📯-ship-news', view: 'everyone', topic: 'News.' },
+    ] },
+    { name: 'BUILDERS', view: 'xenos', channels: [
+      { key: 'archon-only', name: '🗝️-archon-only', view: 'archon', topic: 'Secret.' },
+    ] },
+  ],
+};
+
+await t('planChannelReconcile creates everything for an empty guild', () => {
+  const snap = { categories: [], channels: [] };
+  const { ops } = ch.planChannelReconcile(snap, CONFIG, CTX);
+  const kinds = ops.map((o) => o.op);
+  assert.ok(kinds.includes('create-category'));
+  assert.ok(kinds.filter((k) => k === 'create-channel').length === 2);
+  assert.ok(!kinds.some((k) => k.startsWith('delete')), 'never deletes');
+});
+
+await t('planChannelReconcile is a no-op when the guild already matches', () => {
+  // Build a snapshot that already reflects CONFIG.
+  const pubOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX);
+  const buildOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('xenos', ROLE_MAP), CTX);
+  const newsOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX);
+  const arcOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('archon', ROLE_MAP), CTX);
+  const snap = {
+    categories: [
+      { id: 'C_PUB', name: 'PUBLIC', overwrites: pubOw },
+      { id: 'C_BLD', name: 'BUILDERS', overwrites: buildOw },
+    ],
+    channels: [
+      { id: 'CH_NEWS', name: '📯-ship-news', type: 0, parentId: 'C_PUB', topic: 'News.', overwrites: newsOw },
+      { id: 'CH_ARC', name: '🗝️-archon-only', type: 0, parentId: 'C_BLD', topic: 'Secret.', overwrites: arcOw },
+    ],
+  };
+  // categories in the snapshot need overwrites read for the category diff
+  const { ops } = ch.planChannelReconcile(snap, CONFIG, CTX);
+  assert.deepEqual(ops, [], `expected no ops, got ${JSON.stringify(ops)}`);
+});
+
+await t('planChannelReconcile edits a drifted topic only', () => {
+  const newsOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX);
+  const arcOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('archon', ROLE_MAP), CTX);
+  const pubOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX);
+  const buildOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('xenos', ROLE_MAP), CTX);
+  const snap = {
+    categories: [
+      { id: 'C_PUB', name: 'PUBLIC', overwrites: pubOw },
+      { id: 'C_BLD', name: 'BUILDERS', overwrites: buildOw },
+    ],
+    channels: [
+      { id: 'CH_NEWS', name: '📯-ship-news', type: 0, parentId: 'C_PUB', topic: 'OLD topic', overwrites: newsOw },
+      { id: 'CH_ARC', name: '🗝️-archon-only', type: 0, parentId: 'C_BLD', topic: 'Secret.', overwrites: arcOw },
+    ],
+  };
+  const { ops } = ch.planChannelReconcile(snap, CONFIG, CTX);
+  assert.equal(ops.length, 1);
+  assert.equal(ops[0].op, 'edit-channel');
+  assert.equal(ops[0].id, 'CH_NEWS');
+  assert.equal(ops[0].topic, 'News.');
+  assert.equal(ops[0].overwrites, undefined, 'perms unchanged -> not in the edit');
+});
+
+await t('planChannelReconcile matches existing channel by slug despite emoji change', () => {
+  const newsOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX);
+  const pubOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX);
+  const buildOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('xenos', ROLE_MAP), CTX);
+  const arcOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('archon', ROLE_MAP), CTX);
+  const snap = {
+    categories: [
+      { id: 'C_PUB', name: 'PUBLIC', overwrites: pubOw },
+      { id: 'C_BLD', name: 'BUILDERS', overwrites: buildOw },
+    ],
+    channels: [
+      // no emoji, same slug "ship-news" — must match, not create a duplicate
+      { id: 'CH_NEWS', name: 'ship-news', type: 0, parentId: 'C_PUB', topic: 'News.', overwrites: newsOw },
+      { id: 'CH_ARC', name: '🗝️-archon-only', type: 0, parentId: 'C_BLD', topic: 'Secret.', overwrites: arcOw },
+    ],
+  };
+  const { ops } = ch.planChannelReconcile(snap, CONFIG, CTX);
+  assert.ok(!ops.some((o) => o.op === 'create-channel'), 'no duplicate created');
+});
+
+await t('planChannelReconcile warns when a needed role id is missing', () => {
+  const snap = { categories: [], channels: [] };
+  const { warnings } = ch.planChannelReconcile(snap, CONFIG, { everyoneId: EVERYONE, roleMap: { xenos: 'R_XEN' } });
+  assert.ok(warnings.some((w) => /archon-only/.test(w) && /archon/.test(w)), `expected an archon warning, got ${JSON.stringify(warnings)}`);
+});
+
+// --- self-lockout guard (#738) -------------------------------------------
+// When the bot restricts a channel (denies @everyone), it must keep its OWN
+// VIEW or it locks itself out — the live failure that left the new `thetes`
+// rank (and everyone) unable to act on the BUILDERS category after #727
+// (Discord 50001 "Missing Access" on every later reconcile).
+const BOT = 'BOT_USER';
+const CTX_BOT = { everyoneId: EVERYONE, roleMap: ROLE_MAP, botId: BOT };
+
+await t('mergeViewOverwrites grants the bot a member-type VIEW on a restricted channel', () => {
+  const out = ch.mergeViewOverwrites([], ch.resolveViewRoles('archon', ROLE_MAP), CTX_BOT);
+  assert.ok(deniesView(out, EVERYONE));
+  assert.ok(allowsView(out, 'R_ARC'));
+  assert.ok(allowsView(out, BOT), 'bot keeps its own VIEW on a restricted channel');
+  const bot = out.find((x) => String(x.id) === BOT);
+  assert.equal(bot.type, 1, 'bot overwrite is member-type (1), not role-type');
+});
+
+await t('mergeViewOverwrites adds NO bot overwrite on a public channel (avoids churn)', () => {
+  const out = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX_BOT);
+  assert.ok(!out.some((x) => String(x.id) === BOT), 'public channel needs no explicit bot grant');
+});
+
+await t('planChannelReconcile with a botId is idempotent (no perpetual re-write of the bot grant)', () => {
+  const pubOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX_BOT);
+  const buildOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('xenos', ROLE_MAP), CTX_BOT);
+  const newsOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX_BOT);
+  const arcOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('archon', ROLE_MAP), CTX_BOT);
+  const snap = {
+    categories: [
+      { id: 'C_PUB', name: 'PUBLIC', overwrites: pubOw },
+      { id: 'C_BLD', name: 'BUILDERS', overwrites: buildOw },
+    ],
+    channels: [
+      { id: 'CH_NEWS', name: '📯-ship-news', type: 0, parentId: 'C_PUB', topic: 'News.', overwrites: newsOw },
+      { id: 'CH_ARC', name: '🗝️-archon-only', type: 0, parentId: 'C_BLD', topic: 'Secret.', overwrites: arcOw },
+    ],
+  };
+  const { ops } = ch.planChannelReconcile(snap, CONFIG, CTX_BOT);
+  assert.deepEqual(ops, [], `expected no ops, got ${JSON.stringify(ops)}`);
+});
+
+await t('planChannelReconcile re-grants the bot when a restricted channel is missing it (recovers the lock-out)', () => {
+  // The pre-fix live state: BUILDERS + the archon channel were restricted
+  // WITHOUT the bot in the allow-list. With a botId now in ctx the planner must
+  // queue edits that add the bot's VIEW back so the next reconcile can succeed.
+  const buildOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('xenos', ROLE_MAP), CTX); // no bot
+  const arcOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('archon', ROLE_MAP), CTX);  // no bot
+  const pubOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX_BOT);
+  const newsOw = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX_BOT);
+  const snap = {
+    categories: [
+      { id: 'C_PUB', name: 'PUBLIC', overwrites: pubOw },
+      { id: 'C_BLD', name: 'BUILDERS', overwrites: buildOw },
+    ],
+    channels: [
+      { id: 'CH_NEWS', name: '📯-ship-news', type: 0, parentId: 'C_PUB', topic: 'News.', overwrites: newsOw },
+      { id: 'CH_ARC', name: '🗝️-archon-only', type: 0, parentId: 'C_BLD', topic: 'Secret.', overwrites: arcOw },
+    ],
+  };
+  const { ops } = ch.planChannelReconcile(snap, CONFIG, CTX_BOT);
+  const cat = ops.find((o) => o.op === 'edit-category' && o.id === 'C_BLD');
+  const arc = ops.find((o) => o.op === 'edit-channel' && o.id === 'CH_ARC');
+  assert.ok(cat, 'BUILDERS category edit queued to add the bot');
+  assert.ok(allowsView(cat.overwrites, BOT), 'category edit grants the bot VIEW');
+  assert.ok(arc && arc.overwrites && allowsView(arc.overwrites, BOT), 'archon channel edit grants the bot VIEW');
+});
+
+// --- category overwrites round-trip the IO snapshot (#202) -----------------
+// snapshotFromGuild used to drop type-4 (category) overwrites, so the planner
+// compared the desired perms against `undefined` and re-emitted an
+// edit-category op every run. These tests exercise the real IO function with a
+// minimal fake discord.js guild.
+function fakeChannel({ id, name, type, parentId, topic, ows }) {
+  const cache = new Map((ows || []).map((o) => [String(o.id), {
+    id: String(o.id),
+    type: o.type ?? 0,
+    allow: { bitfield: BigInt(o.allow || 0) },
+    deny: { bitfield: BigInt(o.deny || 0) },
+  }]));
+  return { id: String(id), name, type, parentId: parentId || null, topic: topic || '', permissionOverwrites: { cache } };
+}
+function fakeGuild(channelMap) {
+  return { id: EVERYONE, client: { user: { id: BOT } }, channels: { cache: channelMap } };
+}
+
+await t('snapshotFromGuild captures a category (type-4) permission overwrites (#202)', () => {
+  const catOws = [
+    { id: EVERYONE, type: 0, allow: '0', deny: VIEW.toString() },
+    { id: 'R_XEN', type: 0, allow: VIEW.toString(), deny: '0' },
+  ];
+  const guild = fakeGuild(new Map([
+    ['C_BLD', fakeChannel({ id: 'C_BLD', name: 'BUILDERS', type: 4, ows: catOws })],
+    ['CH', fakeChannel({ id: 'CH', name: '🗝️-archon-only', type: 0, parentId: 'C_BLD', topic: 'Secret.', ows: [] })],
+  ]));
+  const snap = ch.snapshotFromGuild(guild);
+  const cat = snap.categories.find((c) => c.id === 'C_BLD');
+  assert.ok(cat, 'category present in snapshot');
+  assert.ok(Array.isArray(cat.overwrites), 'category carries an overwrites array (was dropped before #202)');
+  assert.equal(cat.overwrites.length, 2, 'both category overwrites captured');
+  assert.ok(deniesView(cat.overwrites, EVERYONE));
+  assert.ok(allowsView(cat.overwrites, 'R_XEN'));
+});
+
+await t('planChannelReconcile no-ops a guild already matching, categories included (idempotent after #202)', () => {
+  const wantPub = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX_BOT);
+  const wantBld = ch.mergeViewOverwrites([], ch.resolveViewRoles('xenos', ROLE_MAP), CTX_BOT);
+  const wantNews = ch.mergeViewOverwrites([], ch.resolveViewRoles('everyone', ROLE_MAP), CTX_BOT);
+  const wantArc = ch.mergeViewOverwrites([], ch.resolveViewRoles('archon', ROLE_MAP), CTX_BOT);
+  // Round-trip through the IO snapshot so category overwrites pass through the
+  // exact code path that was buggy, then plan — must be a clean no-op.
+  const guild = fakeGuild(new Map([
+    ['C_PUB', fakeChannel({ id: 'C_PUB', name: 'PUBLIC', type: 4, ows: wantPub })],
+    ['C_BLD', fakeChannel({ id: 'C_BLD', name: 'BUILDERS', type: 4, ows: wantBld })],
+    ['CH_NEWS', fakeChannel({ id: 'CH_NEWS', name: '📯-ship-news', type: 0, parentId: 'C_PUB', topic: 'News.', ows: wantNews })],
+    ['CH_ARC', fakeChannel({ id: 'CH_ARC', name: '🗝️-archon-only', type: 0, parentId: 'C_BLD', topic: 'Secret.', ows: wantArc })],
+  ]));
+  const snap = ch.snapshotFromGuild(guild);
+  const { ops } = ch.planChannelReconcile(snap, CONFIG, CTX_BOT);
+  assert.deepEqual(ops, [], `expected no ops after #202 fix, got ${JSON.stringify(ops.map((o) => o.op + ' ' + (o.name || o.id)))}`);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);