@oneuptime/common 13.0.3 → 13.0.5

package/build/dist/Server/Utils/SessionReplay/SessionReplayReadService.js

@@ -18,10 +18,12 @@ import TableColumnType from "../../../Types/AnalyticsDatabase/TableColumnType";
 import Includes from "../../../Types/BaseDatabase/Includes";
 import OneUptimeDate from "../../../Types/Date";
 import ChunkMath from "../../../Utils/Rum/ChunkMath";
+import { hasSessionRecordingEnded, } from "../../../Utils/Rum/SessionReplayRecordingEnded";
 import { MAX_SESSION_REPLAY_CHUNKS_PER_READ, MAX_SESSION_REPLAY_READ_BYTES, SESSION_REPLAY_LIST_SEARCH_MAX_LENGTH, SESSION_REPLAY_MAX_SESSION_MS, SESSION_REPLAY_MAX_TAG_KEYS, SESSION_REPLAY_RECORDER_CAPABILITIES, SessionReplaySealedReason, } from "../../../Types/Rum/SessionReplay";
 import { SESSION_REPLAY_SORT_BY_VALUES, } from "../../../Types/Rum/SessionReplayApi";
 import BadDataException from "../../../Types/Exception/BadDataException";
 import CaptureSpan from "../Telemetry/CaptureSpan";
+import ServiceType from "../../../Types/Telemetry/ServiceType";
 /*
  * Bespoke ClickHouse reads for session-replay playback.
  *
@@ -77,6 +79,14 @@ const READ_QUERY_SETTINGS = getQuerySettings({
 /* Page sizes for the session list. */
 export const DEFAULT_SESSION_REPLAY_LIST_LIMIT = 50;
 export const MAX_SESSION_REPLAY_LIST_LIMIT = 200;
