@bongos/core 1.17.0

package/modules/discord/discord-bugs.js

@@ -0,0 +1,257 @@
+'use strict';
+
+// Discord #bugs → GDS tasks (kind='bug') — Phase 3 F8 (ADR 0033 §F8, ADR 0047).
+//
+// The bot turns a message posted in the designated #bugs channel into a GDS
+// task with kind='bug', STRAIGHT THROUGH — no idea_inbox, no triage step. This
+// is the deliberate difference from #ideas (discord-inbound.js): a bug is a
+// small fix a builder wants to drop without context-switching, and it becomes
+// claimable work directly.
+//
+// ANTI-ABUSE GUARD (ADR 0047 — the red-team resolution). Creating claimable
+// work with no triage gate is an injection surface, so this path is guarded in
+// depth, all server-side, all fail-closed:
+//   1. LINKED-BUILDER-ONLY. An unlinked Discord author cannot create a task —
+//      their message is ignored (not filed). Unlike #ideas (which captures
+//      unattributed), making *claimable work* requires being an accountable,
+//      known builder. This is the single biggest lever.
+//   2. RANK-AWARE LANDING. A linked Metic+ builder's bug lands 'ready'
+//      (instantly claimable — the true straight-through path their trust earns).
+//      A linked Xenos/Thetes builder's bug lands 'backlog' (needs a one-click
+//      Metic+ promote, like any other backlog task). Mirrors the trust ladder
+//      used everywhere else in the GDS.
+//   3. PER-BUILDER RATE-LIMIT. At most N bug-tasks per builder per rolling hour
+//      (counted from audit_log). Over-limit filings are ignored AND audited so
+//      a spammer surfaces in forensics / the red-team view.
+//   4. BODY SCREEN. Empty / too-short / text-free messages are ignored before
+//      any DB write; title + body are capped to the GDS limits.
+//
+// TRUST BOUNDARY (ADR 0016 / ADR 0033 §1): the bot asserts only WHO posted
+// (the linked builder); the landing state is decided server-side from that
+// builder's LIVE rank, never from anything in the message. The bot grants
+// nothing. Every filing — and every rate-limit rejection — is audited with
+// surface='discord_bot'.
+//
+// Requires (go-live): the Message Content PRIVILEGED intent + a pinned
+// DISCORD_BUGS_CHANNEL_ID. Inert until both are set.
+
+const db = require('./db');
+const { auditDiscordBot } = require('./discord-audit');
+const auth = require('./auth');
+const attachments = require('./bug-attachments');
+const { combineParts, createMessageAggregator } = require('./discord-message-buffer');
+const { LIMITS } = require('../../src/module-api');
+
+// Ranks whose bugs land 'ready' (instantly claimable). Everyone else linked
+// lands 'backlog'. Metic+ — matches REQUIRES_RANK_TIER >= metic in db.js.
+const READY_RANKS = new Set(['metic', 'archon']);
+
+// Smallest message we'll treat as a real bug report. Anything shorter is noise.
+const MIN_BUG_CHARS = 8;
+
+// Default rate-limit: bug-tasks one builder may create per rolling hour. Env
+// DISCORD_BUGS_RATE_PER_HOUR overrides (a number); falls back to this.
+const DEFAULT_RATE_PER_HOUR = 5;
+
+// Default GDS version a filed bug is filed under. Most builder-filed bugs are
+// about the dev system; an Archon can re-home a game bug to a product version.
+// Env DISCORD_BUGS_VERSION_ID overrides.
+const DEFAULT_BUGS_VERSION_ID = 'GDS-V3';
+
+// Modest reward for fixing a drive-by bug. Env DISCORD_BUGS_CREDITS overrides.
+const DEFAULT_BUGS_CREDITS = 10;
+
+// Auto-pairing window: consecutive #bugs messages from the SAME author within
+// this window are combined into ONE bug-task (so "screenshot" + "here's what
+// happened" posted seconds apart — in either order — become one report, not
+// two). Env DISCORD_BUGS_PAIR_WINDOW_MS overrides.
+const DEFAULT_PAIR_WINDOW_MS = 45 * 1000;
+
+// Title for a bug that arrives as image(s) with no usable text.
+const SCREENSHOT_TITLE = 'Bug report (screenshot)';
+
+function rateLimitPerHour(env = process.env) {
+  const n = Number(env.DISCORD_BUGS_RATE_PER_HOUR);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_RATE_PER_HOUR;
+}
+
+function bugsVersionId(env = process.env) {
+  return env.DISCORD_BUGS_VERSION_ID || DEFAULT_BUGS_VERSION_ID;
+}
+
+function bugsCredits(env = process.env) {
+  const n = Number(env.DISCORD_BUGS_CREDITS);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : DEFAULT_BUGS_CREDITS;
+}
+
+function pairWindowMs(env = process.env) {
+  const n = Number(env.DISCORD_BUGS_PAIR_WINDOW_MS);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_PAIR_WINDOW_MS;
+}
+
+// PURE — decide where a bug lands from the reporter's LIVE rank. Metic+ →
+// 'ready' (straight-through, claimable now); any other linked rank → 'backlog'
+// (a Metic+ promotes it, the lightweight confirm gate). Unit-tested.
+function decideBugLanding(rank) {
+  return READY_RANKS.has(String(rank || '').toLowerCase()) ? 'ready' : 'backlog';
+}
+
+// PURE — screen + shape a raw message into { ok, title, bodyMd } or
+// { ok:false, reason }. The body screen rejects blank / too-short / text-free
+// (no letters) messages before any DB write — UNLESS the message carries
+// image(s): an image is content, so an image-only bug is allowed through with a
+// default title. Title = first non-empty line (capped) or the screenshot
+// title; body = full message text (capped, possibly empty). Unit-tested.
+function screenBug(content, { hasImages = false } = {}) {
+  const trimmed = typeof content === 'string' ? content.trim() : '';
+  const hasText = trimmed.length >= MIN_BUG_CHARS && /[a-zA-Z]/.test(trimmed);
+
+  if (!hasText && !hasImages) {
+    if (!trimmed) return { ok: false, reason: 'empty' };
+    if (trimmed.length < MIN_BUG_CHARS) return { ok: false, reason: 'too_short' };
+    return { ok: false, reason: 'no_text' };
+  }
+
+  const cap = LIMITS.TITLE;
+  let title;
+  if (trimmed) {
+    const firstLine = (trimmed.split('\n').find((l) => l.trim()) || trimmed).trim();
+    title = firstLine.length > cap ? `${firstLine.slice(0, cap - 1)}…` : firstLine;
+  } else {
+    title = SCREENSHOT_TITLE;
+  }
+  const bodyMd = trimmed.length > LIMITS.DESCRIPTION ? trimmed.slice(0, LIMITS.DESCRIPTION) : trimmed;
+  return { ok: true, title, bodyMd };
+}
+
+const realDeps = {
+  getBuilderByDiscordUserId: db.getBuilderByDiscordUserId,
+  countRecentDiscordBugFilings: db.countRecentDiscordBugFilings,
+  createTask: db.createTask,
+  insertAuditLog: db.insertAuditLog,
+  persistImages: attachments.persistImages,
+};
+
+// File one inbound #bugs message as a GDS task (kind='bug'). NEVER throws (the
+// caller is a gateway event handler). Returns a small status object for
+// logging/tests. `config` is injectable so tests don't touch process.env.
+async function recordInboundBug({ discordUserId, content, imageUrls = [], messageId }, deps = realDeps, config = {}) {
+  if (!auth.isValidDiscordUserId(discordUserId)) {
+    return { outcome: 'ignored', reason: 'bad_discord_user_id' };
+  }
+  const hasImages = Array.isArray(imageUrls) && imageUrls.length > 0;
+  const screened = screenBug(content, { hasImages });
+  if (!screened.ok) return { outcome: 'ignored', reason: screened.reason };
+
+  const limit = config.rateLimitPerHour ?? rateLimitPerHour();
+  const versionId = config.versionId ?? bugsVersionId();
+  const credits = config.credits ?? bugsCredits();
+
+  try {
+    // (1) LINKED-BUILDER-ONLY. No linked builder → reject (do not file). An
+    // unlinked author cannot inject claimable work.
+    const builder = await deps.getBuilderByDiscordUserId(discordUserId);
+    if (!builder) return { outcome: 'ignored', reason: 'unlinked' };
+
+    // (3) PER-BUILDER RATE-LIMIT. Count this builder's bug filings in the last
+    // hour; over the cap → reject AND audit (so a spammer is visible in
+    // forensics / the red-team view), but never throw.
+    const sinceIso = new Date(Date.now() - 60 * 60 * 1000).toISOString();
+    let recent = 0;
+    let countFailed = false;
+    try {
+      recent = await deps.countRecentDiscordBugFilings(builder.id, sinceIso);
+    } catch (e) {
+      // L4 (red-team 2026-06-12): FAIL CLOSED on a count error. The old behaviour
+      // proceeded ("fail-open"), which let a DB error be used to slip past the
+      // per-builder limit. A failed count means we cannot prove the caller is
+      // under the cap, so treat it as rate-limited (deny) and audit it. Never
+      // throw — the caller is a gateway event handler.
+      console.error('[discord-bot] bug rate-limit count failed (denying — fail-closed):', e.message);
+      countFailed = true;
+    }
+    if (countFailed || recent >= limit) {
+      const reason = countFailed ? 'rate_limit_count_error' : 'rate_limited';
+      await auditDiscordBot(deps, {
+        builderId: builder.id,
+        route: 'discord:bugs',
+        requestBodyRedacted: { discord_user_id: discordUserId, message_id: messageId, rejected: reason, recent },
+        responseStatus: 429,
+        logLabel: 'bug rate-limit audit failed',
+      });
+      return { outcome: 'ignored', reason, recent };
+    }
+
+    // (2) RANK-AWARE LANDING — decided from the LIVE rank, never the message.
+    const status = decideBugLanding(builder.rank);
+
+    // Re-host any images on our server (durable — Discord CDN links expire). The
+    // guard (host allowlist + content-type + magic-byte sniff + size/count caps)
+    // lives in bug-attachments.persistImages; refused images are skipped, not
+    // fatal. A persist failure must not lose the report.
+    let stored = [];
+    if (hasImages) {
+      try {
+        stored = await deps.persistImages(imageUrls, { messageId });
+      } catch (e) {
+        console.error('[discord-bot] bug image persist failed (filing without images):', e.message);
+      }
+    }
+
+    // Provenance footer so a claimer knows where the bug came from + who to ask.
+    // The raw Discord snowflake is NOT embedded (it lives in the Archon-only
+    // audit_log); only the builder login. Then the durable attachment links.
+    const origin = `\n\n— reported from Discord #bugs by ${builder.github_login}`;
+    let description = `${screened.bodyMd}${origin}`;
+    if (stored.length > 0) {
+      const imgs = stored.map((s, i) => `![attachment ${i + 1}](${s.url})`).join('\n');
+      description += `\n\nAttachments (${stored.length}):\n${imgs}`;
+    }
+    description = description.slice(0, LIMITS.DESCRIPTION);
+
+    const task = await deps.createTask({
+      versionId,
+      title: screened.title,
+      description,
+      status,
+      kind: 'bug',
+      priority: 3,
+      creditsReward: credits,
+      source: 'discord:bugs',
+      sourceRef: `discord:${messageId}`,
+    });
+
+    await auditDiscordBot(deps, {
+      builderId: builder.id,
+      route: 'discord:bugs',
+      requestBodyRedacted: { discord_user_id: discordUserId, message_id: messageId, task_id: task.id, status, images: stored.length },
+      responseStatus: 201,
+      logLabel: 'bug audit-log write failed',
+    });
+
+    return { outcome: 'filed', taskId: task.id, status, builderId: builder.id, images: stored.length };
+  } catch (err) {
+    console.error('[discord-bot] recordInboundBug failed:', err.message);
+    return { outcome: 'error', error: err.message };
+  }
+}
+
+// Auto-pairing aggregator for #bugs — a thin wrapper over the shared
+// per-author burst aggregator (discord-message-buffer.js) that supplies the
+// #bugs default window. onFlush files the combined burst as ONE bug.
+function createBugAggregator({ onFlush, windowMs = pairWindowMs(), timers = global } = {}) {
+  return createMessageAggregator({ onFlush, windowMs, timers });
+}
+
+module.exports = {
+  screenBug,
+  decideBugLanding,
+  recordInboundBug,
+  combineParts,
+  createBugAggregator,
+  realDeps,
+  rateLimitPerHour,
+  bugsVersionId,
+  bugsCredits,
+  pairWindowMs,
+};

