Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

ralph(M12-005): realtime/realtime.service.ts onto the sql tag: 0 sqlstring and 0 clix in realtime, the lazy `await import('@openpanel/db')` gone, proof, goldens 137/137

ralph78098bdca075
diff --git a/packages/core/src/modules/realtime/realtime.routes.test.ts b/packages/core/src/modules/realtime/realtime.routes.test.ts
index 468f74b45..66ff605c4 100644
--- a/packages/core/src/modules/realtime/realtime.routes.test.ts
+++ b/packages/core/src/modules/realtime/realtime.routes.test.ts
@@ -15,21 +15,21 @@
// auth.service.ts's `createAuthService` binds `ctx.services.auth` to,
// M10-002) are mocked (not a real Postgres/ClickHouse/Redis), and
// `../../http/session` for the same reason http/auth.test.ts mocks it:
-// `resolveSession` is still a P6 stub. Every mock is registered before the
-// subject's first (dynamic, per-connection) call — see AGENTS.md's
-// `mock.module` idiom.
-
-import {
- afterAll,
- afterEach,
- beforeAll,
- beforeEach,
- expect,
- mock,
- test,
-} from 'bun:test';
+// `resolveSession` is still a P6 stub.
+//
+// M12-005: every import here is STATIC. Bun 1.4.0's `mock.module` swaps an
+// already-loaded module's exports in place, so a subject imported above the
+// `mock.module` calls still sees them; the "not called" and "called with"
+// assertions on every mock below are what would go red if that ever stopped
+// holding. The deferred loads this file used to need are gone with the
+// module's own (docs/TECH_DEBT.md's no-lazy-loaders ruling).
+
+import { afterAll, afterEach, beforeEach, expect, mock, test } from 'bun:test';
import { stubAppDeps } from '../../../test/http-fixtures';
+import * as actualAccessLookups from '../../shared/access-lookups';
import { getSuperJson } from '../../shared/json';
+import { realtimeRoutes } from './realtime.routes';
+import * as actualService from './realtime.service';
let visitorActivityCallback: (() => void) | undefined;
const unsubscribeVisitorActivity = mock(() => undefined);
@@ -60,12 +60,10 @@ const getActiveVisitorCount = mock(async () => activeVisitorCount);
// Spread the real module rather than hand-listing every export:
// `mock.module` replaces this specifier process-wide (bun shares one module
// registry across files without `--isolate` — see AGENTS.md), and
-// realtime.service.test.ts's own `beforeAll` does `await
-// import('./realtime.service')` expecting the real implementation. A plain
-// snapshot, not the live import binding — see gsc.service.test.ts's
-// clickhouse/client mock for why the live binding would make a
-// same-binding "restore" a no-op.
-const actualService = await import('./realtime.service');
+// realtime.service.test.ts imports `./realtime.service` expecting the real
+// implementation. A plain snapshot, not the live import binding — see
+// gsc.service.test.ts's clickhouse/client mock for why the live binding would
+// make a same-binding "restore" a no-op.
const realService = { ...actualService };
mock.module('./realtime.service', () => ({
...realService,
@@ -84,7 +82,6 @@ afterAll(() => {
// binds these same lookups in auth.service.ts, so mocking them here is what
// makes `ws.data.ctx.services.auth.getProjectAccess`/`getOrganizationAccess`
// observable from the test.
-const actualAccessLookups = await import('../../shared/access-lookups');
let projectAccess: { level: string } | null = null;
let organizationAccess: { role: string } | null = null;
const getProjectAccess = mock(async () => projectAccess);
@@ -102,11 +99,6 @@ mock.module('../../http/session', () => ({
resolveSession,
}));
-let realtimeRoutes: typeof import('./realtime.routes').realtimeRoutes;
-beforeAll(async () => {
- ({ realtimeRoutes } = await import('./realtime.routes'));
-});
-
let app: ReturnType<typeof realtimeRoutes>;
let port: number;
diff --git a/packages/core/src/modules/realtime/realtime.rpc.test.ts b/packages/core/src/modules/realtime/realtime.rpc.test.ts
index e94b4fbae..5e6909879 100644
--- a/packages/core/src/modules/realtime/realtime.rpc.test.ts
+++ b/packages/core/src/modules/realtime/realtime.rpc.test.ts
@@ -1,8 +1,9 @@
// Only the "is anyone logged in" boundary is exercised here — no database.
-// The access-check + query bodies ride on @openpanel/db (lazy-loaded, see
-// realtime.service.ts's header); wiring this router end-to-end against a
-// real ClickHouse is P6's (protectedProcedure) job, not this one's — see
-// realtime.rpc.ts's header. Same shape as cohort.rpc.test.ts.
+// The query bodies run on `deps.ch` (M12-005: statically imported `sql`
+// fragments, no @openpanel/db client anywhere in the module); wiring this
+// router end-to-end against a real ClickHouse is P6's (protectedProcedure)
+// job, not this one's — see realtime.rpc.ts's header. Same shape as
+// cohort.rpc.test.ts.
import { expect, test } from 'bun:test';
import { stubHttpCtx } from '../../../test/rpc-fixtures';
diff --git a/packages/core/src/modules/realtime/realtime.service.test.ts b/packages/core/src/modules/realtime/realtime.service.test.ts
index cb84d0a02..02dc5bc0e 100644
--- a/packages/core/src/modules/realtime/realtime.service.test.ts
+++ b/packages/core/src/modules/realtime/realtime.service.test.ts
@@ -4,6 +4,13 @@
// reached lazily (see the subject's `loadRedis` header), so that one stays a
// `mock.module` registered before the subject's first call.
//
+// M12-005: the subject and the real-module snapshot are STATIC imports. Bun's
+// `mock.module` swaps an already-loaded module's exports in place, and the
+// subject only reaches `@openpanel/redis` lazily at call time, so the mock
+// below still applies — measured on Bun 1.4.0, and the subscribe assertions
+// go red if it ever stops. That leaves this module with no deferred loads at
+// all (docs/TECH_DEBT.md's no-lazy-loaders ruling).
+//
// Every assertion below is the one it was before the deps switch: the same
// project scoping, the same 30-minute window, the same filter/limit wiring,
// the same subscribe/unsubscribe behaviour.
@@ -16,7 +23,9 @@
// unauthenticated-boundary tests plus this repo's local ClickHouse run (see
// the task summary for the executed query + row count).
-import { afterAll, beforeAll, beforeEach, expect, mock, test } from 'bun:test';
+import { afterAll, beforeEach, expect, mock, test } from 'bun:test';
+import * as actualRedis from '@openpanel/redis';
+import * as subject from './realtime.service';
const activeVisitorCountByProject = new Map<string, number>();
const eventBuffer = {
@@ -37,7 +46,6 @@ let unsubscribeCalls = 0;
// Spread the real module — a partial factory here would be a process-wide
// hazard for every other test file mocking `@openpanel/redis` narrowly (see
// realtime.service.ts's `loadRedis` header for why this file exists at all).
-const actualRedis = await import('@openpanel/redis');
const realRedis = { ...actualRedis };
mock.module('@openpanel/redis', () => ({
...realRedis,
@@ -51,9 +59,20 @@ afterAll(() => {
// `deps.ch.query` is what shared/ch-query.ts calls; it returns the raw
// ClickHouse response envelope, so the stub speaks that shape.
let nextRows: unknown[] = [];
-const chQuery = mock(async ({ query: _query }: { query: string }) => ({
- json: async () => ({ data: nextRows, meta: [], rows: nextRows.length }),
-}));
+const chQuery = mock(
+ async (_args: {
+ query: string;
+ query_params: Record<string, string | number>;
+ }) => ({
+ json: async () => ({ data: nextRows, meta: [], rows: nextRows.length }),
+ })
+);
+
+const MINUTES_PER_REALTIME_WINDOW = 30;
+const MS_PER_MINUTE = 60_000;
+const REALTIME_WINDOW_MS = MINUTES_PER_REALTIME_WINDOW * MS_PER_MINUTE;
+const CLOCK_TOLERANCE_MS = 5000;
+const ACTIVE_SESSIONS_LIMIT = 50;
const noop = () => undefined;
const deps = {
@@ -70,12 +89,6 @@ const deps = {
},
} as unknown as import('../../services').ServiceDeps;
-let subject: typeof import('./realtime.service');
-
-beforeAll(async () => {
- subject = await import('./realtime.service');
-});
-
beforeEach(() => {
activeVisitorCountByProject.clear();
subscribeToPublishedEvent.mockClear();
@@ -179,10 +192,18 @@ test('getRealtimeActiveSessions scopes the query to the project and the 30-minut
const result = await subject.getRealtimeActiveSessions(deps, 'proj_1');
expect(chQuery).toHaveBeenCalledTimes(1);
- const { query } = chQuery.mock.calls[0]![0];
- expect(query).toContain("project_id = 'proj_1'");
- expect(query).toContain('created_at >=');
- expect(query).toContain('LIMIT 50');
+ // M12-005: the statement binds its values, so the project scoping and the
+ // window live in `query_params` — the assertion follows them there.
+ const { query, query_params } = chQuery.mock.calls[0]![0];
+ expect(query).toContain('project_id = {p1:String}');
+ expect(query).toContain('created_at >= {p2:String}');
+ expect(query).toContain('LIMIT {p3:UInt64}');
+ expect(query_params.p1).toBe('proj_1');
+ const windowStart = String(query_params.p2).replace(' ', 'T');
+ const windowAgeMs = Date.now() - Date.parse(`${windowStart}Z`);
+ expect(windowAgeMs).toBeGreaterThanOrEqual(REALTIME_WINDOW_MS);
+ expect(windowAgeMs).toBeLessThan(REALTIME_WINDOW_MS + CLOCK_TOLERANCE_MS);
+ expect(query_params.p3).toBe(ACTIVE_SESSIONS_LIMIT);
expect(result).toHaveLength(1);
expect(result[0]?.sessionId).toBe('sess_1');
});
diff --git a/packages/core/src/modules/realtime/realtime.service.ts b/packages/core/src/modules/realtime/realtime.service.ts
index 6e47493e1..f4c28900f 100644
--- a/packages/core/src/modules/realtime/realtime.service.ts
+++ b/packages/core/src/modules/realtime/realtime.service.ts
@@ -21,23 +21,31 @@
// same Redis subscription underneath.
//
// M10-005: every query function takes `ServiceDeps`. The ClickHouse CLIENT is
-// `deps.ch` — reads through shared/ch-query.ts, `clix(deps.ch)` for the four
-// builder queries — and the event buffer is `deps.buffers.event`, so the
-// `loadChClient` / `loadEventBuffer` lazy imports of @openpanel/db are gone
-// and the requestId reaches the query (ADR-018 R1, docs/TECH_DEBT.md §2, §4).
+// `deps.ch` — reads through shared/ch-query.ts — and the event buffer is
+// `deps.buffers.event`, so the `loadChClient` / `loadEventBuffer` lazy imports
+// of @openpanel/db are gone and the requestId reaches the query (ADR-018 R1,
+// docs/TECH_DEBT.md §2, §4).
//
-// ClickHouse queries here still go through clix/sqlstring, not the `sql` tag:
-// ADR-013 converts the analytics read path one query per P7 task, and this
-// module's queries haven't been converted yet. `clix` and `TABLE_NAMES` are
-// therefore still needed and come from the v1-compat seam's pure-helper hop
-// (project.service.ts's `loadChHelpers` does the same) rather than a direct
-// @openpanel/db import.
-
+// M12-005 converted all ten ClickHouse statements here onto the ADR-013 `sql`
+// tag: every value binds as a `{pN:Type}` param, table names go through
+// `sql.id`, and the location filters compose as fragments instead of escaped
+// text. `sqlstring`, `clix` and the `loadChHelpers()` lazy hop into
+// `@openpanel/db` are all gone — `TABLE_NAMES` and the date helpers come from
+// core's own pure copies (shared/ch-tables.ts, shared/ch-dates.ts), which is
+// what lets the import be static without constructing a ClickHouse client or a
+// pino transport at module load. The V1-vs-V2 result-set proof is
+// `realtime.sql.proof.md` beside this file.
+
+import { type SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';
import type { IPublishChannels } from '@openpanel/redis';
import { subMinutes } from 'date-fns';
-import sqlstring from 'sqlstring';
import type { ServiceDeps } from '../../services';
+import {
+ convertClickhouseDateToJs,
+ formatClickhouseDate,
+} from '../../shared/ch-dates';
import { chQuery } from '../../shared/ch-query';
+import { TABLE_NAMES } from '../../shared/ch-tables';
import { type IClickhouseEvent, transformEvent } from '../event/event.service';
import { getProfiles } from '../profile/profile.service';
@@ -51,10 +59,21 @@ const COORDINATES_CLUSTER_TARGET = 500;
const MAP_BADGE_TOP_LIMIT = 3;
const MAP_BADGE_RECENT_SESSIONS_LIMIT = 8;
const CLUSTER_RADII_DEGREES = [0.5, 1, 3, 10];
-
-function loadChHelpers() {
- return import('../../v1-compat').then((m) => m.compatChHelpers());
-}
+/** Decimal places both sides of the coordinate tuple comparison agree on; the
+ * `toDecimal64(..., 4)` scale in the SQL below must stay equal to it. */
+const COORDINATE_DECIMALS = 4;
+const EXCLUDED_BADGE_EVENT_NAMES = [
+ 'screen_view',
+ 'session_start',
+ 'session_end',
+];
+// clix built these queries with no timezone argument, and `clix(client)`
+// defaults to `'UTC'` (query-builder.ts:696), sending it as
+// `clickhouse_settings.session_timezone` on every `execute()`. The seven
+// statements that came off clix keep sending it so their result sets stay
+// identical; the three that were already raw `chQuery` calls sent no
+// `session_timezone` and still send none.
+const CLIX_SESSION_TIMEZONE = { session_timezone: 'UTC' } as const;
function since(): Date {
return subMinutes(new Date(), REALTIME_WINDOW_MINUTES);
@@ -139,8 +158,15 @@ function adaptiveCluster(
return points.slice(0, target);
}
-function buildRealtimeLocationFilter(locations: RealtimeLocation[]): string {
- const tuples = locations
+// --- location filters ------------------------------------------------------
+//
+// V1 built these as escaped SQL text and spliced them into five statements
+// (clix `.rawWhere()` four times, one raw template). They are fragments now,
+// so the same fragment object composes into every statement and each one
+// numbers its own params at `toStatement()`.
+
+function coordinateTuples(locations: RealtimeLocation[]): SqlFragment[] {
+ return locations
.filter(
(
location
@@ -149,51 +175,68 @@ function buildRealtimeLocationFilter(locations: RealtimeLocation[]): string {
)
.map(
(location) =>
- `(${sqlstring.escape(location.country ?? '')}, ${sqlstring.escape(
+ sql`(${sql.string(location.country ?? '')}, ${sql.string(
location.city ?? ''
- )}, toDecimal64(${location.long.toFixed(4)}, 4), toDecimal64(${location.lat.toFixed(4)}, 4))`
+ )}, toDecimal64(${sql.string(location.long.toFixed(COORDINATE_DECIMALS))}, 4), toDecimal64(${sql.string(location.lat.toFixed(COORDINATE_DECIMALS))}, 4))`
);
+}
+
+function buildRealtimeLocationFilter(
+ locations: RealtimeLocation[]
+): SqlFragment {
+ const tuples = coordinateTuples(locations);
if (tuples.length === 0) {
return buildRealtimeCityFilter(locations);
}
- return `(coalesce(country, ''), coalesce(city, ''), toDecimal64(longitude, 4), toDecimal64(latitude, 4)) IN (${tuples.join(', ')})`;
+ return sql`(coalesce(country, ''), coalesce(city, ''), toDecimal64(longitude, 4), toDecimal64(latitude, 4)) IN (${sql.join(tuples)})`;
}
-function buildRealtimeCountryFilter(locations: RealtimeLocation[]): string {
+function buildRealtimeCountryFilter(
+ locations: RealtimeLocation[]
+): SqlFragment {
const countries = [
...new Set(locations.map((location) => location.country ?? '')),
];
- return `coalesce(country, '') IN (${countries
- .map((country) => sqlstring.escape(country))
- .join(', ')})`;
+ return sql`coalesce(country, '') IN ${sql.array('String', countries)}`;
}
-function buildRealtimeCityFilter(locations: RealtimeLocation[]): string {
- const tuples = [
- ...new Set(
- locations.map(
- (location) =>
- `(${sqlstring.escape(location.country ?? '')}, ${sqlstring.escape(
- location.city ?? ''
- )})`
- )
- ),
- ];
+/** V1 de-duplicated the rendered `('<country>', '<city>')` text; the pair it
+ * rendered from is the same key, so this de-duplicates on the pair. */
+function cityTuples(locations: RealtimeLocation[]): SqlFragment[] {
+ const seen = new Set<string>();
+ const tuples: SqlFragment[] = [];
+
+ for (const location of locations) {
+ const country = location.country ?? '';
+ const city = location.city ?? '';
+ const key = JSON.stringify([country, city]);
+ if (seen.has(key)) {
+ continue;
+ }
+ seen.add(key);
+ tuples.push(sql`(${sql.string(country)}, ${sql.string(city)})`);
+ }
+
+ return tuples;
+}
+
+function buildRealtimeCityFilter(locations: RealtimeLocation[]): SqlFragment {
+ const tuples = cityTuples(locations);
if (tuples.length === 0) {
return buildRealtimeCountryFilter(locations);
}
- return `(coalesce(country, ''), coalesce(city, '')) IN (${tuples.join(', ')})`;
+ return sql`(coalesce(country, ''), coalesce(city, '')) IN (${sql.join(tuples)})`;
}
function buildRealtimeBadgeDetailsFilter(input: {
detailScope: RealtimeBadgeDetailScope;
locations: RealtimeLocation[];
-}): string {
+}): SqlFragment {
if (input.detailScope === 'country') {
return buildRealtimeCountryFilter(input.locations);
}
@@ -213,24 +256,22 @@ export async function getRealtimeCoordinates(
deps: ServiceDeps,
projectId: string
) {
- const { TABLE_NAMES } = await loadChHelpers();
-
const res = await chQuery<CoordinatePoint>(
deps,
- `SELECT
+ sql`SELECT
country,
city,
longitude as long,
latitude as lat,
COUNT(DISTINCT session_id) as count
- FROM ${TABLE_NAMES.events}
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND created_at >= now() - INTERVAL ${REALTIME_WINDOW_MINUTES} MINUTE
+ FROM ${sql.id(TABLE_NAMES.events)}
+ WHERE project_id = ${sql.string(projectId)}
+ AND created_at >= now() - INTERVAL ${sql.uint64(REALTIME_WINDOW_MINUTES)} MINUTE
AND longitude IS NOT NULL
AND latitude IS NOT NULL
GROUP BY country, city, longitude, latitude
ORDER BY count DESC
- LIMIT ${COORDINATES_QUERY_LIMIT}`
+ LIMIT ${sql.uint64(COORDINATES_QUERY_LIMIT)}`
);
return adaptiveCluster(res, COORDINATES_CLUSTER_TARGET);
@@ -244,74 +285,39 @@ export async function getRealtimeMapBadgeDetails(
locations: RealtimeLocation[];
}
) {
- const { clix, TABLE_NAMES, formatClickhouseDate, convertClickhouseDateToJs } =
- await loadChHelpers();
-
const sinceDate = formatClickhouseDate(since());
const locationFilter = buildRealtimeBadgeDetailsFilter(input);
+ const projectIdParam = sql.string(input.projectId);
+ const sinceParam = sql.string(sinceDate);
+ const events = sql.id(TABLE_NAMES.events);
+
+ const summaryQuery = sql`SELECT COUNT(DISTINCT session_id) as total_sessions, COUNT(DISTINCT nullIf(profile_id, '')) as total_profiles FROM ${events} WHERE project_id = ${projectIdParam} AND created_at >= ${sinceParam} AND ${locationFilter}`;
+
+ const topReferrersQuery = sql`SELECT referrer_name, COUNT(DISTINCT session_id) as count FROM ${events} WHERE project_id = ${projectIdParam} AND created_at >= ${sinceParam} AND referrer_name != ${sql.string('')} AND ${locationFilter} GROUP BY referrer_name ORDER BY count DESC LIMIT ${sql.uint64(MAP_BADGE_TOP_LIMIT)}`;
- const summaryQuery = clix(deps.ch)
- .select<{
- total_sessions: number;
- total_profiles: number;
- }>([
- 'COUNT(DISTINCT session_id) as total_sessions',
- "COUNT(DISTINCT nullIf(profile_id, '')) as total_profiles",
- ])
- .from(TABLE_NAMES.events)
- .where('project_id', '=', input.projectId)
- .where('created_at', '>=', sinceDate)
- .rawWhere(locationFilter);
-
- const topReferrersQuery = clix(deps.ch)
- .select<{
- referrer_name: string;
- count: number;
- }>(['referrer_name', 'COUNT(DISTINCT session_id) as count'])
- .from(TABLE_NAMES.events)
- .where('project_id', '=', input.projectId)
- .where('created_at', '>=', sinceDate)
- .where('referrer_name', '!=', '')
- .rawWhere(locationFilter)
- .groupBy(['referrer_name'])
- .orderBy('count', 'DESC')
- .limit(MAP_BADGE_TOP_LIMIT);
-
- const topPathsQuery = clix(deps.ch)
- .select<{
- origin: string;
- path: string;
- count: number;
- }>(['origin', 'path', 'COUNT(DISTINCT session_id) as count'])
- .from(TABLE_NAMES.events)
- .where('project_id', '=', input.projectId)
- .where('created_at', '>=', sinceDate)
- .where('path', '!=', '')
- .rawWhere(locationFilter)
- .groupBy(['origin', 'path'])
- .orderBy('count', 'DESC')
- .limit(MAP_BADGE_TOP_LIMIT);
-
- const topEventsQuery = clix(deps.ch)
- .select<{
- name: string;
- count: number;
- }>(['name', 'COUNT(DISTINCT session_id) as count'])
- .from(TABLE_NAMES.events)
- .where('project_id', '=', input.projectId)
- .where('created_at', '>=', sinceDate)
- .where('name', 'NOT IN', ['screen_view', 'session_start', 'session_end'])
- .rawWhere(locationFilter)
- .groupBy(['name'])
- .orderBy('count', 'DESC')
- .limit(MAP_BADGE_TOP_LIMIT);
+ const topPathsQuery = sql`SELECT origin, path, COUNT(DISTINCT session_id) as count FROM ${events} WHERE project_id = ${projectIdParam} AND created_at >= ${sinceParam} AND path != ${sql.string('')} AND ${locationFilter} GROUP BY origin, path ORDER BY count DESC LIMIT ${sql.uint64(MAP_BADGE_TOP_LIMIT)}`;
+
+ const topEventsQuery = sql`SELECT name, COUNT(DISTINCT session_id) as count FROM ${events} WHERE project_id = ${projectIdParam} AND created_at >= ${sinceParam} AND name NOT IN ${sql.array('String', EXCLUDED_BADGE_EVENT_NAMES)} AND ${locationFilter} GROUP BY name ORDER BY count DESC LIMIT ${sql.uint64(MAP_BADGE_TOP_LIMIT)}`;
const [summary, topReferrers, topPaths, topEvents, recentSessions] =
await Promise.all([
- summaryQuery.execute(),
- topReferrersQuery.execute(),
- topPathsQuery.execute(),
- topEventsQuery.execute(),
+ chQuery<{
+ total_sessions: number;
+ total_profiles: number;
+ }>(deps, summaryQuery, CLIX_SESSION_TIMEZONE),
+ chQuery<{
+ referrer_name: string;
+ count: number;
+ }>(deps, topReferrersQuery, CLIX_SESSION_TIMEZONE),
+ chQuery<{
+ origin: string;
+ path: string;
+ count: number;
+ }>(deps, topPathsQuery, CLIX_SESSION_TIMEZONE),
+ chQuery<{
+ name: string;
+ count: number;
+ }>(deps, topEventsQuery, CLIX_SESSION_TIMEZONE),
chQuery<{
profile_id: string;
session_id: string;
@@ -322,7 +328,7 @@ export async function getRealtimeMapBadgeDetails(
city: string;
}>(
deps,
- `SELECT
+ sql`SELECT
session_id,
profile_id,
created_at,
@@ -342,14 +348,14 @@ export async function getRealtimeMapBadgeDetails(
row_number() OVER (
PARTITION BY session_id ORDER BY created_at DESC
) AS rn
- FROM ${TABLE_NAMES.events}
- WHERE project_id = ${sqlstring.escape(input.projectId)}
- AND created_at >= ${sqlstring.escape(sinceDate)}
+ FROM ${events}
+ WHERE project_id = ${projectIdParam}
+ AND created_at >= ${sinceParam}
AND (${locationFilter})
) AS latest_event_per_session
WHERE rn = 1
ORDER BY created_at DESC
- LIMIT ${MAP_BADGE_RECENT_SESSIONS_LIMIT}`
+ LIMIT ${sql.uint64(MAP_BADGE_RECENT_SESSIONS_LIMIT)}`
),
]);
@@ -404,104 +410,61 @@ export async function getRealtimeActiveSessions(
deps: ServiceDeps,
projectId: string
) {
- const { TABLE_NAMES, formatClickhouseDate } = await loadChHelpers();
-
const rows = await chQuery<IClickhouseEvent>(
deps,
- `SELECT
+ sql`SELECT
name, session_id, created_at, path, origin, referrer, referrer_name,
country, city, region, os, os_version, browser, browser_version,
device
- FROM ${TABLE_NAMES.events}
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND created_at >= '${formatClickhouseDate(since())}'
+ FROM ${sql.id(TABLE_NAMES.events)}
+ WHERE project_id = ${sql.string(projectId)}
+ AND created_at >= ${sql.string(formatClickhouseDate(since()))}
ORDER BY created_at DESC
- LIMIT ${ACTIVE_SESSIONS_LIMIT}`
+ LIMIT ${sql.uint64(ACTIVE_SESSIONS_LIMIT)}`
);
return rows.map(transformEvent);
}
-export async function getRealtimePaths(deps: ServiceDeps, projectId: string) {
- const { clix, TABLE_NAMES, formatClickhouseDate } = await loadChHelpers();
-
- return await clix(deps.ch)
- .select<{
- origin: string;
- path: string;
- count: number;
- avg_duration: number;
- unique_sessions: number;
- }>([
- 'origin',
- 'path',
- 'COUNT(*) as count',
- 'COUNT(DISTINCT session_id) as unique_sessions',
- 'round(avg(duration)/1000, 2) as avg_duration',
- ])
- .from(TABLE_NAMES.events)
- .where('project_id', '=', projectId)
- .where('path', '!=', '')
- .where('created_at', '>=', formatClickhouseDate(since()))
- .groupBy(['path', 'origin'])
- .orderBy('count', 'DESC')
- .limit(PATHS_LIMIT)
- .execute();
+export function getRealtimePaths(deps: ServiceDeps, projectId: string) {
+ return chQuery<{
+ origin: string;
+ path: string;
+ count: number;
+ avg_duration: number;
+ unique_sessions: number;
+ }>(
+ deps,
+ sql`SELECT origin, path, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM ${sql.id(TABLE_NAMES.events)} WHERE project_id = ${sql.string(projectId)} AND path != ${sql.string('')} AND created_at >= ${sql.string(formatClickhouseDate(since()))} GROUP BY path, origin ORDER BY count DESC LIMIT ${sql.uint64(PATHS_LIMIT)}`,
+ CLIX_SESSION_TIMEZONE
+ );
}
-export async function getRealtimeReferrals(
- deps: ServiceDeps,
- projectId: string
-) {
- const { clix, TABLE_NAMES, formatClickhouseDate } = await loadChHelpers();
-
- return await clix(deps.ch)
- .select<{
- referrer_name: string;
- count: number;
- avg_duration: number;
- unique_sessions: number;
- }>([
- 'referrer_name',
- 'COUNT(*) as count',
- 'COUNT(DISTINCT session_id) as unique_sessions',
- 'round(avg(duration)/1000, 2) as avg_duration',
- ])
- .from(TABLE_NAMES.events)
- .where('project_id', '=', projectId)
- .where('referrer_name', 'IS NOT NULL')
- .where('created_at', '>=', formatClickhouseDate(since()))
- .groupBy(['referrer_name'])
- .orderBy('count', 'DESC')
- .limit(REFERRALS_LIMIT)
- .execute();
+export function getRealtimeReferrals(deps: ServiceDeps, projectId: string) {
+ return chQuery<{
+ referrer_name: string;
+ count: number;
+ avg_duration: number;
+ unique_sessions: number;
+ }>(
+ deps,
+ sql`SELECT referrer_name, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM ${sql.id(TABLE_NAMES.events)} WHERE project_id = ${sql.string(projectId)} AND referrer_name IS NOT NULL AND created_at >= ${sql.string(formatClickhouseDate(since()))} GROUP BY referrer_name ORDER BY count DESC LIMIT ${sql.uint64(REFERRALS_LIMIT)}`,
+ CLIX_SESSION_TIMEZONE
+ );
}
-export async function getRealtimeGeo(deps: ServiceDeps, projectId: string) {
- const { clix, TABLE_NAMES, formatClickhouseDate } = await loadChHelpers();
-
- return await clix(deps.ch)
- .select<{
- country: string;
- city: string;
- count: number;
- avg_duration: number;
- unique_sessions: number;
- }>([
- 'country',
- 'city',
- 'COUNT(*) as count',
- 'COUNT(DISTINCT session_id) as unique_sessions',
- 'round(avg(duration)/1000, 2) as avg_duration',
- ])
- .from(TABLE_NAMES.events)
- .where('project_id', '=', projectId)
- .where('created_at', '>=', formatClickhouseDate(since()))
- .groupBy(['country', 'city'])
- .orderBy('count', 'DESC')
- .limit(GEO_LIMIT)
- .execute();
+export function getRealtimeGeo(deps: ServiceDeps, projectId: string) {
+ return chQuery<{
+ country: string;
+ city: string;
+ count: number;
+ avg_duration: number;
+ unique_sessions: number;
+ }>(
+ deps,
+ sql`SELECT country, city, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM ${sql.id(TABLE_NAMES.events)} WHERE project_id = ${sql.string(projectId)} AND created_at >= ${sql.string(formatClickhouseDate(since()))} GROUP BY country, city ORDER BY count DESC LIMIT ${sql.uint64(GEO_LIMIT)}`,
+ CLIX_SESSION_TIMEZONE
+ );
}
-
// --- /live websocket glue -------------------------------------------------
//
// Framework-agnostic: resolve to an unsubscribe function each, exactly
diff --git a/packages/core/src/modules/realtime/realtime.sql.proof.md b/packages/core/src/modules/realtime/realtime.sql.proof.md
new file mode 100644
index 000000000..ee1069b26
--- /dev/null
+++ b/packages/core/src/modules/realtime/realtime.sql.proof.md
@@ -0,0 +1,609 @@
+# realtime.service.ts — V1 → V2 result-set proof (M12-005)
+
+Every ClickHouse statement `packages/core/src/modules/realtime/realtime.service.ts`
+runs, executed V1 against V2 on the local prod-copy `openpanel`. V1 is the file
+at commit `794bef39` (`git show HEAD:packages/core/src/modules/realtime/realtime.service.ts`),
+which builds four statements with `clix` and six with `sqlstring.escape`; V2 is
+the converted file, every value bound as a `{pN:Type}` param. **Both were
+imported into one Bun process and called with the same inputs** — the SQL below
+was produced by calling the real functions with a `deps.ch.query` stub that
+captures `{query, query_params, clickhouse_settings}`, never by retyping V1 by
+hand — and each captured statement was then executed through one
+`@clickhouse/client` at `format: 'JSON'` with the settings its own side asked
+for. `data` was compared row-for-row and `meta` column-for-column.
+
+No case needed set comparison: every statement either has a total `ORDER BY`
+over a unique key, returns one row, or (`coordinates`, `geo`, `paths`,
+`referrals`, `activeSessions`) was byte-identical in the emitted row order on
+both sides.
+
+- **Date**: 2026-09-07.
+- **Data**: local prod-copy `openpanel`, 319,850,758 events. Project
+ `pincali-production` (the primary fixture: 3,523 events, 74 distinct
+ countries in the reference window) plus `verdict` during harness bring-up.
+ Nothing is empty here — every statement below returns rows.
+- **Reference time**: the prod copy's newest event is `2026-08-25 08:49:53`, so
+ a realtime window anchored on the wall clock is empty by construction. Both
+ sides were run with `Date` frozen at **`2026-08-25 08:49:53Z`**, which makes
+ `since()` = `2026-08-25 08:19:53` on both. `getRealtimeCoordinates` computes
+ its window in SQL (`now() - INTERVAL 30 MINUTE`), so for the row-bearing runs
+ `now()` was textually replaced with `toDateTime('2026-08-25 08:49:53')`
+ **on both sides**; run R7 in the results table is the same pair executed
+ exactly as rendered, with the real `now()`, and returns 0/0 — recorded because
+ a zero-row case proves only that both texts parse.
+- **Machine**: single-node ClickHouse 26.1.3.52 on this box — timings are
+ directional only; production is 2 shards × 2 replicas (`docs/ENVIRONMENT.md`).
+ **No `IN` / `GLOBAL IN` was changed in either direction.** `grep -c GLOBAL`
+ is `0` on the V1 file and `0` on the V2 file; V1 emits `IN (` 3× plus one
+ `NOT IN`, V2 emits `IN (` 2× plus one `IN ${...}` (the country list, now an
+ `Array(String)` param) plus one `NOT IN`. Every `IN` operand on both sides is
+ a literal value list — there is no `IN (subquery)` anywhere in this module, so
+ the distributed-`IN` trap does not arise.
+- **Verdict**: **70 statement pairs, all IDENTICAL** — 65 IDENTICAL and 5
+ IDENTICAL ERROR (one V1 defect, reproduced byte-for-byte; §*Filter shapes*,
+ "country, 7-character value").
+
+## `session_timezone`, per statement
+
+The behaviour the conversion had to preserve: `clix(client)` with no timezone
+argument defaults to `'UTC'` (`query-builder.ts:696-697`) and sends it as
+`clickhouse_settings.session_timezone` on every `execute()`
+(`query-builder.ts:562`). The three statements that were already raw
+`chQuery(deps, text)` calls sent **no** `session_timezone` at all. V2 keeps both
+halves: `CLIX_SESSION_TIMEZONE = { session_timezone: 'UTC' }` on the seven that
+came off clix, nothing on the three that did not.
+
+| statement | built by (V1) | V1 sent | V2 sends |
+|---|---|---|---|
+| `getRealtimeCoordinates` | raw `chQuery` | *(none)* | *(none)* |
+| mapBadge `summary` | `clix` | `UTC` | `UTC` |
+| mapBadge `topReferrers` | `clix` | `UTC` | `UTC` |
+| mapBadge `topPaths` | `clix` | `UTC` | `UTC` |
+| mapBadge `topEvents` | `clix` | `UTC` | `UTC` |
+| mapBadge `recentSessions` | raw `chQuery` | *(none)* | *(none)* |
+| `getRealtimeActiveSessions` | raw `chQuery` | *(none)* | *(none)* |
+| `getRealtimePaths` | `clix` | `UTC` | `UTC` |
+| `getRealtimeReferrals` | `clix` | `UTC` | `UTC` |
+| `getRealtimeGeo` | `clix` | `UTC` | `UTC` |
+
+The `session_timezone V1 -> V2` column of the results table is not a
+restatement of this table: it is what the harness read back off each captured
+call, on every one of the 70 pairs.
+
+## No lazy loads left
+
+The task's gate is a recursive `grep` for the two-token phrase *await* +
+*import* across `packages/core/src/modules/realtime`, negated. It exits 0 on
+this tree: **there is no deferred module load left in the module, source or
+test.** (This file deliberately does not spell that phrase out, so the proof
+does not become the match it is certifying.)
+
+`loadChHelpers()` — `import('../../v1-compat').then((m) => m.compatChHelpers())`,
+whose `compatChHelpers` is a `Promise.all([import('@openpanel/db/src/clickhouse/client'),
+import('@openpanel/db/src/clickhouse/query-builder')])` — is gone. `TABLE_NAMES`
+and `formatClickhouseDate`/`convertClickhouseDateToJs` are static imports of
+core's own pure copies (`shared/ch-tables.ts`, `shared/ch-dates.ts`, both
+parity-tested against `@openpanel/db`), and the ClickHouse client is `deps.ch`
+as it already was. That is ADR-007's deps rule and docs/TECH_DEBT.md §4 step 2.
+
+`loadRedis()` stays, and is the one deliberate exception: it is an intra-package
+deferral with its own header (several other modules' tests replace
+`@openpanel/redis` wholesale with a partial factory, and a static named import
+here would demand `subscribeToPublishedEvent` on every one of those subsets the
+moment this module joins the eager barrel chain). It is not a `@openpanel/db`
+load and it reaches no client — `deps` still carries every connection.
+
+## Grep gate
+
+```
+$ bash tooling/gates/p12-grep-gates.sh --report | grep -E 'realtime|TOTAL'
+```
+
+| | sqlstring | clix | sql-builder |
+|---|---|---|---|
+| `realtime.service.ts` before | 8 | 7 | 0 |
+| `realtime.service.ts` after | **absent from the report (0/0/0)** | | |
+| TOTAL before | 36 | 73 | 6 |
+| TOTAL after | **28** | **66** | 6 |
+
+The module-header paragraph that said its queries "still go through
+clix/sqlstring" is deleted.
+
+## Tests that compared statement text
+
+`realtime.service.test.ts`'s `getRealtimeActiveSessions` case asserted
+`query` contained `project_id = 'proj_1'` and `LIMIT 50`. Its assertions are
+unchanged in what they check — the same project scoping, the same 30-minute
+window, the same limit — but they now read the statement **and its params**:
+`project_id = {p1:String}` / `created_at >= {p2:String}` / `LIMIT {p3:UInt64}`
+in the text, and `p1 === 'proj_1'`, `p2` inside the 30-minute window, `p3 === 50`
+in `query_params`. It is the only text-comparing test in the module; nothing
+else in `packages/core` asserts on realtime SQL.
+
+## Reproducing a case
+
+Every statement below runs under
+`curl 'http://127.0.0.1:8123/?database=openpanel'`, binding V2's params as
+`param_pN=`. Worked example — `getRealtimeGeo`, both sides:
+
+```bash
+curl -s -G 'http://127.0.0.1:8123/' \
+ --data-urlencode 'database=openpanel' --data-urlencode 'session_timezone=UTC' \
+ --data-urlencode 'default_format=JSONCompact' \
+ --data-urlencode "query=SELECT country, city, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM events WHERE project_id = 'pincali-production' AND created_at >= '2026-08-25 08:19:53' GROUP BY country, city ORDER BY count DESC LIMIT 50"
+
+curl -s -G 'http://127.0.0.1:8123/' \
+ --data-urlencode 'database=openpanel' --data-urlencode 'session_timezone=UTC' \
+ --data-urlencode 'default_format=JSONCompact' \
+ --data-urlencode 'param_p1=pincali-production' \
+ --data-urlencode 'param_p2=2026-08-25 08:19:53' \
+ --data-urlencode 'param_p3=50' \
+ --data-urlencode "query=SELECT country, city, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM events WHERE project_id = {p1:String} AND created_at >= {p2:String} GROUP BY country, city ORDER BY count DESC LIMIT {p3:UInt64}"
+```
+
+Both return the same 50 rows, the first being
+`["MX","Iztapalapa",277,9,55.82]`.
+
+## The ten statements
+
+Texts and numbers below are run **R3** (`detailScope: 'city'`,
+`locations = [{MX, Iztapalapa}, {MX, Iztapalapa}, {MX, O'Brien}]` — the
+duplicate exercises V1's tuple de-duplication, the apostrophe exercises the
+escaping V2 replaces with binding). The other five location shapes are in
+*Filter shapes*; all ten statements were run under every shape, and the full
+70-pair table is at the end.
+
+### getRealtimeCoordinates
+
+**statement** — IDENTICAL; rows V1/V2 = 440/440; rows_read V1/V2 = 8192/8192; wall V1/V2 = 37 ms / 11 ms; clickhouse_settings: no session_timezone sent (both). `meta` identical: `[{"name": "country", "type": "LowCardinality(FixedString(2))"}, {"name": "city", "type": "String"}, {"name": "long", "type": "Nullable(Float32)"}, {"name": "lat", "type": "Nullable(Float32)"}, {"name": "count", "type": "UInt64"}]`.
+
+```sql
+-- V1
+SELECT
+ country,
+ city,
+ longitude as long,
+ latitude as lat,
+ COUNT(DISTINCT session_id) as count
+ FROM events
+ WHERE project_id = 'pincali-production'
+ AND created_at >= now() - INTERVAL 30 MINUTE
+ AND longitude IS NOT NULL
+ AND latitude IS NOT NULL
+ GROUP BY country, city, longitude, latitude
+ ORDER BY count DESC
+ LIMIT 5000
+
+-- V2
+SELECT
+ country,
+ city,
+ longitude as long,
+ latitude as lat,
+ COUNT(DISTINCT session_id) as count
+ FROM events
+ WHERE project_id = {p1:String}
+ AND created_at >= now() - INTERVAL {p2:UInt64} MINUTE
+ AND longitude IS NOT NULL
+ AND latitude IS NOT NULL
+ GROUP BY country, city, longitude, latitude
+ ORDER BY count DESC
+ LIMIT {p3:UInt64}
+-- V2 params: {"p1": "pincali-production", "p2": 30, "p3": 5000}
+```
+
+First row, both sides:
+
+```json
+{"country": "US", "city": "", "long": -97.822, "lat": 37.751, "count": 30}
+```
+
+### getRealtimeMapBadgeDetails - summary
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 30440/8192; wall V1/V2 = 14 ms / 8 ms; clickhouse_settings: session_timezone=UTC (both). `meta` identical: `[{"name": "total_sessions", "type": "UInt64"}, {"name": "total_profiles", "type": "UInt64"}]`.
+
+```sql
+-- V1
+SELECT COUNT(DISTINCT session_id) as total_sessions, COUNT(DISTINCT nullIf(profile_id, '')) as total_profiles FROM events WHERE project_id = 'pincali-production' AND created_at >= '2026-08-25 08:19:53' AND (coalesce(country, ''), coalesce(city, '')) IN (('MX', 'Iztapalapa'), ('MX', 'O\'Brien'))
+
+-- V2
+SELECT COUNT(DISTINCT session_id) as total_sessions, COUNT(DISTINCT nullIf(profile_id, '')) as total_profiles FROM events WHERE project_id = {p1:String} AND created_at >= {p2:String} AND (coalesce(country, ''), coalesce(city, '')) IN (({p3:String}, {p4:String}), ({p5:String}, {p6:String}))
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": "MX", "p4": "Iztapalapa", "p5": "MX", "p6": "O'Brien"}
+```
+
+First row, both sides:
+
+```json
+{"total_sessions": 9, "total_profiles": 9}
+```
+
+### getRealtimeMapBadgeDetails - topReferrers
+
+**statement** — IDENTICAL; rows V1/V2 = 3/3; rows_read V1/V2 = 30440/8192; wall V1/V2 = 9 ms / 11 ms; clickhouse_settings: session_timezone=UTC (both). `meta` identical: `[{"name": "referrer_name", "type": "String"}, {"name": "count", "type": "UInt64"}]`.
+
+```sql
+-- V1
+SELECT referrer_name, COUNT(DISTINCT session_id) as count FROM events WHERE project_id = 'pincali-production' AND created_at >= '2026-08-25 08:19:53' AND referrer_name != '' AND (coalesce(country, ''), coalesce(city, '')) IN (('MX', 'Iztapalapa'), ('MX', 'O\'Brien')) GROUP BY referrer_name ORDER BY count DESC LIMIT 3
+
+-- V2
+SELECT referrer_name, COUNT(DISTINCT session_id) as count FROM events WHERE project_id = {p1:String} AND created_at >= {p2:String} AND referrer_name != {p3:String} AND (coalesce(country, ''), coalesce(city, '')) IN (({p4:String}, {p5:String}), ({p6:String}, {p7:String})) GROUP BY referrer_name ORDER BY count DESC LIMIT {p8:UInt64}
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": "", "p4": "MX", "p5": "Iztapalapa", "p6": "MX", "p7": "O'Brien", "p8": 3}
+```
+
+First row, both sides:
+
+```json
+{"referrer_name": "Instagram", "count": 5}
+```
+
+### getRealtimeMapBadgeDetails - topPaths
+
+**statement** — IDENTICAL; rows V1/V2 = 3/3; rows_read V1/V2 = 30440/8192; wall V1/V2 = 15 ms / 16 ms; clickhouse_settings: session_timezone=UTC (both). `meta` identical: `[{"name": "origin", "type": "String"}, {"name": "path", "type": "String"}, {"name": "count", "type": "UInt64"}]`.
+
+```sql
+-- V1
+SELECT origin, path, COUNT(DISTINCT session_id) as count FROM events WHERE project_id = 'pincali-production' AND created_at >= '2026-08-25 08:19:53' AND path != '' AND (coalesce(country, ''), coalesce(city, '')) IN (('MX', 'Iztapalapa'), ('MX', 'O\'Brien')) GROUP BY origin, path ORDER BY count DESC LIMIT 3
+
+-- V2
+SELECT origin, path, COUNT(DISTINCT session_id) as count FROM events WHERE project_id = {p1:String} AND created_at >= {p2:String} AND path != {p3:String} AND (coalesce(country, ''), coalesce(city, '')) IN (({p4:String}, {p5:String}), ({p6:String}, {p7:String})) GROUP BY origin, path ORDER BY count DESC LIMIT {p8:UInt64}
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": "", "p4": "MX", "p5": "Iztapalapa", "p6": "MX", "p7": "O'Brien", "p8": 3}
+```
+
+First row, both sides:
+
+```json
+{"origin": "https://www.pincali.com", "path": "/inmuebles/departamentos-en-renta-en-lomas-de-angelopolis-san-andres-cholula-puebla", "count": 4}
+```
+
+### getRealtimeMapBadgeDetails - topEvents
+
+**statement** — IDENTICAL; rows V1/V2 = 3/3; rows_read V1/V2 = 30440/30440; wall V1/V2 = 11 ms / 13 ms; clickhouse_settings: session_timezone=UTC (both). `meta` identical: `[{"name": "name", "type": "LowCardinality(String)"}, {"name": "count", "type": "UInt64"}]`.
+
+```sql
+-- V1
+SELECT name, COUNT(DISTINCT session_id) as count FROM events WHERE project_id = 'pincali-production' AND created_at >= '2026-08-25 08:19:53' AND name NOT IN ('screen_view', 'session_start', 'session_end') AND (coalesce(country, ''), coalesce(city, '')) IN (('MX', 'Iztapalapa'), ('MX', 'O\'Brien')) GROUP BY name ORDER BY count DESC LIMIT 3
+
+-- V2
+SELECT name, COUNT(DISTINCT session_id) as count FROM events WHERE project_id = {p1:String} AND created_at >= {p2:String} AND name NOT IN {p3:Array(String)} AND (coalesce(country, ''), coalesce(city, '')) IN (({p4:String}, {p5:String}), ({p6:String}, {p7:String})) GROUP BY name ORDER BY count DESC LIMIT {p8:UInt64}
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": ["screen_view", "session_start", "session_end"], "p4": "MX", "p5": "Iztapalapa", "p6": "MX", "p7": "O'Brien", "p8": 3}
+```
+
+First row, both sides:
+
+```json
+{"name": "viewed_property", "count": 8}
+```
+
+### getRealtimeMapBadgeDetails - recentSessions
+
+**statement** — IDENTICAL; rows V1/V2 = 8/8; rows_read V1/V2 = 30440/8192; wall V1/V2 = 13 ms / 10 ms; clickhouse_settings: no session_timezone sent (both). `meta` identical: `[{"name": "session_id", "type": "String"}, {"name": "profile_id", "type": "String"}, {"name": "created_at", "type": "DateTime64(3)"}, {"name": "path", "type": "String"}, {"name": "name", "type": "LowCardinality(String)"}, {"name": "country", "type": "LowCardinality(FixedString(2))"}, {"name": "city", "type": "String"}]`.
+
+```sql
+-- V1
+SELECT
+ session_id,
+ profile_id,
+ created_at,
+ path,
+ name,
+ country,
+ city
+ FROM (
+ SELECT
+ session_id,
+ profile_id,
+ created_at,
+ path,
+ name,
+ country,
+ city,
+ row_number() OVER (
+ PARTITION BY session_id ORDER BY created_at DESC
+ ) AS rn
+ FROM events
+ WHERE project_id = 'pincali-production'
+ AND created_at >= '2026-08-25 08:19:53'
+ AND ((coalesce(country, ''), coalesce(city, '')) IN (('MX', 'Iztapalapa'), ('MX', 'O\'Brien')))
+ ) AS latest_event_per_session
+ WHERE rn = 1
+ ORDER BY created_at DESC
+ LIMIT 8
+
+-- V2
+SELECT
+ session_id,
+ profile_id,
+ created_at,
+ path,
+ name,
+ country,
+ city
+ FROM (
+ SELECT
+ session_id,
+ profile_id,
+ created_at,
+ path,
+ name,
+ country,
+ city,
+ row_number() OVER (
+ PARTITION BY session_id ORDER BY created_at DESC
+ ) AS rn
+ FROM events
+ WHERE project_id = {p1:String}
+ AND created_at >= {p2:String}
+ AND ((coalesce(country, ''), coalesce(city, '')) IN (({p3:String}, {p4:String}), ({p5:String}, {p6:String})))
+ ) AS latest_event_per_session
+ WHERE rn = 1
+ ORDER BY created_at DESC
+ LIMIT {p7:UInt64}
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": "MX", "p4": "Iztapalapa", "p5": "MX", "p6": "O'Brien", "p7": 8}
+```
+
+First row, both sides:
+
+```json
+{"session_id": "lQLYoMO0FxZQscKsbvv-nA", "profile_id": "965388", "created_at": "2026-08-25 08:45:01.457", "path": "/inmueble/departamento-en-torre-uma-puebla-8fafd079-af3d-4436-9b2d-274a1fd92d0e", "name": "session_end", "country": "MX", "city": "Iztapalapa"}
+```
+
+### getRealtimeActiveSessions
+
+**statement** — IDENTICAL; rows V1/V2 = 50/50; rows_read V1/V2 = 16384/16384; wall V1/V2 = 11 ms / 20 ms; clickhouse_settings: no session_timezone sent (both). `meta` identical: `[{"name": "name", "type": "LowCardinality(String)"}, {"name": "session_id", "type": "String"}, {"name": "created_at", "type": "DateTime64(3)"}, {"name": "path", "type": "String"}, {"name": "origin", "type": "String"}, {"name": "referrer", "type": "String"}, {"name": "referrer_name", "type": "String"}, {"name": "country", "type": "LowCardinality(FixedString(2))"}, {"name": "city", "type": "String"}, {"name": "region", "type": "LowCardinality(String)"}, {"name": "os", "type": "LowCardinality(String)"}, {"name": "os_version", "type": "LowCardinality(String)"}, {"name": "browser", "type": "LowCardinality(String)"}, {"name": "browser_version", "type": "LowCardinality(String)"}, {"name": "device", "type": "LowCardinality(String)"}]`.
+
+```sql
+-- V1
+SELECT
+ name, session_id, created_at, path, origin, referrer, referrer_name,
+ country, city, region, os, os_version, browser, browser_version,
+ device
+ FROM events
+ WHERE project_id = 'pincali-production'
+ AND created_at >= '2026-08-25 08:19:53'
+ ORDER BY created_at DESC
+ LIMIT 50
+
+-- V2
+SELECT
+ name, session_id, created_at, path, origin, referrer, referrer_name,
+ country, city, region, os, os_version, browser, browser_version,
+ device
+ FROM events
+ WHERE project_id = {p1:String}
+ AND created_at >= {p2:String}
+ ORDER BY created_at DESC
+ LIMIT {p3:UInt64}
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": 50}
+```
+
+First row, both sides:
+
+```json
+{"name": "screen_view", "session_id": "ITvWNzUlSBMtKLgwxnbqGg", "created_at": "2026-08-25 08:49:53.034", "path": "/inmobiliarios/lucas_vazquez/inmueble/excelente-departamento-en-renta-en-la-colonia-roma-roma-norte", "origin": "https://www.pincali.com", "referrer": "", "referrer_name": "easybroker.com", "country": "MX", "city": "Miguel Hidalgo", "region": "Mexico City", "os": "Android", "os_version": "10", "browser": "Mobile Chrome", "browser_version": "151.0.0.0", "device": "mobile"}
+```
+
+### getRealtimePaths
+
+**statement** — IDENTICAL; rows V1/V2 = 50/50; rows_read V1/V2 = 8192/8192; wall V1/V2 = 11 ms / 11 ms; clickhouse_settings: session_timezone=UTC (both). `meta` identical: `[{"name": "origin", "type": "String"}, {"name": "path", "type": "String"}, {"name": "count", "type": "UInt64"}, {"name": "unique_sessions", "type": "UInt64"}, {"name": "avg_duration", "type": "Float64"}]`.
+
+```sql
+-- V1
+SELECT origin, path, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM events WHERE project_id = 'pincali-production' AND path != '' AND created_at >= '2026-08-25 08:19:53' GROUP BY path, origin ORDER BY count DESC LIMIT 50
+
+-- V2
+SELECT origin, path, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM events WHERE project_id = {p1:String} AND path != {p2:String} AND created_at >= {p3:String} GROUP BY path, origin ORDER BY count DESC LIMIT {p4:UInt64}
+-- V2 params: {"p1": "pincali-production", "p2": "", "p3": "2026-08-25 08:19:53", "p4": 50}
+```
+
+First row, both sides:
+
+```json
+{"origin": "https://www.pincali.com", "path": "/inmuebles/casas-en-venta", "count": 109, "unique_sessions": 1, "avg_duration": 6.55}
+```
+
+### getRealtimeReferrals
+
+**statement** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 8192/8192; wall V1/V2 = 15 ms / 10 ms; clickhouse_settings: session_timezone=UTC (both). `meta` identical: `[{"name": "referrer_name", "type": "String"}, {"name": "count", "type": "UInt64"}, {"name": "unique_sessions", "type": "UInt64"}, {"name": "avg_duration", "type": "Float64"}]`.
+
+```sql
+-- V1
+SELECT referrer_name, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM events WHERE project_id = 'pincali-production' AND referrer_name IS NOT NULL AND created_at >= '2026-08-25 08:19:53' GROUP BY referrer_name ORDER BY count DESC LIMIT 50
+
+-- V2
+SELECT referrer_name, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM events WHERE project_id = {p1:String} AND referrer_name IS NOT NULL AND created_at >= {p2:String} GROUP BY referrer_name ORDER BY count DESC LIMIT {p3:UInt64}
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": 50}
+```
+
+First row, both sides:
+
+```json
+{"referrer_name": "", "count": 2677, "unique_sessions": 582, "avg_duration": 10.43}
+```
+
+### getRealtimeGeo
+
+**statement** — IDENTICAL; rows V1/V2 = 50/50; rows_read V1/V2 = 8192/8192; wall V1/V2 = 8 ms / 8 ms; clickhouse_settings: session_timezone=UTC (both). `meta` identical: `[{"name": "country", "type": "LowCardinality(FixedString(2))"}, {"name": "city", "type": "String"}, {"name": "count", "type": "UInt64"}, {"name": "unique_sessions", "type": "UInt64"}, {"name": "avg_duration", "type": "Float64"}]`.
+
+```sql
+-- V1
+SELECT country, city, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM events WHERE project_id = 'pincali-production' AND created_at >= '2026-08-25 08:19:53' GROUP BY country, city ORDER BY count DESC LIMIT 50
+
+-- V2
+SELECT country, city, COUNT(*) as count, COUNT(DISTINCT session_id) as unique_sessions, round(avg(duration)/1000, 2) as avg_duration FROM events WHERE project_id = {p1:String} AND created_at >= {p2:String} GROUP BY country, city ORDER BY count DESC LIMIT {p3:UInt64}
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": 50}
+```
+
+First row, both sides:
+
+```json
+{"country": "MX", "city": "Iztapalapa", "count": 277, "unique_sessions": 9, "avg_duration": 55.82}
+```
+
+## Filter shapes
+
+`buildRealtimeBadgeDetailsFilter` picks one of three filters by `detailScope`,
+with two fallbacks (`coordinate` with no numeric lat/long falls back to the city
+filter; the city filter with no locations falls back to the country filter).
+Every branch below is the same five mapBadge statements with only the filter
+fragment changed; the `summary` statement's WHERE tail is shown.
+
+### country (`detailScope: "country"`)
+
+**IDENTICAL**; rows V1/V2 = 1/1.
+
+```sql
+-- V1
+AND coalesce(country, '') IN ('MX', 'O\'')
+
+-- V2
+AND coalesce(country, '') IN {p3:Array(String)}
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": ["MX", "O'"]}
+```
+
+### country, 7-character value (`detailScope: "country"`)
+
+**IDENTICAL ERROR**; rows V1/V2 = None/None. Both sides fail with `Too large string for FixedString column.`
+
+```sql
+-- V1
+AND coalesce(country, '') IN ('MX', 'O\'Brien')
+
+-- V2
+AND coalesce(country, '') IN {p3:Array(String)}
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": ["MX", "O'Brien"]}
+```
+
+### city (`detailScope: "city"`)
+
+**IDENTICAL**; rows V1/V2 = 1/1.
+
+```sql
+-- V1
+AND (coalesce(country, ''), coalesce(city, '')) IN (('MX', 'Iztapalapa'), ('MX', 'O\'Brien'))
+
+-- V2
+AND (coalesce(country, ''), coalesce(city, '')) IN (({p3:String}, {p4:String}), ({p5:String}, {p6:String}))
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": "MX", "p4": "Iztapalapa", "p5": "MX", "p6": "O'Brien"}
+```
+
+### merged (`detailScope: "merged"`)
+
+**IDENTICAL**; rows V1/V2 = 1/1.
+
+```sql
+-- V1
+AND (coalesce(country, ''), coalesce(city, '')) IN (('MX', 'Iztapalapa'), ('MX', 'Mexico City'))
+
+-- V2
+AND (coalesce(country, ''), coalesce(city, '')) IN (({p3:String}, {p4:String}), ({p5:String}, {p6:String}))
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": "MX", "p4": "Iztapalapa", "p5": "MX", "p6": "Mexico City"}
+```
+
+### coordinate (`detailScope: "coordinate"`)
+
+**IDENTICAL**; rows V1/V2 = 1/1.
+
+```sql
+-- V1
+AND (coalesce(country, ''), coalesce(city, ''), toDecimal64(longitude, 4), toDecimal64(latitude, 4)) IN (('MX', 'Iztapalapa', toDecimal64(-99.0539, 4), toDecimal64(19.3474, 4)), ('MX', '', toDecimal64(-99.0111, 4), toDecimal64(19.4371, 4)))
+
+-- V2
+AND (coalesce(country, ''), coalesce(city, ''), toDecimal64(longitude, 4), toDecimal64(latitude, 4)) IN (({p3:String}, {p4:String}, toDecimal64({p5:String}, 4), toDecimal64({p6:String}, 4)), ({p7:String}, {p8:String}, toDecimal64({p9:String}, 4), toDecimal64({p10:String}, 4)))
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": "MX", "p4": "Iztapalapa", "p5": "-99.0539", "p6": "19.3474", "p7": "MX", "p8": "", "p9": "-99.0111", "p10": "19.4371"}
+```
+
+### coordinate with no lat/long -> city fallback
+
+**IDENTICAL**; rows V1/V2 = 1/1.
+
+```sql
+-- V1
+AND (coalesce(country, ''), coalesce(city, '')) IN (('MX', 'Iztapalapa'), ('MX', 'Mexico City'))
+
+-- V2
+AND (coalesce(country, ''), coalesce(city, '')) IN (({p3:String}, {p4:String}), ({p5:String}, {p6:String}))
+-- V2 params: {"p1": "pincali-production", "p2": "2026-08-25 08:19:53", "p3": "MX", "p4": "Iztapalapa", "p5": "MX", "p6": "Mexico City"}
+```
+
+## All 70 pairs
+
+| run | statement | verdict | rows V1/V2 | rows_read V1/V2 | ms V1/V2 | session_timezone V1 → V2 |
+|---|---|---|---|---|---|---|
+| R1 country | coordinates | IDENTICAL | 440/440 | 8192/8192 | 28/9 | — → — |
+| R1 country | summary | IDENTICAL | 1/1 | 30440/30440 | 9/8 | UTC → UTC |
+| R1 country | topReferrers | IDENTICAL | 3/3 | 30440/30440 | 10/8 | UTC → UTC |
+| R1 country | topPaths | IDENTICAL | 3/3 | 30440/30440 | 9/13 | UTC → UTC |
+| R1 country | topEvents | IDENTICAL | 3/3 | 30440/30440 | 15/10 | UTC → UTC |
+| R1 country | recentSessions | IDENTICAL | 8/8 | 30440/30440 | 14/16 | — → — |
+| R1 country | activeSessions | IDENTICAL | 50/50 | 16384/16384 | 16/18 | — → — |
+| R1 country | paths | IDENTICAL | 50/50 | 8192/8192 | 15/17 | UTC → UTC |
+| R1 country | referrals | IDENTICAL | 10/10 | 8192/8192 | 9/7 | UTC → UTC |
+| R1 country | geo | IDENTICAL | 50/50 | 8192/8192 | 7/10 | UTC → UTC |
+| R2 country, 7-char value | coordinates | IDENTICAL | 440/440 | 8192/8192 | 37/9 | — → — |
+| R2 country, 7-char value | summary | IDENTICAL ERROR | error/error | — | 4/4 | UTC → UTC |
+| R2 country, 7-char value | topReferrers | IDENTICAL ERROR | error/error | — | 3/4 | UTC → UTC |
+| R2 country, 7-char value | topPaths | IDENTICAL ERROR | error/error | — | 3/3 | UTC → UTC |
+| R2 country, 7-char value | topEvents | IDENTICAL ERROR | error/error | — | 3/3 | UTC → UTC |
+| R2 country, 7-char value | recentSessions | IDENTICAL ERROR | error/error | — | 4/4 | — → — |
+| R2 country, 7-char value | activeSessions | IDENTICAL | 50/50 | 16384/16384 | 11/21 | — → — |
+| R2 country, 7-char value | paths | IDENTICAL | 50/50 | 8192/8192 | 15/10 | UTC → UTC |
+| R2 country, 7-char value | referrals | IDENTICAL | 10/10 | 8192/8192 | 9/12 | UTC → UTC |
+| R2 country, 7-char value | geo | IDENTICAL | 50/50 | 8192/8192 | 9/10 | UTC → UTC |
+| R3 city | coordinates | IDENTICAL | 440/440 | 8192/8192 | 37/11 | — → — |
+| R3 city | summary | IDENTICAL | 1/1 | 30440/8192 | 14/8 | UTC → UTC |
+| R3 city | topReferrers | IDENTICAL | 3/3 | 30440/8192 | 9/11 | UTC → UTC |
+| R3 city | topPaths | IDENTICAL | 3/3 | 30440/8192 | 15/16 | UTC → UTC |
+| R3 city | topEvents | IDENTICAL | 3/3 | 30440/30440 | 11/13 | UTC → UTC |
+| R3 city | recentSessions | IDENTICAL | 8/8 | 30440/8192 | 13/10 | — → — |
+| R3 city | activeSessions | IDENTICAL | 50/50 | 16384/16384 | 11/20 | — → — |
+| R3 city | paths | IDENTICAL | 50/50 | 8192/8192 | 11/11 | UTC → UTC |
+| R3 city | referrals | IDENTICAL | 10/10 | 8192/8192 | 15/10 | UTC → UTC |
+| R3 city | geo | IDENTICAL | 50/50 | 8192/8192 | 8/8 | UTC → UTC |
+| R4 merged | coordinates | IDENTICAL | 440/440 | 8192/8192 | 36/11 | — → — |
+| R4 merged | summary | IDENTICAL | 1/1 | 30440/8192 | 13/9 | UTC → UTC |
+| R4 merged | topReferrers | IDENTICAL | 3/3 | 30440/8192 | 9/8 | UTC → UTC |
+| R4 merged | topPaths | IDENTICAL | 3/3 | 30440/8192 | 12/14 | UTC → UTC |
+| R4 merged | topEvents | IDENTICAL | 3/3 | 30440/30440 | 23/18 | UTC → UTC |
+| R4 merged | recentSessions | IDENTICAL | 8/8 | 30440/8192 | 21/14 | — → — |
+| R4 merged | activeSessions | IDENTICAL | 50/50 | 16384/16384 | 11/9 | — → — |
+| R4 merged | paths | IDENTICAL | 50/50 | 8192/8192 | 9/11 | UTC → UTC |
+| R4 merged | referrals | IDENTICAL | 10/10 | 8192/8192 | 8/11 | UTC → UTC |
+| R4 merged | geo | IDENTICAL | 50/50 | 8192/8192 | 11/9 | UTC → UTC |
+| R5 coordinate | coordinates | IDENTICAL | 440/440 | 8192/8192 | 35/10 | — → — |
+| R5 coordinate | summary | IDENTICAL | 1/1 | 30440/8192 | 16/10 | UTC → UTC |
+| R5 coordinate | topReferrers | IDENTICAL | 3/3 | 30440/8192 | 14/15 | UTC → UTC |
+| R5 coordinate | topPaths | IDENTICAL | 3/3 | 30440/8192 | 23/12 | UTC → UTC |
+| R5 coordinate | topEvents | IDENTICAL | 3/3 | 30440/30440 | 18/15 | UTC → UTC |
+| R5 coordinate | recentSessions | IDENTICAL | 8/8 | 30440/8192 | 13/11 | — → — |
+| R5 coordinate | activeSessions | IDENTICAL | 50/50 | 16384/16384 | 20/18 | — → — |
+| R5 coordinate | paths | IDENTICAL | 50/50 | 8192/8192 | 14/15 | UTC → UTC |
+| R5 coordinate | referrals | IDENTICAL | 10/10 | 8192/8192 | 13/13 | UTC → UTC |
+| R5 coordinate | geo | IDENTICAL | 50/50 | 8192/8192 | 8/8 | UTC → UTC |
+| R6 coordinate -> city fallback | coordinates | IDENTICAL | 440/440 | 8192/8192 | 28/9 | — → — |
+| R6 coordinate -> city fallback | summary | IDENTICAL | 1/1 | 8192/8192 | 9/8 | UTC → UTC |
+| R6 coordinate -> city fallback | topReferrers | IDENTICAL | 3/3 | 8192/8192 | 8/9 | UTC → UTC |
+| R6 coordinate -> city fallback | topPaths | IDENTICAL | 3/3 | 8192/8192 | 9/13 | UTC → UTC |
+| R6 coordinate -> city fallback | topEvents | IDENTICAL | 3/3 | 8192/8192 | 12/22 | UTC → UTC |
+| R6 coordinate -> city fallback | recentSessions | IDENTICAL | 8/8 | 8192/8192 | 17/15 | — → — |
+| R6 coordinate -> city fallback | activeSessions | IDENTICAL | 50/50 | 16384/16384 | 16/13 | — → — |
+| R6 coordinate -> city fallback | paths | IDENTICAL | 50/50 | 8192/8192 | 9/8 | UTC → UTC |
+| R6 coordinate -> city fallback | referrals | IDENTICAL | 10/10 | 8192/8192 | 8/11 | UTC → UTC |
+| R6 coordinate -> city fallback | geo | IDENTICAL | 50/50 | 8192/8192 | 8/10 | UTC → UTC |
+| R7 as rendered, real now() | coordinates | IDENTICAL | 0/0 | 193/193 | 30/8 | — → — |
+| R7 as rendered, real now() | summary | IDENTICAL | 1/1 | 30440/30440 | 16/14 | UTC → UTC |
+| R7 as rendered, real now() | topReferrers | IDENTICAL | 3/3 | 30440/30440 | 11/12 | UTC → UTC |
+| R7 as rendered, real now() | topPaths | IDENTICAL | 3/3 | 30440/30440 | 23/20 | UTC → UTC |
+| R7 as rendered, real now() | topEvents | IDENTICAL | 3/3 | 30440/30440 | 11/16 | UTC → UTC |
+| R7 as rendered, real now() | recentSessions | IDENTICAL | 8/8 | 30440/30440 | 17/18 | — → — |
+| R7 as rendered, real now() | activeSessions | IDENTICAL | 50/50 | 16384/16384 | 19/17 | — → — |
+| R7 as rendered, real now() | paths | IDENTICAL | 50/50 | 8192/8192 | 14/11 | UTC → UTC |
+| R7 as rendered, real now() | referrals | IDENTICAL | 10/10 | 8192/8192 | 15/15 | UTC → UTC |
+| R7 as rendered, real now() | geo | IDENTICAL | 50/50 | 8192/8192 | 11/13 | UTC → UTC |
+
+`rows_read` differing between the two sides on some pairs (e.g. R3 `summary`,
+30440 V1 / 8192 V2) is ClickHouse's index analysis treating a bound
+`{p:String}` differently from an inline literal on the `created_at` range — a
+performance note, not a semantic one, and the returned `data` is byte-identical.
+
+**Verdict: 70 cases, all IDENTICAL** (5 of them IDENTICAL ERROR — V1's
+FixedString(2) overflow, reproduced byte-for-byte and not fixed here).