Gateway Cache Sync Keeper

Skill: gateway-cache-sync-keeper

Use this skill when work touches:

• src/Discord/WebSockets/Handlers.php
• src/Discord/WebSockets/Event.php
• src/Discord/WebSockets/Events/*

This is event-to-cache coherence skill. Load it when changing gateway dispatch behavior, event return shapes, or cache mutation.

Goal

Keep gateway handling as real-time state sync layer:

• dispatch payloads become typed parts
• related repositories get updated immediately
• emitted event payloads stay semantically useful
• caches for users, members, channels, messages, threads, guilds stay coherent

Read in this order

1. src/Discord/WebSockets/Event.php
2. src/Discord/WebSockets/Handlers.php
3. Matching part/repository families
4. Representative events:
   • src/Discord/WebSockets/Events/MessageCreate.php
   • src/Discord/WebSockets/Events/MessageUpdate.php
   • src/Discord/WebSockets/Events/GuildCreate.php
   • src/Discord/WebSockets/Events/GuildDelete.php
   • src/Discord/WebSockets/Events/InteractionCreate.php
   • src/Discord/WebSockets/Events/ThreadListSync.php
   • src/Discord/WebSockets/Events/GuildMemberAdd.php

Core contract

Event classes in this repo are not dumb payload forwarders. They:

• interpret transport payloads
• instantiate correct typed parts, often via runtime TYPES maps
• update owning repositories and related caches
• warm user/member caches from nested payloads
• preserve secondary invariants like counters or last_message_id
• return semantic values used by userland listeners

If handler only hydrates one object and ignores related caches, change is probably incomplete.

Three files usually move together

When adding or changing event family, inspect all three:

1. src/Discord/WebSockets/Event.php — constant
2. src/Discord/WebSockets/Handlers.php — registration
3. src/Discord/WebSockets/Events/<Name>.php — implementation

If one changes and the others do not, make sure that is intentional.

Event base helpers to use

cacheUser(object $userdata)

Use when payload contains user data. Keeps top-level user cache current.

cacheMember(MemberRepository $members, array $memberdata)

Use when payload contains guild member data. Keeps guild member cache current. Some event families override details for performance reasons, like InteractionCreate.

Do not manually duplicate user/member cache update logic unless event family has special latency or shape constraints.

Hydration rules

Prefer typed parts immediately

Use factory plus subtype maps when payload family is polymorphic:

• channels from Channel::TYPES
• interactions from Interaction::TYPES
• components from component TYPES

Do not push raw stdClass payloads deep into caches when repo already has typed part model.

Create vs update vs delete semantics matter

• create events usually instantiate new parts and set them into owning repo
• update events often clone old cached part, mutate current part, and return both new and old values
• delete events often pull from cache and return removed typed part plus extra status

Preserve those shapes unless you have strong compatibility reason to change them.

Coherence rules by family

Message events

These are easy to break because they carry many side effects:

• store or update message in channel/thread repo when configured
• keep last_message_id current
• handle message-content intent limits correctly
• update author/mention/interacting user caches
• preserve old/new payload behavior on update

If you change MessageCreate or MessageUpdate, inspect:

• message cache behavior
• intent-gated content handling
• DM vs guild channel routing
• thread message counting or parent lookup logic

Guild create/delete/update families

Guild events often do bulk cache work:

• guild create populates guild repo plus member, user, voice state, thread, stage instance, scheduled event, sound caches
• guild delete must preserve unavailable-vs-removed semantics

Do not treat guild create as "just one guild part". It is bootstrap event for several nested repositories.

Thread events

Threads are child collections hanging off parent channels. Thread handlers usually must:

• locate parent channel
• update parent threads repo
• possibly update thread member state
• preserve thread counters or metadata

Interaction events

Interaction handlers are latency-sensitive. They still must:

• hydrate correct interaction subtype
• cache resolved users/members
• avoid unnecessarily slow cache paths
• invoke registered command handlers/autocomplete flow

Event return-shape rules

Userland listens to emitted values. Keep return shapes stable and meaningful.

Common patterns already used:

• MessageCreate returns new Message
• MessageUpdate returns [newOrData, oldMessage]
• GuildDelete returns [$guildPartOrData, $unavailableFlag]

Before changing a return shape, inspect:

• existing event listeners in examples/tests/docs
• parity with sibling events in same family
• whether old state is required for consumers