+/*
+ * Audit tables resolve the opaque session ids on one page in a single
+ * ClickHouse read. Keep both the number of bound IN values and each value's
+ * size bounded; session ids are browser-minted 32-character hex strings, but
+ * older recorders and hand-written API callers may have stored another shape.
+ */
+export const MAX_SESSION_REPLAY_SUMMARIES_BATCH_SIZE = 200;
+export const MAX_SESSION_REPLAY_SESSION_ID_LENGTH = 128;
 /*
  * Page sizes for the per-user rollup (listUsers). Same figures as the
  * list, but the cost model differs: every page of the rollup
@@ -253,6 +263,29 @@ const HEADER_AGGREGATES = [
     { alias: "aggExpiresAt", expression: argMaxDate("retentionDate") },
     { alias: "aggTags", expression: argMaxColumn("tags") },
 ];
+/*
+ * The narrow projection used by the audit-table summary lookup. Derive it
+ * from the list's aggregates so live duration and replacement-row handling
+ * cannot drift between the two reads.
+ */
+const SESSION_SUMMARY_AGGREGATE_ALIASES = [
+    "aggStartTime",
+    "aggDurationMs",
+    "aggEntryUrl",
+    "aggBrowserName",
+    "aggBrowserVersion",
+    "aggOsName",
+    "aggDeviceType",
+];
+const SESSION_SUMMARY_AGGREGATES = SESSION_SUMMARY_AGGREGATE_ALIASES.map((alias) => {
+    const column = HEADER_AGGREGATES.find((candidate) => {
+        return candidate.alias === alias;
+    });
+    if (!column) {
+        throw new Error(`HEADER_AGGREGATES has no column aliased ${alias}`);
+    }
+    return column;
+});
 /* Only the manifest needs these; the list never renders them. */
 const HEADER_DETAIL_AGGREGATES = [
     { alias: "aggMaskingMode", expression: argMaxColumn("maskingMode") },
@@ -535,6 +568,75 @@ function readStringMap(row, key) {
 function readDate(row, key) {
     return new Date(readNumber(row, key));
 }
+/*
+ * A number that has to be MEASURED, not defaulted. readNumber answers 0 for
+ * a missing or garbled value, which is the right degradation for a counter
+ * on a table row but the wrong one for a clock the "has this tab ended?"
+ * rule compares: a missing last-chunk start read as 0 would sit before
+ * every final chunk and call a live tab ended. NaN instead, which the
+ * shared rule refuses outright.
+ */
+function readMeasuredNumber(row, key) {
+    const value = row[key];
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : Number.NaN;
+    }
+    /* Number("") and Number(" ") are 0, which is exactly the default above. */
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : Number.NaN;
+    }
+    return Number.NaN;
+}
+/*
+ * The per-tab facts the shared rule in
+ * Common/Utils/Rum/SessionReplayRecordingEnded.ts is judged on, written
+ * exactly as that file documents them. The clocks and the version are
+ * wrapped in toFloat64 for the same reason as every wide column above:
+ * ClickHouse's JSON format quotes Int64 and UInt64 as strings. The chunk
+ * index is an Int32 and would come back as a number anyway; it is wrapped
+ * too so every fact in the group parses the same way. The aliases do not
+ * collide with a real column (see the NOTE on aliases at the top of this
+ * file).
+ *
+ * Two of the five are not about the tab's own clock:
+ *
+ * - tabMaxChunkIndex lets the rule call a tab that stored its last
+ *   permitted chunk index ended. The ingest gate refuses everything past
+ *   it, the recorder's own truncation seal included, so that tab never
+ *   gets a final chunk and would otherwise read as "recording" until the
+ *   idle finalizer.
+ * - tabLastChunkStoredAtUnixMs is max(version): the SERVER unix ms at
+ *   which the tab's newest chunk row was written. The grace is measured
+ *   on it, never on the device clock the chunk times come from.
+ */
+const TAB_HAS_FINAL_CHUNK_ALIAS = "tabHasFinalChunk";
+const TAB_FINAL_CHUNK_END_ALIAS = "tabFinalChunkEndUnixMs";
+const TAB_LAST_CHUNK_START_ALIAS = "tabLastChunkStartUnixMs";
+const TAB_MAX_CHUNK_INDEX_ALIAS = "tabMaxChunkIndex";
+const TAB_LAST_CHUNK_STORED_AT_ALIAS = "tabLastChunkStoredAtUnixMs";
+const TAB_END_FACT_AGGREGATES = [
+    {
+        alias: TAB_HAS_FINAL_CHUNK_ALIAS,
+        expression: "max(toUInt8(isFinal))",
+    },
+    {
+        alias: TAB_FINAL_CHUNK_END_ALIAS,
+        expression: "toFloat64(toUnixTimestamp64Milli(maxIf(chunkEndTime, isFinal)))",
+    },
+    {
+        alias: TAB_LAST_CHUNK_START_ALIAS,
+        expression: "toFloat64(toUnixTimestamp64Milli(max(chunkStartTime)))",
+    },
+    {
+        alias: TAB_MAX_CHUNK_INDEX_ALIAS,
+        expression: "toFloat64(max(chunkIndex))",
+    },
+    {
+        alias: TAB_LAST_CHUNK_STORED_AT_ALIAS,
+        expression: "toFloat64(max(version))",
+    },
+];
 /*
  * The capability list chunk 0 declared, filtered to the vocabulary this
  * build knows so a stored typo never reaches the player as a capability.
@@ -576,6 +678,82 @@ export default class SessionReplayReadService {
     static clearActivitySummaryCache() {
         activitySummaryCache.clear();
     }
+    /*
+     * Resolve the opaque ids stored on audit rows into compact session facts.
+     * This is intentionally one bespoke query instead of N getSessionHeader
+     * calls (or AnalyticsModelAPI, which RumSession does not expose). The
+     * project and application are both pinned before the caller-controlled IN
+     * list, and argMax collapses provisional/finalized ReplacingMergeTree rows.
+     */
+    static async getSessionSummaries(request) {
+        if (request.sessionIds.length === 0) {
+            throw new BadDataException("sessionIds must contain at least one id");
+        }
+        if (request.sessionIds.length > MAX_SESSION_REPLAY_SUMMARIES_BATCH_SIZE) {
+            throw new BadDataException(`sessionIds must contain at most ${MAX_SESSION_REPLAY_SUMMARIES_BATCH_SIZE} ids`);
+        }
+        for (const sessionId of request.sessionIds) {
+            if (typeof sessionId !== "string" || sessionId.length === 0) {
+                throw new BadDataException("Every sessionId must be a non-empty string");
+            }
+            if (sessionId.length > MAX_SESSION_REPLAY_SESSION_ID_LENGTH) {
+                throw new BadDataException(`Every sessionId must be at most ${MAX_SESSION_REPLAY_SESSION_ID_LENGTH} characters.`);
+            }
+        }
+        /* Preserve first occurrence order while binding every id only once. */
+        const sessionIds = Array.from(new Set(request.sessionIds));
+        const statement = SQL `
+      SELECT
+        sessionId,
+    `;
+        statement.append(`    ${toSelectList(SESSION_SUMMARY_AGGREGATES)}`);
+        statement.append(SQL `
+      FROM ${AnalyticsTableName.RumSession}
+      WHERE projectId = ${{
+            type: TableColumnType.ObjectID,
+            value: request.projectId,
+        }}
+        AND rumApplicationId = ${{
+            type: TableColumnType.ObjectID,
+            value: request.rumApplicationId,
+        }}
+        AND sessionId IN (${{
+            type: TableColumnType.Text,
+            value: new Includes(sessionIds),
+        }})
+    `);
+        statement.append(RETENTION_FILTER);
+        statement.append(" GROUP BY projectId, rumApplicationId, sessionId ORDER BY aggStartTime DESC");
+        statement.append(READ_QUERY_SETTINGS);
+        const dbResult = await RumSessionService.executeQuery(statement);
+        const response = await dbResult.json();
+        const requestedIds = new Set(sessionIds);
+        const summariesById = new Map();
+        for (const row of response.data || []) {
+            const sessionId = readString(row, "sessionId");
+            /* A malformed/unexpected driver row can never add data to the reply. */
+            if (!requestedIds.has(sessionId) || summariesById.has(sessionId)) {
+                continue;
+            }
+            const startTime = readDate(row, "aggStartTime");
+            summariesById.set(sessionId, {
+                sessionId: sessionId,
+                startTime: startTime,
+                startTimeUnixMs: startTime.getTime(),
+                durationMs: readNumber(row, "aggDurationMs"),
+                entryUrl: readString(row, "aggEntryUrl"),
+                browserName: readString(row, "aggBrowserName"),
+                browserVersion: readString(row, "aggBrowserVersion"),
+                osName: readString(row, "aggOsName"),
+                deviceType: readString(row, "aggDeviceType"),
+            });
+        }
+        /* Stable request order makes consumers deterministic; missing ids omit. */
+        return sessionIds.flatMap((sessionId) => {
+            const summary = summariesById.get(sessionId);
+            return summary ? [summary] : [];
+        });
+    }
     /*
      * Session list.
      *
@@ -596,6 +774,7 @@ export default class SessionReplayReadService {
      * the truth - or, worse, would drop the group entirely.
      */
     static async listSessions(request) {
+        var _a;
         const limit = Math.max(1, Math.min(request.limit, MAX_SESSION_REPLAY_LIST_LIMIT));
         const sortBy = request.sortBy || "startTime";
         if (!SESSION_REPLAY_SORT_BY_VALUES.includes(sortBy)) {
@@ -740,6 +919,8 @@ export default class SessionReplayReadService {
                 tags: readStringMap(row, "aggTags"),
                 startTimeUnixMs: startTime.getTime(),
                 endTimeUnixMs: endTime.getTime(),
+                /* Judged below, only for the page's unfinalized sessions. */
+                hasRecordingEnded: false,
             };
             if (request.includeIdentifiedUserLabel) {
                 item.identifiedUserLabel = readString(row, "aggIdentifiedUserLabel");
@@ -747,6 +928,40 @@ export default class SessionReplayReadService {
             }
             return item;
         });
+        /*
+         * "Recording now" or "recording ended"? The header cannot say: a
+         * provisional header stays unfinalized for the whole idle window
+         * after its last tab closed, which is how a closed tab kept its
+         * "Recording now" badge for 10-15 minutes. The chunk rows can, so the
+         * page's unfinalized sessions - and only those - get ONE follow-up
+         * read over the chunk table. A page of finalized sessions (the
+         * overwhelming majority of any list older than a few minutes) runs
+         * no second query at all.
+         *
+         * It is a separate statement rather than a JOIN on the list query
+         * because the list's own read is a range over the HEADER table's sort
+         * key, and joining the chunk table there would aggregate chunk rows
+         * for every session in the window before the LIMIT picked a page.
+         */
+        const unfinalizedSessionIds = sessions
+            .filter((session) => {
+            return !session.isFinalized;
+        })
+            .map((session) => {
+            return session.sessionId;
+        });
+        if (unfinalizedSessionIds.length > 0) {
+            const endedSessionIds = await SessionReplayReadService.readRecordingEndedSessionIds({
+                projectId: request.projectId,
+                rumApplicationId: request.rumApplicationId,
+                sessionIds: unfinalizedSessionIds,
+                nowUnixMs: (_a = request.nowUnixMs) !== null && _a !== void 0 ? _a : Date.now(),
+            });
+            for (const session of sessions) {
+                session.hasRecordingEnded =
+                    !session.isFinalized && endedSessionIds.has(session.sessionId);
+            }
+        }
         const lastSession = sessions[sessions.length - 1];
         return {
             sessions: sessions,
@@ -1051,6 +1266,12 @@ export default class SessionReplayReadService {
             recorderCapabilities: readRecorderCapabilities(row),
             identifiedUserKey: readString(row, "aggIdentifiedUserKey"),
             visitorId: readString(row, "aggVisitorId"),
+            /*
+             * Not judged here: see SessionReplaySessionHeader.hasRecordingEnded.
+             * getManifest, the read that returns this header to the Dashboard,
+             * replaces it for an unfinalized session.
+             */
+            hasRecordingEnded: false,
         };
     }
     /*
@@ -1153,6 +1374,7 @@ export default class SessionReplayReadService {
      * megabytes of decompressed recording.
      */
     static async getManifest(data) {
+        var _a;
         /*
          * LIMIT 1 BY (tabId, chunkIndex) after ORDER BY ... version DESC
          * keeps exactly the highest-version row per chunk. tabId is part of
@@ -1205,7 +1427,34 @@ export default class SessionReplayReadService {
             value: MAX_MANIFEST_ROWS,
         }}`);
         statement.append(READ_QUERY_SETTINGS);
-        const dbResult = await RumSessionChunkService.executeQuery(statement);
+        /*
+         * Whether this unfinalized session's recording is already over, read
+         * alongside the manifest rather than after it: the player re-fetches
+         * the manifest every 30s while a session is not finalized, and this
+         * is what lets it stop calling a closed session "Live" once the
+         * ended grace has passed, instead of waiting for a finalizer run to
+         * seal the header. The same helper, the same grace and the same
+         * clock the list uses, so the list badge and the player pill can
+         * never disagree about one session.
+         *
+         * Its own grouped read rather than a fold over the rows below: those
+         * rows are capped at MAX_MANIFEST_ROWS in (tabId, chunkIndex) order, so
+         * a truncated manifest would lose a tab's newest chunks - exactly the
+         * rows that say whether it kept recording after its final chunk. A
+         * finalized header is authoritative and runs no second read. The
+         * helper never rejects (a failure answers "not ended"), so it cannot
+         * fail the manifest. The manifest statement is issued first.
+         */
+        const manifestResultPromise = RumSessionChunkService.executeQuery(statement);
+        const endedSessionIdsPromise = data.header.isFinalized
+            ? Promise.resolve(new Set())
+            : SessionReplayReadService.readRecordingEndedSessionIds({
+                projectId: data.projectId,
+                rumApplicationId: data.rumApplicationId,
+                sessionIds: [data.sessionId],
+                nowUnixMs: (_a = data.nowUnixMs) !== null && _a !== void 0 ? _a : Date.now(),
+            });
+        const [dbResult, endedSessionIds] = await Promise.all([manifestResultPromise, endedSessionIdsPromise]);
         const response = await dbResult.json();
         const rows = response.data || [];
         const tabsById = new Map();
@@ -1287,6 +1536,7 @@ export default class SessionReplayReadService {
                 liveDurationMs: liveDurationMs,
                 liveEventCount: liveEventCount,
                 liveMaxChunkIndex: liveMaxChunkIndex,
+                hasRecordingEnded: endedSessionIds.has(data.sessionId),
             }),
             tabs: tabs,
             isChunkIndexTruncated: rows.length >= MAX_MANIFEST_ROWS,
@@ -1297,14 +1547,143 @@ export default class SessionReplayReadService {
      * 0 and eventCount 0 while its chunk rows say otherwise; the manifest
      * has just read every chunk row, so it reports what the rows prove. A
      * finalized header is authoritative and returned untouched.
+     *
+     * hasRecordingEnded is set on every unfinalized header, including one
+     * whose chunk rows have not landed yet: getSessionHeader never judges
+     * it, so the manifest is the only place the field is ever true.
      */
     static reconcileLiveHeader(data) {
-        if (data.header.isFinalized || data.chunkRowCount === 0) {
+        if (data.header.isFinalized) {
             return data.header;
         }
+        if (data.chunkRowCount === 0) {
+            return Object.assign(Object.assign({}, data.header), { hasRecordingEnded: data.hasRecordingEnded });
+        }
         const durationMs = Math.max(data.header.durationMs, data.liveDurationMs);
         const endTimeUnixMs = Math.max(data.header.endTimeUnixMs, data.header.startTimeUnixMs + durationMs);
-        return Object.assign(Object.assign({}, data.header), { durationMs: durationMs, endTime: new Date(endTimeUnixMs), endTimeUnixMs: endTimeUnixMs, chunkCount: Math.max(data.header.chunkCount, data.chunkRowCount), eventCount: Math.max(data.header.eventCount, data.liveEventCount), maxChunkIndex: Math.max(data.header.maxChunkIndex, data.liveMaxChunkIndex) });
+        return Object.assign(Object.assign({}, data.header), { durationMs: durationMs, endTime: new Date(endTimeUnixMs), endTimeUnixMs: endTimeUnixMs, chunkCount: Math.max(data.header.chunkCount, data.chunkRowCount), eventCount: Math.max(data.header.eventCount, data.liveEventCount), maxChunkIndex: Math.max(data.header.maxChunkIndex, data.liveMaxChunkIndex), hasRecordingEnded: data.hasRecordingEnded });
+    }
+    /*
+     * Which of these unfinalized sessions have stopped recording, judged by
+     * the shared rule (Common/Utils/Rum/SessionReplayRecordingEnded.ts) over
+     * their chunk rows. The one helper behind both the list badge and the
+     * player's Live pill.
+     *
+     * One statement for any number of sessions:
+     *
+     *   WHERE projectId = ? AND sessionId IN (...) AND rumApplicationId = ?
+     *   GROUP BY sessionId, tabId
+     *
+     * A KEY-RANGE READ. RumSessionChunk is sorted (and primary-keyed) by
+     * (projectId, sessionId, tabId, chunkIndex), so projectId plus a
+     * sessionId IN list is a prefix of the primary index: ClickHouse reads
+     * only the granules of the named sessions - a handful of narrow columns
+     * over at most a few hundred rows each - and never the payload column.
+     * The GROUP BY follows the same key order. rumApplicationId is a plain
+     * column filtered over those granules, and it is not optional: the
+     * table's replace key has no application in it, so two applications
+     * that share a browser-minted sessionId share one key space, and
+     * without the pin one application's closed tab could end another's
+     * recording.
+     *
+     * Grouped per tab, never per session, because the rule is per tab: a
+     * session shared by several tabs (or several page loads of a multi-page
+     * app) is over only when every one of them is. The five aggregates are
+     * maxima, so a redelivered chunk's duplicate row - or a pinned copy -
+     * cannot make a live tab look ended and no LIMIT 1 BY is needed. Such a
+     * row can carry a NEWER version than the original, which only restarts
+     * the grace once; it never shortens it. The retention filter is kept
+     * like on every other replay read.
+     *
+     * The grace. Every tab having ended is not enough on its own: in a
+     * multi-page app, page A's final chunk lands while page B - a new tab id
+     * under the same session - has not stored its first chunk yet, and for
+     * that moment the only tab the rows know about has ended. So the rule
+     * also wants the newest stored chunk of the session to be at least
+     * SESSION_REPLAY_ENDED_FINALIZE_GRACE_MS older than nowUnixMs, the same
+     * grace the finalizer waits on, measured on the same server clock (the
+     * rows' version against this process's Date.now()). The list, the player
+     * and the finalizer therefore call a session ended at the same moment,
+     * give or take the finalizer's one-minute schedule, and none of them
+     * depends on Redis for it.
+     *
+     * Best-effort. A failure logs a warning and answers "nothing has ended",
+     * which is what the Dashboard showed before this existed; neither the
+     * list nor the manifest may fail because of it. A session with no chunk
+     * rows has no tabs, and no tabs is "not known", never "ended".
+     */
+    static async readRecordingEndedSessionIds(data) {
+        const endedSessionIds = new Set();
+        const sessionIds = Array.from(new Set(data.sessionIds.filter((sessionId) => {
+            return sessionId.length > 0;
+        })));
+        if (sessionIds.length === 0) {
+            return endedSessionIds;
+        }
+        const statement = SQL `
+      SELECT
+        sessionId,
+        tabId,
+    `;
+        statement.append(`    ${toSelectList(TAB_END_FACT_AGGREGATES)}`);
+        statement.append(SQL `
+      FROM ${AnalyticsTableName.RumSessionChunk}
+      WHERE projectId = ${{
+            type: TableColumnType.ObjectID,
+            value: data.projectId,
+        }}
+        AND sessionId IN (${{
+            type: TableColumnType.Text,
+            value: new Includes(sessionIds),
+        }})
+        AND rumApplicationId = ${{
+            type: TableColumnType.ObjectID,
+            value: data.rumApplicationId,
+        }}
+    `);
+        statement.append(RETENTION_FILTER);
+        statement.append(" GROUP BY sessionId, tabId");
+        statement.append(READ_QUERY_SETTINGS);
+        let rows;
+        try {
+            const dbResult = await RumSessionChunkService.executeQuery(statement);
+            const response = await dbResult.json();
+            rows = response.data || [];
+        }
+        catch (err) {
+            logger.warn("SessionReplayReadService: could not read chunk rows to tell whether unfinalized sessions have ended; reporting them as still recording");
+            logger.warn(err);
+            return endedSessionIds;
+        }
+        const requested = new Set(sessionIds);
+        const tabsBySessionId = new Map();
+        for (const row of rows) {
+            const sessionId = readString(row, "sessionId");
+            /* Defensive: a row for a session nobody asked about decides nothing. */
+            if (!requested.has(sessionId)) {
+                continue;
+            }
+            const tab = {
+                hasFinalChunk: readBoolean(row, TAB_HAS_FINAL_CHUNK_ALIAS),
+                finalChunkEndUnixMs: readMeasuredNumber(row, TAB_FINAL_CHUNK_END_ALIAS),
+                lastChunkStartUnixMs: readMeasuredNumber(row, TAB_LAST_CHUNK_START_ALIAS),
+                maxChunkIndex: readMeasuredNumber(row, TAB_MAX_CHUNK_INDEX_ALIAS),
+                lastChunkStoredAtUnixMs: readMeasuredNumber(row, TAB_LAST_CHUNK_STORED_AT_ALIAS),
+            };
+            const existing = tabsBySessionId.get(sessionId);
+            if (existing) {
+                existing.push(tab);
+            }
+            else {
+                tabsBySessionId.set(sessionId, [tab]);
+            }
+        }
+        for (const [sessionId, tabs] of tabsBySessionId) {
+            if (hasSessionRecordingEnded(tabs, data.nowUnixMs)) {
+                endedSessionIds.add(sessionId);
+            }
+        }
+        return endedSessionIds;
     }
     /*
      * The payload read. The only query in the system that names the
@@ -1451,11 +1830,22 @@ export default class SessionReplayReadService {
      * fingerprint present only on a superseded row does not produce a false
      * positive.
      *
-     * Always windowed. RumSession is partitioned by day, so without a
-     * window this scanned every partition the project ever wrote on every
-     * exception page load.
+     * Typed RUM and fully unscoped legacy lookups are windowed in WHERE for
+     * partition pruning. Scoped non-RUM and ID-only type-unknown lookups apply
+     * the window in QUALIFY: their instance-proven session ids must first be
+     * checked across every retained application in the project so a duplicate
+     * id cannot be hidden outside the caller's time or authorization scope.
      */
     static async getSessionsForException(data) {
+        const hasPrimaryEntityId = data.primaryEntityId !== undefined;
+        const hasPrimaryEntityType = data.primaryEntityType !== undefined;
+        if (!hasPrimaryEntityId && hasPrimaryEntityType) {
+            throw new BadDataException("primaryEntityId is required with its type");
+        }
+        if (data.primaryEntityType !== undefined &&
+            !Object.values(ServiceType).includes(data.primaryEntityType)) {
+            throw new BadDataException("primaryEntityType is not valid");
+        }
         if (data.accessibleRumApplicationIds &&
             data.accessibleRumApplicationIds.length === 0) {
             return [];
@@ -1467,10 +1857,23 @@ export default class SessionReplayReadService {
         const instanceSessionIds = await SessionReplayReadService.getSessionIdsForExceptionInstances({
             projectId: data.projectId,
             exceptionFingerprint: data.exceptionFingerprint,
+            primaryEntityId: data.primaryEntityId,
+            primaryEntityType: data.primaryEntityType,
             startTime: startTime,
             endTime: endTime,
             sessionId: data.sessionId,
         });
+        const isScopedRumException = data.primaryEntityType === ServiceType.RealUserMonitor;
+        const isScopedNonRumOrUnknownException = hasPrimaryEntityId && !isScopedRumException;
+        /*
+         * A finalized replay header has only a flat fingerprint list. For a
+         * non-RUM or legacy type-unknown entity that list cannot prove ownership,
+         * so only the scoped instance side index may admit a session. Failure or
+         * an empty lookup must therefore fail closed.
+         */
+        if (isScopedNonRumOrUnknownException && instanceSessionIds.length === 0) {
+            return [];
+        }
         const selectList = toSelectList([
             { alias: "aggStartTime", expression: argMaxDateTime("startTime") },
             { alias: "aggEndTime", expression: argMaxDateTime("endTime") },
@@ -1517,6 +1920,10 @@ export default class SessionReplayReadService {
         toString(rumApplicationId) AS applicationId,
     `;
         statement.append(`    ${selectList}`);
+        if (isScopedNonRumOrUnknownException) {
+            /* One grouped row per application makes this a cross-app collision count. */
+            statement.append(", count() OVER (PARTITION BY sessionId) AS matchedApplicationCount");
+        }
         statement.append(SQL `
       FROM ${AnalyticsTableName.RumSession}
       WHERE projectId = ${{
@@ -1524,19 +1931,26 @@ export default class SessionReplayReadService {
             value: data.projectId,
         }}
     `);
-        if (data.accessibleRumApplicationIds) {
+        /*
+         * For non-RUM and legacy type-unknown exceptions, authorization belongs
+         * in QUALIFY after the window has counted inaccessible applications too.
+         * Applying it here would make an ambiguous id appear unique.
+         */
+        if (!isScopedNonRumOrUnknownException && data.accessibleRumApplicationIds) {
             statement.append(SQL ` AND rumApplicationId IN (${{
                 type: TableColumnType.ObjectID,
                 value: new Includes(data.accessibleRumApplicationIds),
             }})`);
         }
-        statement.append(SQL ` AND startTime >= ${{
-            type: TableColumnType.DateTime64,
-            value: startTime,
-        }} AND startTime <= ${{
-            type: TableColumnType.DateTime64,
-            value: endTime,
-        }}`);
+        if (!isScopedNonRumOrUnknownException) {
+            statement.append(SQL ` AND startTime >= ${{
+                type: TableColumnType.DateTime64,
+                value: startTime,
+            }} AND startTime <= ${{
+                type: TableColumnType.DateTime64,
+                value: endTime,
+            }}`);
+        }
         statement.append(RETENTION_FILTER);
         if (data.sessionId) {
             statement.append(SQL ` AND sessionId = ${{
@@ -1544,29 +1958,69 @@ export default class SessionReplayReadService {
                 value: data.sessionId,
             }}`);
         }
-        statement.append(SQL ` AND (hasAny(exceptionFingerprints, [${{
-            type: TableColumnType.Text,
-            value: data.exceptionFingerprint,
-        }}])`);
-        if (instanceSessionIds.length > 0) {
-            statement.append(SQL ` OR sessionId IN (${{
+        if (isScopedRumException && data.primaryEntityId) {
+            /* Both finalized fingerprints and instance-proven ids stay in this RUM app. */
+            statement.append(SQL ` AND rumApplicationId = ${{
+                type: TableColumnType.ObjectID,
+                value: data.primaryEntityId,
+            }}`);
+        }
+        statement.append(" AND (");
+        if (isScopedNonRumOrUnknownException) {
+            statement.append(SQL `sessionId IN (${{
                 type: TableColumnType.Text,
                 value: new Includes(instanceSessionIds),
             }})`);
         }
-        statement.append(")");
-        statement.append(SQL ` GROUP BY projectId, rumApplicationId, sessionId
-           HAVING (hasAny(aggExceptionFingerprints, [${{
-            type: TableColumnType.Text,
-            value: data.exceptionFingerprint,
-        }}])`);
-        if (instanceSessionIds.length > 0) {
+        else {
+            statement.append(SQL `hasAny(exceptionFingerprints, [${{
+                type: TableColumnType.Text,
+                value: data.exceptionFingerprint,
+            }}])`);
+        }
+        if (!isScopedNonRumOrUnknownException && instanceSessionIds.length > 0) {
             statement.append(SQL ` OR sessionId IN (${{
                 type: TableColumnType.Text,
                 value: new Includes(instanceSessionIds),
             }})`);
         }
         statement.append(")");
+        statement.append(" GROUP BY projectId, rumApplicationId, sessionId");
+        if (isScopedNonRumOrUnknownException) {
+            /*
+             * Windowing happens over every application before either the time
+             * window or accessible-app filter is applied. QUALIFY also precedes
+             * ORDER/LIMIT, so a second application can never be sorted away.
+             */
+            statement.append(" QUALIFY matchedApplicationCount = 1");
+            statement.append(SQL ` AND aggStartTime >= ${{
+                type: TableColumnType.BigNumber,
+                value: startTime.getTime(),
+            }} AND aggStartTime <= ${{
+                type: TableColumnType.BigNumber,
+                value: endTime.getTime(),
+            }}`);
+            if (data.accessibleRumApplicationIds) {
+                statement.append(SQL ` AND rumApplicationId IN (${{
+                    type: TableColumnType.ObjectID,
+                    value: new Includes(data.accessibleRumApplicationIds),
+                }})`);
+            }
+        }
+        else {
+            statement.append(" HAVING (");
+            statement.append(SQL `hasAny(aggExceptionFingerprints, [${{
+                type: TableColumnType.Text,
+                value: data.exceptionFingerprint,
+            }}])`);
+            if (instanceSessionIds.length > 0) {
+                statement.append(SQL ` OR sessionId IN (${{
+                    type: TableColumnType.Text,
+                    value: new Includes(instanceSessionIds),
+                }})`);
+            }
+            statement.append(")");
+        }
         statement.append(SQL ` ORDER BY aggStartTime DESC
            LIMIT ${{
             type: TableColumnType.Number,
@@ -1575,7 +2029,16 @@ export default class SessionReplayReadService {
         statement.append(READ_QUERY_SETTINGS);
         const dbResult = await RumSessionService.executeQuery(statement);
         const response = await dbResult.json();
-        return (response.data || []).map((row) => {
+        const responseRows = (response.data || []).filter((row) => {
+            /*
+             * QUALIFY is authoritative. Its count was computed over every app
+             * before ORDER/LIMIT, so retaining only count=1 is also a fail-closed
+             * guard if a changed driver ever returns a row that should not survive.
+             */
+            return (!isScopedNonRumOrUnknownException ||
+                readNumber(row, "matchedApplicationCount") === 1);
+        });
+        return responseRows.map((row) => {
             return {
                 sessionId: readString(row, "sessionId"),
                 rumApplicationId: readString(row, "applicationId"),
@@ -1604,9 +2067,10 @@ export default class SessionReplayReadService {
      * session, so a session that started inside the window threw inside
      * [startTime, endTime + max session length].
      *
-     * Best-effort: the side index only ADDS live sessions to the answer, so
-     * a failure here degrades to the finalized-only lookup with a warning
-     * rather than failing the exception page's replay card.
+     * Best-effort for fully unscoped legacy and typed RUM lookups: there it only
+     * ADDS live sessions, so a failure degrades to finalized headers. Scoped
+     * non-RUM and ID-only lookups rely on it as their sole entity-ownership
+     * proof and therefore fail closed.
      *
      * A caller-pinned sessionId narrows the lookup rather than bypassing it,
      * so the pin can never assert that a session threw something the
@@ -1634,6 +2098,25 @@ export default class SessionReplayReadService {
             value: new Date(data.endTime.getTime() + SESSION_REPLAY_MAX_SESSION_MS),
         }}
     `;
+        if (data.primaryEntityId) {
+            statement.append(SQL ` AND primaryEntityId = ${{
+                type: TableColumnType.ObjectID,
+                value: data.primaryEntityId,
+            }}`);
+        }
+        if (data.primaryEntityType === ServiceType.OpenTelemetry) {
+            /* NULL/empty is the historical discriminator for an OTel service. */
+            statement.append(SQL ` AND (ifNull(primaryEntityType, '') = '' OR primaryEntityType = ${{
+                type: TableColumnType.Text,
+                value: ServiceType.OpenTelemetry,
+            }})`);
+        }
+        else if (data.primaryEntityType) {
+            statement.append(SQL ` AND primaryEntityType = ${{
+                type: TableColumnType.Text,
+                value: data.primaryEntityType,
+            }}`);
+        }
         /*
          * A pinned sessionId narrows this lookup; it does NOT replace it.
          *
@@ -1674,7 +2157,7 @@ export default class SessionReplayReadService {
             });
         }
         catch (err) {
-            logger.warn("SessionReplayReadService: could not look up exception instances by session; answering from finalized headers only");
+            logger.warn("SessionReplayReadService: could not look up exception instances by session; scoped non-RUM lookups fail closed and other lookups answer from finalized headers only");
             logger.warn(err);
             return [];
         }
@@ -2073,6 +2556,12 @@ export default class SessionReplayReadService {
         statement.append(")");
     }
 }
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SessionReplayReadService, "getSessionSummaries", null);
 __decorate([
     CaptureSpan(),
     __metadata("design:type", Function),