feat(teams): the slash-command seam, and the first command through it

Phase 7 of TEAMS.md. `api.registerSlashCommands` stops throwing: a module
registers a command's DEFINITION and its HANDLER together, the bot pulls the
definitions over the internal listener and runs none of our code, and the
handler executes here — forced by the bot container having no `modules` volume,
and the right boundary anyway.

Registration validates what Discord would reject as a batch (names, description
lengths, the four option types, required-before-optional), because the bot
registers the whole set in one PUT and a single bad entry costs every command
including the bot's own. Commands are not namespaced under their owner — there
is no dot in Discord's name grammar — so collisions are first-come with the
holder named.

The dispatcher is the access boundary: `linked` has no Discord equivalent, so
the platform-side permission default can only ever be advertising. It resolves
the actor by `auth_providers.kind` rather than the id slug, treats a banned
account as unlinked, bounds a handler under the bot's own timeout, and keeps
`ok` outside the envelope so a handler cannot forge it.

Liveness is asked at both the pull and the dispatch. The registries have no
removal path, so a module an operator disables at runtime would otherwise keep
a live handler behind a command Discord still advertises.

Co-Authored-By: Claude <noreply@anthropic.com>

bot/package.json

@@ -6,6 +6,7 @@
   "main": "src/server.js",
   "scripts": {
     "start": "node src/server.js",
+    "test": "node --test test/*.test.js",
     "dev": "nodemon src/server.js"
   },
   "keywords": ["discord", "discord.js"],

bot/src/discord/discordManager.js

@@ -5,6 +5,7 @@ const { Client, GatewayIntentBits, REST, Routes } = require('discord.js')
 
 const createLogger = require('../utils/logger')
 const commands = require('./commands')
+const dynamicCommands = require('./dynamicCommands')
 const messageFilter = require('./messageFilter')
 const scheduler = require('../scheduler/scheduler')
 const roleMenuHandler = require('./roleMenuHandler')
@@ -22,12 +23,46 @@ let status = 'disconnected' // disconnected | connecting | connected | error
 let statusDetail = null
 let lastConnectedAt = null
 
