@mulingai-npm/redis 3.42.0 → 3.44.1

package/dist/data/listener-presence.d.ts

@@ -78,3 +78,42 @@ export type ListenerPresence = 'present' | 'away' | 'gone';
 export declare function listenerPresence(lastHeartbeatMs: number, isAway: boolean, now?: number): ListenerPresence;
 /** Shorthand for the common question: is this listener consuming anything right now. */
 export declare function isListenerPresent(lastHeartbeatMs: number, isAway: boolean, now?: number): boolean;
+/**
+ * Is this listener consuming the product right now, for the purposes of deciding
+ * what to translate, what to synthesise, and what a pass is being spent on.
+ *
+ * ─── WHY THIS IS NOT JUST isListenerPresent ─────────────────────────────────
+ *
+ * A dark screen means "receiving nothing" only if the listener is READING. The
+ * whole presence model above was written from the reader's case and then applied
+ * to everyone, and for somebody listening to audio it is simply false. Earbuds
+ * in, phone in a pocket, screen off is the most ordinary way a congregation uses
+ * live audio translation, and it is `visibilityState === 'hidden'` every time.
+ *
+ * What that cost, found on 2026-08-27 while testing H7: the listener tab went to
+ * the background, the client correctly reported PRESENCE_AWAY, and the pipeline
+ * stopped synthesising mid-sentence. Chunks 358 and 359 logged "Active listener
+ * languages: [NONE]" and were skipped, sitting between chunks that generated
+ * normally, with the heartbeat only seventeen seconds old. In a service that is
+ * the congregation losing part of the sermon, with nothing on the speaker's
+ * screen to say it happened. The same mechanism withheld TRANSLATION earlier the
+ * same day, which is why the room kept going quiet for a few chunks at a time.
+ *
+ * ─── WHAT THIS DOES AND DOES NOT CONCEDE ────────────────────────────────────
+ *
+ * Only the CLIENT-DECLARED away is overridden, and only for somebody whose audio
+ * is actually on. That distinction is the whole safety of it:
+ *
+ *   isAway means the page told us it is hidden. The page is alive, it is still
+ *   sending heartbeats, and its audio element is still playing. We know what is
+ *   happening and it is being consumed.
+ *
+ *   A stale heartbeat means we have heard nothing at all for ninety seconds.
+ *   That is the genuinely unknown case, and it stays not-consuming exactly as
+ *   before, because a closed tab that never got to send AUDIO_PAUSE must not go
+ *   on burning speech synthesis for a quarter of an hour.
+ *
+ * So a hidden reader still costs nothing, which was the original point, and a
+ * hidden listener is served, which is the product.
+ */
+export declare function isListenerConsuming(lastHeartbeatMs: number, isAway: boolean, isListening: boolean, now?: number): boolean;

package/dist/data/listener-presence.js

@@ -43,7 +43,7 @@
  * now costs nothing, because nothing expensive waits on it any more.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isListenerPresent = exports.listenerPresence = exports.LISTENER_HEARTBEAT_INTERVAL_MS = exports.LISTENER_GONE_MS = exports.LISTENER_PRESENT_MS = void 0;
