@hogsend/engine 0.21.1 → 0.23.0

package/src/lib/contacts.ts

@@ -100,6 +100,7 @@ export function contactSearchFilter(search: string) {
     ilike(contacts.email, `%${search}%`),
     ilike(contacts.externalId, `%${search}%`),
     ilike(contacts.anonymousId, `%${search}%`),
+    ilike(contacts.discordId, `%${search}%`),
   );
 }
 
@@ -115,7 +116,7 @@ export function normalizeEmail(raw: string): string {
 // Identity resolution
 // ---------------------------------------------------------------------------
 
-type Kind = "external" | "email" | "anonymous";
+type Kind = "external" | "email" | "anonymous" | "discord";
 
 interface ResolveKey {
   kind: Kind;
@@ -137,7 +138,9 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
       ? contacts.externalId
       : key.kind === "email"
         ? contacts.email
-        : contacts.anonymousId;
+        : key.kind === "anonymous"
+          ? contacts.anonymousId
+          : contacts.discordId;
 
   const direct = await tx
     .select()
@@ -187,6 +190,18 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
   return null;
 }
 
+/**
+ * Top-level property keys whose object value is DEEP-merged (one level) rather
+ * than wholly replaced. The §2.1 shallow `||` contract clobbers a top-level key
+ * outright, so a nested metadata object (e.g. the Discord connector's
+ * `properties.discord`) would lose every field the current event doesn't carry
+ * (a reaction knows `last_seen` but not `username`, so it would erase a
+ * previously-captured `username`). Listing the key here makes ONLY that key
+ * additive — siblings stay strictly shallow, preserving the documented contract
+ * for everything else. NON-KEY metadata only; never an identity-resolution key.
+ */
+const DEEP_MERGE_KEYS = ["discord"] as const;
+
 /**
  * Merge `patch` onto the existing jsonb properties (§2.1 contract): additive
  * `COALESCE(existing,'{}') || patch` where the patch wins on key conflict AND an
@@ -197,9 +212,56 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
  * Caveat: `jsonb_strip_nulls` also strips any PRE-EXISTING null-valued keys on
  * the contact, which is the intended "null === unset" model (the condition
  * engine already treats JSON null and absent identically).
+ *
+ * EXCEPTION — keys in {@link DEEP_MERGE_KEYS} that carry an object value are
+ * merged ONE level deep: `existing.discord || patch.discord` instead of the
+ * top-level `||` replacing `discord` wholesale. Postgres has no recursive `||`,
+ * so we build the deep-merged sub-object explicitly and overlay it last. A
+ * non-object value for such a key (or an absent one) falls through to the normal
+ * shallow merge untouched.
  */
 function mergePropertiesSql(patch: Record<string, unknown>) {
-  return sql`jsonb_strip_nulls(COALESCE(${contacts.properties}, '{}'::jsonb) || ${JSON.stringify(patch)}::jsonb)`;
+  let merged = sql`COALESCE(${contacts.properties}, '{}'::jsonb) || ${JSON.stringify(patch)}::jsonb`;
+  for (const key of DEEP_MERGE_KEYS) {
+    const sub = patch[key];
+    if (sub && typeof sub === "object" && !Array.isArray(sub)) {
+      // existing[key] (already an object or absent) || patch[key] — the prior
+      // sub-object's fields survive any field the current patch omits.
+      // `${key}` is cast to ::text: jsonb_build_object is VARIADIC "any" and `->`
+      // is overloaded (text key vs int index), so an untyped bound parameter
+      // can't have its type inferred ("could not determine data type of $n").
+      merged = sql`${merged} || jsonb_build_object(${key}::text, COALESCE(${contacts.properties} -> ${key}::text, '{}'::jsonb) || ${JSON.stringify(sub)}::jsonb)`;
+    }
+  }
+  return sql`jsonb_strip_nulls(${merged})`;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return Boolean(v) && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * Spread-merge one `layer` onto the accumulated `acc` (incoming wins per key),
+ * the in-memory analogue of {@link mergePropertiesSql}'s deep-merge exception
+ * for the collide-MERGE fold (which folds properties via JS spread, not SQL).
+ * For each {@link DEEP_MERGE_KEYS} key that is an object on BOTH `acc` and the
+ * incoming `layer`, the sub-objects are themselves shallow-merged (incoming
+ * wins per sub-key) so the layer can't clobber fields the accumulator already
+ * holds — must read the PRE-spread `acc` value, hence a fresh result object.
+ */
+function foldLayer(
+  acc: Record<string, unknown>,
+  layer: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...acc, ...layer };
+  for (const key of DEEP_MERGE_KEYS) {
+    const a = acc[key];
+    const b = layer[key];
+    if (isPlainObject(a) && isPlainObject(b)) {
+      out[key] = { ...a, ...b };
+    }
+  }
+  return out;
 }
 
 /**
@@ -277,6 +339,7 @@ export async function resolveOrCreateContact(opts: {
   userId?: string;
   email?: string;
   anonymousId?: string;
+  discordId?: string;
   contactProperties?: Record<string, unknown>;
 }): Promise<{
   id: string;
@@ -290,20 +353,40 @@ export async function resolveOrCreateContact(opts: {
   created: boolean;
   linked: boolean;
   merged: boolean;
+  /**
+   * SAFE-to-absorb loser keys (§5.3 MF-2): the anonymous/uuid keys the resolver
+   * folded INTO `resolvedKey` this call — populated only on a collide-MERGE or a
+   * canonical-key flip that absorbed an anon/uuid key. Callers fan these out via
+   * `mergeAnalyticsIdentities({ distinctId: resolvedKey, alias: <key> })`. An
+   * `external_id` is NEVER listed here (it carried an identified PostHog person;
+   * aliasing it is the merge PostHog refuses — R2/R4); it surfaces in
+   * {@link mergedIdentifiedKeys} instead. Empty/absent ⇒ nothing to stitch.
+   */
+  mergedKeys?: string[];
+  /**
+   * Loser keys MF-2 could NOT safely absorb — already-identified `external_id`s
+   * (and the superseded `external_id` on a key flip). These are the known
+   * steady-state twin residual (§10, OQ-1); callers log them as
+   * `identity.merge.residual_twin` for observability. Never aliased.
+   */
+  mergedIdentifiedKeys?: string[];
 }> {
   const { db, contactProperties } = opts;
   const userId = opts.userId?.trim() || undefined;
   const email = opts.email ? normalizeEmail(opts.email) : undefined;
   const anonymousId = opts.anonymousId?.trim() || undefined;
+  const discordId = opts.discordId?.trim() || undefined;
 
   const keys: ResolveKey[] = [];
   if (userId) keys.push({ kind: "external", value: userId });
   if (email) keys.push({ kind: "email", value: email });
   if (anonymousId) keys.push({ kind: "anonymous", value: anonymousId });
+  if (discordId) keys.push({ kind: "discord", value: discordId });
 
   if (keys.length === 0) {
     throw new Error(
-      "resolveOrCreateContact requires at least one of userId, email, anonymousId",
+      "resolveOrCreateContact requires at least one of userId, email, " +
+        "anonymousId, discordId",
     );
   }
 
@@ -338,6 +421,7 @@ export async function resolveOrCreateContact(opts: {
           externalId: userId ?? null,
           email: email ?? null,
           anonymousId: anonymousId ?? null,
+          discordId: discordId ?? null,
           // §2.1: explicit null clears a key — never persist a null-valued prop.
           properties: stripNulls(patch),
         })
@@ -356,25 +440,45 @@ export async function resolveOrCreateContact(opts: {
     // --- CASE: fill-in-link (single existing row) ---
     const single = candidates[0];
     if (candidates.length === 1 && single) {
-      const { id, resolvedKey } = await fillInLink(tx, single, {
+      const { id, resolvedKey, mergedKeys, mergedIdentifiedKeys } =
+        await fillInLink(tx, single, {
+          userId,
+          email,
+          anonymousId,
+          discordId,
+          patch,
+          hasPatch,
+        });
+      return {
+        id,
+        resolvedKey,
+        created: false,
+        linked: true,
+        merged: false,
+        mergedKeys,
+        mergedIdentifiedKeys,
+      };
+    }
+
+    // --- CASE: collide-MERGE (2-3 distinct rows) ---
+    const { id, resolvedKey, mergedKeys, mergedIdentifiedKeys } =
+      await mergeContacts(tx, candidates, {
         userId,
         email,
         anonymousId,
+        discordId,
         patch,
         hasPatch,
       });
-      return { id, resolvedKey, created: false, linked: true, merged: false };
-    }
-
-    // --- CASE: collide-MERGE (2-3 distinct rows) ---
-    const { id, resolvedKey } = await mergeContacts(tx, candidates, {
-      userId,
-      email,
-      anonymousId,
-      patch,
-      hasPatch,
-    });
-    return { id, resolvedKey, created: false, linked: true, merged: true };
+    return {
+      id,
+      resolvedKey,
+      created: false,
+      linked: true,
+      merged: true,
+      mergedKeys,
+      mergedIdentifiedKeys,
+    };
   });
 }
 
@@ -382,6 +486,7 @@ interface ResolveCtx {
   userId?: string;
   email?: string;
   anonymousId?: string;
+  discordId?: string;
   patch: Record<string, unknown>;
   hasPatch: boolean;
 }
@@ -395,7 +500,12 @@ async function fillInLink(
   tx: Tx,
   row: ContactRow,
   ctx: ResolveCtx,
-): Promise<{ id: string; resolvedKey: string }> {
+): Promise<{
+  id: string;
+  resolvedKey: string;
+  mergedKeys?: string[];
+  mergedIdentifiedKeys?: string[];
+}> {
   const set: Record<string, unknown> = {
     lastSeenAt: new Date(),
     updatedAt: new Date(),
@@ -420,6 +530,14 @@ async function fillInLink(
     set.email = ctx.email;
     promoted.push({ kind: "email", value: ctx.email });
   }
+  // discord_id is an attachable resolvable key but NEVER the canonical key
+  // (external_id ?? anonymous_id ?? id), so it does NOT touch
+  // nextExternalId/nextAnonymousId — gaining it never flips the canonical key,
+  // so no own-history re-point follows.
+  if (ctx.discordId && !row.discordId) {
+    set.discordId = ctx.discordId;
+    promoted.push({ kind: "discord", value: ctx.discordId });
+  }
   if (ctx.anonymousId && !row.anonymousId) {
     set.anonymousId = ctx.anonymousId;
     nextAnonymousId = ctx.anonymousId;
@@ -435,6 +553,15 @@ async function fillInLink(
   // updated row (with its new email/keys) is what foldJourneyStates/email_sends
   // denormalize into.
   const newKey = nextExternalId ?? nextAnonymousId ?? row.id;
+  // §5.3 emission point 2 (canonical-key flip): when the key flips, the OLD key
+  // is folded into the NEW one. MF-3 gate — only emit a merge when `oldKey` was
+  // an anonymous/uuid key (never an `external_id` being superseded; that is the
+  // twin case, OQ-1). In practice a flip in fillInLink only fires when the row
+  // had NO external_id (attaching one never happens to an already-external row),
+  // so `oldKey` is structurally always anon/uuid here — the explicit gate guards
+  // the invariant regardless.
+  let mergedKeys: string[] | undefined;
+  let mergedIdentifiedKeys: string[] | undefined;
   if (newKey !== oldKey) {
     const updatedRow: ContactRow = {
       ...row,
@@ -443,6 +570,14 @@ async function fillInLink(
       email: (set.email as string | undefined) ?? row.email,
     };
     await repointOwnHistory(tx, oldKey, newKey, updatedRow);
+
+    const oldKeyWasExternalId =
+      row.externalId != null && oldKey === row.externalId;
+    if (oldKeyWasExternalId) {
+      mergedIdentifiedKeys = [oldKey];
+    } else {
+      mergedKeys = [oldKey];
+    }
   }
 
   for (const key of promoted) {
@@ -462,7 +597,7 @@ async function fillInLink(
 
   // `newKey` IS the post-fill canonical key (external_id ?? anonymous_id ?? id) —
   // the same value the old read-back derived.
-  return { id: row.id, resolvedKey: newKey };
+  return { id: row.id, resolvedKey: newKey, mergedKeys, mergedIdentifiedKeys };
 }
 
 /**
@@ -473,10 +608,22 @@ async function mergeContacts(
   tx: Tx,
   candidates: ContactRow[],
   ctx: ResolveCtx,
-): Promise<{ id: string; resolvedKey: string }> {
+): Promise<{
+  id: string;
+  resolvedKey: string;
+  mergedKeys?: string[];
+  mergedIdentifiedKeys?: string[];
+}> {
   const { survivor, losers } = pickSurvivor(candidates);
   const survivorKey = contactKey(survivor);
 
+  // §5.3 emission point 1 (collide-MERGE) accumulators. MF-2: a loser's
+  // anonymous/uuid key is SAFE to absorb (it never identified a PostHog person);
+  // a loser's `external_id` is an already-identified person PostHog refuses to
+  // merge on the safe path — it is recorded as the twin residual, NEVER aliased.
+  const safeLoserKeys: string[] = [];
+  const identifiedLoserKeys: string[] = [];
+
   for (const loser of losers) {
     const loserStrKeys = [loser.externalId, loser.anonymousId, loser.id].filter(
       (k): k is string => Boolean(k),
@@ -485,6 +632,19 @@ async function mergeContacts(
     // anonymous id (its user_id rows were keyed on contacts.id).
     const loserKeysToRewrite = loserStrKeys;
 
+    // MF-2 split: the SAFE-to-absorb key is the loser's anonymous/uuid key —
+    // `loser.anonymousId`, or `loser.id` ONLY when the loser was never
+    // identified (no external_id). When the loser HAS an external_id, that
+    // external_id was its canonical key, so its events were captured under it
+    // (identified) → residual; `loser.id` never carried events in that case, so
+    // there is no safe key to alias from it.
+    if (loser.externalId) {
+      identifiedLoserKeys.push(loser.externalId);
+      if (loser.anonymousId) safeLoserKeys.push(loser.anonymousId);
+    } else {
+      safeLoserKeys.push(loser.anonymousId ?? loser.id);
+    }
+
     // (ii) user_events.user_id rewrite.
     await tx
       .update(userEvents)
@@ -518,14 +678,23 @@ async function mergeContacts(
   }
 
   // (vii) FOLD properties: survivor wins over losers; then the call's patch wins
-  // last. timezone = survivor ?? loser; firstSeenAt = least.
+  // last. timezone = survivor ?? loser; firstSeenAt = least. DEEP_MERGE_KEYS
+  // (e.g. `discord`) are sub-object-merged at each fold layer (foldLayer) so a
+  // loser/survivor/patch that carries only a subset of the nested object's
+  // fields doesn't clobber the rest — matching mergePropertiesSql's exception.
   let foldedProps: Record<string, unknown> = {};
   for (const loser of losers) {
-    foldedProps = { ...foldedProps, ...((loser.properties ?? {}) as object) };
+    foldedProps = foldLayer(
+      foldedProps,
+      (loser.properties ?? {}) as Record<string, unknown>,
+    );
   }
-  foldedProps = { ...foldedProps, ...((survivor.properties ?? {}) as object) };
+  foldedProps = foldLayer(
+    foldedProps,
+    (survivor.properties ?? {}) as Record<string, unknown>,
+  );
   if (ctx.hasPatch) {
-    foldedProps = { ...foldedProps, ...ctx.patch };
+    foldedProps = foldLayer(foldedProps, ctx.patch);
   }
   // §2.1: an explicit null in the call's patch clears a key — drop null-valued
   // keys from the folded result (matching mergePropertiesSql's strip-nulls).
@@ -562,6 +731,16 @@ async function mergeContacts(
     const next = ctx.anonymousId ?? fromLoser;
     if (next) survivorSet.anonymousId = next;
   }
+  // discord_id lands on the survivor (from the call or a loser), but it is
+  // NEVER the canonical key — so it is intentionally NOT folded into
+  // newSurvivorKey below and a discord-only merge does no history re-point. The
+  // losers are soft-deleted FIRST (below) so the partial-unique discord_id index
+  // is freed before this copy.
+  if (!survivor.discordId) {
+    const fromLoser = losers.find((l) => l.discordId)?.discordId;
+    const next = ctx.discordId ?? fromLoser;
+    if (next) survivorSet.discordId = next;
+  }
 
   // (viii) Soft-delete the losers FIRST — frees their external_id/email/
   // anonymous_id from the partial-unique indexes (WHERE deleted_at IS NULL) —
@@ -606,8 +785,16 @@ async function mergeContacts(
   }
 
   // `newSurvivorKey` IS the post-merge canonical key of the survivor — the same
-  // value the old read-back derived for the merged row.
-  return { id: survivor.id, resolvedKey: newSurvivorKey };
+  // value the old read-back derived for the merged row. The merge folds every
+  // loser key into it, so callers fan out `mergeAnalyticsIdentities` aliasing
+  // each SAFE loser key into `newSurvivorKey` (§5.3 emission point 1).
+  return {
+    id: survivor.id,
+    resolvedKey: newSurvivorKey,
+    mergedKeys: safeLoserKeys.length > 0 ? safeLoserKeys : undefined,
+    mergedIdentifiedKeys:
+      identifiedLoserKeys.length > 0 ? identifiedLoserKeys : undefined,
+  };
 }
 
 /**
@@ -953,6 +1140,20 @@ async function recordMergeAliases(
       reason: "merge",
     });
   }
+  // discord_id is a resolvable key, so a stale loser snowflake must still
+  // resolve to the survivor after the soft-delete takes the loser out of
+  // findByKey's direct lookup. Additive — it never conflicts with the
+  // external/anonymous id-fallback alias below (a discord-only loser produces
+  // BOTH this discord alias AND the id→external alias).
+  if (loser.discordId) {
+    aliasRows.push({
+      contactId: survivorId,
+      aliasKind: "discord",
+      aliasValue: loser.discordId,
+      fromContactId: loser.id,
+      reason: "merge",
+    });
+  }
   // When the loser had neither external_id nor anonymous_id, its CANONICAL key
   // (`external_id ?? anonymous_id ?? id`) was its row id — and that key has
   // circulated (Hatchet payloads, outbound `userId`s, `hs_t` tokens). Alias it
@@ -1002,6 +1203,7 @@ export async function upsertContact(opts: {
   externalId?: string;
   email?: string;
   anonymousId?: string;
+  discordId?: string;
   properties?: Record<string, unknown>;
 }): Promise<{
   id: string;
@@ -1009,12 +1211,17 @@ export async function upsertContact(opts: {
   created: boolean;
   linked: boolean;
   merged: boolean;
+  /** §5.3 MF-2: safe-to-absorb loser keys folded this call (anon/uuid). */
+  mergedKeys?: string[];
+  /** §5.3 MF-2: already-identified loser keys (twin residual); never aliased. */
+  mergedIdentifiedKeys?: string[];
 }> {
   return resolveOrCreateContact({
     db: opts.db,
     userId: opts.externalId,
     email: opts.email,
     anonymousId: opts.anonymousId,
+    discordId: opts.discordId,
     contactProperties: opts.properties,
   });
 }

package/src/lib/discord-gateway-heartbeat.ts

@@ -0,0 +1,164 @@
+import type { Logger } from "./logger.js";
+import { getRedis } from "./redis.js";
+
+/**
+ * Discord Gateway worker liveness heartbeat. The gateway worker is its OWN
+ * long-lived process (a `discord.js` socket forwarding raw dispatches), separate
+ * from BOTH the API and the Hatchet worker — so the API (and Studio's
+ * `/integrations` card) cannot otherwise tell whether the gateway socket is
+ * actually up. The worker writes a TTL'd key to Redis on an interval; readers
+ * treat a fresh key as "the gateway worker is alive".
+ *
+ * This mirrors {@link ./worker-heartbeat.ts} but on a DISTINCT key and with a
+ * richer JSON payload: it also carries the guild id the live worker observed at
+ * `GUILD_CREATE`, which lets the card confirm "Bot installed" for env-only
+ * deploys (no derived credential) — a fresh heartbeat with a guild id IS the
+ * proof-of-configuration the status fix needs.
+ *
+ * Redis is the channel because both processes can already reach it and the
+ * health route already probes it — no direct process-to-process coupling, no
+ * migration. Everything here is best-effort: a missing/unreachable Redis never
+ * crashes the worker and simply reads back as "down".
+ */
+const HEARTBEAT_KEY = "hogsend:discord-gateway:heartbeat";
+const TTL_SECONDS = 30;
+const REFRESH_MS = 10_000;
+
+export interface DiscordGatewayHeartbeat {
+  /** True when a fresh gateway-worker heartbeat is present in Redis. */
+  alive: boolean;
+  /** ISO timestamp the gateway worker last wrote, when alive. */
+  lastSeenAt?: string;
+  /** The guild id the live worker observed (confirms the bot is in a server). */
+  guildId?: string;
+  /** The intents bitfield the live worker requested at login. */
+  intents?: number;
+}
+
+/** The JSON shape persisted under {@link HEARTBEAT_KEY}. */
+interface HeartbeatPayload {
+  lastSeenAt: string;
+  guildId?: string;
+  intents?: number;
+}
+
+/** The mutable state a running heartbeat exposes for late-bound folding. */
+export interface DiscordGatewayHeartbeatState {
+  /**
+   * Fold the worker-observed guild id into the heartbeat and write immediately,
+   * so Studio can confirm "Bot installed" as soon as the socket sees a guild.
+   */
+  setGuildId(guildId: string): void;
+  /**
+   * Fold the worker's resolved intents bitfield into the heartbeat and write
+   * immediately, so Studio's intents chip reflects what the LIVE worker requested
+   * (preferred over the derived credential, which is never written by install).
+   */
+  setIntents(intents: number): void;
+}
+
+export interface DiscordGatewayHeartbeatHandle {
+  /** Mutable state — call `setGuildId` from the worker's `onGuildObserved` tap. */
+  state: DiscordGatewayHeartbeatState;
+  /** Clear the timer and delete the key for an immediate "down" on shutdown. */
+  stop(): Promise<void>;
+}
+
+/**
+ * Begin writing the Discord gateway-worker heartbeat. Writes once immediately,
+ * then refreshes every {@link REFRESH_MS} with a {@link TTL_SECONDS} expiry — so
+ * an ungraceful worker death is reflected as "down" within the TTL. The returned
+ * handle exposes `state.setGuildId(id)` (fold in the observed guild + write now)
+ * and `stop()` (clear the timer + delete the key for an immediate "down").
+ */
+export function startDiscordGatewayHeartbeat(
+  logger: Logger,
+): DiscordGatewayHeartbeatHandle {
+  let warned = false;
+  let guildId: string | undefined;
+  let intents: number | undefined;
+
+  const write = async () => {
+    const payload: HeartbeatPayload = {
+      lastSeenAt: new Date().toISOString(),
+      ...(guildId ? { guildId } : {}),
+      ...(typeof intents === "number" ? { intents } : {}),
+    };
+    try {
+      await getRedis().set(
+        HEARTBEAT_KEY,
+        JSON.stringify(payload),
+        "EX",
+        TTL_SECONDS,
+      );
+    } catch (err) {
+      // Log the first failure only — a Redis-less deploy would otherwise spam.
+      if (!warned) {
+        warned = true;
+        logger.debug(
+          "Discord gateway heartbeat write failed (Redis unreachable?)",
+          { error: err instanceof Error ? err.message : String(err) },
+        );
+      }
+    }
+  };
+
+  void write();
+  const timer = setInterval(() => void write(), REFRESH_MS);
+  // Never hold the process open for the heartbeat alone.
+  timer.unref?.();
+
+  return {
+    state: {
+      setGuildId(id: string) {
+        guildId = id;
+        // Write immediately so the card flips to "Bot installed" without waiting
+        // for the next refresh tick.
+        void write();
+      },
+      setIntents(value: number) {
+        intents = value;
+        // Write immediately so the intents chip reflects the live worker without
+        // waiting for the next refresh tick.
+        void write();
+      },
+    },
+    async stop() {
+      clearInterval(timer);
+      try {
+        await getRedis().del(HEARTBEAT_KEY);
+      } catch {
+        // Best-effort — the TTL expires it anyway.
+      }
+    },
+  };
+}
+
+/**
+ * Read the current Discord gateway-worker heartbeat. Resolves to
+ * `{ alive: false }` if the key is missing or Redis is unreachable. Tolerates a
+ * legacy plain-string value (treated as alive with no guild) so a reader can
+ * outlive a payload-shape change.
+ */
+export async function getDiscordGatewayHeartbeat(): Promise<DiscordGatewayHeartbeat> {
+  try {
+    const raw = await getRedis().get(HEARTBEAT_KEY);
+    if (!raw) return { alive: false };
+    try {
+      const parsed = JSON.parse(raw) as HeartbeatPayload;
+      return {
+        alive: true,
+        lastSeenAt: parsed.lastSeenAt,
+        ...(parsed.guildId ? { guildId: parsed.guildId } : {}),
+        ...(typeof parsed.intents === "number"
+          ? { intents: parsed.intents }
+          : {}),
+      };
+    } catch {
+      // Legacy plain-string value (a bare ISO timestamp) — alive, no guild.
+      return { alive: true, lastSeenAt: raw };
+    }
+  } catch {
+    return { alive: false };
+  }
+}