+// One whole-set PUT of the bot's own commands plus whatever the app has
+// registered (TEAMS.md §7.1). Because it replaces the set rather than adding to
+// it, DEREGISTRATION is free: a module that is gone is simply absent from the
+// next pull, and nobody has to remember to take its command back.
 async function registerCommands(applicationId, targetGuildId) {
+  const dynamic = dynamicCommands.definitions()
   const rest = new REST({ version: '10' }).setToken(client.token)
   await rest.put(Routes.applicationGuildCommands(applicationId, targetGuildId), {
-    body: commands.all.map((c) => c.data),
+    body: [...commands.all.map((c) => c.data), ...dynamic],
   })
-  log.info('registered guild slash commands', { guildId: targetGuildId, count: commands.all.length })
+  log.info('registered guild slash commands', {
+    guildId: targetGuildId,
+    builtIn: commands.all.length,
+    fromApp: dynamic.length,
+  })
+}
+
+/**
+ * Re-pull the app's commands and re-register the set if it moved.
+ *
+ * Called on `ready` and again whenever the app nudges
+ * (`POST /internal/refresh-commands`). A no-op when nothing changed, so a nudge
+ * per module state change costs one cheap GET rather than a REST.put per
+ * install — and a disconnected bot does nothing at all, since there is no
+ * application to register against until it logs in.
+ */
+async function refreshCommands() {
+  const result = await dynamicCommands.pull()
+  if (!result.ok || !result.changed) return result
+  if (!client || !client.isReady()) return result
+  try {
+    await registerCommands(client.application.id, guildId)
+  } catch (err) {
+    // The PUT is all-or-nothing: a definition Discord rejects costs every
+    // command, the built-ins included. Loud, and never fatal to the process.
+    log.error('re-registering slash commands failed — the previous set is still live', {
+      message: err.message,
+    })
+  }
+  return result
 }
 
 async function stop() {
@@ -54,6 +89,11 @@ async function stop() {
 // failure here leaves the client connected but flags an error status.
 async function onReady() {
   try {
+    // Pull BEFORE the single PUT, so the app's commands are in the very first
+    // registration rather than appearing a beat later. The pull never throws —
+    // an unreachable app costs the module commands and nothing else, and the
+    // bot's own set registers exactly as it always did.
+    await dynamicCommands.pull()
     await registerCommands(client.application.id, guildId)
     await scheduler.start(client)
     tempRoleSweeper.start(client)
@@ -70,14 +110,19 @@ async function onReady() {
   }
 }
 
-// Route an interaction: role-menu handler first, then chat-input slash commands.
+// Route an interaction: role-menu handler first, then chat-input slash commands
+// — the bot's own, then the app's. Built-ins are consulted FIRST and the pull
+// already drops any module name that collides with one, so the two orderings
+// agree; checking here as well means a name that somehow reached Discord twice
+// still runs the bot's version rather than whichever registry answered first.
 async function onInteractionCreate(interaction) {
   if (await roleMenuHandler.handleInteraction(interaction)) return
   if (!interaction.isChatInputCommand()) return
   const command = commands.get(interaction.commandName)
-  if (!command) return
+  if (!command && !dynamicCommands.has(interaction.commandName)) return
   try {
-    await command.execute(interaction)
+    if (command) await command.execute(interaction)
+    else await dynamicCommands.execute(interaction)
   } catch (err) {
     log.error('command execution failed', { command: interaction.commandName, message: err.message })
     const payload = { content: 'Something went wrong running that command.', ephemeral: true }
@@ -146,4 +191,4 @@ function getConnection() {
   return { client, guildId }
 }
 
-module.exports = { start, stop, getStatus, getConnection }
+module.exports = { start, stop, getStatus, getConnection, refreshCommands }

bot/src/discord/dynamicCommands.js

@@ -0,0 +1,210 @@
+// Slash commands whose DEFINITION and HANDLER live in the website process
+// (TEAMS.md §7.1). The bot pulls the definitions, registers them alongside its
+// own, and executes one by deferring, asking the app, and editing the reply in.
+//
+// Everything Discord-specific is here and nothing else is: the app's dispatcher
+// resolves the actor, enforces access and produces a platform-neutral envelope,
+// and this file turns that envelope into an interaction reply. A module never
+// touches an interaction, which is what makes the registration API something a
+// second platform could implement.
+const { PermissionFlagsBits } = require('discord.js')
+
+const appInternal = require('../site/appInternalClient')
+const staticCommands = require('./commands')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('dynamic-commands')
+
+// §7.1.1's four types, and the only four. The app rejects anything else at
+// registration; this map is the second half of that agreement.
+const OPTION_TYPE = { string: 3, integer: 4, boolean: 5, user: 6 }
+
+// The pulled set, and the app's module-state counter it came from. `null`
+// version means "never successfully pulled", which is distinct from 0 ("pulled
+// while the app had no modules loaded") — the first should retry, the second is
+// a true answer.
+let pulled = []
+let version = null
+
+/**
+ * Ask the app for the current definitions.
+ *
+ * **A failed pull KEEPS the previous set.** The app being briefly unreachable is
+ * not the same as it having no commands, and treating it as such would
+ * deregister every module command from Discord on a restart blip — then
+ * re-register them a minute later, with members watching commands appear and
+ * disappear. Nothing changes until the app actually answers.
+ *
+ * @returns {Promise<{ok: boolean, changed: boolean, count: number}>}
+ */
+async function pull() {
+  const res = await appInternal.fetchCommands()
+  if (!res.ok) {
+    log.warn('command pull failed — keeping the set already registered', {
+      error: res.error,
+      holding: pulled.length,
+    })
+    return { ok: false, changed: false, count: pulled.length }
+  }
+
+  const { version: pulledVersion, commands } = res.data || {}
+  const next = Array.isArray(commands) ? commands.filter(usable) : []
+  const changed = version === null || pulledVersion !== version || next.length !== pulled.length
+  pulled = next
+  version = typeof pulledVersion === 'number' ? pulledVersion : 0
+  return { ok: true, changed, count: pulled.length }
+}
+
+/**
+ * Drop a pulled definition the bot cannot honour.
+ *
+ * **The name collision the app cannot see.** The app validates a command against
+ * everything IT has registered; it does not know the bot's own static array
+ * exists. A module registering `ping` would produce two `ping` entries in one
+ * `REST.put`, which Discord rejects as a batch — taking down every command
+ * including the bot's own. The bot's built-ins win, because they are the ones a
+ * module cannot be asked to change.
+ */
+function usable(definition) {
+  if (!definition || typeof definition.name !== 'string') return false
+  if (staticCommands.get(definition.name)) {
+    log.warn('module slash command collides with a built-in and is ignored', {
+      command: definition.name,
+      owner: definition.owner,
+    })
+    return false
+  }
+  return true
+}
+
+/**
+ * The pulled definitions as Discord command data, for the whole-set PUT.
+ *
+ * `access: 'staff'` becomes a Discord-side permission default; `linked` cannot
+ * be expressed in Discord's permission model at all — there is no "has a website
+ * account" predicate — so it is simply not advertised and the app's dispatcher
+ * refuses it. That asymmetry is the reason §7.1 says access is enforced twice
+ * and that only the server half is the gate.
+ */
+function definitions() {
+  return pulled.map((c) => {
+    const data = {
+      name: c.name,
+      description: c.description,
+      options: (c.options || []).map((o) => ({
+        name: o.name,
+        description: o.description,
+        type: OPTION_TYPE[o.type],
+        required: Boolean(o.required),
+        ...(o.choices ? { choices: o.choices } : {}),
+      })),
+    }
+    if (c.access === 'staff') data.default_member_permissions = PermissionFlagsBits.ModerateMembers.toString()
+    return data
+  })
+}
+
+/** Is this a command the app owns? Asked before the static registry is consulted. */
+const has = (name) => pulled.some((c) => c.name === name)
+
+// Read the options the member actually supplied, by the names the definition
+// declared. A `user` option is passed on as the Discord user id and nothing else
+// — a handler receives platform ids, never a platform object.
+function collectOptions(interaction, definition) {
+  const out = {}
+  for (const option of definition.options || []) {
+    const supplied = interaction.options.get(option.name)
+    if (supplied === null || supplied === undefined) continue
+    out[option.name] = option.type === 'user' ? String(supplied.value) : supplied.value
+  }
+  return out
+}
+
+// What the caller sees when the app declined. The COPY lives here rather than in
+// the app on purpose: the app answers with a machine reason, and how a refusal is
+// phrased to a member is the platform's own voice.
+function refusal({ reason, access }) {
+  if (reason === 'forbidden' && access === 'linked') {
+    return 'Link your Discord account on the site to use this command.'
+  }
+  if (reason === 'forbidden') return 'You do not have access to that command.'
+  if (reason === 'unknown') return 'That command is no longer available.'
+  return 'Something went wrong running that command.'
+}
+
+// Envelope → interaction payload. A response with fields or a title is an embed;
+// a bare `text` is plain content, which reads better for a one-line answer.
+function render(envelope) {
+  const { text, title, fields, url } = envelope
+  if (!title && !fields) return { content: text || '​' }
+  const embed = {}
+  if (title) embed.title = title
+  if (text) embed.description = text
+  if (url) embed.url = url
+  if (fields) embed.fields = fields
+  return { embeds: [embed] }
+}
+
+/**
+ * Defer, dispatch, edit.
+ *
+ * **The deferral comes first, always.** Discord gives three seconds to acknowledge
+ * an interaction; the app is given four to answer. Deferring before the dispatch
+ * is what keeps the website out of that critical path entirely — a wedged handler
+ * costs its own reply and never an "application did not respond".
+ *
+ * A failure at any point after the defer is an edit, not a reply: the interaction
+ * has already been acknowledged, and `reply()` on a deferred interaction throws.
+ */
+async function execute(interaction) {
+  const definition = pulled.find((c) => c.name === interaction.commandName)
+  if (!definition) return false
+
+  // Ephemerality has to be decided BEFORE the answer exists, because it is a
+  // property of the deferral. A command declared for linked users only is
+  // answered privately by default — its answer is about the caller's own
+  // account — and everything else defers publicly; a handler that wants the
+  // opposite says so, and the follow-up carries it.
+  const ephemeral = definition.access === 'linked'
+  await interaction.deferReply({ ephemeral })
+
+  const res = await appInternal.dispatchCommand({
+    command: definition.name,
+    options: collectOptions(interaction, definition),
+    platformUserId: interaction.user.id,
+    guildId: interaction.guildId,
+  })
+
+  // A transport failure and a handler failure are the same sentence to the
+  // member and different lines in the log: one is the app being unreachable,
+  // the other is a module's code.
+  if (!res.ok) {
+    log.warn('command dispatch failed', { command: definition.name, error: res.error })
+    await interaction.editReply({ content: refusal({ reason: 'error' }) })
+    return true
+  }
+  if (!res.data || !res.data.ok) {
+    await interaction.editReply({ content: refusal(res.data || {}) })
+    return true
+  }
+
+  const envelope = res.data.response || {}
+  await interaction.editReply(render(envelope))
+
+  // The private aside beside a public answer (§9 answer 5). Skipped when the
+  // reply was already private — the member would just be told the same thing
+  // twice, in the same place.
+  if (envelope.notice && !ephemeral && !envelope.ephemeral) {
+    await interaction.followUp({ content: envelope.notice, ephemeral: true })
+  }
+  return true
+}
+
+// Test-only: the pulled set is process-global, so a test that pulls has to be
+// able to hand the process back.
+function _reset() {
+  pulled = []
+  version = null
+}
+
+module.exports = { pull, definitions, has, execute, _reset }

bot/src/internal/internal.controller.js

@@ -99,4 +99,26 @@ async function reverseModAction(req, res) {
   }
 }
 
-module.exports = { setConfig, getStatus: getStatusHandler, announce, reverseModAction }
+// POST /internal/refresh-commands — the app's nudge that its registered
+// slash-command set has moved (TEAMS.md §7.1). No body: the bot re-pulls
+// `/internal/commands` and re-registers only if the set actually changed, so the
+// nudge stays a cheap thing the app can send on every module state change.
+//
+// Deliberately its OWN endpoint rather than riding on /internal/config, which
+// carries the decrypted bot token: saying "commands changed" should not require
+// the app to read a secret out of the database.
+//
+// Answers 200 even when disconnected — there is no application to register
+// against until the bot logs in, and `ready` pulls again anyway. A 5xx here
+// would make an ordinary module install look like a failure in the admin panel.
+async function refreshCommands(req, res) {
+  try {
+    const result = await discordManager.refreshCommands()
+    return res.json({ ok: true, ...result })
+  } catch (err) {
+    log.error('refresh-commands failed', { message: err.message })
+    return res.json({ ok: false, error: err.message })
+  }
+}
+
+module.exports = { setConfig, getStatus: getStatusHandler, announce, reverseModAction, refreshCommands }

bot/src/internal/internal.routes.js

@@ -11,5 +11,6 @@ router.post('/config', ctrl.setConfig)
 router.get('/status', ctrl.getStatus)
 router.post('/announce', ctrl.announce)
 router.post('/mod-reverse', ctrl.reverseModAction)
+router.post('/refresh-commands', ctrl.refreshCommands)
 
 module.exports = router

bot/src/site/appInternalClient.js

@@ -0,0 +1,76 @@
+// Shared-secret client for the APP's internal listener (port 3001) — the
+// bot→app direction of the channel `botInternalClient.js` runs app→bot.
+//
+// Two callers, both slash-command plumbing (TEAMS.md §7.1): pull the registered
+// command definitions, and dispatch one that a member has just run. Distinct
+// from siteApiClient.js, which reads the site's PUBLIC API with no secret at all.
+//
+// **The base URL is derived from `SITE_INTERNAL_URL`'s origin, not configured
+// separately.** That variable already points at the app's internal listener —
+// `http://app:3001/internal/bot-config` — and adding a second variable naming the
+// same host would be one more thing an operator can get half-right. Deriving it
+// means every existing deployment gains these endpoints with no compose change.
+const createLogger = require('../utils/logger')
+
+const log = createLogger('app-internal')
+
+const KEY = process.env.BOT_INTERNAL_KEY || ''
+
+// §7.1's budget, and the same 4s `botInternalClient` uses in the other
+// direction. The app bounds its own handlers UNDER this (3s), so a timeout here
+// normally means the app itself is unreachable rather than a module being slow.
+const TIMEOUT_MS = 4000
+
+function baseUrl() {
+  const configured = process.env.SITE_INTERNAL_URL
+  if (!configured) return null
+  try {
+    return new URL(configured).origin
+  } catch {
+    log.error('SITE_INTERNAL_URL is not a URL — slash-command registration is off', { configured })
+    return null
+  }
+}
+
+async function call(path, { method = 'GET', body } = {}) {
+  const base = baseUrl()
+  if (!base || !KEY) return { ok: false, error: 'SITE_INTERNAL_URL or BOT_INTERNAL_KEY not set' }
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  try {
+    const res = await fetch(`${base}${path}`, {
+      method,
+      headers: { 'Content-Type': 'application/json', 'X-Internal-Key': KEY },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    })
+    if (!res.ok) return { ok: false, status: res.status, error: `app responded ${res.status}` }
+    return { ok: true, status: res.status, data: await res.json() }
+  } catch (err) {
+    log.warn('app internal call failed', { path, message: err.message })
+    return { ok: false, status: 0, error: err.message }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+/** The registered slash-command definitions, plus the version they belong to. */
+function fetchCommands() {
+  return call('/internal/commands')
+}
+
+/**
+ * Run one command in the app and get the response envelope back.
+ *
+ * The bot has already deferred by the time this is called, so the only deadline
+ * that matters is Discord's 15-minute follow-up window — TIMEOUT_MS is about not
+ * holding an interaction open on a wedged app, not about the 3-second ack.
+ */
+function dispatchCommand({ command, options, platformUserId, guildId }) {
+  return call('/internal/commands/dispatch', {
+    method: 'POST',
+    body: { command, options, platform: 'discord', platformUserId, guildId },
+  })
+}
+
+module.exports = { fetchCommands, dispatchCommand }

bot/test/appInternalClient.test.js

@@ -0,0 +1,77 @@
+// The bot→app internal client (TEAMS.md §7.1).
+//
+// One property carries this file: the base URL is DERIVED from
+// `SITE_INTERNAL_URL`, which already names the app's internal listener with a
+// path on the end. That derivation is the reason every existing deployment gains
+// slash commands with no compose change, and it is exactly the kind of string
+// handling that breaks silently — a wrong base means "the app is down" forever,
+// with nothing in the logs but a fetch error.
+
+const { test, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+
+const env = { ...process.env }
+const realFetch = global.fetch
+
+beforeEach(() => {
+  process.env.SITE_INTERNAL_URL = 'http://app:3001/internal/bot-config'
+  process.env.BOT_INTERNAL_KEY = 'shh'
+  delete require.cache[require.resolve('../src/site/appInternalClient')]
+})
+
+afterEach(() => {
+  process.env = { ...env }
+  global.fetch = realFetch
+})
+
+/** Load the client fresh and record the single fetch it makes. */
+function withFetch(response) {
+  const seen = {}
+  global.fetch = async (url, init) => {
+    seen.url = url
+    seen.init = init
+    return response
+  }
+  // eslint-disable-next-line global-require
+  return { client: require('../src/site/appInternalClient'), seen }
+}
+
+const ok = (body) => ({ ok: true, status: 200, json: async () => body })
+
+test('the commands URL is the internal listener’s origin, not its bot-config path', async () => {
+  const { client, seen } = withFetch(ok({ version: 3, commands: [] }))
+  const res = await client.fetchCommands()
+  assert.equal(seen.url, 'http://app:3001/internal/commands')
+  assert.equal(seen.init.headers['X-Internal-Key'], 'shh')
+  assert.deepEqual(res.data, { version: 3, commands: [] })
+})
+
+test('a dispatch names the platform, so the app never has to guess', async () => {
+  const { client, seen } = withFetch(ok({ ok: true, response: {} }))
+  await client.dispatchCommand({ command: 'guild', options: { name: 'KOC' }, platformUserId: '5', guildId: '9' })
+  assert.equal(seen.url, 'http://app:3001/internal/commands/dispatch')
+  assert.deepEqual(JSON.parse(seen.init.body), {
+    command: 'guild', options: { name: 'KOC' }, platform: 'discord', platformUserId: '5', guildId: '9',
+  })
+})
+
+// A bot with no internal URL configured is an ordinary deployment state (the
+// warning already exists in bootstrap.js); it must not become an exception on
+// every `ready`.
+test('an unconfigured or unparseable SITE_INTERNAL_URL is a refusal, not a throw', async () => {
+  delete process.env.SITE_INTERNAL_URL
+  const { client } = withFetch(ok({}))
+  assert.equal((await client.fetchCommands()).ok, false)
+
+  delete require.cache[require.resolve('../src/site/appInternalClient')]
+  process.env.SITE_INTERNAL_URL = 'not a url'
+  // eslint-disable-next-line global-require
+  assert.equal((await require('../src/site/appInternalClient').fetchCommands()).ok, false)
+})
+
+test('a non-2xx carries its status so the caller can tell "down" from "rejected"', async () => {
+  const { client } = withFetch({ ok: false, status: 401, json: async () => ({}) })
+  const res = await client.fetchCommands()
+  assert.equal(res.ok, false)
+  assert.equal(res.status, 401)
+})

bot/test/dynamicCommands.test.js

@@ -0,0 +1,225 @@
+// ── The bot's half of module slash commands (TEAMS.md §7.1) ────────────────
+//
+// The first tests in this package, and they exist for a specific reason: phases
+// 8 and 9 put more of the Discord integration in this process, and the failure
+// modes here are ones no unit test in `server/` can see — a whole-set PUT that
+// one bad entry poisons, a deferral that has to happen before anything slow, and
+// a reply that must be EDITED rather than sent once the interaction is deferred.
+//
+// Nothing here talks to Discord. `interaction` is a fake that records what was
+// called on it, which is the whole of what this file is asserting about.
+
+const { test, beforeEach } = require('node:test')
+const assert = require('node:assert/strict')
+
+const dynamic = require('../src/discord/dynamicCommands')
+const appInternal = require('../src/site/appInternalClient')
+const staticCommands = require('../src/discord/commands')
+
+const originals = {
+  fetchCommands: appInternal.fetchCommands,
+  dispatchCommand: appInternal.dispatchCommand,
+  get: staticCommands.get,
+}
+
+beforeEach(() => {
+  dynamic._reset()
+  Object.assign(appInternal, originals)
+  staticCommands.get = originals.get
+})
+
+const definition = (over = {}) => ({
+  name: 'guild',
+  description: 'Show a guild',
+  owner: 'uo',
+  access: 'everyone',
+  options: [{ name: 'name', type: 'string', description: 'Guild name', required: false }],
+  ...over,
+})
+
+const answers = (commands, version = 1) => {
+  appInternal.fetchCommands = async () => ({ ok: true, data: { version, commands } })
+}
+
+function fakeInteraction({ commandName = 'guild', options = {}, userId = '555' } = {}) {
+  const calls = []
+  return {
+    calls,
+    commandName,
+    guildId: '999',
+    user: { id: userId },
+    options: {
+      get: (name) => (name in options ? { value: options[name] } : null),
+    },
+    deferReply: async (payload) => calls.push(['defer', payload]),
+    editReply: async (payload) => calls.push(['edit', payload]),
+    followUp: async (payload) => calls.push(['followUp', payload]),
+  }
+}
+
+// ── Pulling ────────────────────────────────────────────────────────────────
+
+test('a pull reports whether the set moved, so a nudge is cheap', async () => {
+  answers([definition()], 7)
+  assert.deepEqual(await dynamic.pull(), { ok: true, changed: true, count: 1 })
+  // Same version, same size: nothing to re-register, and re-registering anyway
+  // would mean a REST.put per module state change instead of per real change.
+  assert.deepEqual(await dynamic.pull(), { ok: true, changed: false, count: 1 })
+  answers([definition()], 8)
+  assert.equal((await dynamic.pull()).changed, true)
+})
+
+// Otherwise a restart blip would deregister every module command from Discord
+// and re-register it a minute later, with members watching it happen.
+test('a failed pull keeps the set already registered', async () => {
+  answers([definition()])
+  await dynamic.pull()
+  appInternal.fetchCommands = async () => ({ ok: false, error: 'ECONNREFUSED' })
+  assert.deepEqual(await dynamic.pull(), { ok: false, changed: false, count: 1 })
+  assert.equal(dynamic.definitions().length, 1)
+})
+
+// The collision the app cannot see: it validates against what IT registered and
+// does not know the bot's own array exists. Two entries of one name in a single
+// PUT is rejected as a batch, taking the built-ins down with it.
+test('a module command that collides with a built-in is dropped, not registered', async () => {
+  staticCommands.get = (name) => (name === 'ping' ? { data: { name: 'ping' } } : undefined)
+  answers([definition({ name: 'ping' }), definition()])
+  await dynamic.pull()
+  assert.deepEqual(dynamic.definitions().map((d) => d.name), ['guild'])
+  assert.equal(dynamic.has('ping'), false)
+})
+
+test('definitions carry Discord’s numeric option types, not the contract’s names', async () => {
+  answers([definition({
+    options: [
+      { name: 'who', type: 'user', description: 'A member', required: true },
+      { name: 'n', type: 'integer', description: 'How many', choices: [{ name: 'one', value: 1 }] },
+    ],
+  })])
+  await dynamic.pull()
+  const [data] = dynamic.definitions()
+  assert.deepEqual(data.options.map((o) => o.type), [6, 4])
+  assert.deepEqual(data.options[1].choices, [{ name: 'one', value: 1 }])
+  assert.equal(data.default_member_permissions, undefined)
+})
+
+// `linked` has no Discord equivalent — there is no "has a website account"
+// predicate — so only `staff` maps, and the app re-checks both regardless.
+test('only access: staff becomes a Discord permission default', async () => {
+  answers([definition({ access: 'staff' }), definition({ name: 'other', access: 'linked' })])
+  await dynamic.pull()
+  const [staff, linked] = dynamic.definitions()
+  assert.equal(typeof staff.default_member_permissions, 'string')
+  assert.equal(linked.default_member_permissions, undefined)
+})
+
+// ── Executing ──────────────────────────────────────────────────────────────
+
+test('the deferral happens before the dispatch, always', async () => {
+  answers([definition()])
+  await dynamic.pull()
+  let deferredFirst = false
+  const interaction = fakeInteraction()
+  appInternal.dispatchCommand = async () => {
+    deferredFirst = interaction.calls.length === 1 && interaction.calls[0][0] === 'defer'
+    return { ok: true, data: { ok: true, response: { text: 'hi' } } }
+  }
+  await dynamic.execute(interaction)
+  assert.ok(deferredFirst, 'the website is never in Discord’s 3-second ack path')
+  assert.deepEqual(interaction.calls.at(-1), ['edit', { content: 'hi' }])
+})
+
+test('the options the member supplied are passed by name, as plain values', async () => {
+  answers([definition({
+    options: [
+      { name: 'name', type: 'string', description: 'd' },
+      { name: 'who', type: 'user', description: 'd' },
+      { name: 'missing', type: 'string', description: 'd' },
+    ],
+  })])
+  await dynamic.pull()
+  let sent = null
+  appInternal.dispatchCommand = async (body) => {
+    sent = body
+    return { ok: true, data: { ok: true, response: {} } }
+  }
+  await dynamic.execute(fakeInteraction({ options: { name: 'KOC', who: '42' } }))
+  assert.deepEqual(sent.options, { name: 'KOC', who: '42' })
+  assert.equal(sent.platformUserId, '555')
+  assert.equal(sent.guildId, '999')
+})
+
+test('a title or fields render as an embed; a bare text does not', async () => {
+  answers([definition()])
+  await dynamic.pull()
+  appInternal.dispatchCommand = async () => ({
+    ok: true,
+    data: { ok: true, response: { title: 'Knights', text: 'Alliance: Accord', fields: [{ name: 'Members', value: '12' }], url: 'https://site.test/uo/guilds/7' } },
+  })
+  const interaction = fakeInteraction()
+  await dynamic.execute(interaction)
+  const [, payload] = interaction.calls.at(-1)
+  assert.equal(payload.embeds[0].title, 'Knights')
+  assert.equal(payload.embeds[0].description, 'Alliance: Accord')
+  assert.equal(payload.embeds[0].url, 'https://site.test/uo/guilds/7')
+})
+
+// §9 answer 5: the public projection, plus a private nudge to link. One reply
+// cannot be both, so the aside is a follow-up — which is the bot's decision to
+// make, not the handler's.
+test('a notice becomes an ephemeral follow-up beside a public answer', async () => {
+  answers([definition()])
+  await dynamic.pull()
+  appInternal.dispatchCommand = async () => ({
+    ok: true,
+    data: { ok: true, response: { text: 'public', notice: 'Link your account' } },
+  })
+  const interaction = fakeInteraction()
+  await dynamic.execute(interaction)
+  assert.deepEqual(interaction.calls.at(-1), ['followUp', { content: 'Link your account', ephemeral: true }])
+})
+
+test('a notice is not repeated when the answer was already private', async () => {
+  answers([definition({ access: 'linked' })])
+  await dynamic.pull()
+  appInternal.dispatchCommand = async () => ({
+    ok: true,
+    data: { ok: true, response: { text: 'private', notice: 'Link your account' } },
+  })
+  const interaction = fakeInteraction()
+  await dynamic.execute(interaction)
+  assert.deepEqual(interaction.calls[0], ['defer', { ephemeral: true }])
+  assert.equal(interaction.calls.some(([kind]) => kind === 'followUp'), false)
+})
+
+// Every failure path EDITS. Replying to a deferred interaction throws, so a
+// refusal that used reply() would turn a clean "no" into an unhandled error.
+test('a refusal is phrased by the bot and edited into the deferred reply', async () => {
+  answers([definition({ access: 'linked' })])
+  await dynamic.pull()
+  appInternal.dispatchCommand = async () => ({
+    ok: true, data: { ok: false, reason: 'forbidden', access: 'linked', isLinked: false },
+  })
+  const interaction = fakeInteraction()
+  await dynamic.execute(interaction)
+  assert.match(interaction.calls.at(-1)[1].content, /Link your Discord account/)
+  assert.equal(interaction.calls.filter(([kind]) => kind === 'edit').length, 1)
+})
+
+test('an unreachable app is the same sentence to the member and a different line in the log', async () => {
+  answers([definition()])
+  await dynamic.pull()
+  appInternal.dispatchCommand = async () => ({ ok: false, error: 'timeout' })
+  const interaction = fakeInteraction()
+  await dynamic.execute(interaction)
+  assert.match(interaction.calls.at(-1)[1].content, /Something went wrong/)
+})
+
+test('an interaction for a command the app no longer serves is left alone', async () => {
+  answers([definition()])
+  await dynamic.pull()
+  const interaction = fakeInteraction({ commandName: 'gone' })
+  assert.equal(await dynamic.execute(interaction), false)
+  assert.deepEqual(interaction.calls, [], 'nothing is deferred for a command that is not ours')
+})