feat(notifications): per-channel preferences and the delivery-channel registry (engagement Phase 3)

`notification_subscriptions` answers one question — which streams a user wants
PUSHED — because that is the only question the shipped Android client can ask.
This adds the general one: which subscribable ids, on which channel, in which
mode. The old table becomes the push projection of the new one and keeps its
exact wire shape, so the shipped APK needs no update and no delivery path is
touched.

What lands:

- `engagement/channels.js` — `registerDeliveryChannel` (ENGAGEMENT.md §3.1), the
  declarative half only: id, label, `carriesContent`, `defaultMode`,
  `supportsDigest`. `addressFor`/`render`/`deliver` wait for Phases 6 and 7, for
  the reason `transports/index.js` deferred this file at all. `coreChannels.js`
  declares push / email / inapp through the subsystem's one door.
- `notification_channel_prefs` + a replay-safe `INSERT IGNORE … SELECT` backfill,
  copying the `announce_jobs → announce_job_legs` precedent.
- `GET · PUT /auth/me/notifications/channels`. The PUT is SPARSE — only the
  `(id, channel)` pairs named are written — deliberately unlike the two whole-set
  PUTs beside it. `off` is a mode rather than an omission, so this endpoint has
  no empty-array case and the kotlinx DTO gotcha cannot arise here.

Three decisions the org lead settled before any code, and one corrects the
phase's own acceptance criterion: push's `defaultMode` is `off`, not `instant`.
The plan borrowed "push is opt-OUT" from `team_notification_prefs`, where no row
does mean notified — but stream subscriptions have never worked that way, so
`instant` would have projected the whole catalog into the legacy GET for every
existing user and switched every toggle on in the shipped app after an upgrade
nobody asked for. A test pins the legacy GET at `{streams:[]}` for a fresh user.

One thing not named by the phase, and it is a G24 consequence rather than scope
creep: a trigger ceilinged at `staff` can never reach a non-staff user, so
offering the toggle would be offering a dead control AND disclosing the event
exists — `uo.cheat.detected` would otherwise appear in every player's screen the
moment Phase 11 declared it. Filtered from the catalog and gated on write. That
gave the `staff` label its first consumer, now written down as
`ceilings.STAFF_CEILING_ROLES` (the admin tier's three, deliberately not
`teamGrants.STAFF_ROLES`, which answers a different question).

15 new tests; swagger, route manifest and guards regenerated. No web or app
surface — those are Phases 7 and 8, where a preference governs something visible.

Refs: docs/website/ENGAGEMENT.md Phase 3, §3.1, §4.5

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

server/src/app.js

@@ -192,6 +192,15 @@ app.use('/api', apiRouter)
 // module's collision checks are asked against what is ALREADY registered, so
 // core's streams, its announce leg and its extension-slot fill have to be there
 // before the first module registers anything (MODULE_SYSTEM.md §1.8).