package/modules/discord/discord-channels.js

@@ -0,0 +1,412 @@
+'use strict';
+
+// Discord channel management — config-driven reconcile (ADR 0037, task #727).
+//
+// ONE-WAY: repo config -> Discord. The bot makes the guild's channel layout
+// match docs/discord/channels.json: it matches existing channels by slug
+// (emoji + separators stripped), edits their topic + view-permissions in place,
+// and creates anything missing. It NEVER deletes a channel. Like role-sync
+// (discord-role-sync.js / ADR 0033 §4) this only READS the repo and WRITES
+// Discord, so a channel can never feed authority back into the GDS.
+//
+// TRUST BOUNDARY (ADR 0016): channels are a cosmetic reflection of an
+// Archon-reviewed config file, never a key. The COMMAND surface that triggers a
+// reconcile (routes/discord.js) is gated by requireRank('archon') against the
+// live builders.rank — the same enforcement point every privileged route uses.
+// This module performs no rank checks itself; it is invoked only by the bot's
+// own passive sweep or by an already-authorized Archon command.
+//
+// KILL-SWITCH: the passive sweep in discord-bot.js is gated by
+// DISCORD_CHANNELS_MANAGED (default OFF, fail-closed) so a server never
+// surprise-edits a guild. With it off, channels are only ever touched by an
+// explicit Archon command.
+//
+// FAIL-SAFE / best-effort: every Discord write is wrapped — a 403 (missing
+// Manage Channels), a transient error, or a missing role id logs and the
+// reconcile moves on. It must never throw into the bot's ready handler.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Discord VIEW_CHANNEL permission bit (1 << 10). The only permission this
+// module manages — every other bit on a channel is preserved on edit.
+const VIEW_CHANNEL = 1024n;
+
+// The rank ladder low->high. Canonical copy is db.LIVE_RANK_LADDER, but this
+// module is kept dependency-free (no db.js → no pg Pool side-effect for a
+// Discord-config CLI), so we keep a LOCAL copy rather than import — the same
+// deliberate trade-off permission-path-check.js makes (D1: the ladder has three
+// homes that cannot share one module; do not force-merge). A
+// `view: "<rank>"` grants that rank and everyone above it.
+const RANK_LADDER = ['xenos', 'thetes', 'metic', 'archon'];
+
+const CONFIG_PATH = path.resolve(__dirname, '..', '..', 'docs', 'discord', 'channels.json');
+
+// ---------------------------------------------------------------------------
+// PURE helpers (no Discord, no IO) — the load-bearing, fully-tested logic.
+// ---------------------------------------------------------------------------
+
+// Normalize a channel/category name to a stable slug for matching. Strips
+// emoji and any non-alphanumeric run down to single hyphens, lowercased.
+//   "📯-ship-news"        -> "ship-news"
+//   "👋-welcome-and-start"-> "welcome-and-start"
+//   "BUILDERS"            -> "builders"
+function slugify(name) {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// The set of rank-role ids that should be ALLOWED to view a channel with the
+// given `view`, plus whether @everyone is allowed. Returns role ids resolved
+// through roleMap; ranks with no configured role id are reported in `missing`.
+function resolveViewRoles(view, roleMap) {
+  if (!view || view === 'everyone') {
+    return { everyone: true, allowRoleIds: [], missing: [] };
+  }
+  const idx = RANK_LADDER.indexOf(view);
+  if (idx === -1) {
+    // Unknown view value: fail safe to most-restrictive (archon-only).
+    const aid = roleMap.archon;
+    return { everyone: false, allowRoleIds: aid ? [aid] : [], missing: aid ? [] : ['archon'], unknownView: view };
+  }
+  const ranks = RANK_LADDER.slice(idx); // this rank and every rank above it
+  const allowRoleIds = [];
+  const missing = [];
+  for (const r of ranks) {
+    if (roleMap[r]) allowRoleIds.push(roleMap[r]);
+    else missing.push(r);
+  }
+  return { everyone: false, allowRoleIds, missing };
+}
+
+// Merge the desired VIEW decisions into a channel's CURRENT permission
+// overwrites, preserving every non-VIEW bit and every unmanaged role's
+// overwrite. `current` is an array of { id, type, allow, deny } where allow/deny
+// are bitfield strings (Discord's REST shape). Returns the same shape.
+//   - everyoneId is allowed/denied VIEW per `decision.everyone`.
+//   - each id in decision.allowRoleIds gets VIEW allowed.
+//   - any managed rank role NOT in allowRoleIds (but present in roleMap) gets
+//     its VIEW overwrite cleared so a downgrade actually removes access.
+function mergeViewOverwrites(current, decision, ctx) {
+  const { everyoneId, roleMap } = ctx;
+  const byId = new Map();
+  for (const o of current || []) {
+    byId.set(String(o.id), { id: String(o.id), type: o.type ?? 0, allow: BigInt(o.allow || 0), deny: BigInt(o.deny || 0) });
+  }
+  const ensure = (id, type) => {
+    if (!byId.has(id)) byId.set(id, { id, type, allow: 0n, deny: 0n });
+    return byId.get(id);
+  };
+  const setView = (id, type, allow) => {
+    const e = ensure(id, type);
+    if (allow) { e.allow |= VIEW_CHANNEL; e.deny &= ~VIEW_CHANNEL; }
+    else { e.deny |= VIEW_CHANNEL; e.allow &= ~VIEW_CHANNEL; }
+  };
+
+  // @everyone (role id == guild id, type 0).
+  setView(everyoneId, 0, decision.everyone === true);
+
+  const allowSet = new Set(decision.allowRoleIds.map(String));
+  // Allow the rank roles that should see it.
+  for (const rid of allowSet) setView(rid, 0, true);
+  // For managed rank roles NOT in the allow set, clear any VIEW bit we own so a
+  // tighter `view` actually revokes a previously-granted role.
+  for (const r of RANK_LADDER) {
+    const rid = roleMap[r] ? String(roleMap[r]) : null;
+    if (rid && !allowSet.has(rid) && byId.has(rid)) {
+      const e = byId.get(rid);
+      e.allow &= ~VIEW_CHANNEL;
+      e.deny &= ~VIEW_CHANNEL;
+    }
+  }
+
+  // Never lock the managing bot out of a channel it restricts. When @everyone is
+  // denied VIEW, the bot's own role is in no rank allow-list, so without this the
+  // bot loses access to the very channel it just edited — and every later
+  // reconcile fails with Discord 50001 "Missing Access" (exactly what locked the
+  // BUILDERS category after #727 shipped). Grant the bot an explicit member-level
+  // (type 1) VIEW overwrite on any RESTRICTED channel. We add it only when
+  // restricting (decision.everyone === false): on a public channel the bot
+  // already sees it via @everyone, and not touching public channels keeps the
+  // reconcile idempotent (no perpetual re-write).
+  if (ctx.botId && decision.everyone === false) {
+    setView(String(ctx.botId), 1, true);
+  }
+
+  // Drop entries that ended up empty (no bits) to keep the payload clean —
+  // except @everyone, which we always state explicitly.
+  const out = [];
+  for (const e of byId.values()) {
+    if (e.id !== String(everyoneId) && e.allow === 0n && e.deny === 0n) continue;
+    out.push({ id: e.id, type: e.type, allow: e.allow.toString(), deny: e.deny.toString() });
+  }
+  return out;
+}
+
+// True when two overwrite arrays describe the same VIEW decisions for the
+// managed ids (@everyone + every managed rank role). Non-VIEW bits and
+// unmanaged ids are ignored — we only own VIEW.
+function viewOverwritesEqual(a, b, ctx) {
+  const managed = new Set([String(ctx.everyoneId), ...RANK_LADDER.map((r) => ctx.roleMap[r]).filter(Boolean).map(String)]);
+  // The bot's own VIEW overwrite is managed too, so a missing one on a restricted
+  // channel registers as a needed edit (and a present one as already-applied).
+  if (ctx.botId) managed.add(String(ctx.botId));
+  const view = (arr) => {
+    const m = new Map();
+    for (const o of arr || []) {
+      const id = String(o.id);
+      if (!managed.has(id)) continue;
+      const allow = BigInt(o.allow || 0) & VIEW_CHANNEL ? 'allow' : (BigInt(o.deny || 0) & VIEW_CHANNEL ? 'deny' : 'none');
+      m.set(id, allow);
+    }
+    return m;
+  };
+  const ma = view(a);
+  const mb = view(b);
+  if (ma.size !== mb.size) return false;
+  for (const [k, v] of ma) if (mb.get(k) !== v) return false;
+  return true;
+}
+
+// Compute the reconcile plan. PURE: given a guild snapshot, the parsed config,
+// and the context (everyone role id + rank->role-id map), return the ordered
+// list of ops needed to make Discord match the config, plus any warnings.
+//
+// snapshot = {
+//   categories: [{ id, name }],
+//   channels:   [{ id, name, type, parentId, topic, overwrites:[{id,type,allow,deny}] }]
+// }
+// Ops never include deletions. Categories are planned before their channels so
+// the apply step can resolve a freshly-created parent id.
+function planChannelReconcile(snapshot, config, ctx) {
+  const ops = [];
+  const warnings = [];
+  const catBySlug = new Map((snapshot.categories || []).map((c) => [slugify(c.name), c]));
+  const chBySlug = new Map((snapshot.channels || []).map((c) => [slugify(c.name), c]));
+
+  for (const cat of config.categories || []) {
+    const catSlug = slugify(cat.name);
+    const existingCat = catBySlug.get(catSlug);
+    const catDecision = resolveViewRoles(cat.view, ctx.roleMap);
+    if (catDecision.missing && catDecision.missing.length) {
+      warnings.push(`category "${cat.name}" view=${cat.view}: no Discord role id yet for ${catDecision.missing.join(', ')}`);
+    }
+
+    if (!existingCat) {
+      ops.push({
+        op: 'create-category',
+        slug: catSlug,
+        name: cat.name,
+        overwrites: mergeViewOverwrites([], catDecision, ctx),
+      });
+    } else {
+      const want = mergeViewOverwrites(existingCat.overwrites, catDecision, ctx);
+      if (!viewOverwritesEqual(existingCat.overwrites, want, ctx)) {
+        ops.push({ op: 'edit-category', id: existingCat.id, name: cat.name, overwrites: want });
+      }
+    }
+
+    for (const ch of cat.channels || []) {
+      const chSlug = slugify(ch.name);
+      const view = ch.view || cat.view;
+      const decision = resolveViewRoles(view, ctx.roleMap);
+      if (decision.missing && decision.missing.length) {
+        warnings.push(`channel "${ch.name}" view=${view}: no Discord role id yet for ${decision.missing.join(', ')}`);
+      }
+      const existing = chBySlug.get(chSlug);
+      if (!existing) {
+        ops.push({
+          op: 'create-channel',
+          slug: chSlug,
+          name: ch.name,
+          parentSlug: catSlug,
+          parentName: cat.name,
+          topic: ch.topic || '',
+          overwrites: mergeViewOverwrites([], decision, ctx),
+        });
+        continue;
+      }
+      const want = mergeViewOverwrites(existing.overwrites, decision, ctx);
+      const topicDiffers = (existing.topic || '') !== (ch.topic || '');
+      const permsDiffer = !viewOverwritesEqual(existing.overwrites, want, ctx);
+      const parentDiffers = existing.parentId && catBySlug.get(catSlug) && String(existing.parentId) !== String(catBySlug.get(catSlug).id);
+      if (topicDiffers || permsDiffer || parentDiffers) {
+        const edit = { op: 'edit-channel', id: existing.id, name: ch.name };
+        if (topicDiffers) edit.topic = ch.topic || '';
+        if (permsDiffer) edit.overwrites = want;
+        if (parentDiffers) { edit.parentSlug = catSlug; edit.parentName = cat.name; }
+        ops.push(edit);
+      }
+    }
+  }
+  return { ops, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// IO + Discord REST (impure) — invoked by the bot sweep and the Archon command.
+// ---------------------------------------------------------------------------
+
+function loadConfig(configPath = CONFIG_PATH) {
+  const raw = fs.readFileSync(configPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+// The managing bot's own user id, used to grant it an explicit VIEW overwrite on
+// any channel it restricts so it never locks itself out. Best-effort: returns
+// null if the client/user isn't resolvable (then the self-lockout guard is a
+// no-op and behaviour is unchanged).
+function botIdFromGuild(guild) {
+  const u = guild && guild.client && guild.client.user;
+  return u && u.id ? String(u.id) : null;
+}
+
+// Build a normalized snapshot from a discord.js guild's channel cache.
+function snapshotFromGuild(guild) {
+  const categories = [];
+  const channels = [];
+  for (const ch of guild.channels.cache.values()) {
+    const overwrites = [];
+    if (ch.permissionOverwrites && ch.permissionOverwrites.cache) {
+      for (const ow of ch.permissionOverwrites.cache.values()) {
+        overwrites.push({ id: String(ow.id), type: ow.type === 'role' || ow.type === 0 ? 0 : 1, allow: ow.allow.bitfield.toString(), deny: ow.deny.bitfield.toString() });
+      }
+    }
+    // Categories carry their own VIEW overwrites too — include them, or the
+    // planner compares the desired overwrites against `undefined` every run and
+    // re-emits an edit-category op forever (idea #202: type-4 perms never reach
+    // no-op even though the PATCH succeeds; channels were fine because they
+    // already carried overwrites here).
+    if (ch.type === 4) categories.push({ id: String(ch.id), name: ch.name, overwrites });
+    else if (ch.type === 0) channels.push({ id: String(ch.id), name: ch.name, type: 0, parentId: ch.parentId ? String(ch.parentId) : null, topic: ch.topic || '', overwrites });
+  }
+  return { categories, channels };
+}
+
+const realDeps = {
+  loadConfig,
+  loadGuildId: () => require('./discord-role-sync').loadGuildId(),
+  loadRoleMap: () => require('./discord-role-sync').loadRoleMap(),
+  loadBotToken: () => require('./auth').loadDiscordBotToken(),
+  // Identical to discord-role-sync.getGuild (same lazy bot→client→loadGuildId→
+  // cache.get(gid)||first() chain) — delegate to the canonical copy there
+  // rather than keep a line-for-line duplicate (task 1091, C7).
+  getGuild: () => require('./discord-role-sync').getGuild(),
+};
+
+async function discordRest(token, method, urlPath, body) {
+  const res = await fetch(`https://discord.com/api${urlPath}`, {
+    method,
+    headers: { Authorization: `Bot ${token}`, 'Content-Type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    const err = new Error(`Discord ${method} ${urlPath} -> ${res.status}: ${text}`);
+    err.status = res.status;
+    throw err;
+  }
+  return res.status === 204 ? null : res.json();
+}
+
+// Compute the plan against the live guild WITHOUT writing — for the Archon
+// `plan` (dry-run) command and for logging before an apply.
+function computePlan(deps = realDeps) {
+  const guild = deps.getGuild();
+  if (!guild) return { ok: false, reason: 'no_guild', ops: [], warnings: [] };
+  const config = deps.loadConfig();
+  const roleMap = deps.loadRoleMap();
+  const ctx = { everyoneId: String(guild.id), roleMap, botId: botIdFromGuild(guild) };
+  const snapshot = snapshotFromGuild(guild);
+  const { ops, warnings } = planChannelReconcile(snapshot, config, ctx);
+  return { ok: true, ops, warnings, guildId: String(guild.id) };
+}
+
+// Apply the plan to Discord. Best-effort, never throws. Returns a summary.
+// Categories are created first so child channels can resolve their parent id.
+async function reconcileChannels(deps = realDeps) {
+  const guild = deps.getGuild();
+  if (!guild) return { ok: false, reason: 'no_guild', applied: 0, failed: 0 };
+  const token = deps.loadBotToken();
+  if (!token) return { ok: false, reason: 'no_token', applied: 0, failed: 0 };
+
+  const config = deps.loadConfig();
+  const roleMap = deps.loadRoleMap();
+  const ctx = { everyoneId: String(guild.id), roleMap, botId: botIdFromGuild(guild) };
+  const snapshot = snapshotFromGuild(guild);
+  const { ops, warnings } = planChannelReconcile(snapshot, config, ctx);
+  for (const w of warnings) console.warn(`[discord-bot] channels: ${w}`);
+
+  let applied = 0, failed = 0;
+  // Track newly-created category ids so create-channel can set parent_id.
+  const catIdBySlug = new Map((snapshot.categories || []).map((c) => [slugify(c.name), String(c.id)]));
+
+  // Run one best-effort sub-operation. Each PATCH/POST is counted on its own so
+  // a failure in one facet (e.g. permission_overwrites needs Manage Permissions)
+  // does NOT suppress another that succeeded (e.g. topic needs only Manage
+  // Channels). Returns the created body on success, or null on failure.
+  const run = async (label, fn) => {
+    try {
+      const out = await fn();
+      applied++;
+      console.log(`[discord-bot] channels: ${label}`);
+      return out;
+    } catch (e) {
+      failed++;
+      console.error(`[discord-bot] channels: ${label} failed:`, e.message);
+      return null;
+    }
+  };
+
+  for (const op of ops) {
+    if (op.op === 'create-category') {
+      const created = await run(`created category ${op.name}`, () =>
+        discordRest(token, 'POST', `/guilds/${guild.id}/channels`, { name: op.name, type: 4, permission_overwrites: op.overwrites }));
+      if (created) catIdBySlug.set(op.slug, String(created.id));
+    } else if (op.op === 'edit-category') {
+      await run(`updated category ${op.name} permissions`, () =>
+        discordRest(token, 'PATCH', `/channels/${op.id}`, { permission_overwrites: op.overwrites }));
+    } else if (op.op === 'create-channel') {
+      const parentId = catIdBySlug.get(op.parentSlug) || null;
+      await run(`created #${op.name}`, () =>
+        discordRest(token, 'POST', `/guilds/${guild.id}/channels`, {
+          name: op.name, type: 0, parent_id: parentId, topic: op.topic, permission_overwrites: op.overwrites,
+        }));
+    } else if (op.op === 'edit-channel') {
+      // SPLIT the edit: topic + parent (Manage Channels) in one PATCH, the
+      // permission_overwrites (Manage Permissions) in another. On a private
+      // channel where the bot lacks Manage Permissions, the description still
+      // lands and only the per-rank view perms are deferred.
+      const base = {};
+      if (op.topic !== undefined) base.topic = op.topic;
+      if (op.parentSlug) base.parent_id = catIdBySlug.get(op.parentSlug) || null;
+      if (Object.keys(base).length) {
+        await run(`updated #${op.name} (${Object.keys(base).join(', ')})`, () =>
+          discordRest(token, 'PATCH', `/channels/${op.id}`, base));
+      }
+      if (op.overwrites !== undefined) {
+        await run(`updated #${op.name} (permissions)`, () =>
+          discordRest(token, 'PATCH', `/channels/${op.id}`, { permission_overwrites: op.overwrites }));
+      }
+    }
+  }
+  return { ok: true, applied, failed, total: applied + failed, warnings };
+}
+
+module.exports = {
+  // pure (tested)
+  slugify,
+  resolveViewRoles,
+  mergeViewOverwrites,
+  viewOverwritesEqual,
+  planChannelReconcile,
+  // io
+  loadConfig,
+  snapshotFromGuild,
+  computePlan,
+  reconcileChannels,
+  CONFIG_PATH,
+  VIEW_CHANNEL,
+  RANK_LADDER,
+};