@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/gateway/dispatch-table.ts

@@ -0,0 +1,383 @@
+/**
+ * Gateway dispatch table: One entry per known dispatch type with its decoder, cache effects and projection.
+ * Invariant: An entry delivers nothing unless its decoder accepts the whole body, and cache effects always run before
+ * subscriber delivery. Unknown types are counted and ignored, never treated as protocol failures.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { EventMap, EventName } from "#sdk/events"
+import type { MessageCore } from "#sdk/messages"
+import type { MessageDecoder } from "../message-fields.js"
+import { decodeDeletion, decodeBulkDeletion } from "../message.js"
+import { identifier, record } from "../decode/primitives.js"
+import { decodeUser, decodeDirectMessage } from "../users.js"
+import { decodeReaction, reactionEvents } from "../reactions.js"
+import { decodePinsUpdate } from "../pins.js"
+import {
+    decodeGuildEvent,
+    decodeGuildLifecycleEvent,
+    decodeVoiceState,
+    decodeVoiceStateSnapshot,
+    guildEvents,
+    guildLifecycleEvents,
+} from "../guilds.js"
+import { decodeChannelEvent, channelEvents, decodeThread } from "../channel-decode.js"
+import {
+    decodeOwnThreadMemberUpdate,
+    decodeThreadCreate,
+    decodeThreadDeletion,
+    decodeThreadListSync,
+    decodeThreadMembersUpdate,
+} from "../thread-events.js"
+import { decodeExpressionUpdate } from "../expressions.js"
+import { decodeInviteDelete, decodeInviteMetadata } from "../invites.js"
+import { decodeAuditLogEntry } from "../audit-logs.js"
+import { decodePresenceUpdate, decodePresenceUpdateBulk, type PresenceGatewayOwner } from "../presence.js"
+import type { CountGatewayOwner } from "../counts.js"
+import type { MemberChunkOwner } from "../member-chunks.js"
+import { decodeCallCreate, decodeCallDelete, decodeCallUpdate, decodeEntranceSoundPlay } from "../calls.js"
+
+/** Decoder result for a well-formed dispatch the SDK deliberately does not deliver */
+const ignored: unique symbol = Symbol("ignored dispatch")
+
+/** Values a dispatch decoder depends on besides the body */
+export interface DispatchContext {
+    readonly messageDecoder: MessageDecoder<MessageCore>
+    /** Invite URL base from instance discovery */
+    readonly inviteBase: string
+}
+
+/** Where decoded dispatches go. Every sink is optional except subscriber delivery */
+export interface DispatchSinks {
+    /** Deliver a decoded event to the client's intake, which updates caches before subscribers see it */
+    readonly emit: <K extends EventName>(event: K, value: EventMap<MessageCore>[K]) => void
+    /** Guild and channel cache intake over the raw body. Present only when a resource cache is enabled */
+    readonly guildCache?: ((type: string, body: unknown) => void) | undefined
+    readonly presence?: Pick<PresenceGatewayOwner, "guildCreate"> | undefined
+    readonly counts?: Pick<CountGatewayOwner, "receiveGuildCounts" | "receiveChannelMemberCounts"> | undefined
+    readonly memberChunks?: Pick<MemberChunkOwner, "receive" | "rateLimited"> | undefined
+    /** Received byte length of the whole frame, charged against subscriber and member-chunk budgets */
+    readonly bytes: number
+}
+
+/** One dispatch type's handling */
+interface DispatchEntry<V> {
+    /** Cache intake that validates the raw body itself and runs before this entry's decoder */
+    readonly rawCache?: (body: unknown, sinks: DispatchSinks, type: string) => void
+    /** Validate and convert the body. A result of undefined marks it malformed, and ignored marks a valid body that is not delivered */
+    readonly decode: (body: unknown, context: DispatchContext, type: string) => V | undefined | typeof ignored
+    /** Cache intake that runs after successful decoding and before projection */
+    readonly cache?: (value: V, body: unknown, sinks: DispatchSinks, type: string) => void
+    /** Deliver the decoded value */
+    readonly project: (value: V, sinks: DispatchSinks, type: string) => void
+}
+
+const entry = <V>(value: DispatchEntry<V>) => value as DispatchEntry<unknown>
+
+/** Hand the raw body to an owner that validates it itself, including an absent body */
+const passThrough = (body: unknown) => ({ body })
+
+const guildCache = (body: unknown, sinks: DispatchSinks, type: string) => sinks.guildCache?.(type, body)
+
+/** GUILD_CREATE carries an optional voice-state snapshot that is delivered after the guild itself */
+interface GuildCreateDispatch {
+    readonly guild: EventMap["guildCreate"]
+    readonly voice: ReturnType<typeof decodeVoiceStateSnapshot>
+}
+
+function decodeTypingStart(value: unknown): EventMap["typingStart"] | undefined {
+    if (
+        !record(value) ||
+        !identifier(value.channel_id) ||
+        !identifier(value.user_id) ||
+        typeof value.timestamp !== "number" ||
+        !Number.isSafeInteger(value.timestamp) ||
+        value.timestamp < 0 ||
+        (value.guild_id !== undefined && value.guild_id !== null && !identifier(value.guild_id))
+    )
+        return undefined
+    return Object.freeze({
+        channelId: value.channel_id,
+        userId: value.user_id,
+        timestamp: value.timestamp,
+        ...(typeof value.guild_id === "string" ? { guildId: value.guild_id } : {}),
+    })
+}
+
+function decodeRecipientChange(value: unknown) {
+    if (!record(value) || !identifier(value.channel_id) || !record(value.user) || !identifier(value.user.id))
+        return undefined
+    return Object.freeze({ channelId: value.channel_id, userId: value.user.id })
+}
+
+function decodeGuildHealthUpdate(value: unknown): EventMap["guildHealthUpdate"] | undefined {
+    if (!record(value) || !identifier(value.guild_id) || typeof value.degraded !== "boolean") return undefined
+    return Object.freeze({ guildId: value.guild_id, degraded: value.degraded })
+}
+
+function decodeWebhooksUpdate(value: unknown) {
+    if (!record(value) || !identifier(value.guild_id) || !identifier(value.channel_id)) return undefined
+    return Object.freeze({ guildId: value.guild_id, channelId: value.channel_id })
+}
+
+function decodeAuditLogEntryCreate(value: unknown): EventMap["guildAuditLogEntryCreate"] | undefined {
+    const audit = decodeAuditLogEntry(value)
+    if (
+        !audit ||
+        !record(value) ||
+        !identifier(value.guild_id) ||
+        !identifier(value.user_id) ||
+        (value.target_id !== null && typeof value.target_id !== "string")
+    )
+        return undefined
+    return Object.freeze({ ...audit, guildId: value.guild_id, userId: value.user_id, targetId: value.target_id })
+}
+
+/** Private conversations share the channel dispatch names, distinguished by an absent or null guild ID */
+type ChannelDispatch =
+    | { readonly kind: "directDelete"; readonly id: string }
+    | { readonly kind: "direct"; readonly channel: NonNullable<ReturnType<typeof decodeDirectMessage>> }
+    | { readonly kind: "guild"; readonly event: keyof typeof channelEvents; readonly value: unknown }
+
+function decodeChannelDispatch(body: unknown, type: string): ChannelDispatch | undefined | typeof ignored {
+    const event = type as keyof typeof channelEvents
+    if (record(body) && (body.guild_id === undefined || body.guild_id === null)) {
+        // Type 999 is a private conversation kind this SDK version does not project
+        if (body.type === 999) return ignored
+        if (type === "CHANNEL_DELETE" && identifier(body.id)) return { kind: "directDelete", id: body.id }
+        const channel = decodeDirectMessage(body)
+        return channel ? { kind: "direct", channel } : undefined
+    }
+    const value = decodeChannelEvent(event, body)
+    return value ? { kind: "guild", event, value } : undefined
+}
+
+const entries: Record<string, DispatchEntry<unknown>> = {
+    // Correlated request replies are validated by their owners, which match them to pending requests
+    GUILD_MEMBERS_CHUNK: entry({
+        decode: passThrough,
+        project: ({ body }, sinks) => sinks.memberChunks?.receive(body, sinks.bytes),
+    }),
+    RATE_LIMITED: entry({
+        decode: passThrough,
+        project: ({ body }, sinks) => sinks.memberChunks?.rateLimited(body),
+    }),
+    GUILD_COUNTS_UPDATE: entry({
+        decode: passThrough,
+        project: ({ body }, sinks) => sinks.counts?.receiveGuildCounts(body),
+    }),
+    CHANNEL_MEMBER_COUNTS_UPDATE: entry({
+        decode: passThrough,
+        project: ({ body }, sinks) => sinks.counts?.receiveChannelMemberCounts(body),
+    }),
+    USER_UPDATE: entry({
+        decode: (body) => decodeUser(body),
+        project: (user, sinks) => sinks.emit("userUpdate", user),
+    }),
+    GUILD_CREATE: entry<GuildCreateDispatch>({
+        decode: (body) => {
+            // GUILD_CREATE decodes to the snapshot form with its new-join flag
+            const guild = decodeGuildLifecycleEvent("GUILD_CREATE", body) as EventMap["guildCreate"] | undefined
+            if (!guild) return undefined
+            if (!record(body) || !Object.hasOwn(body, "voice_states")) return { guild, voice: undefined }
+            const voice = decodeVoiceStateSnapshot(body)
+            return voice ? { guild, voice } : undefined
+        },
+        cache: (_value, body, sinks, type) => guildCache(body, sinks, type),
+        project: ({ guild, voice }, sinks) => {
+            sinks.emit("guildCreate", guild)
+            sinks.presence?.guildCreate(guild.id)
+            if (voice) sinks.emit("voiceStateSnapshot", voice)
+        },
+    }),
+    ...Object.fromEntries(
+        (["GUILD_UPDATE", "GUILD_DELETE"] as const).map((type) => [
+            type,
+            entry({
+                rawCache: guildCache,
+                decode: (body) => decodeGuildLifecycleEvent(type, body),
+                project: (update, sinks) => sinks.emit(guildLifecycleEvents[type], update),
+            }),
+        ]),
+    ),
+    GUILD_HEALTH_UPDATE: entry({
+        decode: decodeGuildHealthUpdate,
+        project: (health, sinks) => sinks.emit("guildHealthUpdate", health),
+    }),
+    VOICE_STATE_UPDATE: entry({
+        // Private calls use the same dispatch name with an explicit null guild ID
+        decode: (body) => (record(body) && body.guild_id === null ? ignored : decodeVoiceState(body)),
+        project: (voiceState, sinks) => sinks.emit("voiceStateUpdate", voiceState),
+    }),
+    // Private calls and entrance sounds are notices only and never write a cache
+    CALL_CREATE: entry({
+        decode: decodeCallCreate,
+        project: (call, sinks) => sinks.emit("callCreate", call),
+    }),
+    CALL_UPDATE: entry({
+        decode: decodeCallUpdate,
+        project: (call, sinks) => sinks.emit("callUpdate", call),
+    }),
+    CALL_DELETE: entry({
+        decode: decodeCallDelete,
+        project: (call, sinks) => sinks.emit("callDelete", call),
+    }),
+    ENTRANCE_SOUND_PLAY: entry({
+        decode: decodeEntranceSoundPlay,
+        project: (sound, sinks) => sinks.emit("entranceSoundPlay", sound),
+    }),
+    PRESENCE_UPDATE: entry({
+        decode: (body) => decodePresenceUpdate(body),
+        project: (presence, sinks) => sinks.emit("presenceUpdate", presence),
+    }),
+    PRESENCE_UPDATE_BULK: entry({
+        decode: (body) => decodePresenceUpdateBulk(body),
+        project: (presences, sinks) => sinks.emit("presenceUpdateBulk", presences),
+    }),
+    GUILD_EMOJIS_UPDATE: entry({
+        rawCache: guildCache,
+        decode: (body) => decodeExpressionUpdate("emojis", body),
+        project: (update, sinks) => sinks.emit("guildEmojisUpdate", update),
+    }),
+    GUILD_STICKERS_UPDATE: entry({
+        rawCache: guildCache,
+        decode: (body) => decodeExpressionUpdate("stickers", body),
+        project: (update, sinks) => sinks.emit("guildStickersUpdate", update),
+    }),
+    CHANNEL_RECIPIENT_ADD: entry({
+        decode: decodeRecipientChange,
+        project: (change, sinks) => sinks.emit("directMessageRecipientAdd", change),
+    }),
+    CHANNEL_RECIPIENT_REMOVE: entry({
+        decode: decodeRecipientChange,
+        project: (change, sinks) => sinks.emit("directMessageRecipientRemove", change),
+    }),
+    WEBHOOKS_UPDATE: entry({
+        decode: decodeWebhooksUpdate,
+        project: (update, sinks) => sinks.emit("webhooksUpdate", update),
+    }),
+    INVITE_CREATE: entry({
+        decode: (body, context) => decodeInviteMetadata(body, context.inviteBase),
+        project: (invite, sinks) => sinks.emit("inviteCreate", invite),
+    }),
+    INVITE_DELETE: entry({
+        decode: (body) => decodeInviteDelete(body),
+        project: (invite, sinks) => sinks.emit("inviteDelete", invite),
+    }),
+    THREAD_CREATE: entry({
+        decode: decodeThreadCreate,
+        project: (thread, sinks) => sinks.emit("threadCreate", thread),
+    }),
+    THREAD_UPDATE: entry({
+        decode: (body) => decodeThread(body),
+        project: (thread, sinks) => sinks.emit("threadUpdate", thread),
+    }),
+    THREAD_DELETE: entry({
+        decode: decodeThreadDeletion,
+        project: (deletion, sinks) => sinks.emit("threadDelete", deletion),
+    }),
+    THREAD_LIST_SYNC: entry({
+        decode: decodeThreadListSync,
+        project: (sync, sinks) => sinks.emit("threadListSync", sync),
+    }),
+    THREAD_MEMBERS_UPDATE: entry({
+        decode: decodeThreadMembersUpdate,
+        project: (update, sinks) => sinks.emit("threadMembersUpdate", update),
+    }),
+    // The bot's own thread membership changed. No public event carries it, so only the channel cache reads it
+    THREAD_MEMBER_UPDATE: entry({
+        decode: decodeOwnThreadMemberUpdate,
+        cache: (_value, body, sinks, type) => guildCache(body, sinks, type),
+        project: () => undefined,
+    }),
+    GUILD_AUDIT_LOG_ENTRY_CREATE: entry({
+        decode: decodeAuditLogEntryCreate,
+        project: (audit, sinks) => sinks.emit("guildAuditLogEntryCreate", audit),
+    }),
+    MESSAGE_CREATE: entry({
+        decode: (body, context) => context.messageDecoder(body),
+        project: (message, sinks) => sinks.emit("messageCreate", message),
+    }),
+    MESSAGE_UPDATE: entry({
+        decode: (body, context) => context.messageDecoder(body),
+        project: (message, sinks) => sinks.emit("messageUpdate", message),
+    }),
+    TYPING_START: entry({
+        decode: decodeTypingStart,
+        project: (typing, sinks) => sinks.emit("typingStart", typing),
+    }),
+    ...Object.fromEntries(
+        (Object.keys(guildEvents) as (keyof typeof guildEvents)[]).map((type) => [
+            type,
+            entry({
+                decode: (body) => decodeGuildEvent(type, body),
+                project: (update, sinks) => sinks.emit(guildEvents[type], update as never),
+            }),
+        ]),
+    ),
+    ...Object.fromEntries(
+        Object.keys(channelEvents).map((type) => [
+            type,
+            entry<ChannelDispatch>({
+                decode: (body, _context, type) => decodeChannelDispatch(body, type),
+                project: (value, sinks, type) => {
+                    if (value.kind === "directDelete")
+                        sinks.emit("directMessageDelete", Object.freeze({ id: value.id }))
+                    else if (value.kind === "direct")
+                        sinks.emit(
+                            type === "CHANNEL_CREATE" ? "directMessageCreate" : "directMessageUpdate",
+                            value.channel,
+                        )
+                    else sinks.emit(channelEvents[value.event], value.value as never)
+                },
+            }),
+        ]),
+    ),
+    CHANNEL_PINS_UPDATE: entry({
+        decode: (body) => decodePinsUpdate(body),
+        project: (update, sinks) => sinks.emit("channelPinsUpdate", update),
+    }),
+    MESSAGE_DELETE: entry({
+        decode: (body) => decodeDeletion(body),
+        project: (deletion, sinks) => sinks.emit("messageDelete", deletion),
+    }),
+    MESSAGE_DELETE_BULK: entry({
+        decode: (body) => decodeBulkDeletion(body),
+        project: (deletion, sinks) => sinks.emit("messageDeleteBulk", deletion),
+    }),
+    ...Object.fromEntries(
+        (Object.keys(reactionEvents) as (keyof typeof reactionEvents)[]).map((type) => [
+            type,
+            entry({
+                decode: (body) => decodeReaction(type, body),
+                project: (reaction, sinks) => sinks.emit(reactionEvents[type], reaction as never),
+            }),
+        ]),
+    ),
+}
+
+/** Dispatch types the SDK knows. READY and RESUMED are session control, handled before this table */
+const dispatchTable: Readonly<Record<string, DispatchEntry<unknown>>> = Object.freeze(entries)
+
+/** Result of routing one dispatch through the table */
+export type DispatchResult =
+    | { readonly kind: "delivered" | "ignored" | "unknown" }
+    /** The body failed its decoder. The decode step re-runs it on a copy to locate the failing field */
+    | { readonly kind: "malformed"; readonly decode: (body: unknown) => unknown }
+
+/** Decode, apply cache effects and project one dispatch in that order */
+export function routeDispatch(
+    type: string,
+    body: unknown,
+    context: DispatchContext,
+    sinks: DispatchSinks,
+): DispatchResult {
+    if (!Object.hasOwn(dispatchTable, type)) return { kind: "unknown" }
+    const handler = dispatchTable[type]!
+    handler.rawCache?.(body, sinks, type)
+    const value = handler.decode(body, context, type)
+    if (value === ignored) return { kind: "ignored" }
+    if (value === undefined) return { kind: "malformed", decode: (copy) => handler.decode(copy, context, type) }
+    handler.cache?.(value, body, sinks, type)
+    handler.project(value, sinks, type)
+    return { kind: "delivered" }
+}