+// The engagement subsystem's own door, which is what brings core's mail
+// transports and its three delivery channels into existence (ENGAGEMENT.md
+// §3.1). Requiring `engagement/channels` or `engagement/transports` directly gets
+// the empty registry — populating it is deliberately a side effect of this one
+// require, so there is exactly one place either can be registered from. It runs
+// beside registerCore() and before the loader for the same reason: a preference
+// read or a mail send must never find a half-populated registry.
+require('./engagement')
+
 registries.registerCore()
 modules.load({
   public: require('./router/v1/public'),

server/src/engagement/channels.js

@@ -0,0 +1,128 @@
+// ── The delivery-channel registry ──────────────────────────────────────────
+//
+// ENGAGEMENT.md §3.1, Phase 3. The other half of the axis `transports/index.js`
+// splits: a **channel** is what kind of sink this is (email, push, in-app), a
+// **transport** is how one channel actually delivers (SMTP, ntfy, FCM). Push has
+// had this shape since before anyone named it — `push_devices.transport` is a
+// transport column on a channel with one implementation.
+//
+// **Only the declarative half registers here today**, and that is the whole of
+// what Phase 3 needs. `addressFor` / `render` / `deliver` arrive with the phases
+// that can exercise them: email in Phase 6, in-app in Phase 7. Declaring a
+// function nothing calls freezes a signature before anything has tried to use
+// it, which is the reason `transports/index.js` deferred this file at all.
+//
+// What forced it into Phase 3 rather than Phase 6: `notification_channel_prefs`
+// stores a mode only when a user has expressed one, so reading a preference
+// means knowing the channel's default — and §3.1 says `defaultMode` is expressed
+// **once**. A constant list beside the prefs model would be that expression in a
+// second place two phases before the registry replaced it.
+//
+// Nothing here touches the database, the network or a user record.
+
+// id → channel definition, in registration order.
+const channels = new Map()
+
+// The three modes a preference can take. `digest` is only offered by a channel
+// that declares `supportsDigest` — push and in-app are instant-only in v1,
+// because a digest of content-free tickles is not a thing you can batch.
+const MODES = ['off', 'instant', 'digest']
+
+const isMode = (value) => MODES.includes(value)
+
+/**
+ * Register a delivery channel.
+ *
+ * Validate-then-commit, the same discipline `registerMailTransport` and
+ * `modules/registries.js` use: every check runs before the map is touched, so a
+ * rejected registration leaves nothing behind.
+ *
+ * @param {object} def
+ * @param {string}  def.id             'email' | 'push' | 'inapp' | later 'discord.dm'
+ * @param {string}  def.label          operator/user-facing name
+ * @param {boolean} def.carriesContent false for push — the tickle invariant, stated structurally
+ * @param {string}  def.defaultMode    the mode that applies with no stored row
+ * @param {boolean} def.supportsDigest may a preference for this channel be 'digest'
+ * @param {string}  [def.description]  one line for the preferences screen
+ */
+function registerDeliveryChannel(def) {
+  if (!def || typeof def !== 'object') throw new Error('registerDeliveryChannel: definition required')
+  const { id, label, carriesContent, defaultMode, supportsDigest } = def
+  if (typeof id !== 'string' || !/^[a-z][a-z0-9_.-]*$/.test(id)) {
+    throw new Error(`registerDeliveryChannel: invalid id ${JSON.stringify(id)}`)
+  }
+  if (channels.has(id)) throw new Error(`registerDeliveryChannel: ${id} is already registered`)
+  if (typeof label !== 'string' || !label) throw new Error(`registerDeliveryChannel(${id}): label required`)
+  if (typeof carriesContent !== 'boolean') {
+    throw new Error(`registerDeliveryChannel(${id}): carriesContent must be declared explicitly`)
+  }
+  if (!isMode(defaultMode)) {
+    throw new Error(`registerDeliveryChannel(${id}): defaultMode must be one of ${MODES.join(', ')}`)
+  }
+  if (typeof supportsDigest !== 'boolean') {
+    throw new Error(`registerDeliveryChannel(${id}): supportsDigest must be declared explicitly`)
+  }
+  // A channel that cannot batch cannot default to batching. Cheap to check, and
+  // the failure it prevents is a stored 'digest' row no delivery path can honour.
+  if (defaultMode === 'digest' && !supportsDigest) {
+    throw new Error(`registerDeliveryChannel(${id}): defaultMode 'digest' needs supportsDigest`)
+  }
+
+  channels.set(id, {
+    id,
+    label,
+    description: def.description || null,
+    carriesContent,
+    defaultMode,
+    supportsDigest,
+  })
+  return id
+}
+
+/** Every channel, in registration order. The preferences screen's column set. */
+const all = () => [...channels.values()].map((c) => ({ ...c }))
+
+/** Just the ids. */
+const ids = () => [...channels.keys()]
+
+/** One channel, or null. Callers must handle null: a stored pref row can name a
+ *  channel that is no longer registered, and that must read as "off", not throw. */
+const get = (id) => {
+  const c = channels.get(id)
+  return c ? { ...c } : null
+}
+
+const has = (id) => channels.has(id)
+
+/** The mode that applies when the user has expressed nothing. An unregistered
+ *  channel is 'off' — never on by accident. */
+const defaultMode = (id) => (channels.get(id) || {}).defaultMode || 'off'
+
+/** Which modes this channel will accept from a client. */
+const modesFor = (id) => {
+  const c = channels.get(id)
+  if (!c) return []
+  return c.supportsDigest ? MODES.slice() : MODES.filter((m) => m !== 'digest')
+}
+
+/** Is `mode` a mode this channel accepts? The gate on every preference write. */
+const acceptsMode = (id, mode) => modesFor(id).includes(mode)
+
+// Test-only: the registry is module-level state.
+function _reset() {
+  channels.clear()
+}
+
+module.exports = {
+  MODES,
+  isMode,
+  registerDeliveryChannel,
+  all,
+  ids,
+  get,
+  has,
+  defaultMode,
+  modesFor,
+  acceptsMode,
+  _reset,
+}

server/src/engagement/coreChannels.js

@@ -0,0 +1,74 @@
+// ── Core's own delivery channels ───────────────────────────────────────────
+//
+// ENGAGEMENT.md §3.1 / Phase 3. All three are core's, and none of them is a game
+// concept: a mailbox, a push endpoint and an inbox row are the same three things
+// on any shard running this platform.
+//
+// **They are declared here before two of them can deliver anything**, and that is
+// deliberate rather than premature. A preference is a durable user statement; the
+// three columns of the preferences screen have to exist from the moment the table
+// does, or the first person to open it after Phase 6 finds an email toggle that
+// has never had a value and a screen that changed shape under them. Registering
+// the metadata early costs nothing — the registry holds no behaviour yet — while
+// registering it late means back-filling opinions users were never asked for.
+//
+// The `defaultMode`s below are the whole of G9: "per-channel defaults differ and
+// there is nowhere to express that generically". This is that place.
+
+const { registerDeliveryChannel } = require('./channels')
+
+const CHANNELS = [
+  {
+    id: 'push',
+    label: 'Push',
+    description: 'A silent tickle to your phone; the app then pulls the real content.',
+    // The tickle invariant (docs/android/PLAN.md §11), stated structurally rather
+    // than as a comment: what leaves the server on this channel is { stream, ref }
+    // and never a message body. Phase 7's `deliver` reads this flag; declaring it
+    // false here is what makes "push must not carry content" a property of the
+    // registration instead of a rule each caller has to remember.
+    carriesContent: false,
+    // **Opt-IN, and this is the one place the phase's own acceptance line was
+    // wrong.** ENGAGEMENT.md Phase 3 said a fresh user's push defaults to
+    // 'instant'; §3.1 called push "opt-OUT", borrowing the semantics of
+    // `team_notification_prefs` (where no row does mean notified). But push
+    // STREAM subscriptions have never worked that way: `notification_subscriptions`
+    // holds a row only when a user opted in, so no row means not subscribed.
+    // Defaulting to 'instant' here would have projected the entire catalog into
+    // `GET /auth/me/notifications/subscriptions` for every existing user, and the
+    // shipped Android client would have shown every toggle switched on after an
+    // upgrade nobody asked for. Settled by the org lead 2026-08-29: 'off'.
+    defaultMode: 'off',
+    // A batched tickle is a contradiction — the content is not in the message, so
+    // there is nothing to roll up. Ten events are ten wakeups or one; either way
+    // the app pulls the same inbox.
+    supportsDigest: false,
+  },
+  {
+    id: 'email',
+    label: 'Email',
+    description: 'A message to your verified address.',
+    carriesContent: true,
+    // Opt-IN, per §7.1 Q1: standard marketing-email practice, and the posture
+    // `team_notification_prefs.email_mode` already takes ('off' by default).
+    defaultMode: 'off',
+    supportsDigest: true,
+  },
+  {
+    id: 'inapp',
+    label: 'On the site',
+    description: 'An item in your notification inbox on the website and in the app.',
+    carriesContent: true,
+    // Opt-IN like the other two, and for a reason particular to this channel: the
+    // inbox does not exist until Phase 7. A default of 'instant' would mean every
+    // user is opted into a surface that has no rows and no screen, and the first
+    // thing Phase 7 shipped would be a backlog. Whether the inbox is opt-out once
+    // it is real is a Phase 7 decision with a live surface to look at.
+    defaultMode: 'off',
+    supportsDigest: false,
+  },
+]
+
+for (const channel of CHANNELS) registerDeliveryChannel(channel)
+
+module.exports = { CHANNELS }

server/src/engagement/index.js

@@ -1,8 +1,11 @@
 // ── The engagement subsystem — one door ────────────────────────────────────
 //
-// ENGAGEMENT.md Phase 1. Today this is the mail transport registry and core's
-// own transports; the trigger registry, the rules engine and the delivery
-// channels arrive in later phases and hang here too.
+// ENGAGEMENT.md Phases 1 and 3. Today this is the mail transport registry, core's
+// own transports, and the delivery-channel registry with core's three channels;
+// the rules engine and the render/deliver half of a channel arrive in later
+// phases and hang here too. (The trigger registry lives in `modules/registries.js`
+// instead, because a trigger is something a MODULE declares and modules only ever
+// see one registration door.)
 //
 // **Core's transports register through the same door a module's would**, and
 // they register HERE rather than at the bottom of the registry file. That keeps
@@ -11,12 +14,14 @@
 // `modules/registries.js` (MODULE_API.md §7.6) — and it means requiring the
 // registry never has the side effect of populating it.
 //
-// Requiring this module is what makes `smtp` available. Everything that resolves
-// a transport goes through here, so there is exactly one place a transport can
-// come into existence.
+// Requiring this module is what makes `smtp` and the three channels available.
+// Everything that resolves either goes through here, so there is exactly one
+// place a transport or a channel can come into existence.
 
 require('./transports/smtp')
+require('./coreChannels')
 
 const transports = require('./transports')
+const channels = require('./channels')
 
-module.exports = { transports }
+module.exports = { transports, channels }

server/src/engagement/transports/index.js

@@ -2,9 +2,12 @@
 //
 // ENGAGEMENT.md §3.1, Phase 1. A **channel** is what kind of sink this is (email,
 // push, in-app); a **transport** is how one channel actually delivers. This file
-// is the second half only. The channel registry arrives with the engine that
-// consumes it — registering a channel nothing calls would be a shape frozen
-// before anything had tried to use it.
+// is the second half only; the channel half is `../channels.js`, which Phase 3
+// added when `notification_channel_prefs` needed a single place for `defaultMode`
+// to live. Its render/deliver functions are still deferred to the phases that can
+// exercise them, for the reason this comment used to give about the whole file:
+// registering a function nothing calls freezes a signature before anything has
+// tried to use it.
 //
 // What this replaces: `mailer.buildTransport()` had Gmail's host, port and
 // OAuth2 auth type as literals, so "which provider" was a code edit. Now the

server/src/model/notificationChannelPrefs/notificationChannelPrefs.db.js

@@ -0,0 +1,44 @@
+const { query } = require('../../utils/db')
+
+const listByUser = (userId) =>
+  query(
+    'SELECT stream_id, channel, mode FROM notification_channel_prefs WHERE user_id = ? ORDER BY stream_id, channel',
+    [userId],
+  )
+
+// One (user, stream, channel) row. Upsert rather than insert-or-update in app
+// code: the primary key is exactly the triple, so MariaDB decides, and two
+// concurrent PUTs from a phone and a browser cannot race into a duplicate-key
+// error.
+const upsert = (userId, streamId, channel, mode) =>
+  query(
+    `INSERT INTO notification_channel_prefs (user_id, stream_id, channel, mode)
+     VALUES (?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE mode = VALUES(mode)`,
+    [userId, streamId, channel, mode],
+  )
+
+// Every push row this user holds that is NOT in `keep`, set to 'off'. The legacy
+// whole-set PUT's other half: it says "these streams and no others", and the
+// rows it is silent about have to stop meaning 'instant'.
+//
+// It sets rather than deletes, so a user's explicit "no" survives a later change
+// to push's `defaultMode` (§3.1 / channels.js). Deleting would fold "I turned
+// this off" back into "I never said", and those are the same thing only for as
+// long as the default happens to be 'off'.
+async function offPushExcept(userId, keep) {
+  if (!keep.length) {
+    return query(
+      "UPDATE notification_channel_prefs SET mode = 'off' WHERE user_id = ? AND channel = 'push' AND mode <> 'off'",
+      [userId],
+    )
+  }
+  const marks = keep.map(() => '?').join(', ')
+  return query(
+    `UPDATE notification_channel_prefs SET mode = 'off'
+      WHERE user_id = ? AND channel = 'push' AND mode <> 'off' AND stream_id NOT IN (${marks})`,
+    [userId, ...keep],
+  )
+}
+
+module.exports = { listByUser, upsert, offPushExcept }

server/src/model/notificationSubs/notificationSubs.db.js

@@ -13,4 +13,20 @@ async function replaceForUser(userId, streams) {
   }
 }
 
-module.exports = { listByUser, replaceForUser }
+// ── The single-row pair (ENGAGEMENT.md Phase 3) ────────────────────────────
+//
+// `notification_channel_prefs` is a SPARSE write — one (id, channel) pair at a
+// time — and this table is its push projection, so it needs the same granularity.
+// `replaceForUser` above cannot express "turn this one stream on and leave the
+// rest alone" without the caller first reading the whole set back, which is a
+// read-modify-write race between a phone and a browser saving at once.
+//
+// INSERT IGNORE / DELETE against the (user_id, stream_id) primary key, so both
+// are idempotent and neither needs to know the current state.
+const addForUser = (userId, streamId) =>
+  query('INSERT IGNORE INTO notification_subscriptions (user_id, stream_id) VALUES (?, ?)', [userId, streamId])
+
+const removeForUser = (userId, streamId) =>
+  query('DELETE FROM notification_subscriptions WHERE user_id = ? AND stream_id = ?', [userId, streamId])
+
+module.exports = { listByUser, replaceForUser, addForUser, removeForUser }

server/src/model/notificationSubs/notificationSubs.model.js

@@ -2,6 +2,15 @@
 // applied to every device they register). The catalog is core's plus every
 // installed module's, so it is read back through modules/registries rather than
 // from a config file (MODULE_SYSTEM.md §1.8).
+//
+// **This is now the push PROJECTION of `notification_channel_prefs`**
+// (ENGAGEMENT.md Phase 3), and it keeps its exact wire shape on purpose: the
+// shipped Android client's DTO is `{ streams: [...] }` and cannot be changed from
+// this side. So the general table gained the channel dimension and this one stays
+// the answer to "which streams does this user want pushed" — the only question
+// that client knows how to ask. Every write here fans out to there; every write
+// there that touches push fans out to here. What `utils/pushDispatch` reads did
+// not change at all, which is what makes this phase touch no delivery path.
 
 const db = require('./notificationSubs.db')
 const { isValidStream } = require('../../modules/registries')
@@ -11,9 +20,16 @@ const getForUser = async (userId) => (await db.listByUser(userId)).map((r) => r.
 // Replace the user's subscription set. Ignores unknown ids and de-dupes, so a
 // stale client can't create rows for streams that no longer exist. Returns the
 // stored (cleaned) set.
+//
+// The mirror is required lazily rather than at the top of the file: the channel
+// prefs model requires the registries and the channel registry, and this module
+// is required by the router at boot. A cycle here would be a silent half-loaded
+// module rather than an error, and there is nothing to gain from the eager form.
 async function setForUser(userId, streams) {
   const clean = [...new Set((Array.isArray(streams) ? streams : []).filter(isValidStream))]
   await db.replaceForUser(userId, clean)
+  // eslint-disable-next-line global-require
+  await require('../notificationChannelPrefs/notificationChannelPrefs.model').mirrorPushSet(userId, clean)
   return clean
 }
 

server/src/modules/ceilings.js

@@ -54,6 +54,21 @@ const LABELS = {
   owner: 'Only the user the event is about',
 }
 
+// Which roles the `staff` ceiling actually names. The label above has always
+// claimed "admin / editor / moderator"; Phase 3 gave that claim a consumer, so it
+// is written down once rather than re-derived at each call site.
+//
+// It matches the admin TIER gate — `requireRole('admin','editor','moderator')` in
+// `router/v1/admin/index.js`, and `public.controller`'s own STAFF_ROLES — and NOT
+// `teamGrants.STAFF_ROLES`, which is `['admin','moderator']`. The two are
+// genuinely different questions: teamGrants asks who may act on a Team they are
+// not a member of, and an editor deliberately may not. A ceiling asks who may be
+// TOLD, which is the tier gate's population.
+const STAFF_CEILING_ROLES = ['admin', 'editor', 'moderator']
+
+/** Does this user fall inside the `staff` ceiling? */
+const isStaffRole = (role) => STAFF_CEILING_ROLES.includes(role)
+
 const CEILINGS = Object.keys(PARENT)
 
 /** Is this one of the six? The gate every registration and every rule save runs. */
@@ -104,4 +119,4 @@ function meetAll(list) {
   return list.reduce((acc, next) => (acc === null ? null : meet(acc, next)), list[0])
 }
 
-module.exports = { CEILINGS, LABELS, isCeiling, permits, meet, meetAll }
+module.exports = { CEILINGS, LABELS, STAFF_CEILING_ROLES, isStaffRole, isCeiling, permits, meet, meetAll }

server/src/router/v1/auth/notifications.controller.js

@@ -5,6 +5,7 @@
 
 const pushDevices = require('../../../model/pushDevices/pushDevices.model')
 const notificationSubs = require('../../../model/notificationSubs/notificationSubs.model')
+const channelPrefs = require('../../../model/notificationChannelPrefs/notificationChannelPrefs.model')
 const registries = require('../../../modules/registries')
 const teamPrefs = require('../../../model/teams/teamNotify.model')
 const { isAllowedEndpoint } = require('../../../utils/pushDispatch')
@@ -79,6 +80,39 @@ async function putSubscriptions(req, res) {
   }
 }
 
+// GET /auth/me/notifications/channels — the per-channel preferences surface
+// (ENGAGEMENT.md Phase 3): the channel registry's declarative half, plus one item
+// per subscribable id with its EFFECTIVE mode on each channel that applies.
+//
+// The superset of `/notifications/streams` + `/notifications/subscriptions`,
+// which stay exactly as they are for the shipped app.
+async function getChannelPrefs(req, res) {
+  try {
+    return res.json(await channelPrefs.getForUser(req.user.id, req.user))
+  } catch (err) {
+    log.error('getChannelPrefs', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// PUT /auth/me/notifications/channels — apply a SPARSE set of preferences.
+//
+// Only the (id, channel) pairs in the body are written; every other pair is left
+// alone, so a screen that manages one channel need not know about the others. Off
+// is a mode, not an omission — which is also why this endpoint has no
+// empty-array case to get wrong, unlike its two neighbours. Entries naming an
+// unknown id, an inapplicable channel or a mode that channel does not accept are
+// dropped by the model; the full stored state is echoed back so the caller can
+// see what actually took.
+async function putChannelPrefs(req, res) {
+  try {
+    return res.json(await channelPrefs.applyForUser(req.user.id, req.body.prefs, req.user))
+  } catch (err) {
+    log.error('putChannelPrefs', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
 // GET /auth/me/notifications/teams — this user's per-Team preferences, one row
 // per Team they could be notified about whether or not they have ever set one.
 //
@@ -119,6 +153,8 @@ module.exports = {
   getStreams,
   getSubscriptions,
   putSubscriptions,
+  getChannelPrefs,
+  putChannelPrefs,
   getTeamPrefs,
   putTeamPrefs,
 }

server/src/router/v1/auth/notifications.routes.js

@@ -14,6 +14,7 @@ const { requireAuth } = require('../../../auth/session.middleware')
 const noindex = require('../../../middleware/noindex')
 const validate = require('../../../middleware/validate')
 const { EMAIL_MODES } = require('../../../model/teams/teamNotify.model')
+const { MODES } = require('../../../engagement/channels')
 
 const notifRouter = express.Router()
 
@@ -98,6 +99,44 @@ notifRouter.put(
   notif.putSubscriptions,
 )
 
+// ── Per-channel preferences (ENGAGEMENT.md §4.5, phase 3) ──────────────────
+//
+// The channel dimension `notification_subscriptions` lacks. The two endpoints
+// above are unchanged and become the push projection of these — the shipped app
+// keeps its wire shape, and a newer client manages email and in-app through here.
+//
+// The PUT is SPARSE, deliberately unlike the two whole-set PUTs either side of
+// it: only the pairs named are written. `off` is a mode rather than an omission,
+// so there is no "clearing the last entry" case and no empty-array DTO gotcha.
+notifRouter.get(
+  '/notifications/channels',
+  // #swagger.tags = ['Auth · Me']
+  // #swagger.summary = 'Get the current user’s per-channel notification preferences'
+  // #swagger.description = 'The delivery channels (email, push, in-app) with their defaults, plus one item per subscribable id — every push stream and every event trigger, one namespace — carrying the effective mode on each channel that applies to it. A trigger-only id has no push toggle. Modes not stored are reported as the channel’s default, so a client never has to know which it is looking at.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Per-channel preferences', content: { "application/json": { schema: { $ref: "#/components/schemas/NotificationChannelPrefs" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  notif.getChannelPrefs,
+)
+
+notifRouter.put(
+  '/notifications/channels',
+  // #swagger.tags = ['Auth · Me']
+  // #swagger.summary = 'Update the current user’s per-channel notification preferences'
+  // #swagger.description = 'A SPARSE update: only the (id, channel) pairs in `prefs` are written and every other pair is left untouched, so setting `email` does not disturb `push`. Entries naming an unknown id, a channel that does not apply to that id, or a mode that channel does not accept are ignored. A `push` entry is mirrored into /notifications/subscriptions. The full stored state is echoed back.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/NotificationChannelPrefsUpdate" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated preferences', content: { "application/json": { schema: { $ref: "#/components/schemas/NotificationChannelPrefs" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  body('prefs').isArray(),
+  body('prefs.*.id').isString().isLength({ min: 1, max: 64 }),
+  body('prefs.*.channel').isString().isLength({ min: 1, max: 32 }),
+  body('prefs.*.mode').isIn(MODES),
+  validate,
+  notif.putChannelPrefs,
+)
+
 // ── Per-Team preferences (TEAMS.md §6.3, phase 6) ──────────────────────────
 //
 // The granularity per-stream opt-in cannot express: "I am in five Teams and want