feat(teams): phase 9 — one voice channel per Team, granted by a role

TEAMS.md §7.3. Each qualifying Team gets a Discord voice channel of its own
and a role that opens it, kept in step by a reconciler that rides the Team
reconcile it already depends on.

Access is a per-Team ROLE, always. §7.3 designed per-member overwrites with
escalation to a role above ~90 members; the org lead settled on roles always
(2026-08-18), which deletes `voice_overwrite_max`, the escalation and the
`mode` column — and moves the ceiling. Overwrites are capped per channel, so
the old shape's limit was "how big can one Team be"; roles are capped per
guild at 250, so the new one is "how many Teams can have voice at all". That
is a limit an operator must be told about before they hit it, so the panel
reports it and the pass refuses the create rather than letting Discord do it.

Three things §7.3 named that this codebase does not have, all settled by
asking the operator because nothing in the data model can answer:

  - "the staff role" — there is no staff-role concept anywhere. Now a list of
    role ids the admin designates; empty is a normal answer, since guild
    administrators bypass overwrites and what is really missing is a way to
    let NON-admin staff in.
  - the parent category — §7.3 said the bot creates it and gave the id nowhere
    to live (`team_integrations.team_id` is NOT NULL). The bot creates it and
    the server stores the id in settings.
  - whether the bot can act at all — nothing has ever checked. The operator
    invites the bot by hand and no invite URL with a permission integer exists
    in the tree, so a deployment can be one unticked box from every call
    failing. A preflight is now a PRECONDITION to enabling (422), not a
    per-Team error discovered afterwards.

Two more, decided rather than asked:

  - the threshold counts every active member, not linked ones. §7.3 wrote
    `voice_min_linked_members`; the operator is judging whether a Team is real,
    and link state answers a different question.
  - hidden Teams are never provisioned. A channel name is a game-sourced string
    published outside the site, which is exactly §2.8's concern —
    reservedNames.js already names "and eventually a Discord channel name" as a
    surface it protects — so the screen that suppresses a Team's page suppresses
    its channel, and a Team that becomes hidden takes the grace window.

Turning voice OFF tears nothing down: the pass suspends in both directions and
the panel offers per-row removal. A checkbox must not delete structure in
somebody's guild.

Fixes a phase 8 defect that blocks this phase's own artifact: `npm run swagger`
has been unable to run on `edge` at all. `param('teamId').custom((v) => ... ||
/^[0-9]+$/.test(v))` makes swagger-autogen's parser run away — a regex literal
followed directly by `.test(`. Hoisted to a const, as modules.router.js
already does. Underneath it, `teams.router.js` sits exactly at that parser's
per-file limit: at twenty `teamsRouter.*` statements it dies, at nineteen it
generates, and one more statement of ANY shape tips it — an unannotated route
does, and so does a bare `use`. So the voice routes are their own router file
mounted from `admin/index.js`, and teams.router.js keeps its nineteen.

Also breaks a require cycle this phase would have introduced:
teamSync -> teamVoiceSync -> teams.model -> teamSync left `teams.model` holding
the reconciler's exports object as it stood mid-load — the empty one, since
`module.exports = {…}` replaces rather than fills. The symptom is not in the
new code: it is `teamSync.intervalSeconds is not a function` thrown out of
`syncStatus()`, the freshness banner on every public Team page.

Tests: 1160 server (+40), 53 bot (+21), 284 client (+21). Swagger, routes
manifest and guards regenerated; the guard shape of the four new routes is
byte-identical to the existing admin-only ones.

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

server/src/model/teams/teamVoice.db.js