package/src/internal/gateway/event-dispatches.ts

@@ -0,0 +1,201 @@
+/**
+ * Event filtering for Identify: Which dispatch types deliver each public event, which types SDK-owned state needs, and
+ * the ignored_events list the SDK sends for explicit and automatic filtering.
+ * Invariant: Automatic filtering never suppresses a dispatch that a registered event, an enabled cache category,
+ * presence member selection, reaction pages, READY or RESUMED needs, and suppresses nothing while a raw subscriber exists. Types
+ * without an entry here, such as correlated request replies and types this SDK version does not know, are never
+ * suppressed automatically.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { EventName } from "#sdk/events"
+
+/**
+ * Dispatch types that can deliver each public event, keyed by event name.
+ * Several events share one dispatch type, such as GUILD_CREATE for guildCreate and voiceStateSnapshot, so a type is
+ * suppressed only when none of its events is needed. The map is typed by string so it compiles while event additions
+ * land separately. The event-filter test checks it against the event bus names
+ */
+const eventDispatchMap = {
+    userUpdate: ["USER_UPDATE"],
+    directMessageCreate: ["CHANNEL_CREATE"],
+    directMessageUpdate: ["CHANNEL_UPDATE"],
+    directMessageDelete: ["CHANNEL_DELETE"],
+    directMessageRecipientAdd: ["CHANNEL_RECIPIENT_ADD"],
+    directMessageRecipientRemove: ["CHANNEL_RECIPIENT_REMOVE"],
+    guildCreate: ["GUILD_CREATE"],
+    guildUpdate: ["GUILD_UPDATE"],
+    guildDelete: ["GUILD_DELETE"],
+    guildHealthUpdate: ["GUILD_HEALTH_UPDATE"],
+    webhooksUpdate: ["WEBHOOKS_UPDATE"],
+    inviteCreate: ["INVITE_CREATE"],
+    inviteDelete: ["INVITE_DELETE"],
+    guildAuditLogEntryCreate: ["GUILD_AUDIT_LOG_ENTRY_CREATE"],
+    guildEmojisUpdate: ["GUILD_EMOJIS_UPDATE"],
+    guildStickersUpdate: ["GUILD_STICKERS_UPDATE"],
+    guildChannelCreate: ["CHANNEL_CREATE"],
+    guildChannelUpdate: ["CHANNEL_UPDATE"],
+    guildChannelDelete: ["CHANNEL_DELETE"],
+    guildChannelUpdateBulk: ["CHANNEL_UPDATE_BULK"],
+    threadCreate: ["THREAD_CREATE"],
+    threadUpdate: ["THREAD_UPDATE"],
+    threadDelete: ["THREAD_DELETE"],
+    threadListSync: ["THREAD_LIST_SYNC"],
+    threadMembersUpdate: ["THREAD_MEMBERS_UPDATE"],
+    channelPinsUpdate: ["CHANNEL_PINS_UPDATE"],
+    guildMemberAdd: ["GUILD_MEMBER_ADD"],
+    guildMemberUpdate: ["GUILD_MEMBER_UPDATE"],
+    guildMemberRemove: ["GUILD_MEMBER_REMOVE"],
+    presenceUpdate: ["PRESENCE_UPDATE"],
+    presenceUpdateBulk: ["PRESENCE_UPDATE_BULK"],
+    voiceStateSnapshot: ["GUILD_CREATE"],
+    voiceStateUpdate: ["VOICE_STATE_UPDATE"],
+    guildBanAdd: ["GUILD_BAN_ADD"],
+    guildBanRemove: ["GUILD_BAN_REMOVE"],
+    guildRoleDelete: ["GUILD_ROLE_DELETE"],
+    guildRoleCreate: ["GUILD_ROLE_CREATE"],
+    guildRoleUpdate: ["GUILD_ROLE_UPDATE"],
+    guildRoleUpdateBulk: ["GUILD_ROLE_UPDATE_BULK"],
+    typingStart: ["TYPING_START"],
+    messageCreate: ["MESSAGE_CREATE"],
+    messageUpdate: ["MESSAGE_UPDATE"],
+    messageDelete: ["MESSAGE_DELETE"],
+    messageDeleteBulk: ["MESSAGE_DELETE_BULK"],
+    messageReactionAdd: ["MESSAGE_REACTION_ADD"],
+    // Fluxer filters ADD before buffering it, then generates MANY without filtering its name. Filtering follows ADD
+    // (session_dispatch and session_dispatch_voice at fluxerapp/fluxer commit 841fb7af4174fc8fc025307776e87e7dba51a669)
+    messageReactionAddMany: ["MESSAGE_REACTION_ADD"],
+    messageReactionRemove: ["MESSAGE_REACTION_REMOVE"],
+    messageReactionRemoveAll: ["MESSAGE_REACTION_REMOVE_ALL"],
+    messageReactionRemoveEmoji: ["MESSAGE_REACTION_REMOVE_EMOJI"],
+    entranceSoundPlay: ["ENTRANCE_SOUND_PLAY"],
+    callCreate: ["CALL_CREATE"],
+    callUpdate: ["CALL_UPDATE"],
+    callDelete: ["CALL_DELETE"],
+} as const satisfies Readonly<Record<string, readonly string[]>>
+
+/** Event names with a mapping, for the completeness check against the public event names */
+export type MappedEvent = keyof typeof eventDispatchMap
+
+export const eventDispatchTypes: Readonly<Record<string, readonly string[]>> = Object.freeze(eventDispatchMap)
+
+/** Every dispatch type that automatic filtering may suppress, in a stable order */
+const filterableTypes: readonly string[] = Object.freeze([...new Set(Object.values(eventDispatchTypes).flat())].sort())
+
+/**
+ * Dispatch types SDK-owned state needs whatever the application registers.
+ * GUILD_CREATE replays presence member selections for guilds that become available, and GUILD_DELETE clears every
+ * cache category for a removed or unavailable guild. Both arrive about once per guild per session
+ */
+const alwaysNeeded: readonly string[] = ["GUILD_CREATE", "GUILD_DELETE"]
+
+/**
+ * Dispatch types reaction pages read for clicks. Pages can start after Identify from any handler, through
+ * ctx.paginate, a multi-page ctx.sendHelp or messages.paginate, so automatic filtering keeps them in every session
+ */
+const reactionPageNeeds: readonly string[] = ["MESSAGE_REACTION_ADD", "MESSAGE_REACTION_REMOVE"]
+
+/**
+ * Dispatch types SDK-internal owners always need. Suppressing them would stop session control, member requests or
+ * count requests, so an explicit list naming them fails creation
+ */
+export const protectedDispatchTypes: ReadonlySet<string> = new Set([
+    "READY",
+    "RESUMED",
+    "GUILD_MEMBERS_CHUNK",
+    "RATE_LIMITED",
+    "GUILD_COUNTS_UPDATE",
+    "CHANNEL_MEMBER_COUNTS_UPDATE",
+])
+
+/** Cache categories that consume gateway dispatches, as configured at creation */
+export type FilterCacheKind =
+    "messages" | "guilds" | "members" | "roles" | "channels" | "users" | "directMessages" | "emojis" | "stickers"
+
+/** Dispatch types each enabled cache category reads to stay consistent with Fluxer */
+const cacheDispatchTypes: Readonly<Record<FilterCacheKind, readonly string[]>> = Object.freeze({
+    // THREAD_DELETE removes a deleted thread's messages, and CHANNEL_DELETE those of a channel and of its threads
+    messages: [
+        "MESSAGE_CREATE",
+        "MESSAGE_UPDATE",
+        "MESSAGE_DELETE",
+        "MESSAGE_DELETE_BULK",
+        "CHANNEL_DELETE",
+        "THREAD_DELETE",
+    ],
+    guilds: ["GUILD_UPDATE"],
+    members: [
+        "GUILD_MEMBER_ADD",
+        "GUILD_MEMBER_UPDATE",
+        "GUILD_MEMBER_REMOVE",
+        "GUILD_BAN_ADD",
+        "GUILD_BAN_REMOVE",
+        "GUILD_ROLE_DELETE",
+    ],
+    roles: ["GUILD_ROLE_CREATE", "GUILD_ROLE_UPDATE", "GUILD_ROLE_UPDATE_BULK", "GUILD_ROLE_DELETE"],
+    // The channel cache also holds threads. THREAD_MEMBER_UPDATE has no public event, so it is never filtered
+    // automatically, and listing it here keeps an explicit ignored list from dropping it
+    channels: [
+        "CHANNEL_CREATE",
+        "CHANNEL_UPDATE",
+        "CHANNEL_DELETE",
+        "CHANNEL_UPDATE_BULK",
+        "THREAD_CREATE",
+        "THREAD_UPDATE",
+        "THREAD_DELETE",
+        "THREAD_LIST_SYNC",
+        "THREAD_MEMBERS_UPDATE",
+        "THREAD_MEMBER_UPDATE",
+    ],
+    users: ["USER_UPDATE", "GUILD_MEMBER_UPDATE"],
+    directMessages: [
+        "CHANNEL_CREATE",
+        "CHANNEL_UPDATE",
+        "CHANNEL_DELETE",
+        "CHANNEL_RECIPIENT_ADD",
+        "CHANNEL_RECIPIENT_REMOVE",
+        "USER_UPDATE",
+        "GUILD_MEMBER_UPDATE",
+    ],
+    emojis: ["GUILD_EMOJIS_UPDATE"],
+    stickers: ["GUILD_STICKERS_UPDATE"],
+})
+
+/**
+ * Dispatch types the enabled cache categories need to avoid keeping stale snapshots, fixed at creation.
+ * Every category with guild-scoped entries also needs GUILD_DELETE, which clears a removed or unavailable guild's entries
+ */
+export function cacheNeeds(kinds: readonly FilterCacheKind[]): ReadonlySet<string> {
+    const guildScoped = kinds.some((kind) => kind !== "users" && kind !== "directMessages")
+    return new Set([...(guildScoped ? ["GUILD_DELETE"] : []), ...kinds.flatMap((kind) => cacheDispatchTypes[kind])])
+}
+
+/** Dispatch types automatic filtering keeps whatever the application registers */
+export function automaticNeeds(kinds: readonly FilterCacheKind[]): ReadonlySet<string> {
+    return new Set([...alwaysNeeded, ...reactionPageNeeds, ...cacheNeeds(kinds)])
+}
+
+/**
+ * The automatic ignored_events list for one Identify: Every filterable type that no registered event, cache category or
+ * SDK owner needs. A raw subscriber needs every type, so the list is then empty
+ */
+export function automaticIgnoredEvents(
+    registered: ReadonlySet<EventName>,
+    needed: ReadonlySet<string>,
+): readonly string[] {
+    if (registered.has("raw")) return []
+    const wanted = new Set(needed)
+    for (const event of registered) for (const type of eventDispatchTypes[event] ?? []) wanted.add(type)
+    return Object.freeze(filterableTypes.filter((type) => !wanted.has(type)))
+}
+
+/** Registered events whose every dispatch type an explicit ignored list suppresses */
+export function suppressedRegistrations(
+    registered: ReadonlySet<EventName>,
+    ignored: ReadonlySet<string>,
+): readonly string[] {
+    if (ignored.size === 0) return []
+    return [...registered].filter((event) => {
+        const types = eventDispatchTypes[event]
+        return types !== undefined && types.length > 0 && types.every((type) => ignored.has(type))
+    })
+}