@bongos/core 1.17.0

package/modules/discord/CLAUDE.md

@@ -0,0 +1,50 @@
+# `discord` module — the Discord mirror (bot + broadcast + link/role)
+
+Optional feature module: the outbound `#ship-news`/`#ship-feed` broadcast, the inbound `#ideas`/`#bugs` bot, ship-feed applause, role-sync, channel management, and the account-link state the hall reads. **Discord is a one-way mirror of the GDS — never authority** ([ADR 0033](../../docs/adr/<redacted>.md)). Gated by `config/modules.json` (`discord: true` for the OTB instance; off on a vanilla Cloud Bongos boot). The loader (`src/module-loader/loader.js`) discovers this dir via `module.json`, mounts the route factories, and starts the bot poller. Extracted from core in BV1.R47 ([task 1416](https://example.com/builders#/task/1416)).
+
+## The boundary (the one rule)
+
+This module reaches core **only** through the published doorway `../../src/module-api.js` (the semver'd contract; this module needs `coreVersion ^1.4.0`). It must **never** `require()` a core internal (`../../src/bongos/db`, `../../src/bongos/auth`, `../../scripts/discord/lib`, …) directly, and never another module. Core, in turn, must never `require()` a file in here — that's the forbidden core→module edge this extraction removed (enforced by the BV1.R44/R45 fitness checks).
+
+## Files
+
+| File | What |
+|---|---|
+| `routes/discord.js` | Archon-only `/discord/channels/{plan,reconcile}` (ADR 0037). Its factory also **registers this module's seams** (port + listener; idempotent). |
+| `routes/bug-attachments.js` | serves `GET /bug-attachments/:name` (images attached to `#bugs` reports). Moved with the lib it reads. |
+| `discord-bot.js` | the gateway client (reactions, inbound, role-sync timer). Started/stopped via `pollers/discord-bot.js`. |
+| `discord-reaction.js` · `discord-inbound.js` · `discord-bugs.js` · `discord-approvals.js` | the passive bot features: 👍 applause, `#ideas` → idea_inbox, `#bugs` → task, member-approval reactions. |
+| `discord-role-sync.js` · `discord-channels.js` | rank→role badge reconcile + channel/topic/view management from `docs/discord/channels.json`. |
+| `discord-message-buffer.js` · `discord-audit.js` · `bug-attachments.js` | message-pair aggregator, bot-action audit helper, attachment persistence (pure). |
+| `ship-broadcast.js` | the server-side ship poster — fired by the `task.shipped` seam listener, not a core import. |
+| `db.js` | the module's data layer — owns the `discord_links`/`discord_applause` queries (via the doorway `pool`) + re-exports kernel db helpers. |
+| `auth.js` · `webhook.js` | **vendored twins** of core helpers (see below). |
+| `pollers/discord-bot.js` | the loader's web-process poller entry — `start()`/`stop()` over the bot. |
+
+## Seams (how core and this module talk without importing each other)
+
+- **Provides — port `discord.isLinked`** `(builderId) → Promise<bool>`. Core (`routes/me.js`, `routes/builders.js`) reads it via `resolveOptional('discord.isLinked', async () => false)` so the hall renders Connect/Unlink and onboarding's discord step auto-clears; degrades to `false` on a discord-less instance. (`discord.configured` — does the server hold OAuth creds — stays **core**: the account-LINK flow in `routes/auth.js` is not part of this module.)
+- **Listens — event `task.shipped`** `(shippedTaskRow)`. Core (`publish-reconciler.js`, `routes/tasks.js`) emits it on the confirmed→shipped transition; this module posts the `#ship-news`/`#ship-feed` broadcast. Replaces the old `require('./ship-broadcast')` core→discord import.
+- No consumed ports.
+
+Registration happens in `routes/discord.js`'s factory (the loader runs it at boot, already module-gated): the port is `hasProvider`-guarded; the `task.shipped` listener is off→on replaced so a test re-instantiating the router never accumulates duplicates.
+
+## Vendored twins (boundary-forced — keep in sync)
+
+The kernel doorway must stay module-agnostic (the "core carries no module code" fitness check forbids naming a module in `src/module-api.js`), and a module can't require core/scripts. So three small helpers are **copied** here, with their core originals kept for the parts of Discord that stay core:
+
+- **`auth.js`** — `isValidDiscordUserId` + `loadDiscordBotToken`. Core `src/bongos/auth.js` keeps its copies for the OAuth account-LINK flow (`routes/auth.js`).
+- **`webhook.js`** — `postWebhook`/`loadWebhooks`/`CHANNELS`, a twin of `scripts/discord/lib.js` (which stays for core `approval-broadcast.js` + the `scripts/discord/post.js` CLI).
+- **`db.js`** — `getDiscordLink`/`recordApplause` are also defined in core `src/bongos/db.js` (still used by the link flow / a seed); the others (`getBuilderByDiscordUserId`, `listDiscordLinks`, `countRecentDiscordBugFilings`) are owned here.
+
+## NOT in this module
+
+- **The OAuth account-link flow** — `routes/auth.js` + the Discord OAuth helpers in `src/bongos/auth.js` (`discordConfigured`, `addDiscordGuildMember`, …). Linking writes a core `builders`-adjacent row; it stays core. This module only surfaces the resulting *state* via the `discord.isLinked` port.
+- **`migrations/<redacted>.sql`** — stays in **core** `migrations/`. It also `ALTER`s core tables (`builders.system_role`, `audit_log.surface`) and seeds the `discord_bot` principal, so the module-migration namespacing rule (which forbids a module migration touching non-`discord_` objects) can't host it. Any *future* discord migration that touches only `discord_*` objects can live in `modules/discord/migrations/`.
+- **`ship-card.js`** — the CLI lifecycle card (claimed→shipped) used by `claim.js`/`ship.js` on every instance; not a Discord concern, stays in `src/bongos/`.
+- **`approval-broadcast.js` · `scripts/discord/{lib,post}.js`** — core/CLI Discord posters (see Vendored twins).
+- **The hall UI** (`modules/hall-ui/public/`, carved in BV1.R85) — per-module client UI is a later design phase; it stays gated by `window.__MODULES__.enabled['discord']`.
+
+## Tests
+
+`tests/discord_*.mjs` + `tests/bug_attachments.mjs` import from `modules/discord/…`. `scripts/discord/smoke*.sh` (if present) exercises the outbound poster.

package/modules/discord/auth.js

@@ -0,0 +1,54 @@
+// modules/discord/auth.js — the discord module's auth surface (BV1.R47 / task 1416).
+//
+// One `auth` namespace behind which the moved discord-*.js files keep their
+// `const auth = require('./auth')` call sites unchanged:
+//
+//   • KERNEL gates, re-exported off the published doorway — requireBuilder /
+//     requireRank (the same rank machinery every route uses; ADR 0016).
+//
+//   • DISCORD-SPECIFIC helpers VENDORED here — the snowflake validator + the bot-
+//     token loader. These are deliberately NOT on the kernel doorway: the doorway
+//     stays module-agnostic (the "core carries no module code" fitness check
+//     forbids naming a module in src/module-api.js). Core's src/bongos/auth.js keeps
+//     its OWN copies for the OAuth account-LINK flow (routes/auth.js, which is not
+//     part of this module); these are byte-identical twins — keep them in sync.
+//
+// The boundary: this file requires ONLY src/module-api.js.
+
+'use strict';
+
+const api = require('../../src/module-api');
+
+// PURE — a Discord user id is a numeric snowflake (17–20 digits). Reject anything
+// else BEFORE it reaches a link/insert. (Twin of src/bongos/auth.js's copy, kept for
+// the link flow; this module no longer reaches into core auth.)
+function isValidDiscordUserId(id) {
+  return typeof id === 'string' && /^\d{17,20}$/.test(id);
+}
+
+// Bot-token loader (ADR 0033 §F3). The bot authenticates to the Discord GATEWAY
+// with a bot token. env DISCORD_BOT_TOKEN wins (the systemd path ADR 0022 prefers
+// for the always-on droplet), else the bot_token field of the local
+// discord-bot.json (mode 600). The token is a secret — never log it. Reads config
+// through the doorway's instance-config accessor. (Twin of src/bongos/auth.js's copy.)
+function loadDiscordBotToken() {
+  const envToken = process.env.DISCORD_BOT_TOKEN;
+  if (envToken) return envToken;
+  try {
+    const raw = api.readConfigFileSync('discord-bot.json');
+    if (raw) {
+      const creds = JSON.parse(raw);
+      if (creds.bot_token) return creds.bot_token;
+    }
+  } catch (_) { /* not configured */ }
+  return null;
+}
+
+module.exports = {
+  // kernel gates (doorway)
+  requireBuilder: api.requireBuilder,
+  requireRank: api.requireRank,
+  // vendored discord-specific helpers
+  isValidDiscordUserId,
+  loadDiscordBotToken,
+};

package/modules/discord/bug-attachments.js

@@ -0,0 +1,210 @@
+'use strict';
+
+// Bug-attachment storage — durable re-hosting of #bugs screenshots (task #936,
+// follow-on to ADR 0047 / task #931).
+//
+// Discord CDN attachment URLs are signed and EXPIRE (~24h). A bug-task can sit
+// in the queue for days before it's claimed, so a bare Discord link would be a
+// dead image by then. Lars's call (2026-06-12): SAVE OUR OWN COPY. The bot
+// downloads each image attachment and re-hosts it on our server under a
+// builders-only, auth-gated route (routes/bug-attachments.js), and the task
+// description embeds that durable link.
+//
+// This module is the pure-ish storage core: where files live, how a filename
+// is validated (path-traversal-safe), and how one image is fetched + screened
+// + written. It has NO express/discord deps so it unit-tests with an injected
+// fetch.
+//
+// ANTI-ABUSE (extends the ADR 0047 guard to bytes): only image/* with an
+// allowlisted extension, magic-byte sniff (don't trust the content-type
+// header), a per-image size cap, a per-bug image cap, and a strict
+// download-host allowlist (the URL must be a Discord CDN host — defense against
+// a crafted attachment pointing our fetch at something else, i.e. SSRF).
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const crypto = require('node:crypto');
+
+// ext ⇄ content-type for the formats we accept.
+const EXT_BY_TYPE = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+};
+const TYPE_BY_EXT = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+};
+
+const MAX_BYTES = 8 * 1024 * 1024; // 8 MB per image
+const MAX_IMAGES_PER_BUG = 6;       // cap attachments folded into one bug
+
+// Stored filenames are bot-generated, never user-supplied: a fixed shape we can
+// validate exactly. This is the whole path-traversal defense — the serve route
+// only ever opens a name that matches this.
+const NAME_RE = /^bug-[a-z0-9]{1,40}-[0-9a-f]{16}\.(png|jpg|gif|webp)$/;
+
+// Where re-hosted images live. Outside the git tree (a `var/` dir) so a deploy's
+// `git reset --hard` / pull never wipes them; gitignored. Env override for tests
+// / non-default layouts.
+function attachmentsDir() {
+  return process.env.BUG_ATTACHMENTS_DIR || path.join(__dirname, '..', '..', 'var', 'bug-attachments');
+}
+
+// PURE — is this a well-formed, bot-generated attachment name?
+function isSafeName(name) {
+  return typeof name === 'string' && NAME_RE.test(name);
+}
+
+// PURE — resolve a name to an absolute path INSIDE attachmentsDir, or null if
+// the name is unsafe or would escape the dir. Belt (regex) and braces (prefix
+// check on the resolved path).
+function resolveSafe(name) {
+  if (!isSafeName(name)) return null;
+  const dir = path.resolve(attachmentsDir());
+  const p = path.resolve(dir, name);
+  if (p !== path.join(dir, name)) return null;
+  if (!p.startsWith(dir + path.sep)) return null;
+  return p;
+}
+
+// PURE — the content-type to serve a stored file with (from its extension).
+function contentTypeForName(name) {
+  const ext = String(name).split('.').pop().toLowerCase();
+  return TYPE_BY_EXT[ext] || 'application/octet-stream';
+}
+
+// PURE — only fetch from Discord's own CDN hosts. Anything else is refused
+// before a network call (SSRF guard). Discord serves message attachments from
+// EXACTLY these two hosts, so we match them exactly rather than by a
+// `.discordapp.{com,net}` suffix. (L4 residual, red-team 2026-06-12: the suffix
+// form would also accept any future/attacker-influenced `*.discordapp.com` or
+// `*.discordapp.net` subdomain — a value-judgement we don't need to make for an
+// attachment fetch where the real hosts are known and fixed.)
+const ALLOWED_ATTACHMENT_HOSTS = new Set([
+  'cdn.discordapp.com',
+  'media.discordapp.net',
+]);
+function isAllowedAttachmentHost(urlStr) {
+  let u;
+  try { u = new URL(urlStr); } catch { return false; }
+  if (u.protocol !== 'https:') return false;
+  return ALLOWED_ATTACHMENT_HOSTS.has(u.hostname.toLowerCase());
+}
+
+// PURE — confirm the bytes really are the claimed image format (magic bytes),
+// so a mislabeled content-type can't smuggle a non-image onto disk.
+function sniffMatches(buf, ext) {
+  if (!buf || buf.length < 12) return false;
+  switch (ext) {
+    case 'png':
+      return buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47;
+    case 'jpg':
+      return buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff;
+    case 'gif':
+      return buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38;
+    case 'webp':
+      return (
+        buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 && // 'RIFF'
+        buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50 // 'WEBP'
+      );
+    default:
+      return false;
+  }
+}
+
+// Download one image and re-host it. Returns { ok:true, file, url, bytes } on
+// success, or { ok:false, reason } when the image is refused (never throws on a
+// refusal; throws only on an unexpected fs error the caller wraps). `messageId`
+// just seeds the (still-random) filename so attachments group readably.
+// How many manual redirect hops we'll re-validate + follow before giving up.
+// Discord CDN attachments are direct (0 redirects) in practice; a small bound
+// covers a CDN edge bounce without becoming an open redirect-follow loop.
+const MAX_REDIRECT_HOPS = 3;
+
+async function persistImageFromUrl(url, { messageId = 'x', fetchImpl = globalThis.fetch, dir = attachmentsDir() } = {}) {
+  if (!isAllowedAttachmentHost(url)) return { ok: false, reason: 'bad_host' };
+  // L3 residual (red-team 2026-06-12): fetch with redirect:'manual' and re-run
+  // the host allowlist on every Location before following. With redirect:'follow'
+  // a 30x from an allowed host to an arbitrary host would be followed silently —
+  // re-opening the SSRF hole the host check was meant to close (defense in depth).
+  let resp;
+  let currentUrl = url;
+  let hops = 0;
+  for (;;) {
+    try {
+      resp = await fetchImpl(currentUrl, { redirect: 'manual' });
+    } catch (e) {
+      return { ok: false, reason: 'fetch_failed', error: e.message };
+    }
+    const status = resp && resp.status;
+    if (status >= 300 && status < 400) {
+      const location = resp.headers?.get?.('location');
+      if (!location) return { ok: false, reason: 'redirect_no_location' };
+      // Resolve relative redirects against the current URL, then re-validate the
+      // RESOLVED host against the SAME allowlist before following it.
+      let next;
+      try { next = new URL(location, currentUrl).toString(); } catch { return { ok: false, reason: 'redirect_bad_location' }; }
+      if (!isAllowedAttachmentHost(next)) return { ok: false, reason: 'redirect_bad_host' };
+      if (++hops > MAX_REDIRECT_HOPS) return { ok: false, reason: 'too_many_redirects' };
+      currentUrl = next;
+      continue;
+    }
+    break;
+  }
+  if (!resp || !resp.ok) return { ok: false, reason: 'fetch_status' };
+
+  const rawType = (resp.headers?.get?.('content-type') || '').split(';')[0].trim().toLowerCase();
+  const ext = EXT_BY_TYPE[rawType];
+  if (!ext) return { ok: false, reason: 'bad_type', type: rawType };
+
+  const ab = await resp.arrayBuffer();
+  const buf = Buffer.from(ab);
+  if (buf.length === 0) return { ok: false, reason: 'empty' };
+  if (buf.length > MAX_BYTES) return { ok: false, reason: 'too_big', bytes: buf.length };
+  if (!sniffMatches(buf, ext)) return { ok: false, reason: 'sniff_mismatch' };
+
+  const idSlug = String(messageId).replace(/[^a-z0-9]/gi, '').slice(0, 40).toLowerCase() || 'x';
+  const file = `bug-${idSlug}-${crypto.randomBytes(8).toString('hex')}.${ext}`;
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(path.join(dir, file), buf, { mode: 0o640 });
+  return { ok: true, file, url: `/api/gds/bug-attachments/${file}`, bytes: buf.length };
+}
+
+// Persist a list of image URLs (capped). Best-effort: refused/failed images are
+// skipped (logged), never aborting the others. Returns the stored refs
+// ({ file, url }) in input order. Used by discord-bugs.recordInboundBug.
+async function persistImages(urls, { messageId = 'x', fetchImpl = globalThis.fetch } = {}) {
+  const capped = (Array.isArray(urls) ? urls : []).slice(0, MAX_IMAGES_PER_BUG);
+  const out = [];
+  for (const u of capped) {
+    let r;
+    try {
+      r = await persistImageFromUrl(u, { messageId, fetchImpl });
+    } catch (e) {
+      console.error('[discord-bot] image persist threw (skipping):', e.message);
+      continue;
+    }
+    if (r.ok) out.push({ file: r.file, url: r.url });
+    else console.warn(`[discord-bot] image refused (${r.reason}) — skipping one attachment.`);
+  }
+  return out;
+}
+
+module.exports = {
+  EXT_BY_TYPE,
+  TYPE_BY_EXT,
+  MAX_BYTES,
+  MAX_IMAGES_PER_BUG,
+  attachmentsDir,
+  isSafeName,
+  resolveSafe,
+  contentTypeForName,
+  isAllowedAttachmentHost,
+  sniffMatches,
+  persistImageFromUrl,
+  persistImages,
+};

package/modules/discord/db.js

@@ -0,0 +1,96 @@
+// modules/discord/db.js — the discord module's data layer (BV1.R47 / task 1416).
+//
+// Two halves, behind ONE `db` surface so the moved discord-*.js files keep their
+// existing `const db = require('./db')` call sites unchanged:
+//
+//   • DOMAIN queries the module OWNS — the discord_links / discord_applause
+//     tables (created by migration 067) + the discord-bug-filing count over the
+//     shared audit_log. These were lifted verbatim from src/bongos/db.js; the module
+//     reaches Postgres through the published doorway's `pool` (ADR 0083 — a module
+//     never requires a core internal like ../../src/bongos/db).
+//
+//   • KERNEL db helpers the module CONSUMES — insertAuditLog / createTask /
+//     getBuilderById + the LIVE_RANK_LADDER constant — re-exported straight off
+//     the doorway so a single `db.*` namespace serves both.
+//
+// The boundary: this file requires ONLY src/module-api.js. The three DISCORD-ONLY
+// queries (getBuilderByDiscordUserId / listDiscordLinks / countRecentDiscordBugFilings)
+// were removed from src/bongos/db.js — they live here now. getDiscordLink +
+// recordApplause are INTENTIONALLY duplicated: core keeps its copies (the OAuth
+// link flow in routes/auth.js + a seed still call them) and this module owns its
+// own (a module can't import core db). Both read the same discord_links /
+// discord_applause tables.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool } = api;
+
+// --- domain: the discord_links / discord_applause tables this module owns ----
+
+async function getBuilderByDiscordUserId(discordUserId) {
+  const { rows } = await pool.query(
+    `SELECT b.id, b.github_login, b.display_name, b.rank, b.status, b.system_role
+       FROM discord_links dl
+       JOIN builders b ON b.id = dl.builder_id
+      WHERE dl.discord_user_id = $1`,
+    [discordUserId]
+  );
+  return rows[0] || null;
+}
+
+async function listDiscordLinks() {
+  const { rows } = await pool.query(
+    `SELECT builder_id, discord_user_id FROM discord_links ORDER BY builder_id`
+  );
+  return rows;
+}
+
+async function getDiscordLink(builderId) {
+  const { rows } = await pool.query(
+    `SELECT builder_id, discord_user_id, linked_at FROM discord_links WHERE builder_id = $1`,
+    [builderId]
+  );
+  return rows[0] || null;
+}
+
+async function countRecentDiscordBugFilings(builderId, sinceIso) {
+  const { rows } = await pool.query(
+    `SELECT count(*)::int AS n
+       FROM audit_log
+      WHERE builder_id = $1
+        AND route = 'discord:bugs'
+        AND response_status = 201
+        AND recorded_at > $2`,
+    [builderId, sinceIso]
+  );
+  return rows[0].n;
+}
+
+async function recordApplause({ targetTaskId, discordUserId }) {
+  const { rowCount } = await pool.query(
+    `INSERT INTO discord_applause (target_task_id, discord_user_id)
+     VALUES ($1, $2)
+     ON CONFLICT (target_task_id, discord_user_id) DO NOTHING`,
+    [targetTaskId, discordUserId]
+  );
+  return { counted: rowCount > 0 };
+}
+
+module.exports = {
+  // domain (this module's tables)
+  getBuilderByDiscordUserId,
+  listDiscordLinks,
+  getDiscordLink,
+  countRecentDiscordBugFilings,
+  recordApplause,
+  // kernel db helpers, re-exported off the doorway (one `db.*` namespace)
+  insertAuditLog: (...a) => api.insertAuditLog(...a),
+  // createTask is a LIFECYCLE write — resolve the `lifecycle` kernel port at call
+  // time (the doorway leak retired at BV1.R86); used by discord-bugs (#bugs → task).
+  createTask: (...a) => api.resolveOptional('lifecycle').createTask(...a),
+  getBuilderById: (...a) => api.getBuilderById(...a),
+  get LIVE_RANK_LADDER() { return api.LIVE_RANK_LADDER; },
+  // the shared pool, for any module file that wants it via db.pool
+  pool,
+};

package/modules/discord/discord-approvals.js

@@ -0,0 +1,145 @@
+'use strict';
+
+// Discord reaction → Archon approval (task 1100).
+//
+// An Archon's 👍/👎 on a request line in #member-approvals fires the SAME server
+// action the amazonprimea hall fires:
+//   #member-approvals  👍 → access_requests → 'invited'   (PATCH /access-requests/:id)
+//                      👎 → access_requests → 'dismissed'
+//
+// TRUST BOUNDARY (ADR 0016 / 0033 §1) — the one invariant: every bot-triggered
+// write re-checks the LINKED builder's LIVE rank. The bot asserts only WHO
+// reacted (Discord user → linked builder via the F1 table, which reads rank
+// FRESH from `builders`); the GDS decides WHAT they may do. Both these actions
+// are Archon-only on the web (auth.requireRank('archon')), so here we re-derive
+// the reactor's live rank and act ONLY when it is 'archon'. Anything else (an
+// unlinked reactor, a Metic, a player) is a no-op. The bot cannot escalate; the
+// worst a compromised bot could do is mis-report which Archon reacted, bounded
+// by the audit_log (surface='discord_bot').
+//
+// WHY A FUNCTION, NOT AN HTTP ENDPOINT: the bot is in-process (ADR 0033 F3), so
+// it calls this directly — no localhost self-HTTP, no minted bot session token.
+//
+// FAIL-CLOSED + NEVER THROWS: the caller is a gateway event handler that must
+// not crash the bot; every path returns { outcome } and all failure is caught.
+
+const { pool } = require('../../src/module-api');
+const db = require('./db');
+const { auditDiscordBot } = require('./discord-audit');
+const auth = require('./auth');
+
+// Only the top rank may approve admissions (identical to the
+// web routes' auth.requireRank('archon')).
+const APPROVING_RANK = 'archon';
+
+// PURE — map a discord.js emoji name to an approval decision, or null for any
+// other reaction (which the handler then ignores).
+function emojiToDecision(emojiName) {
+  if (emojiName === '👍') return 'approve';
+  if (emojiName === '👎') return 'decline';
+  return null;
+}
+
+// PURE — extract { kind, id } from an approval request line. The producer
+// (approval-broadcast.js) LEADS each line with a `member-request #<id>` token; we
+// anchor to the start so a body that mentions another "#7" can't hijack the
+// mapping. kind is always 'member'. Returns null when the line carries no leading
+// approval marker (e.g. a confirmation reply we post).
+function parseApprovalMarker(content) {
+  if (typeof content !== 'string') return null;
+  const m = /^\s*(member-request)\s+#(\d{1,15})\b/.exec(content);
+  if (!m) return null;
+  const id = Number(m[2]);
+  if (!Number.isInteger(id) || id <= 0) return null;
+  return { kind: 'member', id };
+}
+
+// DB — resolve a pending access request to 'invited' | 'dismissed', stamping the
+// approving Archon. GUARDED on status='pending' (idempotent: a second reaction,
+// or one on an already-resolved request, matches nothing → null), exactly like
+// the PATCH /access-requests/:id route. Returns the updated row or null.
+async function resolveAccessRequest({ id, status, builderId }) {
+  const { rows } = await pool.query(
+    `UPDATE access_requests
+        SET status = $1, resolved_by_builder_id = $2, resolved_at = now()
+      WHERE id = $3 AND status = 'pending'
+      RETURNING id, github_login, status`,
+    [status, builderId, id]
+  );
+  return rows[0] || null;
+}
+
+// The real dependency set — injected so recordApprovalReaction is unit-testable
+// against fakes with NO database.
+const realDeps = {
+  getBuilderByDiscordUserId: db.getBuilderByDiscordUserId,
+  resolveAccessRequest,
+  insertAuditLog: db.insertAuditLog,
+};
+
+// Orchestrate one approval reaction. NEVER throws. `kind` is fixed by WHICH
+// channel the reaction landed in (the bot knows the channel id) and is always
+// 'member'; `decision` ('approve'|'decline') comes from the emoji; `recordId`
+// from the parsed marker. Returns { outcome, ... } where outcome ∈
+//   'approved' | 'declined'        — action fired
+//   'already_resolved'             — record was gone/resolved (idempotent no-op)
+//   'ignored' (+reason)            — not an Archon / bad input
+//   'error' (+error)
+async function recordApprovalReaction({ discordUserId, kind, decision, recordId }, deps = realDeps) {
+  if (!auth.isValidDiscordUserId(discordUserId)) {
+    return { outcome: 'ignored', reason: 'bad_discord_user_id' };
+  }
+  if (kind !== 'member') {
+    return { outcome: 'ignored', reason: 'bad_kind' };
+  }
+  if (decision !== 'approve' && decision !== 'decline') {
+    return { outcome: 'ignored', reason: 'bad_decision' };
+  }
+  if (!Number.isInteger(recordId) || recordId <= 0) {
+    return { outcome: 'ignored', reason: 'bad_record_id' };
+  }
+
+  try {
+    // Re-derive the reactor's LIVE rank — the whole trust boundary (ADR 0016).
+    const builder = await deps.getBuilderByDiscordUserId(discordUserId);
+    if (!builder) return { outcome: 'ignored', reason: 'unlinked_reactor' };
+    if (builder.rank !== APPROVING_RANK) return { outcome: 'ignored', reason: 'not_archon' };
+
+    const status = decision === 'approve' ? 'invited' : 'dismissed';
+    const resolved = await deps.resolveAccessRequest({ id: recordId, status, builderId: builder.id });
+
+    // A guarded UPDATE matched nothing → the record was already resolved or gone.
+    // Idempotent no-op (a duplicate/late reaction), not an error.
+    if (!resolved) {
+      return { outcome: 'already_resolved', kind, recordId, builderId: builder.id };
+    }
+
+    const outcome = decision === 'approve' ? 'approved' : 'declined';
+
+    // Audit every bot-triggered write (ADR 0033 §1). Best-effort — an audit
+    // failure must not undo the approval.
+    await auditDiscordBot(deps, {
+      builderId: builder.id,
+      route: `discord:approval:${kind}`,
+      requestBodyRedacted: { discord_user_id: discordUserId, kind, record_id: recordId, decision, outcome },
+      responseStatus: 200,
+      logLabel: 'approval audit-log write failed',
+    });
+
+    return { outcome, kind, recordId, builderId: builder.id, resolved };
+  } catch (err) {
+    console.error('[discord-bot] recordApprovalReaction failed:', err.message);
+    return { outcome: 'error', error: err.message };
+  }
+}
+
+module.exports = {
+  // pure (unit-tested)
+  emojiToDecision,
+  parseApprovalMarker,
+  APPROVING_RANK,
+  // orchestration + DB
+  recordApprovalReaction,
+  resolveAccessRequest,
+  realDeps,
+};

package/modules/discord/discord-audit.js

@@ -0,0 +1,29 @@
+// src/bongos/discord-audit.js
+//
+// Shared wrapper for the bot's audit-log writes (task 1091, C7 — dedup audit
+// 2026-06-14 §2A discord). Every bot-triggered write is audited (ADR 0033 §1)
+// with method='POST' and surface='discord_bot', best-effort: an audit failure
+// must NEVER undo or throw out of the action it records, so it is caught and
+// logged non-fatally. The five call sites (approvals, bugs ×2, inbound,
+// reaction) differ only in builderId / route / requestBodyRedacted /
+// responseStatus and the log label — everything else is fixed here.
+//
+// `deps` carries the injected insertAuditLog (deps.insertAuditLog) so the
+// existing unit tests' mocked deps continue to observe the identical call.
+
+async function auditDiscordBot(deps, { builderId, route, requestBodyRedacted, responseStatus, logLabel }) {
+  try {
+    await deps.insertAuditLog({
+      builderId,
+      route,
+      method: 'POST',
+      requestBodyRedacted,
+      responseStatus,
+      surface: 'discord_bot',
+    });
+  } catch (auditErr) {
+    console.error(`[discord-bot] ${logLabel} (non-fatal):`, auditErr.message);
+  }
+}
+
+module.exports = { auditDiscordBot };