+exports.isListenerConsuming = exports.isListenerPresent = exports.listenerPresence = exports.LISTENER_HEARTBEAT_INTERVAL_MS = exports.LISTENER_GONE_MS = exports.LISTENER_PRESENT_MS = void 0;
 /**
  * How long a heartbeat stays fresh: three missed beats at the client's 30 second
  * interval, so one dropped beat on a bad connection never marks anybody away.
@@ -91,3 +91,53 @@ function isListenerPresent(lastHeartbeatMs, isAway, now = Date.now()) {
     return listenerPresence(lastHeartbeatMs, isAway, now) === 'present';
 }
 exports.isListenerPresent = isListenerPresent;
+/**
+ * Is this listener consuming the product right now, for the purposes of deciding
+ * what to translate, what to synthesise, and what a pass is being spent on.
+ *
+ * ─── WHY THIS IS NOT JUST isListenerPresent ─────────────────────────────────
+ *
+ * A dark screen means "receiving nothing" only if the listener is READING. The
+ * whole presence model above was written from the reader's case and then applied
+ * to everyone, and for somebody listening to audio it is simply false. Earbuds
+ * in, phone in a pocket, screen off is the most ordinary way a congregation uses
+ * live audio translation, and it is `visibilityState === 'hidden'` every time.
+ *
+ * What that cost, found on 2026-08-27 while testing H7: the listener tab went to
+ * the background, the client correctly reported PRESENCE_AWAY, and the pipeline
+ * stopped synthesising mid-sentence. Chunks 358 and 359 logged "Active listener
+ * languages: [NONE]" and were skipped, sitting between chunks that generated
+ * normally, with the heartbeat only seventeen seconds old. In a service that is
+ * the congregation losing part of the sermon, with nothing on the speaker's
+ * screen to say it happened. The same mechanism withheld TRANSLATION earlier the
+ * same day, which is why the room kept going quiet for a few chunks at a time.
+ *
+ * ─── WHAT THIS DOES AND DOES NOT CONCEDE ────────────────────────────────────
+ *
+ * Only the CLIENT-DECLARED away is overridden, and only for somebody whose audio
+ * is actually on. That distinction is the whole safety of it:
+ *
+ *   isAway means the page told us it is hidden. The page is alive, it is still
+ *   sending heartbeats, and its audio element is still playing. We know what is
+ *   happening and it is being consumed.
+ *
+ *   A stale heartbeat means we have heard nothing at all for ninety seconds.
+ *   That is the genuinely unknown case, and it stays not-consuming exactly as
+ *   before, because a closed tab that never got to send AUDIO_PAUSE must not go
+ *   on burning speech synthesis for a quarter of an hour.
+ *
+ * So a hidden reader still costs nothing, which was the original point, and a
+ * hidden listener is served, which is the product.
+ */
+function isListenerConsuming(lastHeartbeatMs, isAway, isListening, now = Date.now()) {
+    const age = now - lastHeartbeatMs;
+    // Heard nothing recently: unknown, and unknown is not consuming. Covers both
+    // 'gone' and the stale-heartbeat half of 'away'.
+    if (age > exports.LISTENER_PRESENT_MS)
+        return false;
+    // Hidden and reading only. Nothing is reaching them, so nothing is made.
+    if (isAway && !isListening)
+        return false;
+    return true;
+}
+exports.isListenerConsuming = isListenerConsuming;

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