@@ -0,0 +1,201 @@
+// SQL for per-Team external resources — today, the Discord voice channel
+// (TEAMS.md §7.3, phase 9).
+//
+// Two queries carry the phase. `desiredTeams` is what SHOULD have a channel and
+// `holdersWithoutClaim` is what HAS one and should not; the reconciler is the
+// difference between them, and keeping both as single queries is what stops a
+// pass from being one round trip per Team before it has made a single Discord
+// call.
+//
+// **`discordSubjectsFor` is the whole identity chain in one statement** (§2.6):
+// team_members → users → user_identities. A member with no site account has no
+// row to join, and a member with a site account but no Discord identity drops out
+// at the second join — which is exactly right, because a role can only be granted
+// to somebody Discord knows about. Nothing else in the phase is allowed to
+// shortcut this with `teams.linked_count`, which counts hop 1 and is always the
+// larger number.
+
+const { query } = require('../../utils/db')
+
+// The provider id a Discord identity is stored under. Matches `auth_providers.id`
+// and the built-in provider in `auth/providers/discord.provider.js`; a constant
+// rather than a literal because it appears in two queries and a typo in either
+// would silently return an empty grant set — a Team whose channel nobody can
+// enter, with no error anywhere.
+const DISCORD_PROVIDER = 'discord'
+
+const COLUMNS = `
+  i.id, i.team_id, i.platform, i.resource, i.external_ref, i.role_ref,
+  i.state, i.remove_after, i.last_error, i.synced_at, i.updated_at`
+
+/**
+ * Every Team that qualifies for a resource, with its integration row if it has
+ * one.
+ *
+ * The three conditions are §7.3's provisioning gate and §2.8's publication rule
+ * together:
+ *
+ *   - `status = 'active'` — an archived Team is a record, not a place to talk.
+ *   - `hidden = 0` — the channel is NAMED after the Team, and a Discord channel
+ *     name is a game-sourced string published outside the site. A hidden Team's
+ *     name is suppressed on every public surface; a voice channel would be the
+ *     one place it still appeared.
+ *   - `member_count >= ?` — the operator's threshold, counting ALL active members
+ *     regardless of what they have linked (org lead, 2026-08-18). §7.3 wrote
+ *     `voice_min_linked_members`; the number an operator is actually judging is
+ *     "is this Team real", and link state answers a different question.
+ *
+ * LEFT JOIN rather than two queries: the reconciler needs "should have, and does
+ * it" as one answer, and a Team with no row yet is the create case.
+ */
+async function desiredTeams({ platform, resource, minMembers }) {
+  return query(
+    `SELECT t.id AS team_id, t.name, t.display_name_override, t.slug, t.abbr,
+            t.member_count, t.linked_count, ${COLUMNS}
+       FROM teams t
+       LEFT JOIN team_integrations i
+         ON i.team_id = t.id AND i.platform = ? AND i.resource = ?
+      WHERE t.status = 'active' AND t.hidden = 0 AND t.member_count >= ?
+      ORDER BY t.id`,
+    [platform, resource, Number(minMembers)],
+  )
+}
+
+/**
+ * Rows that hold a resource for a Team that no longer qualifies.
+ *
+ * The mirror of `desiredTeams`, and deliberately not its negation in JavaScript:
+ * a Team can stop qualifying by being archived, by being hidden, by losing
+ * members, or by having its row deleted out from under core, and enumerating
+ * those in a filter would mean re-deriving the gate in a second place that could
+ * disagree with the first.
+ *
+ * Rows already in 'pending_removal' are included — the grace window is decided by
+ * the caller, which needs to see them to know whether one has expired.
+ */
+async function holdersWithoutClaim({ platform, resource, minMembers }) {
+  return query(
+    `SELECT t.id AS team_id, t.name, t.display_name_override, t.status, t.hidden,
+            t.member_count, ${COLUMNS}
+       FROM team_integrations i
+       JOIN teams t ON t.id = i.team_id
+      WHERE i.platform = ? AND i.resource = ?
+        AND (i.external_ref IS NOT NULL OR i.role_ref IS NOT NULL)
+        AND (t.status <> 'active' OR t.hidden = 1 OR t.member_count < ?)
+      ORDER BY t.id`,
+    [platform, resource, Number(minMembers)],
+  )
+}
+
+/**
+ * The Discord user ids of a Team's members — hop 3 of §2.6, and the only set a
+ * role can be granted to.
+ *
+ * DISTINCT because a user could in principle hold two rows for the same provider
+ * across a provider rename; the unique key prevents it for one (provider,
+ * subject) pair, not for one user with two subjects. Two role-adds for the same
+ * person is harmless and one duplicate in a diff is a phantom removal next pass,
+ * which is not.
+ */
+async function discordSubjectsFor(teamId) {
+  const rows = await query(
+    `SELECT DISTINCT ui.subject
+       FROM team_members m
+       JOIN user_identities ui ON ui.user_id = m.user_id AND ui.provider = ?
+      WHERE m.team_id = ? AND m.status = 'active' AND m.user_id IS NOT NULL
+      ORDER BY ui.subject`,
+    [DISCORD_PROVIDER, Number(teamId)],
+  )
+  return rows.map((row) => String(row.subject))
+}
+
+/** Every row for a platform, with the Team's name — the admin panel's listing. */
+async function listForPlatform(platform, resource) {
+  return query(
+    `SELECT ${COLUMNS}, t.name AS team_name, t.slug AS team_slug,
+            t.display_name_override, t.status AS team_status, t.hidden AS team_hidden,
+            t.member_count, t.linked_count
+       FROM team_integrations i
+       JOIN teams t ON t.id = i.team_id
+      WHERE i.platform = ? AND i.resource = ?
+      ORDER BY t.name`,
+    [platform, resource],
+  )
+}
+
+async function getForTeam(teamId, platform, resource) {
+  const rows = await query(
+    `SELECT ${COLUMNS} FROM team_integrations i
+      WHERE i.team_id = ? AND i.platform = ? AND i.resource = ? LIMIT 1`,
+    [Number(teamId), platform, resource],
+  )
+  return rows[0] || null
+}
+
+/**
+ * Write what the reconciler believes after a pass.
+ *
+ * A full upsert of the mutable columns rather than a patch, because every caller
+ * has just decided all of them together: a pass that created a channel knows the
+ * state, the refs, the error (none) and the stamp, and letting it write three of
+ * the four would leave the fourth describing a previous pass.
+ *
+ * `remove_after` is written explicitly on every call, `NULL` included — a Team
+ * that climbs back above the threshold inside its window has to have the window
+ * cleared, and an upsert that skipped NULLs would leave it armed.
+ */
+async function upsert({ teamId, platform, resource, externalRef, roleRef, state, removeAfter, lastError, syncedAt }) {
+  await query(
+    `INSERT INTO team_integrations
+       (team_id, platform, resource, external_ref, role_ref, state, remove_after, last_error, synced_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE
+       external_ref = VALUES(external_ref),
+       role_ref     = VALUES(role_ref),
+       state        = VALUES(state),
+       remove_after = VALUES(remove_after),
+       last_error   = VALUES(last_error),
+       synced_at    = VALUES(synced_at)`,
+    [
+      Number(teamId),
+      platform,
+      resource,
+      externalRef || null,
+      roleRef || null,
+      state,
+      removeAfter || null,
+      lastError ? String(lastError).slice(0, 500) : null,
+      syncedAt || null,
+    ],
+  )
+  return getForTeam(teamId, platform, resource)
+}
+
+async function remove(teamId, platform, resource) {
+  const res = await query(
+    'DELETE FROM team_integrations WHERE team_id = ? AND platform = ? AND resource = ?',
+    [Number(teamId), platform, resource],
+  )
+  return Number(res && res.affectedRows) || 0
+}
+
+/** How many rows currently hold a role — the input to the 250-role ceiling. */
+async function roleCount(platform) {
+  const rows = await query(
+    'SELECT COUNT(*) AS n FROM team_integrations WHERE platform = ? AND role_ref IS NOT NULL',
+    [platform],
+  )
+  return Number(rows[0] && rows[0].n) || 0
+}
+
+module.exports = {
+  DISCORD_PROVIDER,
+  desiredTeams,
+  holdersWithoutClaim,
+  discordSubjectsFor,
+  listForPlatform,
+  getForTeam,
+  upsert,
+  remove,
+  roleCount,
+}