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.tsindex 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.tsindex 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.tsindex 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-minutconst 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.tsindex 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`SELECTcountry,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)} MINUTEAND longitude IS NOT NULLAND latitude IS NOT NULLGROUP BY country, city, longitude, latitudeORDER 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`SELECTsession_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_sessionWHERE rn = 1ORDER 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`SELECTname, 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, exactlydiff --git a/packages/core/src/modules/realtime/realtime.sql.proof.md b/packages/core/src/modules/realtime/realtime.sql.proof.mdnew file mode 100644index 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).