@@ -1,6 +1,6 @@
 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 { LISTENER_PRESENT_MS, LISTENER_GONE_MS, LISTENER_HEARTBEAT_INTERVAL_MS, listenerPresence, isListenerConsuming } from '../data/listener-presence';
 export type { ListenerPresence } from '../data/listener-presence';
 export type ListenerBreakpoint = 'mobile' | 'desktop' | 'display';
 export type MulingstreamListenerData = {
@@ -97,12 +97,19 @@ export declare class MulingstreamListenerManager {
      * 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.
+     * Consuming rather than merely registered, and that is the deliberate part. A
+     * listener we have not heard from 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.
+     *
+     * It has to be the SAME test getUniqueLanguagesByRoom uses, which is why this
+     * moved to isListenerConsuming with it on 2026-08-27 rather than being left on
+     * isListenerPresent. Leaving it would have broken the invariant this comment
+     * opens with, in the least visible direction: somebody listening with their
+     * phone in a pocket would keep receiving their language while the room quietly
+     * handed their slot to somebody else.
      */
     countListenersOnLanguage(roomId: string, language: string): Promise<number>;
     /**

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

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MulingstreamListenerManager = exports.listenerPresence = exports.LISTENER_HEARTBEAT_INTERVAL_MS = exports.LISTENER_GONE_MS = exports.LISTENER_PRESENT_MS = void 0;
+exports.MulingstreamListenerManager = exports.isListenerConsuming = 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; } });
+Object.defineProperty(exports, "isListenerConsuming", { enumerable: true, get: function () { return listener_presence_2.isListenerConsuming; } });
 const EXPIRATION = 24 * 60 * 60; // 24 hours in seconds
 /**
  * Generates a bright RGB color suitable for dark backgrounds.
@@ -244,9 +245,16 @@ class MulingstreamListenerManager {
      * 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.
      */
+    /*
+     * Consuming, not merely present. A listener with audio on and a hidden screen
+     * still needs the translation their speech is synthesised from, so excluding
+     * them here would withhold the text and leave the TTS below with nothing to
+     * say. See isListenerConsuming for why a hidden READER still counts for
+     * nothing. Corrected 2026-08-27.
+     */
     async getUniqueLanguagesByRoom(roomId) {
         const now = Date.now();
-        const listeners = (await this.getListenersByRoom(roomId)).filter((listener) => (0, listener_presence_1.isListenerPresent)(listener.lastHeartbeat, listener.isAway === true, now));
+        const listeners = (await this.getListenersByRoom(roomId)).filter((listener) => (0, listener_presence_1.isListenerConsuming)(listener.lastHeartbeat, listener.isAway === true, listener.isListening === true, now));
         // Count how many times each language appears.
         const languageCountMap = {};
         for (const listener of listeners) {
@@ -271,19 +279,27 @@ class MulingstreamListenerManager {
      * 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.
+     * Consuming rather than merely registered, and that is the deliberate part. A
+     * listener we have not heard from 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.
+     *
+     * It has to be the SAME test getUniqueLanguagesByRoom uses, which is why this
+     * moved to isListenerConsuming with it on 2026-08-27 rather than being left on
+     * isListenerPresent. Leaving it would have broken the invariant this comment
+     * opens with, in the least visible direction: somebody listening with their
+     * phone in a pocket would keep receiving their language while the room quietly
+     * handed their slot to somebody else.
      */
     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;
+        return listeners.filter((listener) => listener.language === language &&
+            (0, listener_presence_1.isListenerConsuming)(listener.lastHeartbeat, listener.isAway === true, listener.isListening === true, now)).length;
     }
     /**
      * The client saying its page went into the background, or came back.
@@ -384,10 +400,18 @@ class MulingstreamListenerManager {
      * expensive thing we produce and nobody should pay to generate audio no one
      * is playing. Text is already produced for the room either way.
      */
+    /*
+     * This decides whether a pass is being spent, so it has to agree with what we
+     * actually served. Since 2026-08-27 a hidden listener with audio on IS served,
+     * and counting them is not generosity: they are receiving the product, and a
+     * church whose congregation listens with their phones in their pockets would
+     * otherwise get every service for free while we paid for all of the speech.
+     * A hidden reader still counts for nothing, because nothing reaches them.
+     */
     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;
+        return listeners.filter((l) => (0, listener_presence_1.isListenerConsuming)(l.lastHeartbeat, l.isAway === true, l.isListening === 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
@@ -564,9 +588,18 @@ 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))
+            /*
+             * Speech synthesis is the most expensive thing we do, so this stays a
+             * real gate. What changed on 2026-08-27 is what a dark phone means.
+             *
+             * It used to skip anyone marked away, and a phone in a pocket is
+             * marked away the instant its screen goes off, which is precisely how
+             * somebody listens. So the one listener whose audio we were certain
+             * about was the one we stopped generating for, mid-sermon. The gate
+             * now turns on whether they are CONSUMING: audio on and heartbeats
+             * still arriving qualifies, a stale heartbeat still does not.
+             */
+            if (!(0, listener_presence_1.isListenerConsuming)(listener.lastHeartbeat, listener.isAway === true, 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,34 +1,34 @@
-{
-    "name": "@mulingai-npm/redis",
-    "version": "3.42.0",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/mulingai/mulingai-backend.git"
-    },
-    "publishConfig": {
-        "registry": "https://registry.npmjs.org/"
-    },
-    "private": false,
-    "scripts": {
-        "dev": "rm -f tsconfig.tsbuildinfo && tsc --watch",
-        "build": "rm -f tsconfig.tsbuildinfo && tsc",
-        "prepublishOnly": "npm run build"
-    },
-    "dependencies": {
-        "ioredis": "^5.6.0",
-        "uuid": "^11.1.0"
-    },
-    "devDependencies": {
-        "concurrently": "^9.1.2",
-        "copyfiles": "^2.4.1",
-        "nodemon": "^3.1.9",
-        "typescript": "^4.9.5"
-    },
-    "files": [
-        "dist",
-        "package.json",
-        "README.md"
-    ]
-}
+{
+    "name": "@mulingai-npm/redis",
+    "version": "3.44.1",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mulingai/mulingai-backend.git"
+    },
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org/"
+    },
+    "private": false,
+    "scripts": {
+        "dev": "rm -f tsconfig.tsbuildinfo && tsc --watch",
+        "build": "rm -f tsconfig.tsbuildinfo && tsc",
+        "prepublishOnly": "npm run build"
+    },
+    "dependencies": {
+        "ioredis": "^5.6.0",
+        "uuid": "^11.1.0"
+    },
+    "devDependencies": {
+        "concurrently": "^9.1.2",
+        "copyfiles": "^2.4.1",
+        "nodemon": "^3.1.9",
+        "typescript": "^4.9.5"
+    },
+    "files": [
+        "dist",
+        "package.json",
+        "README.md"
+    ]
+}