@mulingai-npm/redis 3.41.0 → 3.43.1

package/dist/managers/mulingstream-listener-manager.d.ts

@@ -1,4 +1,7 @@
 import { RedisClient } from '../redis-client';
+import { ListenerPresence } from '../data/listener-presence';
+export { LISTENER_PRESENT_MS, LISTENER_GONE_MS, LISTENER_HEARTBEAT_INTERVAL_MS, listenerPresence } from '../data/listener-presence';
+export type { ListenerPresence } from '../data/listener-presence';
 export type ListenerBreakpoint = 'mobile' | 'desktop' | 'display';
 export type MulingstreamListenerData = {
     listenerId: string;
@@ -12,12 +15,54 @@ export type MulingstreamListenerData = {
     color?: string;
     isListening?: boolean;
     breakpoint?: ListenerBreakpoint;
+    /**
+     * The listener told us their page went into the background: screen locked,
+     * app switched, tab hidden.
+     *
+     * Set by the client rather than inferred, because the socket cannot tell the
+     * difference between a locked phone and a closed tab, and waiting for missed
+     * heartbeats to decide costs ninety seconds of translating for somebody who
+     * is demonstrably not looking. Cleared by the next heartbeat, which is what a
+     * returning page sends immediately.
+     *
+     * Being away is not being gone. See data/listener-presence.ts.
+     */
+    isAway?: boolean;
 };
 export declare class MulingstreamListenerManager {
     private redisClient;
     constructor(redisClient: RedisClient);
     private parseHashData;
     addListener(listenerData: MulingstreamListenerData): Promise<string>;
+    /**
+     * Every listener currently known, across every room.
+     *
+     * WHY THIS USES SCAN AND NOT KEYS
+     *
+     * It used to be `KEYS 'listener:*'`, with a TODO next to it saying it should
+     * not be. KEYS walks the entire keyspace in one go and Redis is single
+     * threaded, so for as long as it runs nothing else in the process is served:
+     * not a heartbeat, not a chunk being handed to the pipeline, not a listener
+     * joining. The cost is invisible on a development database with a few dozen
+     * keys and grows with the busiest moment we will ever have, which is precisely
+     * when it must not stall. This is called by the cleanup sweep every sixty
+     * seconds, for the entire life of the process, so it would have been the most
+     * frequently executed blocking command in the system.
+     *
+     * SCAN answers the same question in cursored batches, yielding between each,
+     * so a large keyspace costs more round trips rather than one long stall. The
+     * guarantees are weaker, deliberately: a key added or removed mid-scan may or
+     * may not appear. That is exactly right for the caller, which is looking for
+     * listeners who went silent minutes ago. One arriving during the scan is one
+     * for the next sweep, sixty seconds later, and there is nothing to do about a
+     * brand new listener anyway.
+     *
+     * The pattern also has to reject keys that merely start with `listener:`. The
+     * legacy `listener:panel-state:*` keys matched the old pattern and were parsed
+     * as listener records, producing entries with NaN timestamps. They never
+     * caused harm, since NaN fails every comparison, which is exactly how a
+     * defect like that survives.
+     */
     getAllListeners(): Promise<MulingstreamListenerData[]>;
     getListenersByRoom(roomId: string): Promise<MulingstreamListenerData[]>;
     getListener(listenerIdOrToken: string): Promise<MulingstreamListenerData | null>;
@@ -30,13 +75,126 @@ export declare class MulingstreamListenerManager {
      */
     updateBreakpoint(listenerIdOrToken: string, breakpoint: ListenerBreakpoint): Promise<MulingstreamListenerData | null>;
     getTargetSocketIdsByRoomLanguage(roomId: string, language: string): Promise<string[]>;
+    /**
+     * Which languages this room has someone PRESENT on.
+     *
+     * Feeds consumersFor, which decides what gets translated at all, so an
+     * over-generous answer here is money spent on every chunk for nobody. It
+     * therefore counts present listeners only: somebody whose phone has been dark
+     * for two minutes is receiving nothing, and translating for them is pure loss.
+     *
+     * It used to count every listener the room had ever registered, including ones
+     * whose heartbeat had been silent for fourteen minutes, because the only thing
+     * that removed a listener was the cleanup sweep. See data/listener-presence.ts
+     * for why that single threshold could not be lowered and had to be split.
+     */
     getUniqueLanguagesByRoom(roomId: string): Promise<string[]>;
+    /**
+     * How many PRESENT listeners in this room are on a language.
+     *
+     * Decides whether a guest-added language slot can be handed back, and counts
+     * the same population `consumersFor` reads, so the two cannot disagree about
+     * whether a language has an audience: a slot is released exactly when the
+     * translation for it stops, never one without the other.
+     *
+     * Present rather than merely registered, and that is the deliberate part. A
+     * listener whose phone has been dark for two minutes is not hearing the
+     * language, so holding the room's last slot for them denies it to a guest
+     * standing in the room who is. If they come back and the slot has gone to
+     * somebody else, they choose again from what the room now has; if it is still
+     * free they simply take it back.
+     */
+    countListenersOnLanguage(roomId: string, language: string): Promise<number>;
+    /**
+     * The client saying its page went into the background, or came back.
+     *
+     * This is the difference between reacting to a locked screen at once and
+     * reacting to it after three missed heartbeats. Both end in the same state;
+     * one of them costs ninety seconds of translation and synthesis for a phone
+     * nobody is looking at, on every language in the room.
+     *
+     * Does NOT touch lastHeartbeat. That field is now also the recorded end of the
+     * listener's session, so it has to keep meaning "when they were genuinely last
+     * there" and nothing else.
+     */
+    setAwayState(listenerIdOrToken: string, isAway: boolean): Promise<MulingstreamListenerData | null>;
+    /**
+     * Present, away or gone, for one listener. For anything that needs to SHOW the
+     * distinction rather than act on it.
+     */
+    getPresence(listenerIdOrToken: string): Promise<ListenerPresence | null>;
     updateHeartbeat(listenerIdOrToken: string): Promise<MulingstreamListenerData | null>;
     getListenerStats(roomId: string): Promise<{
         totalListeners: number;
         languageBreakdown: Record<string, number>;
     }>;
+    /**
+     * How many people in this room are ACTUALLY RECEIVING translation right now.
+     *
+     * Church passes turn on this number rather than on how many people joined. A
+     * pass is spent only when translation reached a human being, so somebody
+     * sitting on the join screen must not burn a church's pass.
+     *
+     * ─── RECEIVING MEANS AUDIO **OR** TEXT ──────────────────────────────────
+     *
+     * Corrected 2026-08-19. This used to require `isListening`, the audio
+     * playback flag, so a guest who joined, chose their language and sat reading
+     * the translated text counted for nothing: the pass clock stayed at zero
+     * until they pressed Listening. David found it on a phone, and the counting
+     * spec had said otherwise all along, in as many words: "the listener session
+     * is open AND we are delivering translated output to it, audio or text".
+     *
+     * The reading is the product. A deaf guest, a guest in a quiet room, a guest
+     * with no headphones and a guest who simply prefers to read are all being
+     * served, all costing us translation on every chunk, and none of them are
+     * pressing an audio button. Charging only for audio would have meant a
+     * church whose congregation reads never spends a pass, which sounds generous
+     * until you notice we are paying for every word of it.
+     *
+     * So the test is PRESENCE, and nothing else. Presence already means joined,
+     * in a language, and with a heartbeat inside the last ninety seconds, which
+     * is exactly the population `consumersFor` is translating for. Whether they
+     * also chose to hear it is not our business, and the spec is explicit that we
+     * do not police attention: a phone in a pocket with audio playing is
+     * listening, and a phone in a hand with text on it is reading.
+     *
+     * `isListening` keeps its real job, which is a different question: whether to
+     * SYNTHESISE SPEECH. See getLanguagesWithActiveListeners. Speech is the most
+     * expensive thing we produce and nobody should pay to generate audio no one
+     * is playing. Text is already produced for the room either way.
+     */
+    getReceivingCount(roomId: string): Promise<number>;
     private capKey;
+    private previewKey;
+    private previewCountKey;
+    /** Open a preview window on one language. Re-pressing simply extends it. */
+    openPreview(roomId: string, language: string, windowSeconds: number): Promise<void>;
+    /** Seconds left on a language's preview window, or 0 when none is open. */
+    getPreviewRemaining(roomId: string, language: string): Promise<number>;
+    /**
+     * Which of `candidates` currently have a preview open.
+     *
+     * Takes the candidate list rather than scanning for a pattern on purpose:
+     * KEYS and SCAN against a live Redis to answer a question asked on every
+     * audio chunk is the kind of thing that is fine until it is not.
+     */
+    getPreviewLanguages(roomId: string, candidates: string[]): Promise<string[]>;
+    /**
+     * Count one press against the room's allowance and say whether it is allowed.
+     *
+     * The cap exists because a preview translates for real. Without it, holding
+     * the button open is a way to run a translation service for nothing, and the
+     * obvious abuse is someone using a speaker preview as a free manual
+     * translation tool. The counter's own TTL resets the allowance, so a church
+     * running a genuine service every week is never permanently locked out.
+     */
+    consumePreviewAllowance(roomId: string, maxPresses: number, resetSeconds: number): Promise<{
+        allowed: boolean;
+        used: number;
+        remaining: number;
+    }>;
+    /** Presses already spent in the current window. Read only, never increments. */
+    getPreviewUsage(roomId: string): Promise<number>;
     /**
      * Cache the room's listener cap. Called by the speaker service at go-live and
      * on reconnect; `ttlSeconds` should comfortably exceed a session so the key

package/dist/managers/mulingstream-listener-manager.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MulingstreamListenerManager = void 0;
+exports.MulingstreamListenerManager = exports.listenerPresence = exports.LISTENER_HEARTBEAT_INTERVAL_MS = exports.LISTENER_GONE_MS = exports.LISTENER_PRESENT_MS = void 0;
+const listener_presence_1 = require("../data/listener-presence");
+var listener_presence_2 = require("../data/listener-presence");
+Object.defineProperty(exports, "LISTENER_PRESENT_MS", { enumerable: true, get: function () { return listener_presence_2.LISTENER_PRESENT_MS; } });
+Object.defineProperty(exports, "LISTENER_GONE_MS", { enumerable: true, get: function () { return listener_presence_2.LISTENER_GONE_MS; } });
+Object.defineProperty(exports, "LISTENER_HEARTBEAT_INTERVAL_MS", { enumerable: true, get: function () { return listener_presence_2.LISTENER_HEARTBEAT_INTERVAL_MS; } });
+Object.defineProperty(exports, "listenerPresence", { enumerable: true, get: function () { return listener_presence_2.listenerPresence; } });
 const EXPIRATION = 24 * 60 * 60; // 24 hours in seconds
 /**
  * Generates a bright RGB color suitable for dark backgrounds.
@@ -48,7 +54,8 @@ class MulingstreamListenerManager {
             language: data.language || '',
             color: data.color || '',
             isListening: data.isListening === 'true',
-            breakpoint: bp === 'mobile' || bp === 'desktop' || bp === 'display' ? bp : undefined
+            breakpoint: bp === 'mobile' || bp === 'desktop' || bp === 'display' ? bp : undefined,
+            isAway: data.isAway === 'true'
         };
     }
     // Creates a new listener.
@@ -74,25 +81,60 @@ class MulingstreamListenerManager {
             language: (_c = listenerData.language) !== null && _c !== void 0 ? _c : '',
             color,
             isListening: 'false',
-            breakpoint: (_d = listenerData.breakpoint) !== null && _d !== void 0 ? _d : ''
+            breakpoint: (_d = listenerData.breakpoint) !== null && _d !== void 0 ? _d : '',
+            // A listener who just joined is looking at the page by definition.
+            isAway: 'false'
         });
         // expire listener
         await this.redisClient.expire(`listener:${listenerId}`, EXPIRATION);
         return listenerId;
     }
+    /**
+     * Every listener currently known, across every room.
+     *
+     * WHY THIS USES SCAN AND NOT KEYS
+     *
+     * It used to be `KEYS 'listener:*'`, with a TODO next to it saying it should
+     * not be. KEYS walks the entire keyspace in one go and Redis is single
+     * threaded, so for as long as it runs nothing else in the process is served:
+     * not a heartbeat, not a chunk being handed to the pipeline, not a listener
+     * joining. The cost is invisible on a development database with a few dozen
+     * keys and grows with the busiest moment we will ever have, which is precisely
+     * when it must not stall. This is called by the cleanup sweep every sixty
+     * seconds, for the entire life of the process, so it would have been the most
+     * frequently executed blocking command in the system.
+     *
+     * SCAN answers the same question in cursored batches, yielding between each,
+     * so a large keyspace costs more round trips rather than one long stall. The
+     * guarantees are weaker, deliberately: a key added or removed mid-scan may or
+     * may not appear. That is exactly right for the caller, which is looking for
+     * listeners who went silent minutes ago. One arriving during the scan is one
+     * for the next sweep, sixty seconds later, and there is nothing to do about a
+     * brand new listener anyway.
+     *
+     * The pattern also has to reject keys that merely start with `listener:`. The
+     * legacy `listener:panel-state:*` keys matched the old pattern and were parsed
+     * as listener records, producing entries with NaN timestamps. They never
+     * caused harm, since NaN fails every comparison, which is exactly how a
+     * defect like that survives.
+     */
     async getAllListeners() {
-        // get all keys that match 'listener:*'
-        // TODO: if we have many keys, consider using SCAN instead of KEYS to avoid performance issues.
-        const keys = await this.redisClient.keys('listener:*');
-        if (!keys || keys.length === 0) {
-            return [];
-        }
-        // fetch each hash with HGETALL
         const listeners = [];
-        for (const key of keys) {
-            const data = await this.redisClient.hgetall(key);
-            listeners.push(this.parseHashData(data));
-        }
+        let cursor = 0;
+        do {
+            const [nextCursor, keys] = await this.redisClient.scan(cursor, 'listener:*', 500);
+            cursor = Number(nextCursor);
+            for (const key of keys || []) {
+                // `listener:{id}` only. Anything with a further colon belongs to
+                // some other feature that happens to share the prefix.
+                if (key.split(':').length !== 2)
+                    continue;
+                const data = await this.redisClient.hgetall(key);
+                if (!data || Object.keys(data).length === 0)
+                    continue;
+                listeners.push(this.parseHashData(data));
+            }
+        } while (cursor !== 0);
         return listeners;
     }
     async getListenersByRoom(roomId) {
@@ -189,13 +231,23 @@ class MulingstreamListenerManager {
         });
         return filteredListeners.map((listener) => listener.socketId);
     }
+    /**
+     * Which languages this room has someone PRESENT on.
+     *
+     * Feeds consumersFor, which decides what gets translated at all, so an
+     * over-generous answer here is money spent on every chunk for nobody. It
+     * therefore counts present listeners only: somebody whose phone has been dark
+     * for two minutes is receiving nothing, and translating for them is pure loss.
+     *
+     * It used to count every listener the room had ever registered, including ones
+     * whose heartbeat had been silent for fourteen minutes, because the only thing
+     * that removed a listener was the cleanup sweep. See data/listener-presence.ts
+     * for why that single threshold could not be lowered and had to be split.
+     */
     async getUniqueLanguagesByRoom(roomId) {
-        // 1) Fetch all listeners for the room.
-        //    (This includes inactive ones, but feel free to filter out isActive === false if you only want active ones.)
-        const listeners = await this.getListenersByRoom(roomId);
-        // if I wanted to get only active listeners
-        // const listeners = (await this.getListenersByRoom(roomId)).filter(l => l.isActive);
-        // 2) Count how many times each language appears.
+        const now = Date.now();
+        const listeners = (await this.getListenersByRoom(roomId)).filter((listener) => (0, listener_presence_1.isListenerPresent)(listener.lastHeartbeat, listener.isAway === true, now));
+        // Count how many times each language appears.
         const languageCountMap = {};
         for (const listener of listeners) {
             // skip blank/unset language
@@ -211,6 +263,57 @@ class MulingstreamListenerManager {
         // 4) Map back to just the language strings in order
         return sortedEntries.map(([language]) => language);
     }
+    /**
+     * How many PRESENT listeners in this room are on a language.
+     *
+     * Decides whether a guest-added language slot can be handed back, and counts
+     * the same population `consumersFor` reads, so the two cannot disagree about
+     * whether a language has an audience: a slot is released exactly when the
+     * translation for it stops, never one without the other.
+     *
+     * Present rather than merely registered, and that is the deliberate part. A
+     * listener whose phone has been dark for two minutes is not hearing the
+     * language, so holding the room's last slot for them denies it to a guest
+     * standing in the room who is. If they come back and the slot has gone to
+     * somebody else, they choose again from what the room now has; if it is still
+     * free they simply take it back.
+     */
+    async countListenersOnLanguage(roomId, language) {
+        if (!roomId || !language)
+            return 0;
+        const now = Date.now();
+        const listeners = await this.getListenersByRoom(roomId);
+        return listeners.filter((listener) => listener.language === language && (0, listener_presence_1.isListenerPresent)(listener.lastHeartbeat, listener.isAway === true, now)).length;
+    }
+    /**
+     * The client saying its page went into the background, or came back.
+     *
+     * This is the difference between reacting to a locked screen at once and
+     * reacting to it after three missed heartbeats. Both end in the same state;
+     * one of them costs ninety seconds of translation and synthesis for a phone
+     * nobody is looking at, on every language in the room.
+     *
+     * Does NOT touch lastHeartbeat. That field is now also the recorded end of the
+     * listener's session, so it has to keep meaning "when they were genuinely last
+     * there" and nothing else.
+     */
+    async setAwayState(listenerIdOrToken, isAway) {
+        const listener = await this.getListener(listenerIdOrToken);
+        if (!listener)
+            return null;
+        await this.redisClient.hset(`listener:${listener.listenerId}`, { isAway: isAway.toString() });
+        return { ...listener, isAway };
+    }
+    /**
+     * Present, away or gone, for one listener. For anything that needs to SHOW the
+     * distinction rather than act on it.
+     */
+    async getPresence(listenerIdOrToken) {
+        const listener = await this.getListener(listenerIdOrToken);
+        if (!listener)
+            return null;
+        return (0, listener_presence_1.listenerPresence)(listener.lastHeartbeat, listener.isAway === true);
+    }
     async updateHeartbeat(listenerIdOrToken) {
         const listener = await this.getListener(listenerIdOrToken);
         if (!listener) {
@@ -218,9 +321,16 @@ class MulingstreamListenerManager {
             return null;
         }
         const now = Date.now();
-        // Update the heartbeat timestamp
+        // Update the heartbeat timestamp, and clear away in the same write.
+        //
+        // A heartbeat only arrives from a page that is running, so receiving one is
+        // proof the listener is back: an explicit "I have returned" event would be
+        // a second way of saying the same thing, and a second way to get it wrong.
+        // A returning page sends a heartbeat immediately on visibility, so this is
+        // as fast as anything else could be.
         await this.redisClient.hset(`listener:${listener.listenerId}`, {
-            lastHeartbeat: now.toString()
+            lastHeartbeat: now.toString(),
+            isAway: 'false'
         });
         // Reset expiration on activity
         await this.redisClient.expire(`listener:${listener.listenerId}`, EXPIRATION);
@@ -239,6 +349,46 @@ class MulingstreamListenerManager {
             languageBreakdown
         };
     }
+    /**
+     * How many people in this room are ACTUALLY RECEIVING translation right now.
+     *
+     * Church passes turn on this number rather than on how many people joined. A
+     * pass is spent only when translation reached a human being, so somebody
+     * sitting on the join screen must not burn a church's pass.
+     *
+     * ─── RECEIVING MEANS AUDIO **OR** TEXT ──────────────────────────────────
+     *
+     * Corrected 2026-08-19. This used to require `isListening`, the audio
+     * playback flag, so a guest who joined, chose their language and sat reading
+     * the translated text counted for nothing: the pass clock stayed at zero
+     * until they pressed Listening. David found it on a phone, and the counting
+     * spec had said otherwise all along, in as many words: "the listener session
+     * is open AND we are delivering translated output to it, audio or text".
+     *
+     * The reading is the product. A deaf guest, a guest in a quiet room, a guest
+     * with no headphones and a guest who simply prefers to read are all being
+     * served, all costing us translation on every chunk, and none of them are
+     * pressing an audio button. Charging only for audio would have meant a
+     * church whose congregation reads never spends a pass, which sounds generous
+     * until you notice we are paying for every word of it.
+     *
+     * So the test is PRESENCE, and nothing else. Presence already means joined,
+     * in a language, and with a heartbeat inside the last ninety seconds, which
+     * is exactly the population `consumersFor` is translating for. Whether they
+     * also chose to hear it is not our business, and the spec is explicit that we
+     * do not police attention: a phone in a pocket with audio playing is
+     * listening, and a phone in a hand with text on it is reading.
+     *
+     * `isListening` keeps its real job, which is a different question: whether to
+     * SYNTHESISE SPEECH. See getLanguagesWithActiveListeners. Speech is the most
+     * expensive thing we produce and nobody should pay to generate audio no one
+     * is playing. Text is already produced for the room either way.
+     */
+    async getReceivingCount(roomId) {
+        const now = Date.now();
+        const listeners = await this.getListenersByRoom(roomId);
+        return listeners.filter((l) => (0, listener_presence_1.isListenerPresent)(l.lastHeartbeat, l.isAway === true, now)).length;
+    }
     // ─── Per-room listener capacity (design B, 2026-07-09) ────────────────────
     // The cap value is the room owner's plan `max_audience`, resolved ONCE by the
     // speaker service when it goes live (it already fetches the plan entitlements)
@@ -250,6 +400,82 @@ class MulingstreamListenerManager {
     capKey(roomId) {
         return `room:${roomId}:listener-cap`;
     }
+    /*
+     * SPEAKER PREVIEW
+     *
+     * A speaker looking at their own translation feed is a consumer of
+     * translation but must never be a payer for it: nobody should be able to
+     * spend a church's pass, or their own credits, by watching their own screen.
+     * So a preview is a short window they open deliberately, not a state they
+     * fall into by leaving a tab open.
+     *
+     * In Redis rather than in the pipeline's memory because the request arrives
+     * at the room service and the decision is read by the pipeline service, and
+     * because a pipeline replica restarting mid window must not silently start
+     * translating for nobody. The TTL IS the expiry: nothing has to remember to
+     * close it, and a crash fails in the safe direction.
+     */
+    previewKey(roomId, language) {
+        return `room:${roomId}:preview:${language}`;
+    }
+    previewCountKey(roomId) {
+        return `room:${roomId}:preview-count`;
+    }
+    /** Open a preview window on one language. Re-pressing simply extends it. */
+    async openPreview(roomId, language, windowSeconds) {
+        if (!roomId || !language || windowSeconds <= 0)
+            return;
+        const key = this.previewKey(roomId, language);
+        await this.redisClient.set(key, '1');
+        await this.redisClient.expire(key, Math.floor(windowSeconds));
+    }
+    /** Seconds left on a language's preview window, or 0 when none is open. */
+    async getPreviewRemaining(roomId, language) {
+        const ttl = await this.redisClient.ttl(this.previewKey(roomId, language));
+        return ttl > 0 ? ttl : 0;
+    }
+    /**
+     * Which of `candidates` currently have a preview open.
+     *
+     * Takes the candidate list rather than scanning for a pattern on purpose:
+     * KEYS and SCAN against a live Redis to answer a question asked on every
+     * audio chunk is the kind of thing that is fine until it is not.
+     */
+    async getPreviewLanguages(roomId, candidates) {
+        if (!roomId || candidates.length === 0)
+            return [];
+        const open = [];
+        for (const language of candidates) {
+            if (await this.redisClient.get(this.previewKey(roomId, language)))
+                open.push(language);
+        }
+        return open;
+    }
+    /**
+     * Count one press against the room's allowance and say whether it is allowed.
+     *
+     * The cap exists because a preview translates for real. Without it, holding
+     * the button open is a way to run a translation service for nothing, and the
+     * obvious abuse is someone using a speaker preview as a free manual
+     * translation tool. The counter's own TTL resets the allowance, so a church
+     * running a genuine service every week is never permanently locked out.
+     */
+    async consumePreviewAllowance(roomId, maxPresses, resetSeconds) {
+        const key = this.previewCountKey(roomId);
+        const used = await this.redisClient.incr(key);
+        // Only the first press starts the clock, so the window is a fixed period
+        // from first use rather than one that slides forward on every press.
+        if (used === 1)
+            await this.redisClient.expire(key, Math.floor(resetSeconds));
+        const allowed = used <= maxPresses;
+        return { allowed, used, remaining: Math.max(0, maxPresses - used) };
+    }
+    /** Presses already spent in the current window. Read only, never increments. */
+    async getPreviewUsage(roomId) {
+        const raw = await this.redisClient.get(this.previewCountKey(roomId));
+        const used = raw ? parseInt(raw, 10) : 0;
+        return Number.isFinite(used) && used > 0 ? used : 0;
+    }
     /**
      * Cache the room's listener cap. Called by the speaker service at go-live and
      * on reconnect; `ttlSeconds` should comfortably exceed a session so the key
@@ -330,6 +556,7 @@ class MulingstreamListenerManager {
      * Used by pipeline to determine which languages need TTS generation.
      */
     async getLanguagesWithActiveListeners(roomId) {
+        const now = Date.now();
         const listeners = await this.getListenersByRoom(roomId);
         const languageCountMap = {};
         for (const listener of listeners) {
@@ -337,6 +564,10 @@ class MulingstreamListenerManager {
                 continue;
             if (!listener.isListening)
                 continue;
+            // Speech synthesis is the most expensive thing we do. A language whose
+            // only listener has a dark phone must not be synthesised.
+            if (!(0, listener_presence_1.isListenerPresent)(listener.lastHeartbeat, listener.isAway === true, now))
+                continue;
             const lang = listener.language;
             languageCountMap[lang] = (languageCountMap[lang] || 0) + 1;
         }

package/dist/managers/mulingstream-speaker-manager.d.ts

@@ -36,6 +36,18 @@ export declare class MulingstreamSpeakerManager {
     removeSpeakerBySocketId(socketId: string): Promise<boolean>;
     removeSpeakersByUserId(userId: string): Promise<number>;
     removeSpeakersByRoomId(roomId: string): Promise<number>;
+    /**
+     * Remove a speaker by its own id, without needing a live socket mapping.
+     *
+     * This is the removal that always works, and it is the one the cleanup
+     * sweeps must use. Removing by socket depends on `socket:<id>:speaker`
+     * still pointing at the record, and after a reconnect self-heal it does
+     * not: see updateSocketId. A ghost with a broken mapping is exactly the
+     * record a sweep is trying to delete, so resolving it through the mapping
+     * fails on precisely the case that matters and the ghost survives every
+     * sweep for the full 24 hour TTL.
+     */
+    removeSpeakerBySpeakerId(speakerId: string): Promise<boolean>;
     private removeSpeakerById;
     getSpeakerBySpeakerId(speakerId: string): Promise<MulingstreamSpeakerData | null>;
     getSpeakerBySocketId(socketId: string): Promise<MulingstreamSpeakerData | null>;
@@ -54,6 +66,22 @@ export declare class MulingstreamSpeakerManager {
     /**
      * Update socketId for a speaker (called by heartbeat self-heal when reconnect creates a new socket).
      * Mirrors the listener-side self-heal pattern — see MULINGSTREAM_RELIABILITY_ROADMAP.md §0.2.
+     *
+     * ─── THE MAPPING MOVES WITH THE FIELD, OR THE RECORD BECOMES A GHOST ───
+     *
+     * This used to rewrite the field alone, and that one omission is where
+     * every ghost speaker came from. `socket:<id>:speaker` is how a socket is
+     * resolved back to its speaker, and it is how disconnect, leave and both
+     * cleanup sweeps find the record they mean to delete. Leave it pointing at
+     * the OLD socket and the record becomes unreachable from the socket that
+     * actually owns it: the speaker's own disconnect finds nothing to remove,
+     * so the record survives its socket and lives out the 24 hour TTL.
+     *
+     * Room 500032 held four of them on 2026-08-27, one per Go Live that day,
+     * and three had a socketId field that did not match the socket in their own
+     * key: the signature of exactly this. They are not harmless. Ghosts inflate
+     * every "is anyone still in this room" count, and cleaning one up is what
+     * told a live congregation the speaker had left.
      */
     updateSocketId(speakerId: string, newSocketId: string): Promise<boolean>;
     updateTargetLanguages(socketId: string, languages: string[]): Promise<boolean>;

package/dist/managers/mulingstream-speaker-manager.js

@@ -129,6 +129,20 @@ class MulingstreamSpeakerManager {
                 deleted += 1;
         return deleted;
     }
+    /**
+     * Remove a speaker by its own id, without needing a live socket mapping.
+     *
+     * This is the removal that always works, and it is the one the cleanup
+     * sweeps must use. Removing by socket depends on `socket:<id>:speaker`
+     * still pointing at the record, and after a reconnect self-heal it does
+     * not: see updateSocketId. A ghost with a broken mapping is exactly the
+     * record a sweep is trying to delete, so resolving it through the mapping
+     * fails on precisely the case that matters and the ghost survives every
+     * sweep for the full 24 hour TTL.
+     */
+    async removeSpeakerBySpeakerId(speakerId) {
+        return this.removeSpeakerById(speakerId);
+    }
     async removeSpeakerById(speakerId) {
         const key = this.buildKey(speakerId);
         const data = await this.redisClient.hgetall(key);
@@ -136,6 +150,21 @@ class MulingstreamSpeakerManager {
             await this.cleanIndexes(speakerId);
             return false;
         }
+        /*
+         * Drop the mapping for the socket this record CURRENTLY holds, before
+         * the hash goes.
+         *
+         * cleanIndexes can only delete the socket baked into the speakerId,
+         * which is the socket the record was created with. A record that has
+         * been through a reconnect self-heal holds a different one in its
+         * field, and nothing else will ever delete that key: it would sit
+         * pointing at a deleted speaker until its TTL, and getSpeakerBySocketId
+         * would resolve a socket to a record that no longer exists.
+         */
+        const currentSocketId = data.socketId;
+        if (currentSocketId) {
+            await this.redisClient.del(`socket:${currentSocketId}:speaker`);
+        }
         await this.redisClient.del(key);
         await this.cleanIndexes(speakerId);
         return true;
@@ -231,12 +260,37 @@ class MulingstreamSpeakerManager {
     /**
      * Update socketId for a speaker (called by heartbeat self-heal when reconnect creates a new socket).
      * Mirrors the listener-side self-heal pattern — see MULINGSTREAM_RELIABILITY_ROADMAP.md §0.2.
+     *
+     * ─── THE MAPPING MOVES WITH THE FIELD, OR THE RECORD BECOMES A GHOST ───
+     *
+     * This used to rewrite the field alone, and that one omission is where
+     * every ghost speaker came from. `socket:<id>:speaker` is how a socket is
+     * resolved back to its speaker, and it is how disconnect, leave and both
+     * cleanup sweeps find the record they mean to delete. Leave it pointing at
+     * the OLD socket and the record becomes unreachable from the socket that
+     * actually owns it: the speaker's own disconnect finds nothing to remove,
+     * so the record survives its socket and lives out the 24 hour TTL.
+     *
+     * Room 500032 held four of them on 2026-08-27, one per Go Live that day,
+     * and three had a socketId field that did not match the socket in their own
+     * key: the signature of exactly this. They are not harmless. Ghosts inflate
+     * every "is anyone still in this room" count, and cleaning one up is what
+     * told a live congregation the speaker had left.
      */
     async updateSocketId(speakerId, newSocketId) {
         const speaker = await this.getSpeakerBySpeakerId(speakerId);
         if (speaker === null)
             return false;
+        const previousSocketId = speaker.socketId;
         await this.redisClient.hset(this.buildKey(speakerId), { socketId: newSocketId });
+        // Old mapping first: if the process dies between the two, an absent
+        // mapping is recoverable (the next heartbeat re-heals it) while a
+        // mapping pointing at the wrong record is not.
+        if (previousSocketId && previousSocketId !== newSocketId) {
+            await this.redisClient.del(`socket:${previousSocketId}:speaker`);
+        }
+        await this.redisClient.set(`socket:${newSocketId}:speaker`, speakerId);
+        await this.redisClient.expire(`socket:${newSocketId}:speaker`, EXPIRATION);
         return true;
     }
     async updateTargetLanguages(socketId, languages) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mulingai-npm/redis",
-    "version": "3.41.0",
+    "version": "3.43.1",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "repository": {