OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
comments: trim the rewrite's commentary down to what carries knowledge
Carl-Gerhard Lindesvärd9cdfa64681a6
diff --git a/apps/api/e2e/legacy-job-proof.ts b/apps/api/e2e/legacy-job-proof.tsindex 8ad972ef0..377dc1388 100644--- a/apps/api/e2e/legacy-job-proof.ts+++ b/apps/api/e2e/legacy-job-proof.ts@@ -1,14 +1,16 @@/**- * Acceptance proof: a LEGACY-shaped job already sitting in Redis is still- * picked up and run by the V2 worker, with no drain and no rename. Plus the- * other direction — a job the V2 producer enqueues carries the `{payload,- * meta}` envelope and its `requestId` reaches the handler's logger.+ * Acceptance proof: a job already sitting in Redis in the legacy shape is+ * still picked up and run by the current worker, with no drain and no+ * rename. Plus the other direction — a job the current producer enqueues+ * carries the `{payload, meta}` envelope and its `requestId` reaches the+ * handler's logger.** What is real here: the registry (`queues`), every `compat` hook, every job* payload schema, `resolveJob`, BullMQ, and Redis. The legacy jobs are put in- * Redis by `Queue.add(name, data)` with V1's exact data — byte-for-byte the- * call `packages/queue`'s producers make — before any worker starts, so they- * are genuinely waiting on the list when the worker connects.+ * Redis by `Queue.add(name, data)` with the old producer's exact data —+ * byte-for-byte the same call the previous producers made — before any+ * worker starts, so they are genuinely waiting on the list when the worker+ * connects.** Two deliberate narrowings, both stated in the output:*@@ -18,9 +20,9 @@* differs; the un-namespaced keys' byte-identity is pinned separately by* `packages/core/src/jobs/naming.test.ts`. 2. `cron` runs its REAL handlers* over the REAL boot buffers. The other six queues' handlers reach- * `ctx.services`, which needs the db/ch clients `AppDeps` does not carry until- * M9-002/M9-003, so for those six the handler body is a recorder — everything- * up to and including the handler lookup is the real thing.+ * `ctx.services`, which needs db/ch clients `AppDeps` does not carry, so for+ * those six the handler body is a recorder — everything up to and including+ * the handler lookup is the real thing.** Run: `bash apps/api/e2e/legacy-job-proof.sh`*/@@ -53,18 +55,17 @@ type QueueKey = keyof Queues;interface LegacyCase {queue: QueueKey;- /** The BullMQ job name V1 put on the wire. */+ /** The BullMQ job name the old producer put on the wire. */wireName: string;- /** V1's job data, verbatim (was packages/queue/src/queues.ts). */+ /** The legacy producer's job data, verbatim. */data: unknown;- /** The V2 job the compat hook must resolve it to. */+ /** The job the compat hook must resolve it to. */expectJob: string;expectPayload: unknown;}-// One per queue. Every `data` below is a V1 payload type from-// packages/queue/src/queues.ts; `undefined` fields are omitted because JSON-// drops them, which is exactly what is in Redis today.+// One per queue. `undefined` fields are omitted because JSON drops them,+// which is exactly what is in Redis today.const LEGACY_CASES: LegacyCase[] = [{queue: 'cron',@@ -147,8 +148,8 @@ const LEGACY_CASES: LegacyCase[] = [expectPayload: { projectId: 'proj_m9001' },},{- // The one V1 payload with no discriminant at all — a bare `{cohortId}`,- // which must NOT be mistaken for an envelope.+ // The one payload shape with no discriminant at all — a bare+ // `{cohortId}`, which must NOT be mistaken for an envelope.queue: 'cohortCompute',wireName: 'cohortCompute',data: { cohortId: 'coh_m9001' },@@ -249,8 +250,8 @@ function delay(ms: number): Promise<void> {async function main() {const connections: Redis[] = [];const newConnection = () => {- // BullMQ requires `maxRetriesPerRequest: null`; V1's `getRedisQueue` sets- // the same three options.+ // BullMQ requires `maxRetriesPerRequest: null`, plus these matching+ // connection options.const client = new Redis(REDIS_URL, {maxRetriesPerRequest: null,enableReadyCheck: false,diff --git a/apps/api/e2e/metrics-monitor.ts b/apps/api/e2e/metrics-monitor.tsindex 473856f63..bf74153b2 100644--- a/apps/api/e2e/metrics-monitor.ts+++ b/apps/api/e2e/metrics-monitor.ts@@ -1,15 +1,13 @@/*** Queue + buffer sampling from the Prometheus scrape endpoint.*- * Carl asked how ALL the queues are doing, not just Kafka. Everything needed- * is already on `/metrics`: the BullMQ per-queue gauges and the buffer gauges- * and histograms. Scraping is deliberate rather than reaching into Redis or- * into the buffer objects — V1 and V2 both expose the same endpoint, so the- * identical sampler works against either side when the V1 comparison is run.+ * Everything needed is already on `/metrics`: the BullMQ per-queue gauges and+ * the buffer gauges and histograms. Scraping is deliberate rather than+ * reaching into Redis or into the buffer objects directly.*- * Sampling costs the measured process a scrape per tick (~2,700 lines here).- * `session-stress.ts` ties this to the same `E2E_NO_SAMPLING` lever as the- * process/lag monitors so that cost can be ruled in or out.+ * Sampling costs the measured process a scrape per tick. `session-stress.ts`+ * ties this to the same `E2E_NO_SAMPLING` lever as the process/lag monitors+ * so that cost can be ruled in or out.*/const QUEUE_GAUGE =diff --git a/apps/api/e2e/process-monitor.ts b/apps/api/e2e/process-monitor.tsindex c32d98263..3acd581af 100644--- a/apps/api/e2e/process-monitor.ts+++ b/apps/api/e2e/process-monitor.ts@@ -1,10 +1,9 @@/*** RSS/CPU sampling for an arbitrary local process.*- * Prefers the pid file `verification/harness` (the controller's V1 boot- * script) writes per role — `$V1_HARNESS_RUN_DIR/<label>.pid`, default- * `/tmp/openpanel-v1-harness` — since that's the exact process the- * verification stack boots. Falls back to resolving the pid from the TCP+ * Prefers the pid file written per role at `$V1_HARNESS_RUN_DIR/<label>.pid`+ * (default `/tmp/openpanel-v1-harness`), since that's the exact process a+ * harness-managed run boots. Falls back to resolving the pid from the TCP* listen socket on the role's port for any other way of starting the stack* (e.g. `pnpm dev`), where no pid file exists.*@@ -33,7 +32,7 @@ async function isAlive(pid: number): Promise<boolean> {);}-/** Resolve the pid `verification/harness` recorded for `label` ('api' | 'worker'), if live. */+/** Resolve the pid recorded for `label` ('api' | 'worker') in the harness pid file, if live. */async function resolvePidFromHarnessFile(label: string): Promise<number | null> {diff --git a/apps/api/e2e/redis-command-cost.ts b/apps/api/e2e/redis-command-cost.tsindex a0c1c32de..b5f3a493e 100644--- a/apps/api/e2e/redis-command-cost.ts+++ b/apps/api/e2e/redis-command-cost.ts@@ -5,7 +5,7 @@* ingest path now runs under, including the event buffer's writes and reads.* Picking it needs the cost of the heaviest honest command, not a guess: if the* deadline is anywhere near a busy flush, a healthy server starts looking like- * a down one and M18-001's shutdown path starts refusing to commit offsets it+ * a down one and the shutdown path starts refusing to commit offsets it* should have committed.** Measures the four shapes the cache client actually issues, worst first: -diff --git a/apps/api/e2e/redis-fail-fast.ts b/apps/api/e2e/redis-fail-fast.tsindex 048fe0e18..729881d0c 100644--- a/apps/api/e2e/redis-fail-fast.ts+++ b/apps/api/e2e/redis-fail-fast.ts@@ -1,9 +1,8 @@/*** How long does `/track` take when the Redis CACHE is unreachable?*- * Drill 02 measured 9,427 / 12,039 / 41,978 ms and 10-of-20 no-answer. This- * harness reproduces that measurement in-repo so the fix can be justified with- * a before/after on the same box, and re-run by anyone.+ * This harness reproduces that in-repo so a fix can be justified with a+ * before/after on the same box, and re-run by anyone.** It never touches the shared Redis server: the API under test is pointed at a* local TCP proxy which is then stopped (`refuse`, docker-stop shaped) or@@ -31,7 +30,7 @@ const CORS_ORIGIN = 'https://e2e.test';const UA ='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36';-/** What drill 02's ledger client waited before recording "no response". */+/** How long the client waits before recording "no response". */const CLIENT_TIMEOUT_MS = Number(process.env.M18_CLIENT_TIMEOUT_MS ?? 30_000);const BOOT_TIMEOUT_MS = 60_000;const WARMUP_REQUESTS = 6;@@ -207,9 +206,9 @@ interface Probe {}/**- * A client that gives up after `CLIENT_TIMEOUT_MS`, the way drill 02's ledger- * client did. An explicit controller rather than `AbortSignal.timeout`, which- * does not interrupt an in-flight Bun fetch here.+ * A client that gives up after `CLIENT_TIMEOUT_MS`. An explicit controller+ * rather than `AbortSignal.timeout`, which does not interrupt an in-flight+ * Bun fetch here.*/async function timedFetch(url: string, init: RequestInit = {}): Promise<Probe> {const controller = new AbortController();diff --git a/apps/api/e2e/session-stress.ts b/apps/api/e2e/session-stress.tsindex 9776c90ae..3ace18bb3 100644--- a/apps/api/e2e/session-stress.ts+++ b/apps/api/e2e/session-stress.ts@@ -6,14 +6,13 @@* session_end emitted, Redis cleaned, the session buffer empty — and reconciles* the ClickHouse counts. Exits 0 only when nothing is left open.*- * Also instruments the run (BENCH-001): per-request /track latency+ * Also instruments the run: per-request /track latency* (P50/P95/P99, emit phase only), RSS/CPU of the api + worker processes (>=1Hz,* peak + steady-state), Kafka consumer-group lag on the events topic (>=1Hz;* peak, lag at emit-end, seconds-to-zero after emit stops), and every BullMQ* queue depth + buffer pending count scraped off /metrics (>=1Hz; peak, depth- * at emit-end, whether it returned to zero — M16-001). None of it changes what- * the run asserts — see `check` calls below, unchanged from the un-instrumented- * version.+ * at emit-end, whether it returned to zero). None of it changes what+ * the run asserts — see `check` calls below.** `saturation-sweep.ts` drives this script across a ladder of offered loads;* see docs/BENCHMARK_HARNESS.md.@@ -116,7 +115,7 @@ const RECONCILE_STABLE_SAMPLES = 3;// leave within milliseconds of the captured start.const RECONCILE_WINDOW_LEAD_MS = 2000;-// >=1Hz per the acceptance criteria; 1000ms is the floor, not a target.+// Sampling runs at >=1Hz; 1000ms is the floor, not a target.const SAMPLE_INTERVAL_MS = 1000;const E2E_RUNS = Number.parseInt(process.env.E2E_RUNS || '1', 10);@@ -127,11 +126,10 @@ const E2E_RUNS = Number.parseInt(process.env.E2E_RUNS || '1', 10);const IS_REPEAT_CHILD = process.env.E2E_STRESS_CHILD === '1';const RESULT_MARKER = 'E2E_STRESS_RESULT ';-// Control lever for BENCH-001's 10% rule: a run with this set skips the-// process/lag monitors so their >=1Hz polling can be ruled in or out as the-// cause of a throughput delta against the P1 baseline. Latency recording-// stays on regardless — it wraps the request the run is already making, not-// an added background poller.+// Control lever: a run with this set skips the process/lag monitors so+// their >=1Hz polling can be ruled in or out as the cause of a throughput+// delta. Latency recording stays on regardless — it wraps the request the+// run is already making, not an added background poller.const SAMPLING_ENABLED = process.env.E2E_NO_SAMPLING !== '1';type Session = { sessionId: string; deviceId: string };@@ -158,7 +156,7 @@ export interface RunResult {}// Unique IP per session → unique device → unique session. Namespaced by runId-// so reruns and the correctness harness (10.x) never collide.+// so reruns and the correctness harness never collide.const ipForSession = (i: number) =>`100.${(runId >> 8) & 255}.${(i >> 8) & 255}.${i & 255}`;@@ -178,7 +176,7 @@ const pick = <T>(arr: T[]): T => arr[Math.floor(Math.random() * arr.length)]!;function randomProps(ip: string): Record<string, unknown> {const props: Record<string, unknown> = { __ip: ip };- const n = Math.floor(Math.random() * 4); // 0–3 extra properties+ const n = Math.floor(Math.random() * 4);for (let k = 0; k < n; k++) {props[`prop_${pick(WORDS)}`] =Math.random() < 0.5 ? pick(WORDS) : Math.floor(Math.random() * 1000);@@ -221,7 +219,7 @@ async function emit(): Promise<{async (i) => {const ip = ipForSession(i);try {- const first = await sendSessionEvent(ip, i, 0); // entry is a screen_view+ const first = await sendSessionEvent(ip, i, 0);for (let e = 1; e < EVENTS_PER_SESSION; e++) {await sendSessionEvent(ip, i, e);}@@ -345,8 +343,8 @@ async function drain(sessions: Session[]) {** Why the device: until the worker has persisted the session blob, the API* answers from a session id that is deterministic per SESSION_TIMEOUT_MS-wide- * time bucket (apps/api/src/utils/ids.ts). At the harness's compressed 4s- * window a bucket boundary falls inside the emit ramp, so an in-flight+ * time bucket. At the harness's compressed 4s window a bucket boundary falls+ * inside the emit ramp, so an in-flight* session's next event is told a different id — the row still lands, under a* session id the harness was never given. The device is the stable identity* for "what this run sent"; `since` keeps earlier runs' rows out, because adiff --git a/apps/api/e2e/trpc-routing-golden.ts b/apps/api/e2e/trpc-routing-golden.tsindex a98eec31a..959e7e781 100644--- a/apps/api/e2e/trpc-routing-golden.ts+++ b/apps/api/e2e/trpc-routing-golden.ts@@ -2,7 +2,7 @@/*** TRPC routing golden — proves every procedure the mounted router declares is* reachable through the real HTTP lifecycle, and that the auth layer answers- * identically before and after the M11-001 mount swap.+ * identically before and after swapping the mount.** Only 11 of 217 procedures have any end-to-end coverage and 22 of the 29* routers have none, so swapping `apps/api/src/main.ts`'s `appRouter` import@@ -27,8 +27,8 @@ import { readFileSync, writeFileSync } from 'node:fs';import { dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';-// `import.meta.dir` is the Bun idiom (ADR-019 row 6), but apps/api's tsconfig-// carries no bun type declarations, so this file uses the portable form.+// `import.meta.dir` is the Bun idiom, but apps/api's tsconfig carries no bun+// type declarations, so this file uses the portable form.const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)),'..',diff --git a/apps/api/scripts/test-manage-api.ts b/apps/api/scripts/test-manage-api.tsindex 2b2236fab..a4169beac 100644--- a/apps/api/scripts/test-manage-api.ts+++ b/apps/api/scripts/test-manage-api.ts@@ -80,7 +80,6 @@ async function makeRequest(async function testProjects() {console.log('\n📁 Testing Projects endpoints...\n');- // Create projectconst createResult = await makeRequest('POST', '/manage/projects', {name: `Test Project ${Date.now()}`,domain: 'https://example.com',@@ -110,7 +109,6 @@ async function testProjects() {}}- // List projectsconst listResult = await makeRequest('GET', '/manage/projects');results.push(listResult);console.log(@@ -121,14 +119,12 @@ async function testProjects() {}if (projectId) {- // Get projectconst getResult = await makeRequest('GET', `/manage/projects/${projectId}`);results.push(getResult);console.log(`✓ GET /manage/projects/:id: ${getResult.success ? '✅' : '❌'} ${getResult.status}`);- // Update projectconst updateResult = await makeRequest('PATCH',`/manage/projects/${projectId}`,@@ -159,7 +155,6 @@ async function testProjects() {async function testClients(projectId?: string) {console.log('\n🔑 Testing Clients endpoints...\n');- // Create clientconst createResult = await makeRequest('POST', '/manage/clients', {name: `Test Client ${Date.now()}`,projectId: projectId || undefined,@@ -183,7 +178,6 @@ async function testClients(projectId?: string) {}}- // List clientsconst listResult = await makeRequest('GET',projectId ? `/manage/clients?projectId=${projectId}` : '/manage/clients'@@ -197,14 +191,12 @@ async function testClients(projectId?: string) {}if (clientId) {- // Get clientconst getResult = await makeRequest('GET', `/manage/clients/${clientId}`);results.push(getResult);console.log(`✓ GET /manage/clients/:id: ${getResult.success ? '✅' : '❌'} ${getResult.status}`);- // Update clientconst updateResult = await makeRequest('PATCH',`/manage/clients/${clientId}`,@@ -217,7 +209,6 @@ async function testClients(projectId?: string) {`✓ PATCH /manage/clients/:id: ${updateResult.success ? '✅' : '❌'} ${updateResult.status}`);- // Delete clientconst deleteResult = await makeRequest('DELETE',`/manage/clients/${clientId}`@@ -237,7 +228,6 @@ async function testReferences(projectId?: string) {return;}- // Create referenceconst createResult = await makeRequest('POST', '/manage/references', {projectId,title: `Test Reference ${Date.now()}`,@@ -258,7 +248,6 @@ async function testReferences(projectId?: string) {console.log(` Created reference: ${referenceId}`);}- // List referencesconst listResult = await makeRequest('GET',`/manage/references?projectId=${projectId}`@@ -272,7 +261,6 @@ async function testReferences(projectId?: string) {}if (referenceId) {- // Get referenceconst getResult = await makeRequest('GET',`/manage/references/${referenceId}`@@ -282,7 +270,6 @@ async function testReferences(projectId?: string) {`✓ GET /manage/references/:id: ${getResult.success ? '✅' : '❌'} ${getResult.status}`);- // Update referenceconst updateResult = await makeRequest('PATCH',`/manage/references/${referenceId}`,@@ -297,7 +284,6 @@ async function testReferences(projectId?: string) {`✓ PATCH /manage/references/:id: ${updateResult.success ? '✅' : '❌'} ${updateResult.status}`);- // Delete referenceconst deleteResult = await makeRequest('DELETE',`/manage/references/${referenceId}`@@ -318,13 +304,11 @@ async function main() {// Test projects first (creates a project we can use for other tests)const { projectId } = await testProjects();- // Test clientsawait testClients(projectId);// Test references (requires a project)await testReferences(projectId);- // Summaryconsole.log(`\n${'='.repeat(60)}`);console.log('📊 Test Summary\n');const successful = results.filter((r) => r.success).length;diff --git a/apps/api/src/config/env.ts b/apps/api/src/config/env.tsindex 4fc322501..522448f31 100644--- a/apps/api/src/config/env.ts+++ b/apps/api/src/config/env.ts@@ -1,30 +1,22 @@-// The sole `process.env` READER on the V2 boot path, and since M15-006 that is-// true rather than aspirational: `packages/core` reads none, so every variable-// core used to read itself is parsed here and travels down as `AppDeps.config`-// (`CoreConfig`). The one other `process.env` touch on the path is `main.ts`'s-// `process.env.TZ = 'UTC'` write, which sets the process's timezone rather than-// reading configuration. `packages/db` and `packages/redis` keep reading their-// own connection env until they grow factories — an accepted pragmatic-// deviation (ADR-007 §7).+// The sole `process.env` reader on the boot path: `packages/core` reads none,+// so every variable it needs is parsed here and travels down as+// `AppDeps.config` (`CoreConfig`). `packages/db` and `packages/redis` still+// read their own connection env directly — an accepted pragmatic deviation.//-// The shape is ADR-022 R17's, in this order: 1. one zod object over the raw-// environment; 2. every cross-field invariant as a `.superRefine` BEFORE the-// transform, so a contradiction is named at boot rather than discovered at-// runtime; 3. one `.transform` that computes every derived value — URLs,-// namespaces, IS_PRODUCTION, the listen address, the concurrency map — so-// nothing downstream re-derives one; 4. `loadConfig(source = process.env)`, so-// a test hands in a minimal object.+// Every cross-field invariant runs as a `.superRefine` BEFORE the `.transform`,+// so a contradiction is named at boot rather than discovered at runtime.+// `loadConfig(source = process.env)` takes the environment as a parameter so a+// test can hand in a minimal object.//// A blank `KEY=` is absent everywhere: `blankToUndefined` runs in front of// every field, so `.default` fires on an empty value exactly as it does on an// unset one.//// Invalid config fails boot loudly, with every issue reported at once — never a-// fail-fast on the first bad var. Two classes, deliberately different: --// boot-critical values (roles, queues, Kafka wiring) FAIL; - tuning knobs+// fail-fast on the first bad var. Two classes, deliberately different:+// boot-critical values (roles, queues, Kafka wiring) FAIL; tuning knobs// (batch sizes, limits, TTLs) fall back to the module's own documented default-// on a malformed value, which is what the modules did when they parsed these-// themselves.+// on a malformed value.import type { CoreConfig, KafkaSaslMechanism } from '@openpanel/core';import { KAFKA_SASL_MECHANISMS, queues } from '@openpanel/core';@@ -42,7 +34,6 @@ const PRODUCTION = 'production';const DEVELOPMENT = 'development';/** pino's own service-name suffix when NODE_ENV is unset. */const DEFAULT_SERVICE_ENVIRONMENT = 'dev';-/** V1's worker deadline (apps/worker/src/boot-workers.ts). */const DEFAULT_SHUTDOWN_FORCE_EXIT_MS = 20_000;const DEFAULT_KAFKA_CLIENT_ID = 'openpanel';@@ -62,23 +53,23 @@ const DEFAULT_KAFKA_PRODUCER_RETRIES = 2;const DEFAULT_KAFKA_PRODUCER_INITIAL_RETRY_MS = 100;const DEFAULT_KAFKA_PRODUCER_MAX_RETRY_MS = 1000;/**- * One produce round-trip at a time. ADR-023 rejects raising this: measured at- * +2-3%, i.e. noise, for a documented reordering hazard.+ * One produce round-trip at a time — raising this trades a documented+ * reordering hazard for a throughput gain that measured as noise (2-3%).*/const DEFAULT_KAFKA_PRODUCER_MAX_IN_FLIGHT = 1;-/** Messages per `send()`. ADR-023: batching on; the win is flat above 25. */+/** Messages per `send()`; batching's throughput win is flat above this size. */const DEFAULT_KAFKA_PRODUCER_BATCH_SIZE = 25;/**- * A partial batch's maximum wait. The linger is added to the request's own- * response time, so ADR-023 takes 5 ms (82% of the available gain) over the 25- * ms that would roughly double a quiet install's ingest latency.+ * A partial batch's maximum wait, added to the request's own response time —+ * kept small because a larger linger would roughly double ingest latency on a+ * quiet install.*/const DEFAULT_KAFKA_PRODUCER_BATCH_LINGER_MS = 5;const DEFAULT_KAFKA_HANDLER_MAX_ATTEMPTS = 3;/**- * How many dead-lettered events the capped Redis list keeps. A debugging- * sample, not a recovery mechanism — the volume is in- * `kafka_events_dead_lettered_total`. Carl's "only keep the last N events".+ * How many dead-lettered events the capped Redis list keeps — a debugging+ * sample, not a recovery mechanism; the real volume is in the+ * `kafka_events_dead_lettered_total` metric.*/const DEFAULT_INGEST_DEAD_LETTER_MAX_ENTRIES = 1000;const DEFAULT_KAFKA_HANDLER_RETRY_INITIAL_MS = 100;@@ -86,26 +77,22 @@ const DEFAULT_KAFKA_HANDLER_RETRY_MAX_MS = 1000;const DEFAULT_KAFKA_SASL_MECHANISM: KafkaSaslMechanism = 'scram-sha-512';/**- * How long a duplicate marker outlives its event. It only has to outlive the- * REPLAY window, not the data: drill 08's eviction rejoin — the one- * reassignment that costs duplicate rows — was 3,094 ms, and drill 06's- * lost-ACK replay landed ~30 s after the produce. Two minutes is ~40x the first- * and 4x the second, and covers a process restart resuming from its last- * committed offset.+ * How long a duplicate marker outlives its event — it only needs to outlive+ * the replay window, not the data. Two minutes gives comfortable margin over+ * observed redelivery windows (a consumer-eviction rejoin lands in seconds; a+ * lost-ACK replay lands ~30s out) and covers a process restart resuming from+ * its last committed offset.*- * It is the knob that decides the key count, which is `events/s x TTL`: at the- * 5,000 events/s the scaling requirement targets that is 600,000 live markers.- * Measured on this box's Redis 2026-09-14 — 200,000 real markers cost 137.6- * bytes each including the expires dict — so ~79 MB. Longer is only worth- * buying if a redelivery window longer than this is ever observed.+ * It also sets the live key count (`events/s x TTL`), so raising it is a+ * direct Redis-memory cost, not a free knob.*/const DEFAULT_INGEST_DUPLICATE_MARKER_TTL_MS = 120_000;/**- * The Kafka events consumer's token. Renamed from `events_kafka` — there is one- * events transport now, so there is one token for it (ADR-004 rec 5/6). Carl- * updates the cloud env at cutover, which is why the old spelling gets its own- * message below rather than being aliased.+ * The Kafka events consumer's token. Renamed from `events_kafka` — there is+ * one events transport now, so there is one token for it. The old spelling+ * gets its own error message below (`RENAMED_QUEUE_TOKENS`) rather than being+ * silently aliased, since a deployment's env is updated at its own pace.*/export const KAFKA_QUEUE_TOKEN = 'events';@@ -122,17 +109,17 @@ const RENAMED_QUEUE_TOKENS: Record<string, string> = {events_kafka: KAFKA_QUEUE_TOKEN,};-/** V1's `getConcurrencyFor` key derivation, verbatim — `cohortCompute` keeps- * Reading `COHORTCOMPUTE_CONCURRENCY` (ADR-005 acceptance note: no rename). */+/** Uppercases and strips non-alphanumerics to build the env key, so+ * `cohortCompute` deliberately keeps reading `COHORTCOMPUTE_CONCURRENCY`+ * rather than a hyphenated or underscored variant. */const NON_ENV_KEY_CHARS = /[^A-Z0-9]/g;export function concurrencyEnvKey(queueName: string): string {return `${queueName.toUpperCase().replace(NON_ENV_KEY_CHARS, '_')}_CONCURRENCY`;}-// An unset or blank var falls through to the default, matching the-// `value?.trim() || fallback` idiom the ported reads used before this file-// existed — `.default()` alone only fires on `undefined`, not `""`.+// An unset or blank var falls through to the default — `.default()` alone+// only fires on `undefined`, not `""`.function blankToUndefined(value: unknown): unknown {if (typeof value !== 'string') {return value;@@ -158,7 +145,7 @@ const optionalString = z.preprocess(blankToUndefined, z.string().optional());const stringWithDefault = (fallback: string) =>z.preprocess(blankToUndefined, z.string().default(fallback));-/** `KEY=true` or `KEY=1`. The two spellings V1 accepted interchangeably. */+/** `KEY=true` or `KEY=1` are both accepted as on. */const trueOrOneSchema = z.preprocess(blankToUndefined,z@@ -215,7 +202,7 @@ const kafkaSaslMechanismSchema = z.preprocess(.transform((value) => value as KafkaSaslMechanism | undefined));-/** Any defined value means on — V1's spelling for DISABLE_WORKERS. */+/** Any defined value means on. */const definedIsTrueSchema = z.preprocess(blankToUndefined,z@@ -253,8 +240,7 @@ const onUnlessZeroSchema = z.preprocess(/*** A tuning knob: a positive integer, or `undefined` when unset OR malformed.* Malformed keeps the module's own default rather than failing boot — `-1`,- * `0` and `5000junk` all land on `undefined`, which is what the hand-rolled- * `parsePositiveInt` guards in `cohort.service.ts` and `lookback.ts` did.+ * `0` and `5000junk` all land on `undefined`.*/const optionalPositiveInt = z.preprocess(blankToUndefined,@@ -288,9 +274,8 @@ const tokenList = z.preprocess();/**- * Same doctrine as `ENABLED_QUEUES` (apps/worker/src/boot-workers.ts's- * `assertKnownQueue`): a stale or mistyped value fails boot loudly, naming- * both the offending value and the accepted set.+ * Same doctrine as `ENABLED_QUEUES` below: a stale or mistyped value fails+ * boot loudly, naming both the offending value and the accepted set.*/const roleSchema = z.preprocess(blankToUndefined,@@ -343,8 +328,8 @@ const enabledQueuesSchema = z.preprocess());-/** One `<QUEUE>_CONCURRENCY` slot per registry queue. V1 ignored a- * non-numeric or non-positive value and kept the default; so does this. */+/** One `<QUEUE>_CONCURRENCY` slot per registry queue. A non-numeric or+ * non-positive value is ignored and the default kept. */const concurrencyShape = Object.fromEntries(Object.keys(queues).map((name) => [concurrencyEnvKey(name),@@ -364,21 +349,16 @@ const rawSchema = z.object({z.coerce.number().int().min(0).default(DEFAULT_API_PORT)),/**- * Left UNSET means Bun's own default, `0.0.0.0`.- *- * Deliberate deviation from V1, which defaulted to `localhost` outside- * production (apps/api/src/index.ts): `Bun.serve({hostname:'localhost'})`- * binds `::1` ONLY, so a dev box's `127.0.0.1` request is refused. Making- * the loopback-only bind explicit rather than the accidental default is- * what keeps `bun run src/main.ts` reachable the way `node dist/index.js`- * was.+ * Left UNSET means Bun's own default, `0.0.0.0`. `localhost` is deliberately+ * not the default: `Bun.serve({hostname:'localhost'})` binds `::1` ONLY, so+ * a dev box's `127.0.0.1` request would be refused.*/API_HOST: optionalString,/**- * One truthiness rule for the whole tree. Core used to read this three- * different ways — `=== 'true'`, `'true' || '1'`, and any truthy string — so- * a `SELF_HOSTED=1` deployment got the SSRF guard dropped but kept the- * cloud-only cron jobs. `true` or `1`, everywhere.+ * One truthiness rule for the whole tree — `true` or `1`, everywhere.+ * Reading this inconsistently across call sites is how a `SELF_HOSTED=1`+ * deployment could get the SSRF guard dropped while keeping the+ * cloud-only cron jobs.*/SELF_HOSTED: trueOrOneSchema,SHUTDOWN_FORCE_EXIT_MS: z.preprocess(@@ -388,12 +368,9 @@ const rawSchema = z.object({// --- queues ---/**- * Redis Cluster hash-tags every queue key (`cron` -> `{cron}`). Read here- * because `main.ts` hands it to `createProducers`, and it decides a Redis- * key name: set it on a deployment whose queues already exist unbraced and- * every one of them is orphaned. V1 read it as a bare truthy check- * (`packages/queue/src/queues.ts` `getQueueName`); a blank value is unset,- * exactly as before.+ * Redis Cluster hash-tags every queue key (`cron` -> `{cron}`). It decides a+ * Redis key name: set it on a deployment whose queues already exist+ * unbraced and every one of them is orphaned.*/QUEUE_CLUSTER: definedIsTrueSchema,/**@@ -411,16 +388,13 @@ const rawSchema = z.object({// --- HTTP surface ---/**- * The CORS delegator's allowlist (apps/api/src/app.ts:107-110): the- * dashboard's own origin plus any extra comma-separated ones. Read once at- * boot, exactly as V1 did — changing an origin has always needed a restart.+ * The CORS delegator's allowlist: the dashboard's own origin plus any extra+ * comma-separated ones. Read once at boot — changing an origin needs a+ * restart.*/DASHBOARD_URL: optionalString,API_CORS_ORIGINS: optionalString,- /**- * Signs the three GSC OAuth cookies. Always set in a real deployment; an- * unset value degrades to V1's `?? ''`.- */+ /** Signs the three GSC OAuth cookies. Always set in a real deployment. */COOKIE_SECRET: z.preprocess(blankToUndefined,z.string().optional().default('')@@ -428,7 +402,7 @@ const rawSchema = z.object({/** Set on the demo deployment only. `validateSessionToken` short-circuits on* it, and `enforceAccess` bans mutations for it. */DEMO_USER_ID: optionalString,- /** V1's `requestLoggingHook`: the client ids whose requests log ip/UA. */+ /** The client ids whose requests log ip/UA. */ENABLE_VERBOSE_LOGGING: optionalString,// --- logging ---@@ -771,7 +745,7 @@ function deriveKafkaConfig(raw: RawEnv): CoreConfig['kafka'] {brokers: raw.KAFKA_BROKERS,eventsTopic: raw.KAFKA_EVENTS_TOPIC,// Same broker as the events topic, so a poison message is retained and- // countable instead of dropped (ADR-004 delivery semantics).+ // countable instead of dropped.eventsDlqTopic:raw.KAFKA_EVENTS_DLQ_TOPIC ?? `${raw.KAFKA_EVENTS_TOPIC}-dlq`,consumerGroup: raw.KAFKA_CONSUMER_GROUP,diff --git a/apps/api/src/main.ts b/apps/api/src/main.tsindex bdfc9b010..7e3d91ba7 100644--- a/apps/api/src/main.ts+++ b/apps/api/src/main.ts@@ -1,27 +1,10 @@-// THE boot entrypoint (ADR-007 §7 "apps/api — three files"; TARGET_ARCHITECTURE-// §7 main.ts boot order). Runs on Bun. M9-004 deleted the V1 Fastify boot-// (`./index.ts` + `./app.ts`), so this file is the only way the API starts and-// `app.ts`'s mounting half lives in `buildHttpApp` below.+// The boot entrypoint. Runs on Bun; this is the only way the API starts, and+// `buildHttpApp` below mounts the whole HTTP surface.//-// THE ROLE TABLE (TARGET_ARCHITECTURE §7). One process, three shapes:-//-// | | api | worker | all | | ops HTTP + /metrics | x | x | x | | producers | x-// | x | x | | BullMQ workers | | x | x | | schedulers (cron) | | x | x | |-// Kafka ingest | | x | x | | initial salts | | x | x | | bull-board | | x | x |-// | queue/buffer/session scrape gauges | | x | x | | redis keyspace-notify | x-// | | x |-//-// An unknown ROLE fails boot loudly, naming the value — `config/env.ts`. Inside-// a consuming role, ENABLED_QUEUES narrows *which* of the eight consumers start+// An unknown ROLE fails boot loudly, naming the value — `config/env.ts`.+// Inside a consuming role, ENABLED_QUEUES narrows *which* consumers start// (cloud runs 4 replicas on `events` and 6 on the rest), and an unknown token// there fails boot the same way.-//-// THE MOUNTED SURFACE. `AppDeps` now carries the real db, ClickHouse, Redis and-// outbound clients, and `buildHttpApp` hangs all four V1 scopes on one-// Bun.serve: the root chain (CORS -> requestId -> timestamp -> ip -> the error-// handler, in V1's order), the ops surface, the public API, the dashboard-// surface and `/trpc`. A role that only consumes serves none of the last three-// — V1's worker never did either.// The only `process.env` touch outside config/env.ts, and a WRITE: it sets the// process timezone. Every value the app READS comes from `loadConfig` below.@@ -97,7 +80,6 @@ const CRON_QUEUE_NAME = 'cron';// Used only to report a config error itself — the real level isn't known// until `config/env.ts` has validated `LOG_LEVEL`.const BOOTSTRAP_LOG_LEVEL = 'info';-// V1's cron drain bound (apps/worker/src/boot-workers.ts `waitForQueueToEmpty`).const CRON_DRAIN_TIMEOUT_MS = 60_000;const CRON_DRAIN_POLL_MS = 500;const FATAL_EXIT_DELAY_MS = 1000;@@ -133,21 +115,16 @@ const logger = pino({ name: 'api', level: config.LOG_LEVEL });/** ROLE=api produces and serves; it never consumes. */const roleConsumes = config.ROLE !== 'api';-/** ROLE=worker consumes and never serves a URL surface, exactly as V1's- * worker did (it ran bull-board, /debug/cron and /metrics, nothing else). */+/** Gates only the public API, dashboard and /trpc surfaces — bull-board,+ * /debug/cron and /metrics are gated separately by `roleConsumes`. */const roleServesHttp = config.ROLE !== 'worker';const workersEnabled = roleConsumes && !config.DISABLE_WORKERS;/**- * All seven queues, envelope on, on the Redis keys V1 already uses — so a job- * V1 enqueued before the cutover is read back by V2's `resolveJob` through that- * queue's compat hook, with no drain and no rename.- *- * The connection is `packages/redis`'s dedicated queue client: a separate- * client from cache/pub/sub with `maxRetriesPerRequest: null`, which is what- * BullMQ requires and exactly what V1's `packages/queue` producers connect- * through. It stays that package's singleton to close (ADR-007 §7's accepted- * pragmatic deviation); `producers.close` closes the queues over it.+ * The connection is `packages/redis`'s dedicated queue client: separate from+ * cache/pub/sub, with `maxRetriesPerRequest: null`, which BullMQ requires. It+ * stays that package's singleton to close; `producers.close` closes the+ * queues over it.*/function buildProducerHandle(): QueueProducerHandle {return createProducers(queues, {@@ -160,9 +137,8 @@ function buildProducerHandle(): QueueProducerHandle {/*** A named child of the boot logger per buffer, plus the buffers' one direct- * BullMQ read — ADR-005's `bullQueues` escape hatch. Pausing `cron` from- * bull-board halts ALL buffer flushing, preserved deliberately as an- * accepted trade-off.+ * BullMQ read. Pausing `cron` from bull-board halts ALL buffer flushing —+ * preserved deliberately as an accepted trade-off.*/function bufferDeps(producers: QueueProducerHandle): BufferDeps {const cron = findBullQueue(producers, CRON_QUEUE_NAME);@@ -190,12 +166,11 @@ function findBullQueue(producers: QueueProducerHandle, name: string) {function buildDeps(): AppDeps {const producers = buildProducerHandle();return {- // The four boot handles. `packages/db` and `packages/redis` still own their- // own singletons and read their own env (ADR-007 §7's accepted pragmatic- // deviation), so these are references to those, not new connections: one- // Prisma client, one round-robin ClickHouse client and the cache Redis,- // handed down so a service reaches them through its request-scoped `Ctx`- // instead of importing them.+ // The four boot handles. `packages/db` and `packages/redis` still own+ // their own singletons and read their own env, so these are references+ // to those, not new connections: one Prisma client, one round-robin+ // ClickHouse client and the cache Redis, handed down so a service reaches+ // them through its request-scoped `Ctx` instead of importing them.db,// Prisma's two JSON sentinels, so the four modules that write a nullable// `Json?` column read them off the scope instead of importing the client.@@ -213,9 +188,8 @@ function buildDeps(): AppDeps {/*** The queues this process consumes, `<QUEUE>_CONCURRENCY` applied.*- * ENABLED_QUEUES is the same allowlist V1 read, and its `events` token selects- * the Kafka consumer rather than a BullMQ queue — hence it is filtered out- * here and asked about separately.+ * ENABLED_QUEUES's `events` token selects the Kafka consumer rather than a+ * BullMQ queue — hence it is filtered out here and asked about separately.*/function consumedQueues(): Record<string, QueueDefinition> {const enabled = new Set(config.ENABLED_QUEUES);@@ -277,21 +251,20 @@ async function startIngestConsumer(handleEvent: createIncomingEventHandler(deps, {checkNotificationRulesForEvent,// MARKS a redelivery, never drops one — the event is inserted either- // way. The CACHE client, again, and for the same reason: a handler that- // blocks on Redis is what got drill 02's consumer evicted past its- // session timeout, and an eviction is the one reassignment M19 measured- // costing duplicate rows.+ // way. The CACHE client, again, and for the same reason: a handler+ // that blocks on Redis risks evicting the consumer past its session+ // timeout, and an eviction is what causes duplicate rows.markDuplicateEvent: createDuplicateEventMarker({client: deps.redis,ttlMs: config.INGEST_DUPLICATE_MARKER_TTL_MS,}),}),- // A capped Redis list, and the event is DROPPED whether or not the record- // lands. The Kafka DLQ it replaced (`produceDeadLetterEvent`, still- // exported from core) produced to a topic nothing creates — 1,592- // failures, 0 successes in drill 08 — and every failure held the offset- // back, which was the redelivery loop. The CACHE client, not the queue- // client: only that one fails fast, and failing fast is the point here.+ // A capped Redis list, and the event is DROPPED whether or not the+ // record lands. The Kafka DLQ it replaced (`produceDeadLetterEvent`,+ // still exported from core) produced to a topic nothing creates, and+ // every failure held the offset back — a redelivery loop. The CACHE+ // client, not the queue client: only that one fails fast, and failing+ // fast is the point here.sendToDeadLetter: createDeadLetterRecorder({client: deps.redis,maxEntries: config.INGEST_DEAD_LETTER_MAX_ENTRIES,@@ -312,10 +285,8 @@ async function startIngestConsumer(}/**- * V1's shutdown drain (apps/worker/src/boot-workers.ts): let the cron queue- * finish what it started before closing the workers, because a cron job cut in- * half comes back as a stalled retry. One of ADR-005's four sanctioned- * `bullQueues` call sites.+ * Let the cron queue finish what it started before closing the workers,+ * because a cron job cut in half comes back as a stalled retry.*/async function waitForCronToDrain(producers: QueueProducerHandle) {const cron = findBullQueue(producers, CRON_QUEUE_NAME);@@ -344,7 +315,7 @@ async function waitForCronToDrain(producers: QueueProducerHandle) {function registerConsumerMetrics(deps: AppDeps): void {// Scrape-time collectors register only where a role consumes: each is a// Redis round trip per scrape, and ten API replicas exposing them would- // multiply that for no new information (TARGET_ARCHITECTURE §18).+ // multiply that for no new information.registerBufferMetrics(deps.buffers);registerQueueMetrics(deps.producers.bullQueues);registerSessionScrapeMetrics(@@ -353,11 +324,10 @@ function registerConsumerMetrics(deps: AppDeps): void {}/**- * The three cookies the GSC OAuth flow signs (gsc.rpc.ts's `signed: true`). V1- * signed them through `@fastify/cookie`'s `secret`; Elysia takes the same list,- * and `signCookie` below produces the identical `value.<b64 hmac>` form on the- * tRPC side, which writes cookies through the fetch adapter's `resHeaders`- * rather than through Elysia (ADR-009 constraint 1).+ * The three cookies the GSC OAuth flow signs (gsc.rpc.ts's `signed: true`).+ * `signCookie` below produces the same `value.<b64 hmac>` form on the tRPC+ * side, which writes cookies through the fetch adapter's `resHeaders` rather+ * than through Elysia.*/const SIGNED_COOKIE_NAMES = ['gsc_oauth_state',@@ -378,25 +348,18 @@ function signCookie(value: string): string {}/**- * V1's `app.ts`, merged into the one entrypoint: the four Fastify scopes become- * one Elysia tree.- *- * THE ROOT CHAIN ORDER IS THE CONTRACT (ADR-002 "behaviour that must be- * preserved explicitly" 2): cors -> requestId -> timestamp -> ip, before every- * route-level hook. `requestLogging` brings `requestContext` — and therefore- * those three hooks — with it, and the error handler is registered on the same- * root so it covers every scope below.+ * THE ROOT CHAIN ORDER IS THE CONTRACT: cors -> requestId -> timestamp -> ip,+ * before every route-level hook. `requestLogging` brings `requestContext` —+ * and therefore those three hooks — with it, and the error handler is+ * registered on the same root so it covers every scope below.*- * `ROLE=worker` mounts NONE of the three URL surfaces: V1's worker served only- * bull-board, the debug routes and `/metrics`, and a worker replica answering- * `/track` would take traffic no load balancer routes to it.+ * `ROLE=worker` mounts NONE of the three URL surfaces: a worker replica+ * answering `/track` would take traffic no load balancer routes to it.*/async function buildHttpApp(deps: AppDeps) {const app = new Elysia({- // Elysia throws on an empty `secrets`, where V1 passed `secret: ''` to- // @fastify/cookie and simply produced signatures nobody could rely on. A- // deployment without COOKIE_SECRET therefore gets unsigned cookies rather- // than a dead process — the same outcome V1 had, arrived at explicitly.+ // Elysia throws on an empty `secrets`. A deployment without COOKIE_SECRET+ // therefore gets unsigned cookies rather than a dead process.cookie: config.COOKIE_SECRET? { secrets: config.COOKIE_SECRET, sign: SIGNED_COOKIE_NAMES }: {},@@ -438,9 +401,9 @@ async function buildHttpApp(deps: AppDeps) {}// Local-only: trigger a cron job on demand instead of waiting for its- // schedule. Two conditions, both V1's: `NODE_ENV != production`, because it- // is an unauthenticated "run anything now" surface, and a consuming role,- // because in V1 these routes only ever existed on the worker.+ // schedule. Gated by `NODE_ENV != production`, because it is an+ // unauthenticated "run anything now" surface, and by a consuming role,+ // since these routes only make sense there.if (roleConsumes && !config.core.isProduction) {app.use(debugRoutes(deps));logger.info('Debug routes enabled at /debug/cron');@@ -460,10 +423,9 @@ async function buildHttpApp(deps: AppDeps) {** Fatals are mirrored to the REAL stderr, bypassing the output interceptor:* the OTLP flush window is often lost on the way down, and `docker logs` must- * always show why we died (V1 did this in both apps).+ * always show why we died.*- * Installed in every role. V1's api only did so in production and its worker- * did so always; the merged process takes the worker's.+ * Installed in every role, always.*/function installFatalHandlers(): void {process.on('uncaughtException', (error) => {@@ -488,7 +450,7 @@ async function main() {const role = config.ROLE;const deps = buildDeps();- // HTTP and default metrics register everywhere (TARGET_ARCHITECTURE §18).+ // HTTP and default metrics register everywhere.registerDefaultMetrics();if (roleConsumes) {registerConsumerMetrics(deps);@@ -505,7 +467,7 @@ async function main() {definitions,deps,// BullMQ duplicates this for each worker's blocking fetch; the queue- // client itself stays packages/redis's singleton, as in V1.+ // client itself stays packages/redis's singleton.createConnection: () => getRedisQueue(),cluster: config.QUEUE_CLUSTER,namespace: config.QUEUE_NAMESPACE,@@ -608,7 +570,7 @@ async function main() {role,port: config.API_PORT,hostname: config.listen.hostname ?? '0.0.0.0',- // Rule 5: the running Bun version, asserted against.bun-version by+ // The running Bun version, asserted against .bun-version by// scripts/doctor.sh — logged so a wrong-runtime incident is one log// line away rather than an inference.bunVersion: Bun.version,@@ -617,8 +579,7 @@ async function main() {);});- // V1's api did this and its worker did not — the expiry notifications only- // matter where something subscribes (apps/api/src/index.ts).+ // The expiry notifications only matter where something subscribes.if (role !== 'worker') {try {await getRedisPub().config('SET', 'notify-keyspace-events', 'Ex');diff --git a/apps/api/src/shutdown.test.ts b/apps/api/src/shutdown.test.tsindex 9d0b3bf5d..8e64d6977 100644--- a/apps/api/src/shutdown.test.ts+++ b/apps/api/src/shutdown.test.ts@@ -1,11 +1,9 @@/**- * The regression test for drill 03's loss.- *- * Both halves matter and the happy path alone would not have caught the bug:- * (a) the event buffer is flushed to Redis BEFORE the Kafka consumer is- * stopped, and (b) a FAILED flush stops the sequence there — the consumer is- * never stopped and the process exits non-zero, so Kafka redelivers instead of- * dropping the events for good.+ * Regression test: both halves below matter, and the happy path alone would+ * not catch the bug — (a) the event buffer is flushed to Redis BEFORE the+ * Kafka consumer is stopped, and (b) a FAILED flush stops the sequence+ * there: the consumer is never stopped and the process exits non-zero, so+ * Kafka redelivers instead of dropping the events for good.*/import { describe, expect, it, mock } from 'bun:test';@@ -77,9 +75,9 @@ describe('runShutdownSequence', () => {});it('lets in-flight handlers finish before it flushes', async () => {- // The shape drill 03 measured: a message is still being handled when the- // signal arrives. `stopConsuming` must not resolve until that handler has,- // and the flush must not start until `stopConsuming` has resolved.+ // A message is still being handled when the shutdown signal arrives.+ // `stopConsuming` must not resolve until that handler has, and the+ // flush must not start until `stopConsuming` has resolved.const calls: string[] = [];let handlerFinished = false;diff --git a/apps/api/src/shutdown.ts b/apps/api/src/shutdown.tsindex 59a5e0c5d..08b039571 100644--- a/apps/api/src/shutdown.ts+++ b/apps/api/src/shutdown.ts@@ -2,9 +2,9 @@// thing a test can assert rather than a property of how a `Promise.all` was// typed.//-// Drill 03 (`verification/drills/03-restart-in-flight.md`) measured a SIGTERM-// restart permanently losing 2 of 44,075 accepted events while both SIGKILL-// arms lost none. Graceful shutdown lost them BECAUSE it was graceful: the+// A SIGTERM restart once permanently lost accepted events (2 of 44,075)+// while a SIGKILL restart lost none. Graceful shutdown lost them BECAUSE+// it was graceful: the// event buffer's in-process `pendingEvents` array was never flushed to Redis,// and the offsets for those events had already been committed, so nothing was// redelivered. A crash commits nothing, so Kafka replays the same window.@@ -25,8 +25,8 @@export const SHUTDOWN_EXIT_OK = 0;/*** Something failed. Exiting non-zero without committing is deliberately the- * crash shape, which drill 03 proved is the safe one: Kafka redelivers and a- * duplicate is recoverable where a loss is not.+ * crash shape — the safe one: Kafka redelivers and a duplicate is+ * recoverable where a loss is not.*/export const SHUTDOWN_EXIT_FAILED = 1;diff --git a/apps/public/src/app/og/[...og]/route.tsx b/apps/public/src/app/og/[...og]/route.tsxindex 8c52d90dc..450a466cd 100644--- a/apps/public/src/app/og/[...og]/route.tsx+++ b/apps/public/src/app/og/[...og]/route.tsx@@ -5,7 +5,6 @@ import { getFeatureData } from '@/lib/features';import { url as baseUrl } from '@/lib/layout.shared';import { articleSource, guideSource, pageSource, source } from '@/lib/source';-// Truncate text helperfunction truncateText(text: string, maxLength: number): string {if (text.length <= maxLength) {return text;@@ -195,19 +194,15 @@ export async function GET(try {const { og } = await params;- // Get OG data based on segmentsconst { title, description } = await getOgData(og);- // Truncate title and descriptionconst truncatedTitle = truncateText(title, 100);const truncatedDescription = description? truncateText(description, 200): undefined;- // Get background image URLconst backgroundImageUrl = baseUrl('/ogimage-empty.png');- // Fetch Geist font files from CDN (cache fonts for better performance)const [geistRegular, geistBold] = await Promise.all([fetch('https://cdn.jsdelivr.net/npm/[email protected]/dist/fonts/geist-sans/Geist-Regular.ttf'@@ -229,7 +224,6 @@ export async function GET(display: 'flex',}}>- {/* Title and Description at bottom left */}<divstyle={{bottom: '55px',@@ -240,7 +234,6 @@ export async function GET(marginTop: 'auto',}}>- {/* Title */}<divstyle={{fontSize: truncatedTitle.length > 40 ? '56px' : '72px',@@ -254,7 +247,6 @@ export async function GET({truncatedTitle}</div>- {/* Description */}{truncatedDescription ? (<divstyle={{diff --git a/apps/start/src/agents/client.ts b/apps/start/src/agents/client.tsindex 8d716a1a0..7435e4dac 100644--- a/apps/start/src/agents/client.ts+++ b/apps/start/src/agents/client.ts@@ -6,20 +6,13 @@ import type { ChatApp } from '@openpanel/core';* every context schema, and every typed tool input — so `useAgent(client, {* agent: 'gpt-4-1' })` is autocompleted and validated end-to-end.*- * About the import: `ChatApp = typeof chatApp` is the full Better- * Agent-inferred application type, which inherently binds to the server-side- * agent definition (models, tools, context). It can't be moved into- * `@openpanel/core`'s assistant.constants without dragging the entire agent- * definition (DB services, providers, etc.) along with it. It is type-only,- * erased at build time — no runtime coupling, which is what keeps it inside- * ADR-008's rule that only `*.constants.ts` may be VALUE-imported here. The- * barrel is the only door: `@openpanel/core`'s exports map publishes `.` and- * `./modules/*.constants`, and `ChatApp` cannot live in a constants file. The- * shared schemas (context, client tool inputs, model whitelist) do live in- * `@openpanel/core`'s assistant.constants, so this is the one type import that- * crosses the app boundary — a second one past `AppRouter`, which ADR-022 R12- * says should be the only one. Recorded as an open R12 finding: widening R12 to- * `AppRouter` + `ChatApp` is an ADR amendment, not a code change.+ * `ChatApp = typeof chatApp` is the full Better Agent-inferred application+ * type, bound to the server-side agent definition (models, tools, context).+ * It can't move into `@openpanel/core`'s assistant.constants without+ * dragging the entire agent definition (DB services, providers, etc.) along+ * with it. It is type-only, erased at build time, so it stays within R12's+ * rule that only `*.constants.ts` may be value-imported here — a second+ * type-only exception, alongside `AppRouter`.*/export type AppClient = ReturnType<typeof createClient<ChatApp>>;diff --git a/apps/start/src/components/charts/area.tsx b/apps/start/src/components/charts/area.tsxindex b06c0b8c6..27242bbbf 100644--- a/apps/start/src/components/charts/area.tsx+++ b/apps/start/src/components/charts/area.tsx@@ -83,9 +83,8 @@ export function Area({// Stable slice only: hover state lives inside `<SeriesHoverDim>` and// `<SeriesHighlightLayer>` so this component (and its expensive// <SeriesDashTailOverlay> child) does not re-render on cursor motion.- // The reveal-clip is now a single shared clipPath at the chart-shell- // level (`time-series-chart-shell.tsx`); we no longer render a per-area- // `<ChartRevealClip>` or read `revealEpoch` here.+ // The reveal-clip is a single shared clipPath at the chart-shell level+ // (`time-series-chart-shell.tsx`).const {data,renderData,@@ -100,7 +99,6 @@ export function Area({const pathMetricsKey = `${renderData.length}:${innerWidth}:${dashFromIndex}:${showLine}`;const { pathLength, pathD } = usePathStrokeMetrics(pathRef, pathMetricsKey);- // Unique IDs for this areaconst uniqueId = useId();const gradientId = `area-gradient-${dataKey}-${uniqueId}`;const strokeGradientId = `area-stroke-gradient-${dataKey}-${uniqueId}`;@@ -150,7 +148,6 @@ export function Area({/><SeriesHoverDim dimOpacity={0.6} enabled={showHighlight}>- {/* Area fill */}{showAreaFill ? (<gmask={@@ -170,7 +167,6 @@ export function Area({</g>) : null}- {/* Stroke line on top of area */}{showLine ? (<><LinePathdiff --git a/apps/start/src/components/charts/bar-chart.tsx b/apps/start/src/components/charts/bar-chart.tsxindex 547bfb93b..8a2551597 100644--- a/apps/start/src/components/charts/bar-chart.tsx+++ b/apps/start/src/components/charts/bar-chart.tsx@@ -66,7 +66,6 @@ export interface BarChartProps {const DEFAULT_MARGIN: Margin = { top: 40, right: 40, bottom: 40, left: 40 };-// Extract bar configs from children synchronouslyfunction extractBarConfigs(children: ReactNode): LineConfig[] {const configs: LineConfig[] = [];@@ -105,7 +104,6 @@ function extractBarConfigs(children: ReactNode): LineConfig[] {return configs;}-// Check if a component should render after the mouse overlayfunction isPostOverlayComponent(child: ReactElement): boolean {const childType = child.type as {displayName?: string;@@ -178,13 +176,11 @@ const ChartCore = memo(function ChartCore({const isHorizontal = orientation === 'horizontal';- // Extract bar configs synchronously from childrenconst lines = useMemo(() => extractBarConfigs(children), [children]);const innerWidth = width - margin.left - margin.right;const innerHeight = height - margin.top - margin.bottom;- // Category accessor function - returns string for categorical scaleconst categoryAccessor = useCallback((d: Record<string, unknown>): string => {const value = d[xDataKey];@@ -208,7 +204,6 @@ const ChartCore = memo(function ChartCore({[xDataKey]);- // Category scale (band) - for the categorical axisconst categoryScale = useMemo(() => {const domain = data.map((d) => categoryAccessor(d));const range: [number, number] = isHorizontal@@ -221,13 +216,10 @@ const ChartCore = memo(function ChartCore({});}, [innerWidth, innerHeight, data, categoryAccessor, barGap, isHorizontal]);- // Band width for bars - use prop if provided, otherwise use scale's bandwidthconst bandWidth = barWidthProp ?? categoryScale.bandwidth();- // Compute max value considering stackingconst maxValue = useMemo(() => {if (stacked) {- // For stacked bars, sum all values at each data pointlet max = 0;for (const d of data) {let sum = 0;@@ -243,7 +235,6 @@ const ChartCore = memo(function ChartCore({}return max || 100;}- // For grouped bars, find max single valuelet max = 0;for (const line of lines) {for (const d of data) {@@ -256,7 +247,6 @@ const ChartCore = memo(function ChartCore({return max || 100;}, [data, lines, stacked]);- // Value scale (linear) - for the value axisconst valueScale = useMemo(() => {const range = isHorizontal ? [0, innerWidth] : [innerHeight, 0];return scaleLinear({@@ -266,7 +256,6 @@ const ChartCore = memo(function ChartCore({});}, [innerWidth, innerHeight, maxValue, isHorizontal]);- // Compute stack offsets for stacked barsconst stackOffsets = useMemo(() => {if (!stacked) {return undefined;@@ -330,7 +319,6 @@ const ChartCore = memo(function ChartCore({return () => clearTimeout(timer);}, [animationDuration, revealSignature]);- // Mouse move handlerconst handleMouseMove = useCallback((event: React.MouseEvent<SVGGElement>) => {const point = localPoint(event);@@ -340,7 +328,6 @@ const ChartCore = memo(function ChartCore({const pos = isHorizontal ? point.y - margin.top : point.x - margin.left;- // Find which band the mouse is overconst bandIndex = Math.floor(pos / columnWidth);const clampedIndex = Math.max(0, Math.min(data.length - 1, bandIndex));const d = data[clampedIndex];@@ -349,7 +336,6 @@ const ChartCore = memo(function ChartCore({return;}- // Calculate positions for each barconst yPositions: Record<string, number> = {};const xPositions: Record<string, number> = {};const barPos = categoryScale(categoryAccessor(d)) ?? 0;@@ -388,7 +374,6 @@ const ChartCore = memo(function ChartCore({});}} else if (stacked) {- // Vertical stacked barslet cumulative = 0;let seriesIdx = 0;for (const line of lines) {@@ -402,7 +387,6 @@ const ChartCore = memo(function ChartCore({}}} else {- // Vertical grouped barsconst seriesCount = lines.length;const groupGap = seriesCount > 1 ? 4 : 0;const individualBarWidth =@@ -425,7 +409,6 @@ const ChartCore = memo(function ChartCore({// Tooltip position: for horizontal, position at max bar end; for vertical, center of bandlet tooltipX: number;if (isHorizontal) {- // Position tooltip at the end of the longest barconst maxX = Math.max(...Object.values(xPositions), 0);tooltipX = maxX;} else {@@ -463,7 +446,6 @@ const ChartCore = memo(function ChartCore({const canInteract = isLoaded;- // Separate children into defs, pre-overlay, and post-overlayconst defsChildren: ReactElement[] = [];const preOverlayChildren: ReactElement[] = [];const postOverlayChildren: ReactElement[] = [];@@ -521,7 +503,6 @@ const ChartCore = memo(function ChartCore({return (<ChartProvider value={contextValue}><svg aria-hidden="true" height={height} width={width}>- {/* Gradient and pattern definitions */}{defsChildren.length > 0 && <defs>{defsChildren}</defs>}<rect fill="transparent" height={height} width={width} x={0} y={0} />@@ -542,7 +523,6 @@ const ChartCore = memo(function ChartCore({y={0}/>- {/* SVG children rendered before markers */}{preOverlayChildren}{/* Markers rendered last so they're on top for interaction */}diff --git a/apps/start/src/components/charts/bar.tsx b/apps/start/src/components/charts/bar.tsxindex 2cc61ac6c..fc2b4848e 100644--- a/apps/start/src/components/charts/bar.tsx+++ b/apps/start/src/components/charts/bar.tsx@@ -157,17 +157,15 @@ const BarInner = memo(function BarInner({revealEpoch = 0,} = useChart();- // Calculate stagger delay automatically if not provided// Total animation duration is ~1200ms, with 40% for stagger spread and 60% for bar animationconst totalAnimDuration = animationDuration || 1100;- const staggerSpread = totalAnimDuration * 0.4; // 40% of time for stagger spread+ const staggerSpread = totalAnimDuration * 0.4;const calculatedStaggerDelay =staggerDelay ?? (data.length > 1 ? staggerSpread / 1000 / data.length : 0);const uniqueId = useId();const isHorizontal = orientation === 'horizontal';- // Find the index of this bar series among all bar seriesconst seriesIndex = useMemo(() => {const idx = lines.findIndex((l) => l.dataKey === dataKey);return idx >= 0 ? idx : 0;@@ -176,21 +174,17 @@ const BarInner = memo(function BarInner({const seriesCount = lines.length;const isLastSeries = seriesIndex === seriesCount - 1;- // Calculate the width for each bar within a group (for non-stacked)const barWidth = useMemo(() => {if (!bandWidth || seriesCount === 0) {return 0;}if (stacked) {- // Stacked bars use full band widthreturn bandWidth;}- // Leave a gap between grouped bars (controlled by groupGap prop)const effectiveGroupGap = seriesCount > 1 ? groupGap : 0;return (bandWidth - effectiveGroupGap * (seriesCount - 1)) / seriesCount;}, [bandWidth, seriesCount, stacked, groupGap]);- // Calculate corner radius based on lineCapconst cornerRadius = useMemo(() => {if (typeof lineCap === 'number') {return lineCap;@@ -227,7 +221,6 @@ const BarInner = memo(function BarInner({const offset = stackOffsets.get(i)?.get(dataKey) ?? 0;x = yScale(offset) ?? 0;barW = valuePos - x;- // Apply stack gap for horizontal: shift right and reduce widthconst gapOffset = seriesIndex * stackGap;x += gapOffset;if (!isLastSeries && stackGap > 0) {@@ -235,7 +228,6 @@ const BarInner = memo(function BarInner({}} else {x = 0;- // For grouped bars, offset y positionconst effectiveGroupGap = seriesCount > 1 ? groupGap : 0;y = bandPos + seriesIndex * (barWidth + effectiveGroupGap);}@@ -252,7 +244,6 @@ const BarInner = memo(function BarInner({if (stacked && stackOffsets) {const offset = stackOffsets.get(i)?.get(dataKey) ?? 0;const offsetY = yScale(offset) ?? innerHeight;- // Apply stack gap: shift up and reduce heightconst gapOffset = seriesIndex * stackGap;y = offsetY - barHeight - gapOffset;// Reduce height slightly for non-last bars to create visual gap@@ -261,7 +252,6 @@ const BarInner = memo(function BarInner({}} else {y = valuePos;- // For grouped bars, offset x positionconst effectiveGroupGap = seriesCount > 1 ? groupGap : 0;x = bandPos + seriesIndex * (barWidth + effectiveGroupGap);}diff --git a/apps/start/src/components/charts/grid.tsx b/apps/start/src/components/charts/grid.tsxindex 42e322f47..b63cf7945 100644--- a/apps/start/src/components/charts/grid.tsx+++ b/apps/start/src/components/charts/grid.tsx@@ -60,13 +60,9 @@ export function Grid({const { xScale, yScale, innerWidth, innerHeight, orientation, barScale } =useChartStable();- // For bar charts, determine which scale to use for grid lines- // Horizontal bar charts: vertical grid should use yScale (value scale)- // Vertical bar charts: horizontal grid uses yScale (value scale)+ // Bar charts swap axes: for a horizontal bar chart the vertical grid needs+ // the value scale (yScale), not the category scale.const isHorizontalBarChart = orientation === 'horizontal' && barScale;-- // For vertical grid lines in horizontal bar charts, use yScale (the value scale)- // For time-based charts, use xScaleconst columnScale = isHorizontalBarChart ? yScale : xScale;const uniqueId = useId();@@ -80,7 +76,6 @@ export function Grid({return (<g className="chart-grid">- {/* Gradient mask for horizontal grid lines - fades at left/right */}{horizontal && fadeHorizontal && (<defs><linearGradient id={hGradientId} x1="0%" x2="100%" y1="0%" y2="0%">@@ -104,7 +99,6 @@ export function Grid({</defs>)}- {/* Gradient mask for vertical grid lines - fades at top/bottom */}{vertical && fadeVertical && (<defs><linearGradient id={vGradientId} x1="0%" x2="0%" y1="0%" y2="100%">diff --git a/apps/start/src/components/charts/highlight-segment-bounds.ts b/apps/start/src/components/charts/highlight-segment-bounds.tsindex 4fc0a9136..bd15301f6 100644--- a/apps/start/src/components/charts/highlight-segment-bounds.ts+++ b/apps/start/src/components/charts/highlight-segment-bounds.ts@@ -2,7 +2,7 @@ import type { TooltipData } from './chart-context';import type { ChartSelection } from './use-chart-interaction';// Pure geometry for the hover-highlight band, split out from the hook so it can-// be unit-tested without React/motion (see __tests__).+// be unit-tested without React/motion.//// The band is the pixel x-range one data point either side of the hovered point:// [ xScale(t(idx-1)), xScale(t(idx+1)) ]diff --git a/apps/start/src/components/charts/line.tsx b/apps/start/src/components/charts/line.tsxindex cab61c237..3e63f01eb 100644--- a/apps/start/src/components/charts/line.tsx+++ b/apps/start/src/components/charts/line.tsx@@ -73,9 +73,8 @@ export function Line({// Stable slice only: hover state lives inside `<SeriesHoverDim>` and// `<SeriesHighlightLayer>` so this component (and its expensive// <SeriesDashTailOverlay> child) does not re-render on cursor motion.- // The reveal-clip is now a single shared clipPath at the chart-shell- // level (`time-series-chart-shell.tsx`); we no longer render a per-line- // `<ChartRevealClip>` or read `revealEpoch` here.+ // The reveal-clip is a single shared clipPath at the chart-shell level+ // (`time-series-chart-shell.tsx`).const {data,renderData,diff --git a/apps/start/src/components/charts/markers/marker-group.tsx b/apps/start/src/components/charts/markers/marker-group.tsxindex 17b3c2ae4..76b6ad7a9 100644--- a/apps/start/src/components/charts/markers/marker-group.tsx+++ b/apps/start/src/components/charts/markers/marker-group.tsx@@ -191,7 +191,6 @@ export function MarkerGroup({return (<>- {/* Position group - no interaction */}<g transform={`translate(${x}, ${y})`}>{/* Vertical guide line - non-interactive, rendered first (behind marker) */}{showLine && lineHeight > 0 && (@@ -221,7 +220,6 @@ export function MarkerGroup({/>)}- {/* Interactive marker group */}{/* biome-ignore lint/a11y/noStaticElementInteractions: Chart marker interaction */}<gonMouseEnter={handleMouseEnter}@@ -249,7 +247,6 @@ export function MarkerGroup({y={-size}/>- {/* Main marker */}<MarkerCircleborderColor={borderColor}borderWidth={borderWidth}@@ -259,7 +256,6 @@ export function MarkerGroup({size={size}/>- {/* Count badge */}<AnimatePresence>{hasMultiple && !shouldFan && (<motion.g@@ -292,7 +288,6 @@ export function MarkerGroup({</g></g>- {/* Portal for fanned circles */}{containerRef?.current &&createPortal(// biome-ignore lint/a11y/noStaticElementInteractions: Marker hover portaldiff --git a/apps/start/src/components/charts/op-date-pill.tsx b/apps/start/src/components/charts/op-date-pill.tsxindex 205e6e234..50afefc5b 100644--- a/apps/start/src/components/charts/op-date-pill.tsx+++ b/apps/start/src/components/charts/op-date-pill.tsx@@ -154,7 +154,6 @@ function formatPillDate(if (spanHours <= 25) {return `${pad(date.getHours())}:00`;}- // Otherwise include the datereturn `${dayMonth} ${pad(date.getHours())}:00`;case 'day':diff --git a/apps/start/src/components/charts/time-series-chart-shell.tsx b/apps/start/src/components/charts/time-series-chart-shell.tsxindex 8bffe6d6c..6b757afbb 100644--- a/apps/start/src/components/charts/time-series-chart-shell.tsx+++ b/apps/start/src/components/charts/time-series-chart-shell.tsx@@ -347,11 +347,10 @@ const TimeSeriesChartCore = memo(function TimeSeriesChartCore({]);- // Single shared reveal clip for every series. Replaces the per-<Line> /- // per-<Area> `<ChartRevealClip>` motion.rects: one motion-driven attribute- // animation instead of N, with all series referencing the same `<clipPath>`.- // The wipe semantics (left-to-right unveil of static path geometry) are- // identical to the previous per-series clips.+ // Single shared reveal clip for every series: one motion-driven attribute+ // animation instead of one per line/area, with all series referencing the+ // same `<clipPath>`. The wipe is a left-to-right unveil of static path+ // geometry.// animationDuration === 0 truly disables the reveal (no clipPath wrapper),// so consumers can opt out without having to also pass enterTransition.const showReveal =diff --git a/apps/start/src/components/charts/tooltip/chart-tooltip.tsx b/apps/start/src/components/charts/tooltip/chart-tooltip.tsxindex 34752ad16..317f123cf 100644--- a/apps/start/src/components/charts/tooltip/chart-tooltip.tsx+++ b/apps/start/src/components/charts/tooltip/chart-tooltip.tsx@@ -134,7 +134,6 @@ const ChartTooltipInner = memo(function ChartTooltipInner({};}, [dotColorProp, rowsRenderer, tooltipData, tooltipRows]);- // Resolve indicator color (static or from hovered point)const indicatorColor = useMemo(() => {if (indicatorColorProp == null) {return chartCssVars.crosshair;@@ -147,16 +146,13 @@ const ChartTooltipInner = memo(function ChartTooltipInner({return indicatorColorProp;}, [indicatorColorProp, tooltipData]);- // Title from date or categoryconst title = useMemo(() => {if (!tooltipData) {return undefined;}- // For bar charts (horizontal or vertical), use the category nameif (barXAccessor) {return barXAccessor(tooltipData.point);}- // For line/area charts, use the datereturn weekdayDateFmt.format(xAccessor(tooltipData.point));}, [tooltipData, barXAccessor, xAccessor]);diff --git a/apps/start/src/components/chat/chat-context.tsx b/apps/start/src/components/chat/chat-context.tsxindex 14eeb7602..8e74370e9 100644--- a/apps/start/src/components/chat/chat-context.tsx+++ b/apps/start/src/components/chat/chat-context.tsx@@ -209,7 +209,6 @@ export function ChatStateProvider({ children }: { children: ReactNode }) {setAgentNameState(defaultModelId);}, [agentName, defaultModelId, models]);- // Transient session state.const [streamingTitle, setStreamingTitle] = useState<string | null>(null);const [pendingMessage, setPendingMessage] = useState<string | null>(null);diff --git a/apps/start/src/components/chat/chat-drawer-header.tsx b/apps/start/src/components/chat/chat-drawer-header.tsxindex 3722a24dc..d6b105c5a 100644--- a/apps/start/src/components/chat/chat-drawer-header.tsx+++ b/apps/start/src/components/chat/chat-drawer-header.tsx@@ -146,7 +146,6 @@ function InlineDeleteButton({ onConfirm }: { onConfirm: () => void }) {}};- // Cleanup on unmount.useEffect(() => clearTimer, []);const handleClick = (e: React.MouseEvent) => {diff --git a/apps/start/src/components/chat/chat-message.tsx b/apps/start/src/components/chat/chat-message.tsxindex 15e8e5846..8eef28ecc 100644--- a/apps/start/src/components/chat/chat-message.tsx+++ b/apps/start/src/components/chat/chat-message.tsx@@ -32,7 +32,6 @@ export function ChatMessage({}) {const isUser = message.role === 'user';- // Index tool results by callId so we can attach them to their call.const resultByCallId = new Map<string,{ result?: unknown; status: string }diff --git a/apps/start/src/components/chat/tool-results/output-types.ts b/apps/start/src/components/chat/tool-results/output-types.tsindex 37dd8d49d..4557c42cb 100644--- a/apps/start/src/components/chat/tool-results/output-types.ts+++ b/apps/start/src/components/chat/tool-results/output-types.ts@@ -1,8 +1,8 @@/*** Frontend-side TypeScript types for the chat tool outputs we render- * with custom UIs. These mirror what the matching backend tool returns- * — see `apps/api/src/chat/tools/*.ts`. The renderers narrow `unknown`- * via the type guards below before reading any field.+ * with custom UIs. These mirror what the matching backend tool returns.+ * The renderers narrow `unknown` via the type guards below before+ * reading any field.** If the backend changes a tool's return shape, the matching renderer* will fall back to a "no data" card rather than crashing — that's whydiff --git a/apps/start/src/components/facehash/avatar-fallback.tsx b/apps/start/src/components/facehash/avatar-fallback.tsxindex 61b982991..9eaac5be9 100644--- a/apps/start/src/components/facehash/avatar-fallback.tsx+++ b/apps/start/src/components/facehash/avatar-fallback.tsx@@ -44,9 +44,6 @@ export type AvatarFallbackProps = Omit<facehashProps?: Omit<FacehashProps, 'name'>;};-/**- * Extracts initials from a name string.- */function getInitials(name: string): string {const parts = name.trim().split(WHITESPACE_REGEX);if (parts.length === 0) {diff --git a/apps/start/src/components/facehash/facehash.tsx b/apps/start/src/components/facehash/facehash.tsxindex 139e76257..94ed7b5bf 100644--- a/apps/start/src/components/facehash/facehash.tsx+++ b/apps/start/src/components/facehash/facehash.tsx@@ -240,28 +240,22 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(const [isHovered, setIsHovered] = React.useState(false);const resolvedScheme = useColorScheme(colorScheme);- // For group-hover, we use CSS instead of JS stateconst usesCssHover = groupHover;- // Determine which colors to use based on schemeconst effectiveColors = React.useMemo(() => {- // If explicit colors prop is provided, use itif (colors) {return colors;}- // If colorClasses is provided, don't use inline colorsif (colorClasses) {return undefined;}- // Use scheme-specific colors or defaultsconst lightColors = colorsLight ?? DEFAULT_COLORS_LIGHT;const darkColors = colorsDark ?? DEFAULT_COLORS_DARK;return resolvedScheme === 'dark' ? darkColors : lightColors;}, [colors, colorClasses, colorsLight, colorsDark, resolvedScheme]);- // Generate deterministic values from nameconst { FaceComponent, colorIndex, rotation } = React.useMemo(() => {const hash = stringHash(name);const faceIndex = hash % FACES.length;@@ -277,10 +271,8 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(};}, [name, effectiveColors?.length, colorClasses?.length]);- // Get intensity presetconst preset = INTENSITY_PRESETS[intensity3d];- // Calculate 3D transformsconst { baseTransform, hoverTransform } = React.useMemo(() => {if (intensity3d === 'none') {return { baseTransform: undefined, hoverTransform: undefined };@@ -295,7 +287,6 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(};}, [intensity3d, rotation, preset]);- // For JS-based hover, apply transform based on hover stateconst transform = React.useMemo(() => {if (usesCssHover || !interactive) {return baseTransform;@@ -303,17 +294,14 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(return isHovered ? hoverTransform : baseTransform;}, [usesCssHover, interactive, isHovered, baseTransform, hoverTransform]);- // Size styleconst sizeValue = typeof size === 'number' ? `${size}px` : size;- // Initial letterconst initial = name.charAt(0).toUpperCase();- // Background: either hex color (inline) or classconst bgColorClass = colorClasses?.[colorIndex];const bgColorHex = effectiveColors?.[colorIndex];- // Event handlers (only used for JS-based hover, not group-hover)+ // Event handlers only apply to JS-based hover; group-hover uses CSS.const handleMouseEnter = React.useCallback((e: React.MouseEvent<HTMLDivElement>) => {if (interactive && !usesCssHover) {@@ -357,7 +345,6 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(}}{...props}>- {/* Gradient overlay */}{variant === 'gradient' && (<divaria-hidden="true"@@ -371,7 +358,6 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(/>)}- {/* Face container with 3D transform */}<divclassName={usesCssHover && interactive@@ -393,7 +379,6 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(} as React.CSSProperties}>- {/* Face SVG */}<FaceComponentstyle={{position: 'absolute',@@ -402,7 +387,6 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(}}/>- {/* Initial letter */}{showInitial && (<spandata-facehash-avatar-initial=""diff --git a/apps/start/src/components/facehash/faces.tsx b/apps/start/src/components/facehash/faces.tsxindex cb519c53b..f5a305374 100644--- a/apps/start/src/components/facehash/faces.tsx+++ b/apps/start/src/components/facehash/faces.tsx@@ -5,9 +5,6 @@ export type FaceProps = {style?: React.CSSProperties;};-/**- * Round eyes face - simple circular eyes- */export const RoundFace: React.FC<FaceProps> = ({ className, style }) => (<svgaria-hidden="true"@@ -21,9 +18,6 @@ export const RoundFace: React.FC<FaceProps> = ({ className, style }) => (</svg>);-/**- * Cross eyes face - X-shaped eyes- */export const CrossFace: React.FC<FaceProps> = ({ className, style }) => (<svgaria-hidden="true"@@ -47,9 +41,6 @@ export const CrossFace: React.FC<FaceProps> = ({ className, style }) => (</svg>);-/**- * Line eyes face - horizontal line eyes- */export const LineFace: React.FC<FaceProps> = ({ className, style }) => (<svgaria-hidden="true"@@ -79,9 +70,6 @@ export const LineFace: React.FC<FaceProps> = ({ className, style }) => (</svg>);-/**- * Curved eyes face - sleepy/happy curved eyes- */export const CurvedFace: React.FC<FaceProps> = ({ className, style }) => (<svgaria-hidden="true"@@ -107,9 +95,6 @@ export const CurvedFace: React.FC<FaceProps> = ({ className, style }) => (</svg>);-/**- * All available face components- */export const FACES = [RoundFace, CrossFace, LineFace, CurvedFace] as const;export type FaceComponent = (typeof FACES)[number];diff --git a/apps/start/src/components/organization/billing.tsx b/apps/start/src/components/organization/billing.tsxindex 1eed08932..2f45d7dd3 100644--- a/apps/start/src/components/organization/billing.tsx+++ b/apps/start/src/components/organization/billing.tsx@@ -177,7 +177,6 @@ export default function Billing({ organization }: Props) {}}, [success]);- // Clear query state when modal is closeduseOnPushModal('BillingSuccess', (open) => {if (!open) {setSuccess(null);diff --git a/apps/start/src/components/overview/overview-list-modal.tsx b/apps/start/src/components/overview/overview-list-modal.tsxindex f3dead5b4..a29b36ffa 100644--- a/apps/start/src/components/overview/overview-list-modal.tsx+++ b/apps/start/src/components/overview/overview-list-modal.tsx@@ -9,7 +9,6 @@ import { ModalContent } from '@/modals/Modal/Container';const ROW_HEIGHT = 36;-// Revenue pie chart componentfunction RevenuePieChart({ percentage }: { percentage: number }) {const size = 16;const strokeWidth = 2;@@ -45,7 +44,6 @@ function RevenuePieChart({ percentage }: { percentage: number }) {);}-// Base data type that all items must conform toexport interface OverviewListItem {sessions: number;pageviews: number;@@ -53,27 +51,19 @@ export interface OverviewListItem {}interface OverviewListModalProps<T extends OverviewListItem> {- /** Modal title */title: string;- /** Search placeholder text */searchPlaceholder?: string;- /** The data to display */data: T[];- /** Extract a unique key for each item */keyExtractor: (item: T) => string;- /** Filter function for search - receives item and lowercase search query */+ /** Receives the item and the already-lowercased search query. */searchFilter: (item: T, query: string) => boolean;- /** Render the main content cell (first column) */+ /** Renders the first column's content. */renderItem: (item: T) => React.ReactNode;- /** Optional footer content */footer?: React.ReactNode;- /** Optional header content (appears below title/search) */+ /** Appears below the title/search area. */headerContent?: React.ReactNode;- /** Column name for the first column */columnName?: string;- /** Whether to show pageviews column */showPageviews?: boolean;- /** Whether to show sessions column */showSessions?: boolean;}@@ -94,7 +84,6 @@ export function OverviewListModal<T extends OverviewListItem>({const scrollAreaRef = useRef<HTMLDivElement>(null);const number = useNumber();- // Filter data based on search queryconst filteredData = useMemo(() => {if (!searchQuery.trim()) {return data;@@ -103,7 +92,6 @@ export function OverviewListModal<T extends OverviewListItem>({return data.filter((item) => searchFilter(item, queryLower));}, [data, searchQuery, searchFilter]);- // Calculate totals and check for revenueconst { maxSessions, totalRevenue, hasRevenue, hasPageviews } =useMemo(() => {const maxSessions = Math.max(@@ -119,7 +107,6 @@ export function OverviewListModal<T extends OverviewListItem>({return { maxSessions, totalRevenue, hasRevenue, hasPageviews };}, [filteredData, showPageviews]);- // Virtual list setupconst virtualizer = useVirtualizer({count: filteredData.length,getScrollElement: () => scrollAreaRef.current,@@ -131,7 +118,6 @@ export function OverviewListModal<T extends OverviewListItem>({return (<ModalContent className="!max-h-[90vh] flex flex-col gap-0 p-0 sm:max-w-2xl">- {/* Sticky Header */}<div className="flex-shrink-0 border-border border-b"><div className="p-6 pb-4"><DialogTitle className="mb-4 font-semibold text-lg">@@ -150,7 +136,6 @@ export function OverviewListModal<T extends OverviewListItem>({{headerContent}</div>- {/* Column Headers */}<divclassName="grid bg-def-100 px-4 py-2 font-medium text-muted-foreground text-sm"style={{@@ -165,7 +150,6 @@ export function OverviewListModal<T extends OverviewListItem>({</div></div>- {/* Virtualized Scrollable Body */}<divclassName="min-h-0 flex-1 overflow-y-auto"ref={scrollAreaRef}@@ -197,7 +181,6 @@ export function OverviewListModal<T extends OverviewListItem>({transform: `translateY(${virtualRow.start}px)`,}}>- {/* Background bar */}<div className="absolute inset-0 overflow-hidden"><divclassName="h-full bg-def-200 transition-colors group-hover/row:bg-blue-200 dark:group-hover/row:bg-blue-900"@@ -205,7 +188,6 @@ export function OverviewListModal<T extends OverviewListItem>({/></div>- {/* Row content */}<divclassName="relative grid h-full items-center border-border border-b px-4"style={{@@ -213,12 +195,10 @@ export function OverviewListModal<T extends OverviewListItem>({`1fr ${hasRevenue ? '100px' : ''} ${hasPageviews ? '80px' : ''} ${showSessions ? '80px' : ''}`.trim(),}}>- {/* Main content cell */}<div className="min-w-0 truncate pr-2">{renderItem(item)}</div>- {/* Revenue cell */}{hasRevenue && (<div className="flex items-center justify-end gap-2"><span@@ -235,14 +215,12 @@ export function OverviewListModal<T extends OverviewListItem>({</div>)}- {/* Pageviews cell */}{hasPageviews && (<div className="text-right font-mono font-semibold text-sm">{number.short(item.pageviews)}</div>)}- {/* Sessions cell */}{showSessions && (<div className="text-right font-mono font-semibold text-sm">{number.short(item.sessions)}@@ -254,7 +232,6 @@ export function OverviewListModal<T extends OverviewListItem>({})}</div>- {/* Empty state */}{filteredData.length === 0 && (<div className="flex h-32 items-center justify-center text-muted-foreground">{searchQuery ? 'No results found' : 'No data available'}@@ -262,7 +239,6 @@ export function OverviewListModal<T extends OverviewListItem>({)}</div>- {/* Fixed Footer */}{footer && (<div className="flex-shrink-0 border-border border-t p-4">{footer}</div>)}diff --git a/apps/start/src/components/overview/overview-metrics.tsx b/apps/start/src/components/overview/overview-metrics.tsxindex a8dfdabf3..a29505ba9 100644--- a/apps/start/src/components/overview/overview-metrics.tsx+++ b/apps/start/src/components/overview/overview-metrics.tsx@@ -309,7 +309,7 @@ function Chart({};}- // Pin revenue peak at ~60% of the primary metric's peak so bars stay+ // Pin revenue peak at 40% of the primary metric's peak so bars stay// legible without overshadowing the line/area.const scale = (maxPrimary * 0.4) / maxRevenue;return {diff --git a/apps/start/src/components/realtime/map/coordinates.ts b/apps/start/src/components/realtime/map/coordinates.tsindex 51baf147e..7f66c12c5 100644--- a/apps/start/src/components/realtime/map/coordinates.ts+++ b/apps/start/src/components/realtime/map/coordinates.ts@@ -329,19 +329,14 @@ export function clusterCoordinates(const { zoom = 1, adaptiveRadius = true, viewport } = options;const detailLevel = getClusterDetailLevel(zoom);- // Calculate adaptive radius based on zoom level and coordinate densitylet adjustedRadius = radius;if (adaptiveRadius) {- // Much more aggressive clustering at lower zoom levels- // At zoom 1: use 3x larger radius for very aggressive clustering- // At zoom 2: use 2x radius- // At zoom 4: use 1x radius- // At zoom 8: use 0.2x radius for precision+ // More aggressive clustering at lower zoom levels: the radius shrinks+ // roughly with 4 / (zoom + 1), e.g. ~3x at zoom 1 down to ~0.2x by zoom 8.const zoomFactor = Math.max(0.1, 4 / (zoom + 1));adjustedRadius = radius * zoomFactor;- // Further adjust based on coordinate density if viewport is providedif (viewport && coordinates.length > 0) {const viewportCoords = coordinates.filter((coord) =>@@ -367,7 +362,6 @@ export function clusterCoordinates(}}} else {- // Simple zoom-based adjustment when adaptive is disabledadjustedRadius = radius * Math.max(0.5, 1 / Math.sqrt(zoom));}@@ -415,7 +409,6 @@ function basicClusterCoordinates(coordinates: Coordinate[], radius: number) {},};- // Mark the initial coordinate as visitedvisited.add(originalIdx);// Iteratively expand the cluster to include nearby points@@ -423,7 +416,6 @@ function basicClusterCoordinates(coordinates: Coordinate[], radius: number) {while (expandedInLastIteration) {expandedInLastIteration = false;- // For each existing cluster member, find nearby unvisited coordinatesfor (const member of [...cluster.members]) {coordinatesWithDensity.forEach(({@@ -459,7 +451,6 @@ function basicClusterCoordinates(coordinates: Coordinate[], radius: number) {}}- // Calculate the proper center for the clustercluster.center = calculateClusterCenter(cluster.members);cluster.location = getLocationSummary(cluster.members);@@ -474,7 +465,6 @@ function basicClusterCoordinates(coordinates: Coordinate[], radius: number) {// Note: Optimized clustering algorithm was removed temporarily// TODO: Re-implement optimized clustering after basic algorithm is working well-// Utility function to get clustering statistics for debuggingexport function getClusteringStats(coordinates: Coordinate[],clusters: ReturnType<typeof clusterCoordinates>@@ -505,7 +495,6 @@ function calculateClusterCenter(members: Coordinate[]): Coordinate {return { ...members[0]! };}- // Check if we need to handle longitude wrapping around the datelineconst longitudes = members.map((m) => m.long);const minLong = Math.min(...longitudes);const maxLong = Math.max(...longitudes);@@ -515,7 +504,6 @@ function calculateClusterCenter(members: Coordinate[]): Coordinate {let totalWeight = 0;if (maxLong - minLong > 180) {- // Handle dateline crossinglet adjustedLongSum = 0;for (const member of members) {const weight = member.count ?? 1;@@ -530,7 +518,6 @@ function calculateClusterCenter(members: Coordinate[]): Coordinate {avgLong -= 360;}} else {- // Normal case - no dateline crossingfor (const member of members) {const weight = member.count ?? 1;avgLat += member.lat * weight;diff --git a/apps/start/src/components/realtime/realtime-live-histogram.tsx b/apps/start/src/components/realtime/realtime-live-histogram.tsxindex 20c44600a..c634e6c11 100644--- a/apps/start/src/components/realtime/realtime-live-histogram.tsx+++ b/apps/start/src/components/realtime/realtime-live-histogram.tsx@@ -33,8 +33,7 @@ export function RealtimeLiveHistogram({);const chartData = liveData?.minuteCounts ?? [];- // Calculate total unique visitors (sum of unique visitors per minute)- // Note: This is an approximation - ideally we'd want unique visitors across all minutes+ // Approximation: totalSessions, not unique visitors across the window.const totalVisitors = liveData?.totalSessions ?? 0;if (isLoading) {diff --git a/apps/start/src/components/report-chart/common/chart-click-menu.tsx b/apps/start/src/components/report-chart/common/chart-click-menu.tsxindex f343bb67f..abe7210ea 100644--- a/apps/start/src/components/report-chart/common/chart-click-menu.tsx+++ b/apps/start/src/components/report-chart/common/chart-click-menu.tsx@@ -21,14 +21,8 @@ export interface ChartClickMenuItem {interface ChartClickMenuProps {children: React.ReactNode;- /**- * Function that receives the click event and clicked data, returns menu items- * This allows conditional menu items based on what was clicked- */+ /** Returns menu items for the clicked data, so items can be conditional on it. */getMenuItems: (e: any, clickedData: any) => ChartClickMenuItem[];- /**- * Optional callback when menu closes- */onClose?: () => void;}@@ -37,10 +31,6 @@ export interface ChartClickMenuHandle {getContainerElement: () => HTMLDivElement | null;}-/**- * Reusable component for handling chart clicks and showing a dropdown menu- * Wraps the chart and handles click position tracking and dropdown positioning- */export const ChartClickMenu = forwardRef<ChartClickMenuHandle,ChartClickMenuProps@@ -58,11 +48,9 @@ export const ChartClickMenu = forwardRef<if (e?.activePayload?.[0] && containerRef.current) {const payload = e.activePayload[0].payload;- // Calculate click position relative to chart containerconst containerRect = containerRef.current.getBoundingClientRect();- // Try to get viewport coordinates from the event- // Recharts passes nativeEvent with clientX/clientY (viewport coordinates)+ // Recharts passes nativeEvent with clientX/clientY (viewport coordinates).let clientX = 0;let clientY = 0;@@ -86,14 +74,13 @@ export const ChartClickMenu = forwardRef<clientX = svgRect.left + (e.activeCoordinate.x ?? 0);clientY = svgRect.top + (e.activeCoordinate.y ?? 0);} else {- // If no SVG found, use container position + activeCoordinateclientX = containerRect.left + (e.activeCoordinate.x ?? 0);clientY = containerRect.top + (e.activeCoordinate.y ?? 0);}}setClickedData(payload);- setClickEvent(e); // Store the full event+ setClickEvent(e);setClickPosition({x: clientX - containerRect.left,y: clientY - containerRect.top,@@ -131,7 +118,6 @@ export const ChartClickMenu = forwardRef<[onClose]);- // Expose methods via ref (for advanced use cases)useImperativeHandle(ref,() => ({@@ -143,15 +129,12 @@ export const ChartClickMenu = forwardRef<[]);- // Clone children and add onClick handler to chart componentsconst chartWithClickHandler = React.useMemo(() => {const addClickHandler = (node: React.ReactNode): React.ReactNode => {- // Handle null, undefined, strings, numbersif (!React.isValidElement(node)) {return node;}- // Check if this is a chart componentconst componentName =(node.type as any)?.displayName || (node.type as any)?.name;const isChartComponent =@@ -168,12 +151,10 @@ export const ChartClickMenu = forwardRef<return children;}- // Handle arraysif (Array.isArray(children)) {return children.map(addClickHandler);}- // Handle React fragmentsif (React.isValidElement(children) &&children.type === React.Fragment@@ -186,7 +167,6 @@ export const ChartClickMenu = forwardRef<});}- // Recursively process single childreturn addClickHandler(children);};@@ -202,14 +182,12 @@ export const ChartClickMenu = forwardRef<children: processChildren(element.props.children),});}- // For chart components, add onClick directlyreturn React.cloneElement(element, {onClick: handleChartClick,children: processChildren(element.props.children),});}- // Recursively process children for non-chart componentsif (element.props.children != null) {return React.cloneElement(element, {children: processChildren(element.props.children),@@ -219,7 +197,6 @@ export const ChartClickMenu = forwardRef<return node;};- // Handle multiple children (array) or single childif (Array.isArray(children)) {return children.map(addClickHandler);}diff --git a/apps/start/src/components/report-chart/common/report-table-utils.ts b/apps/start/src/components/report-chart/common/report-table-utils.tsindex 04bd70772..bc1c2ab0e 100644--- a/apps/start/src/components/report-chart/common/report-table-utils.ts+++ b/apps/start/src/components/report-chart/common/report-table-utils.ts@@ -12,7 +12,6 @@ export type TableRow = {min: number;max: number;dateValues: Record<string, number>; // date -> count- // Group metadatagroupKey?: string;parentGroupKey?: string;isSummaryRow?: boolean;@@ -23,33 +22,25 @@ export type GroupedTableRow = TableRow & {breakdownDisplay: (string | null)[]; // null means show empty cell};-/**- * Row type that supports TanStack Table's expanding feature- * Can represent both group header rows and data rows- */+/** Row type that supports TanStack Table's expanding feature. */export type ExpandableTableRow = TableRow & {subRows?: ExpandableTableRow[];- isGroupHeader?: boolean; // True if this is a group header row- groupValue?: string; // The value this group represents- groupLevel?: number; // The level in the hierarchy (0-based)- breakdownDisplay?: (string | null)[]; // For display purposes+ isGroupHeader?: boolean;+ groupValue?: string;+ groupLevel?: number; // 0-based+ breakdownDisplay?: (string | null)[];};-/**- * Hierarchical group structure for better collapse/expand functionality- */+/** Hierarchical group structure for collapse/expand. */export type GroupedItem<T> = {group: string;items: Array<GroupedItem<T> | T>;level: number;- groupKey: string; // Unique key for this group (path-based)- parentGroupKey?: string; // Key of parent group+ groupKey: string; // path-based+ parentGroupKey?: string;};-/**- * Transform flat array of items with hierarchical names into nested group structure- * This creates a tree structure that makes it easier to toggle specific groups- */+/** Transform a flat array with hierarchical names into a nested group tree. */export function groupByNames<T extends { names: string[] }>(items: T[]): Array<GroupedItem<T>> {@@ -85,7 +76,6 @@ export function groupByNames<T extends { names: string[] }>(const groupKey = `${parentGroupKey}:${levelName}`;const level = i - 1; // Breakdown levels start at 0- // Find existing group at this levelconst existingGroup = currentGroup.items.find((child): child is GroupedItem<T> =>typeof child === 'object' &&@@ -99,7 +89,6 @@ export function groupByNames<T extends { names: string[] }>(currentGroup = existingGroup;parentGroupKey = groupKey;} else {- // Create new group at this levelconst newGroup: GroupedItem<T> = {group: levelName,items: [],@@ -113,17 +102,13 @@ export function groupByNames<T extends { names: string[] }>(}}- // Add the actual item to the deepest groupcurrentGroup.items.push(item);}return Array.from(rootGroups.values());}-/**- * Flatten a grouped structure back into a flat array of items- * Useful for getting all items in a group or its children- */+/** Flatten a grouped structure back into a flat array of items. */export function flattenGroupedItems<T>(groupedItems: Array<GroupedItem<T> | T>): T[] {@@ -131,10 +116,8 @@ export function flattenGroupedItems<T>(for (const item of groupedItems) {if (item && typeof item === 'object' && 'items' in item) {- // It's a group, recursively flatten its itemsresult.push(...flattenGroupedItems(item.items));} else if (item) {- // It's an actual itemresult.push(item);}}@@ -154,7 +137,6 @@ export function findGroup<T>(return group;}- // Search in nested groupsfor (const item of group.items) {if (item && typeof item === 'object' && 'items' in item) {const found = findGroup([item], groupKey);@@ -169,15 +151,9 @@ export function findGroup<T>(}/**- * Convert hierarchical groups to TanStack Table's expandable row format- *- * Transforms nested GroupedItem structure into flat ExpandableTableRow array- * that TanStack Table can use with its native expanding feature.- *- * Key behaviors:- * - Serie level (level -1) and breakdown levels 0 to breakdownCount-2 create group headers- * - Last breakdown level (breakdownCount-1) does NOT create group headers (always individual rows)- * - Individual rows are explicitly marked as NOT group headers or summary rows+ * Convert hierarchical groups into TanStack Table's flat expandable-row+ * format. The serie level and every breakdown level except the last create+ * group header rows; the last breakdown level is always individual rows.*/export function groupsToExpandableRows(groups: Array<GroupedItem<TableRow>>,@@ -192,7 +168,6 @@ export function groupsToExpandableRows(const currentPath = [...parentPath, group.group];const subRows: ExpandableTableRow[] = [];- // Separate nested groups from individual data itemsconst nestedGroups: GroupedItem<TableRow>[] = [];const individualItems: TableRow[] = [];@@ -204,30 +179,25 @@ export function groupsToExpandableRows(}}- // Process nested groups recursively (they become expandable group headers)for (const nestedGroup of nestedGroups) {subRows.push(...processGroup(nestedGroup, currentPath));}- // Process individual data items (leaf nodes)+ // Build breakdownDisplay: the first row shows all breakdown values;+ // subsequent rows show the parent path's values, then the item's own.individualItems.forEach((item, index) => {- // Build breakdownDisplay: first row shows all values, subsequent rows show parent path + item valuesconst breakdownDisplay: (string | null)[] = [];const breakdownValues = item.breakdownValues;for (let i = 0; i < breakdownCount; i++) {if (index === 0) {- // First row: show all breakdown values+ breakdownDisplay.push(breakdownValues[i] ?? null);+ } else if (i < currentPath.length) {+ breakdownDisplay.push(currentPath[i] ?? null);+ } else if (i < breakdownValues.length) {breakdownDisplay.push(breakdownValues[i] ?? null);} else {- // Subsequent rows: show parent path values, then item values- if (i < currentPath.length) {- breakdownDisplay.push(currentPath[i] ?? null);- } else if (i < breakdownValues.length) {- breakdownDisplay.push(breakdownValues[i] ?? null);- } else {- breakdownDisplay.push(null);- }+ breakdownDisplay.push(null);}}@@ -241,18 +211,13 @@ export function groupsToExpandableRows(});});- // If this group has subRows and is not the last breakdown level, create a group header row- // Don't create group headers for the last breakdown level (level === breakdownCount - 1)- // because the last breakdown should always be individual rows- // -1 is serie level (should be grouped)- // 0 to breakdownCount-2 are breakdown levels (should be grouped)- // breakdownCount-1 is the last breakdown level (should NOT be grouped, always individual)+ // Every level groups into a header row except the last breakdown level+ // (level === breakdownCount - 1), which always stays individual rows.const shouldCreateGroupHeader =subRows.length > 0 &&(group.level === -1 || group.level < breakdownCount - 1);if (shouldCreateGroupHeader) {- // Create a summary row for the groupconst groupItems = flattenGroupedItems(group.items);const summaryRow = createSummaryRow(groupItems,@@ -302,7 +267,6 @@ export function groupsToTableRows<T extends TableRow>(const currentPath = [...parentPath, group.group];if (isGroupCollapsed) {- // Group is collapsed - add summary rowconst groupItems = flattenGroupedItems(group.items);if (groupItems.length > 0) {const summaryRow = createSummaryRow(@@ -315,8 +279,6 @@ export function groupsToTableRows<T extends TableRow>(return;}- // Group is expanded - process items- // Separate nested groups from actual itemsconst nestedGroups: GroupedItem<T>[] = [];const actualItems: T[] = [];@@ -328,26 +290,19 @@ export function groupsToTableRows<T extends TableRow>(}}- // Process actual items firstactualItems.forEach((item, index) => {const breakdownDisplay: (string | null)[] = [];const breakdownValues = item.breakdownValues;- // For the first item in the group, show all breakdown values- // For subsequent items, show values based on hierarchyif (index === 0) {- // First row shows all breakdown valuesfor (let i = 0; i < breakdownCount; i++) {breakdownDisplay.push(breakdownValues[i] ?? null);}} else {- // Subsequent rows: show values from parent path, then item valuesfor (let i = 0; i < breakdownCount; i++) {if (i < currentPath.length) {- // Show value from parent group pathbreakdownDisplay.push(currentPath[i] ?? null);} else if (i < breakdownValues.length) {- // Show current breakdown value from the itembreakdownDisplay.push(breakdownValues[i] ?? null);} else {breakdownDisplay.push(null);@@ -363,7 +318,6 @@ export function groupsToTableRows<T extends TableRow>(});});- // Process nested groupsfor (const nestedGroup of nestedGroups) {processGroup(nestedGroup, currentPath, group.groupKey);}@@ -376,9 +330,7 @@ export function groupsToTableRows<T extends TableRow>(return rows;}-/**- * Extract unique dates from all series- */+/** Extract unique dates from all series. */function getUniqueDates(series: IChartData['series']): string[] {const dateSet = new Set<string>();series.forEach((serie) => {@@ -390,20 +342,18 @@ function getUniqueDates(series: IChartData['series']): string[] {}/**- * Get breakdown property names from series- * Breakdown values are in names.slice(1), so we need to infer the property names- * from the breakdowns array or from the series structure+ * Get breakdown property names from series. Breakdown values live in+ * names.slice(1), so the property names have to be inferred from the+ * breakdowns array or from the series structure.*/function getBreakdownPropertyNames(series: IChartData['series'],breakdowns: Array<{ name: string }>): string[] {- // If we have breakdowns from state, use thoseif (breakdowns.length > 0) {return breakdowns.map((b) => getPropertyLabel(b.name));}- // Otherwise, infer from series names// All series should have the same number of breakdown valuesif (series.length === 0) {return [];@@ -442,11 +392,7 @@ export function createFlatRows(});}-/**- * Transform series into hierarchical groups- * Uses the new groupByNames function for better structure- * Groups by serie name first, then by breakdown values- */+/** Transform series into hierarchical groups: serie name, then breakdown values. */export function createGroupedRowsHierarchical(series: IChartData['series'],dates: string[]@@ -463,9 +409,8 @@ export function createGroupedRowsHierarchical(return [];}- // Create hierarchical groups using groupByNames- // Note: groupByNames expects items with a `names` array, so we create a temporary array- // This is a minor inefficiency but keeps groupByNames generic and reusable+ // groupByNames expects items with a `names` array; building a temporary+ // one here is a minor inefficiency that keeps groupByNames generic.const itemsWithNames = flatRows.map((row) => ({...row,names: [row.serieName, ...row.breakdownValues],@@ -476,7 +421,6 @@ export function createGroupedRowsHierarchical(/*** Transform series into grouped table rows (legacy flat format)- * Groups rows hierarchically by breakdown values* @deprecated Use createGroupedRowsHierarchical + groupsToTableRows instead*/export function createGroupedRows(@@ -485,26 +429,18 @@ export function createGroupedRows(): GroupedTableRow[] {const flatRows = createFlatRows(series, dates);- // Sort by sum descendingflatRows.sort((a, b) => b.sum - a.sum);- // Group rows by breakdown values hierarchicallyconst grouped: GroupedTableRow[] = [];const breakdownCount = flatRows[0]?.breakdownValues.length ?? 0;if (breakdownCount === 0) {- // No breakdowns, just return flat rowsreturn flatRows.map((row) => ({...row,breakdownDisplay: [],}));}- // Group rows hierarchically by breakdown values- // We need to group by parent breakdowns first, then by child breakdowns- // This creates the nested structure shown in the user's example-- // First, group by first breakdown valueconst groupsByFirstBreakdown = new Map<string, TableRow[]>();flatRows.forEach((row) => {const firstBreakdown = row.breakdownValues[0] ?? '';@@ -514,7 +450,6 @@ export function createGroupedRows(groupsByFirstBreakdown.get(firstBreakdown)!.push(row);});- // Sort groups by sum of highest row in groupconst sortedGroups = Array.from(groupsByFirstBreakdown.entries()).sort((a, b) => {const aMax = Math.max(...a[1].map((r) => r.sum));@@ -523,26 +458,20 @@ export function createGroupedRows(});- // Process each group hierarchicallysortedGroups.forEach(([firstBreakdownValue, groupRows]) => {- // Within each first-breakdown group, sort by sumgroupRows.sort((a, b) => b.sum - a.sum);- // Generate group key for this first-breakdown groupconst groupKey = firstBreakdownValue;- // For each row in the groupgroupRows.forEach((row, index) => {const breakdownDisplay: (string | null)[] = [];const firstRow = groupRows[0]!;if (index === 0) {- // First row shows all breakdown valuesbreakdownDisplay.push(...row.breakdownValues);} else {- // Subsequent rows: show all values, but mark duplicates for muted styling+ // Always show the value, even if it matches the first row.for (let i = 0; i < row.breakdownValues.length; i++) {- // Always show the value, even if it matches the first rowbreakdownDisplay.push(row.breakdownValues[i] ?? null);}}@@ -558,9 +487,7 @@ export function createGroupedRows(return grouped;}-/**- * Create a summary row for a collapsed group- */+/** Create a summary row for a collapsed group. */export function createSummaryRow(groupRows: TableRow[],groupKey: string,@@ -568,7 +495,6 @@ export function createSummaryRow(): GroupedTableRow {const firstRow = groupRows[0]!;- // Aggregate metrics from all rows in the groupconst totalSum = groupRows.reduce((sum, row) => sum + row.sum, 0);const totalCount = groupRows.reduce((sum, row) => sum + row.count, 0);const totalAverage =@@ -576,7 +502,6 @@ export function createSummaryRow(const totalMin = Math.min(...groupRows.map((row) => row.min));const totalMax = Math.max(...groupRows.map((row) => row.max));- // Aggregate date values across all rowsconst dateValues: Record<string, number> = {};groupRows.forEach((row) => {Object.keys(row.dateValues).forEach((date) => {@@ -607,9 +532,7 @@ export function createSummaryRow(};}-/**- * Reorder breakdowns by number of unique values (fewest first)- */+/** Reorder breakdowns by number of unique values (fewest first). */function reorderBreakdownsByUniqueCount(series: IChartData['series'],breakdownPropertyNames: string[]@@ -626,7 +549,6 @@ function reorderBreakdownsByUniqueCount(};}- // Count unique values for each breakdown indexconst uniqueCounts = breakdownPropertyNames.map((_, index) => {const uniqueValues = new Set<string>();series.forEach((serie) => {@@ -638,10 +560,8 @@ function reorderBreakdownsByUniqueCount(return { index, count: uniqueValues.size };});- // Sort by count (ascending - fewest first)uniqueCounts.sort((a, b) => a.count - b.count);- // Create reordered names and mappingconst reorderedNames = uniqueCounts.map((item) => breakdownPropertyNames[item.index]!);@@ -654,9 +574,7 @@ function reorderBreakdownsByUniqueCount(return { reorderedNames, reorderMap, reverseMap };}-/**- * Transform chart data into table-ready format- */+/** Transform chart data into table-ready format. */export function transformToTableData(data: IChartData,breakdowns: Array<{ name: string }>,@@ -672,15 +590,13 @@ export function transformToTableData(breakdowns);- // Reorder breakdowns by unique count (fewest first)const { reorderedNames: breakdownPropertyNames, reorderMap } =reorderBreakdownsByUniqueCount(data.series, originalBreakdownPropertyNames);- // Reorder breakdown values in series before creating rowsconst reorderedSeries = data.series.map((serie) => {const reorderedNames = [- serie.names[0], // Keep serie name first- ...reorderMap.map((oldIndex) => serie.names[oldIndex + 1] ?? ''), // Reorder breakdown values+ serie.names[0],+ ...reorderMap.map((oldIndex) => serie.names[oldIndex + 1] ?? ''),];return {...serie,@@ -692,7 +608,6 @@ export function transformToTableData(? createGroupedRows(reorderedSeries, dates): createFlatRows(reorderedSeries, dates);- // Sort flat rows by sum descendingif (!grouped) {(rows as TableRow[]).sort((a, b) => b.sum - a.sum);}@@ -704,10 +619,7 @@ export function transformToTableData(};}-/**- * Transform chart data into hierarchical groups- * Returns hierarchical structure for better group management- */+/** Transform chart data into hierarchical groups. */export function transformToHierarchicalGroups(data: IChartData,breakdowns: Array<{ name: string }>@@ -722,15 +634,13 @@ export function transformToHierarchicalGroups(breakdowns);- // Reorder breakdowns by unique count (fewest first)const { reorderedNames: breakdownPropertyNames, reorderMap } =reorderBreakdownsByUniqueCount(data.series, originalBreakdownPropertyNames);- // Reorder breakdown values in series before creating rowsconst reorderedSeries = data.series.map((serie) => {const reorderedNames = [- serie.names[0], // Keep serie name first- ...reorderMap.map((oldIndex) => serie.names[oldIndex + 1] ?? ''), // Reorder breakdown values+ serie.names[0],+ ...reorderMap.map((oldIndex) => serie.names[oldIndex + 1] ?? ''),];return {...serie,diff --git a/apps/start/src/components/report-chart/common/report-table.tsx b/apps/start/src/components/report-chart/common/report-table.tsxindex 8e172ab84..30ebdc81c 100644--- a/apps/start/src/components/report-chart/common/report-table.tsx+++ b/apps/start/src/components/report-chart/common/report-table.tsx@@ -60,7 +60,6 @@ interface VirtualRowProps {isResizingRef: React.MutableRefObject<boolean>;resizingColumnId: string | null;setResizingColumnId: (id: string | null) => void;- // Horizontal virtualization propsleftPinnedColumns: Header<TableRow | GroupedTableRow, unknown>['column'][];scrollableColumns: Header<TableRow | GroupedTableRow, unknown>['column'][];rightPinnedColumns: Header<TableRow | GroupedTableRow, unknown>['column'][];@@ -167,13 +166,11 @@ const VirtualRow = function VirtualRow({minWidth: 'fit-content',}}>- {/* Left Pinned Columns */}{leftPinnedColumns.map((column) => {const header = headers.find((h) => h.column.id === column.id);return renderCell(column, header);})}- {/* Scrollable Columns (Virtualized) */}<divstyle={{position: 'relative',@@ -209,7 +206,6 @@ const VirtualRow = function VirtualRow({})}</div>- {/* Right Pinned Columns */}{rightPinnedColumns.map((column) => {const header = headers.find((h) => h.column.id === column.id);return renderCell(column, header);@@ -241,7 +237,6 @@ export function ReportTable({short: true,});- // Transform data to hierarchical groups or flat rowsconst {groups: hierarchicalGroups,rows: flatRows,@@ -266,7 +261,6 @@ export function ReportTable({};}, [data, breakdowns, grouped]);- // Convert hierarchical groups to expandable rows (for TanStack Table's expanding feature)const expandableRows = useMemo(() => {if (!(grouped && hierarchicalGroups) || hierarchicalGroups.length === 0) {return null;@@ -278,23 +272,18 @@ export function ReportTable({);}, [grouped, hierarchicalGroups, breakdownPropertyNames.length]);- // Use expandable rows if available, otherwise use flat rowsconst rows = expandableRows ?? flatRows ?? [];- // Filter rows based on global search and apply sortingconst filteredRows = useMemo(() => {let result = rows;- // Apply search filterif (globalFilter.trim()) {const searchLower = globalFilter.toLowerCase();result = rows.filter((row) => {- // Search in serie nameif (row.serieName.toLowerCase().includes(searchLower)) {return true;}- // Search in breakdown valuesif (row.breakdownValues.some((val) =>val?.toLowerCase().includes(searchLower)@@ -303,7 +292,6 @@ export function ReportTable({return true;}- // Search in metric valuesconst metrics = ['count', 'sum', 'average', 'min', 'max'] as const;if (metrics.some((metric) =>@@ -313,7 +301,6 @@ export function ReportTable({return true;}- // Search in date valuesif (Object.values(row.dateValues).some((val) =>String(val).toLowerCase().includes(searchLower)@@ -326,16 +313,13 @@ export function ReportTable({});}- // Apply sorting - if grouped, always sort groups by highest count, then sort within each groupif (grouped && result.length > 0) {const groupedRows = result as ExpandableTableRow[] | GroupedTableRow[];- // Sort function based on current sort stateconst sortFn = (a: ExpandableTableRow | GroupedTableRow | TableRow,b: ExpandableTableRow | GroupedTableRow | TableRow) => {- // If no sorting is selected, return 0 (no change)if (sorting.length === 0) {return 0;}@@ -372,7 +356,6 @@ export function ReportTable({continue;}- // Handle null/undefined valuesif (aValue == null && bValue == null) {continue;}@@ -383,7 +366,6 @@ export function ReportTable({return -1;}- // Compare valuesif (typeof aValue === 'string' && typeof bValue === 'string') {const comparison = aValue.localeCompare(bValue);if (comparison !== 0) {@@ -401,14 +383,11 @@ export function ReportTable({return 0;};- // For expandable rows, we need to sort recursivelyfunction sortExpandableRows(rows: ExpandableTableRow[],isTopLevel = true): ExpandableTableRow[] {- // Sort rows: groups by count first (only at top level), then apply user sortconst sorted = [...rows].sort((a, b) => {- // At top level, sort groups by count firstif (isTopLevel) {const aIsGroupHeader = 'isGroupHeader' in a && a.isGroupHeader;const bIsGroupHeader = 'isGroupHeader' in b && b.isGroupHeader;@@ -422,18 +401,16 @@ export function ReportTable({const aCount = a.count ?? 0;const bCount = b.count ?? 0;if (aCount !== bCount) {- return bCount - aCount; // Highest first+ return bCount - aCount;}// If counts are equal, fall through to user sort}}}- // Apply user's sort criteria (for all rows, including within groups)return sortFn(a, b);});- // Sort subRows recursively (within each group) - these are NOT top levelreturn sorted.map((row) => {if ('subRows' in row && row.subRows) {return {@@ -448,7 +425,6 @@ export function ReportTable({return sortExpandableRows(groupedRows as ExpandableTableRow[]);}- // For flat mode, apply sortingif (!grouped && result.length > 0 && sorting.length > 0) {return [...result].sort((a, b) => {for (const sort of sorting) {@@ -475,7 +451,6 @@ export function ReportTable({continue;}- // Handle null/undefined valuesif (aValue == null && bValue == null) {continue;}@@ -486,7 +461,6 @@ export function ReportTable({return -1;}- // Compare valuesif (typeof aValue === 'string' && typeof bValue === 'string') {const comparison = aValue.localeCompare(bValue);if (comparison !== 0) {@@ -508,7 +482,6 @@ export function ReportTable({return result;}, [rows, globalFilter, grouped, sorting]);- // Calculate min/max values for color visualizationconst { metricRanges, dateRanges } = useMemo(() => {const metricRanges: Record<string, { min: number; max: number }> = {count: {@@ -532,7 +505,6 @@ export function ReportTable({};});- // Helper function to flatten expandable rows and get only individual rowsfunction getIndividualRows(rows: (ExpandableTableRow | TableRow)[]): TableRow[] {@@ -543,11 +515,9 @@ export function ReportTable({const isSummary = 'isSummaryRow' in row && row.isSummaryRow === true;if (!(isGroupHeader || isSummary)) {- // It's an individual row - add itindividualRows.push(row as TableRow);}- // Always recursively process subRows if they exist (regardless of whether this is a group header)if ('subRows' in row && row.subRows && Array.isArray(row.subRows)) {individualRows.push(...getIndividualRows(row.subRows));}@@ -555,12 +525,10 @@ export function ReportTable({return individualRows;}- // Get only individual rows from all rows to ensure consistent rangesconst individualRows = getIndividualRows(rows);const isSingleSeries = individualRows.length === 1;if (isSingleSeries) {- // For single series, calculate ranges from date valuesconst singleRow = individualRows[0]!;const allDateValues = dates.map((date) => singleRow.dateValues[date] ?? 0@@ -568,7 +536,6 @@ export function ReportTable({const dateMin = Math.min(...allDateValues);const dateMax = Math.max(...allDateValues);- // For date columns, use the range across all datesdates.forEach((date) => {dateRanges[date] = {min: dateMin,@@ -576,50 +543,41 @@ export function ReportTable({};});- // For metric columns, use date values to create meaningful ranges- // This ensures we can still show color variation even with one seriesmetricRanges.count = { min: dateMin, max: dateMax };metricRanges.sum = { min: dateMin, max: dateMax };metricRanges.average = { min: dateMin, max: dateMax };metricRanges.min = { min: dateMin, max: dateMax };metricRanges.max = { min: dateMin, max: dateMax };+ } else if (individualRows.length === 0) {} else {- // Multiple series: calculate ranges across individual rows only- if (individualRows.length === 0) {- // No individual rows found - this shouldn't happen, but handle gracefully- } else {- individualRows.forEach((row) => {- // Calculate metric ranges- Object.keys(metricRanges).forEach((key) => {- const value = row[key as keyof typeof row] as number;- if (typeof value === 'number' && !Number.isNaN(value)) {- metricRanges[key]!.min = Math.min(metricRanges[key]!.min, value);- metricRanges[key]!.max = Math.max(metricRanges[key]!.max, value);- }- });-- // Calculate date ranges- dates.forEach((date) => {- const value = row.dateValues[date] ?? 0;- if (!dateRanges[date]) {- dateRanges[date] = {- min: Number.POSITIVE_INFINITY,- max: Number.NEGATIVE_INFINITY,- };- }- if (typeof value === 'number' && !Number.isNaN(value)) {- dateRanges[date]!.min = Math.min(dateRanges[date]!.min, value);- dateRanges[date]!.max = Math.max(dateRanges[date]!.max, value);- }- });+ individualRows.forEach((row) => {+ Object.keys(metricRanges).forEach((key) => {+ const value = row[key as keyof typeof row] as number;+ if (typeof value === 'number' && !Number.isNaN(value)) {+ metricRanges[key]!.min = Math.min(metricRanges[key]!.min, value);+ metricRanges[key]!.max = Math.max(metricRanges[key]!.max, value);+ }});- }++ dates.forEach((date) => {+ const value = row.dateValues[date] ?? 0;+ if (!dateRanges[date]) {+ dateRanges[date] = {+ min: Number.POSITIVE_INFINITY,+ max: Number.NEGATIVE_INFINITY,+ };+ }+ if (typeof value === 'number' && !Number.isNaN(value)) {+ dateRanges[date]!.min = Math.min(dateRanges[date]!.min, value);+ dateRanges[date]!.max = Math.max(dateRanges[date]!.max, value);+ }+ });+ });}return { metricRanges, dateRanges };}, [rows, dates]);- // Helper to get background color style and opacity for a value// Returns both style and opacity (for text color calculation) to avoid parsingconst getCellBackgroundStyle = (value: number,@@ -631,7 +589,6 @@ export function ReportTable({return { style: {}, opacity: 0 };}- // If min equals max (e.g. single row or all values same), show moderate opacitylet opacity: number;if (max === min) {opacity = 0.5;@@ -652,7 +609,6 @@ export function ReportTable({};};- // Normalize visibleSeries to string arrayconst visibleSeriesIds = useMemo(() => {if (visibleSeries.length === 0) {return [];@@ -663,17 +619,14 @@ export function ReportTable({return (visibleSeries as IChartData['series']).map((s) => s.id);}, [visibleSeries]);- // Create a hash of visibleSeriesIds to track checkbox state changesconst visibleSeriesIdsHash = useMemo(() => {return visibleSeriesIds.sort().join(',');}, [visibleSeriesIds]);- // Get serie index for colorconst getSerieIndex = (serieId: string): number => {return data.series.findIndex((s) => s.id === serieId);};- // Toggle serie visibilityconst toggleSerieVisibility = (serieId: string) => {setVisibleSeries((prev) => {if (prev.includes(serieId)) {@@ -683,19 +636,13 @@ export function ReportTable({});};- // Toggle group collapse (now handled by TanStack Table's expanding feature)- // This is kept for backward compatibility with header click handlersconst toggleGroupCollapse = (groupKey: string) => {- // This will be handled by TanStack Table's row expansion- // We can find the row by groupKey and toggle it// For now, this is a no-op as TanStack Table handles it};- // Define columnsconst columns = useMemo<ColumnDef<TableRow | GroupedTableRow>[]>(() => {const cols: ColumnDef<TableRow | GroupedTableRow>[] = [];- // Serie name column (pinned left) with checkboxcols.push({id: 'serie-name',header: 'Serie',@@ -724,7 +671,6 @@ export function ReportTable({original.groupKey &&!original.isSummaryRow) {- // Find all rows in this group from the current rows arrayconst groupRows = rows.filter((r): r is GroupedTableRow =>'groupKey' in r &&@@ -735,7 +681,6 @@ export function ReportTable({if (groupRows.length > 0) {const firstRowInGroup = groupRows[0]!;- // Check if this is the first row in the groupif (firstRowInGroup.id === original.id) {isFirstRowInGroup = true;} else {@@ -781,7 +726,6 @@ export function ReportTable({onClick={(e) => {e.stopPropagation();e.preventDefault();- // Toggle expanded state manuallysetExpanded((prev) => {const newExpanded: ExpandedState =typeof prev === 'object' ? { ...prev } : {};@@ -804,7 +748,6 @@ export function ReportTable({},});- // Breakdown columns (pinned left, collapsible)breakdownPropertyNames.forEach((propertyName, index) => {const isLastBreakdown = index === breakdownPropertyNames.length - 1;const isCollapsible = grouped && !isLastBreakdown;@@ -827,7 +770,6 @@ export function ReportTable({return propertyName;}- // Find all rows at this breakdown level that can be expandedconst rowsAtLevel: string[] = [];if (grouped && expandableRows) {function collectRowIdsAtLevel(@@ -843,7 +785,6 @@ export function ReportTable({) {rowsAtLevel.push(row.id);}- // Recurse into subRows if we haven't reached target level yetif (currentLevel < targetLevel && row.subRows) {collectRowIdsAtLevel(row.subRows,@@ -856,7 +797,6 @@ export function ReportTable({collectRowIdsAtLevel(expandableRows, index);}- // Check if all groups at this level are expandedconst allExpanded =rowsAtLevel.length > 0 &&rowsAtLevel.every(@@ -870,7 +810,6 @@ export function ReportTable({if (!grouped) {return;}- // Toggle all groups at this breakdown levelsetExpanded((prev) => {const newExpanded: ExpandedState =typeof prev === 'object' ? { ...prev } : {};@@ -969,7 +908,6 @@ export function ReportTable({});});- // Metric columnsconst metrics = [{ key: 'count', label: 'Unique' },{ key: 'sum', label: 'Sum' },@@ -996,7 +934,6 @@ export function ReportTable({const isIndividualRow = !(isSummary || isGroupHeader);const range = metricRanges[metric.key];- // Only apply colors to individual rows, not summary or group header rows// Also check that range is valid (not still at initial values)const hasValidRange =range &&@@ -1024,7 +961,6 @@ export function ReportTable({});});- // Date columnsdates.forEach((date) => {cols.push({id: `date-${date}`,@@ -1040,7 +976,6 @@ export function ReportTable({row.original.isGroupHeader === true;const isIndividualRow = !(isSummary || isGroupHeader);const range = dateRanges[date];- // Only apply colors to individual rows, not summary or group header rows// Also check that range is valid (not still at initial values)const hasValidRange =range &&@@ -1086,15 +1021,13 @@ export function ReportTable({data,]);- // Create a hash of column IDs to track when columns changeconst columnsHash = useMemo(() => {return columns.map((col) => col.id).join(',');}, [columns]);- // Memoize table options to ensure table updates when filteredRows changesconst tableOptions = useMemo(() => ({- data: filteredRows, // This is already sorted in filteredRows+ data: filteredRows,columns,getCoreRowModel: getCoreRowModel(),getExpandedRowModel: grouped ? getExpandedRowModel() : undefined,@@ -1131,9 +1064,9 @@ export function ReportTable({onSortingChange: setSorting,onColumnSizingChange: setColumnSizing,onExpandedChange: grouped ? setExpanded : undefined,- globalFilterFn: () => true, // We handle filtering manually- manualSorting: true, // We handle sorting manually for both modes- manualFiltering: true, // We handle filtering manually+ globalFilterFn: () => true,+ manualSorting: true,+ manualFiltering: true,}),[filteredRows,@@ -1151,7 +1084,6 @@ export function ReportTable({const table = useReactTable(tableOptions);- // Virtualization setupuseEffect(() => {const updateScrollMargin = throttle(() => {if (parentRef.current) {@@ -1169,7 +1101,6 @@ export function ReportTable({};}, []);- // Handle global mouseup to reset resize flaguseEffect(() => {const handleMouseUp = () => {if (isResizingRef.current) {@@ -1190,7 +1121,6 @@ export function ReportTable({};}, []);- // Get the row model to use (expanded when grouped, regular otherwise)// Always call the table helpers so React Table can manage its own memoizationconst rowModelToUse = grouped? table.getExpandedRowModel()@@ -1205,12 +1135,10 @@ export function ReportTable({const virtualRows = virtualizer.getVirtualItems();- // Get visible columns in orderconst headerColumns = table.getAllLeafColumns().filter((col) => table.getState().columnVisibility[col.id] !== false);- // Separate columns into pinned and scrollableconst leftPinnedColumns = headerColumns.filter((col) => col.columnDef.meta?.pinned === 'left');@@ -1221,7 +1149,6 @@ export function ReportTable({(col) => !col.columnDef.meta?.pinned);- // Calculate widths for virtualizationconst leftPinnedWidth = useMemo(() => leftPinnedColumns.reduce((sum, col) => sum + col.getSize(), 0),[leftPinnedColumns, columnSizing]@@ -1235,7 +1162,6 @@ export function ReportTable({[scrollableColumns, columnSizing]);- // Horizontal virtualization for scrollable columns// Only virtualize if we have enough columns to benefit from itconst shouldVirtualizeHorizontal = scrollableColumns.length > 10;@@ -1248,7 +1174,6 @@ export function ReportTable({overscan: shouldVirtualizeHorizontal ? 5 : scrollableColumns.length,});- // Get virtual columns - if not virtualizing, return all columnsconst virtualColumns = shouldVirtualizeHorizontal? horizontalVirtualizer.getVirtualItems(): scrollableColumns.map((col, index) => ({@@ -1262,7 +1187,6 @@ export function ReportTable({lane: 0,}));- // Pre-compute grid template columns string and headersconst { gridTemplateColumns, headers } = useMemo(() => {const headerGroups = table.getHeaderGroups();const firstGroupHeaders = headerGroups[0]?.headers ?? [];@@ -1273,7 +1197,6 @@ export function ReportTable({};}, [table, columnSizing, columnsHash]);- // Pre-compute pinning styles for all columnsconst pinningStylesMap = useMemo(() => {const stylesMap = new Map<string, React.CSSProperties>();const headerGroups = table.getHeaderGroups();@@ -1319,7 +1242,6 @@ export function ReportTable({return stylesMap;}, [table, leftPinnedColumns, rightPinnedColumns, columnSizing, columnsHash]);- // Helper to get pinning styles (for backward compatibility with header)const getPinningStyles = (column: ReturnType<typeof table.getColumn> | undefined) => {@@ -1361,7 +1283,6 @@ export function ReportTable({minWidth: 'fit-content',}}>- {/* Header */}<divclassName="sticky top-0 z-20 border-b bg-card"style={{@@ -1373,7 +1294,6 @@ export function ReportTable({minWidth: 'fit-content',}}>- {/* Left Pinned Columns */}{leftPinnedColumns.map((column) => {const header = headers.find((h) => h.column.id === column.id);if (!header) {@@ -1489,7 +1409,6 @@ export function ReportTable({);})}- {/* Scrollable Columns (Virtualized) */}<divstyle={{position: 'relative',@@ -1580,7 +1499,6 @@ export function ReportTable({})}</div>- {/* Right Pinned Columns */}{rightPinnedColumns.map((column) => {const header = headers.find((h) => h.column.id === column.id);if (!header) {@@ -1662,7 +1580,6 @@ export function ReportTable({})}</div>- {/* Virtualized Body */}<divstyle={{height: `${virtualizer.getTotalSize()}px`,diff --git a/apps/start/src/components/report-chart/conversion/conversion-table.tsx b/apps/start/src/components/report-chart/conversion/conversion-table.tsxindex a2d080c7e..1d3ab982f 100644--- a/apps/start/src/components/report-chart/conversion/conversion-table.tsx+++ b/apps/start/src/components/report-chart/conversion/conversion-table.tsx@@ -33,7 +33,6 @@ export function ConversionTable({short: true,});- // Get all unique dates from the first seriesconst dates = useMemo(() => data.current[0]?.data.map((item) => item.date) ?? [],[data.current]@@ -42,7 +41,6 @@ export function ConversionTable({// Get all series (including non-visible ones for toggle functionality)const allSeries = data.current;- // Transform data to table rows with memoizationconst rows = useMemo(() => {return allSeries.map((serie) => {const dateValues: Record<string, number> = {};@@ -84,7 +82,6 @@ export function ConversionTable({});}, [allSeries, dates, data.previous]);- // Calculate ranges for color visualization (memoized)const { metricRanges, dateRanges } = useMemo(() => {const metricRanges: Record<string, { min: number; max: number }> = {avgRate: {@@ -110,7 +107,6 @@ export function ConversionTable({});rows.forEach((row) => {- // Metric rangesmetricRanges.avgRate.min = Math.min(metricRanges.avgRate.min,row.avgRate@@ -130,7 +126,6 @@ export function ConversionTable({row.conversions);- // Date rangesdates.forEach((date) => {const value = row.dateValues[date] ?? 0;dateRanges[date]!.min = Math.min(dateRanges[date]!.min, value);@@ -141,7 +136,6 @@ export function ConversionTable({return { metricRanges, dateRanges };}, [rows, dates]);- // Helper to get background color styleconst getCellBackgroundStyle = (value: number,min: number,@@ -189,7 +183,6 @@ export function ConversionTable({if (globalFilter.trim()) {const searchLower = globalFilter.toLowerCase();result = rows.filter((row) => {- // Search in serie nameif (row.serieName.some((name) =>name?.toLowerCase().includes(searchLower)@@ -198,7 +191,6 @@ export function ConversionTable({return true;}- // Search in breakdown valuesif (row.breakdownValues.some((val) =>val?.toLowerCase().includes(searchLower)@@ -207,7 +199,6 @@ export function ConversionTable({return true;}- // Search in metric valuesif (String(row.avgRate).toLowerCase().includes(searchLower) ||String(row.total).toLowerCase().includes(searchLower) ||@@ -216,7 +207,6 @@ export function ConversionTable({return true;}- // Search in date valuesif (Object.values(row.dateValues).some((val) =>String(val).toLowerCase().includes(searchLower)@@ -268,7 +258,6 @@ export function ConversionTable({return -1;}- // Compare valuesif (typeof aValue === 'string' && typeof bValue === 'string') {const comparison = aValue.localeCompare(bValue);if (comparison !== 0) {diff --git a/apps/start/src/components/report/reportSlice.ts b/apps/start/src/components/report/reportSlice.tsindex c693be607..58e391875 100644--- a/apps/start/src/components/report/reportSlice.ts+++ b/apps/start/src/components/report/reportSlice.ts@@ -34,7 +34,6 @@ type InitialState = IReport & {globalFilters: IChartEventFilter[];};-// First approach: define the initial state using that typeconst initialState: InitialState = {ready: false,dirty: false,@@ -217,7 +216,6 @@ export const reportSlice = createSlice({state.metric = 'count';}- // Initialize sankey options if switching to sankeyif (action.payload === 'sankey' && !state.options) {state.options = {type: 'sankey',@@ -428,7 +426,6 @@ export const reportSlice = createSlice({},});-// Action creators are generated for each case reducer functionexport const {reset,ready,diff --git a/apps/start/src/components/report/sidebar/filters/FilterItem.tsx b/apps/start/src/components/report/sidebar/filters/FilterItem.tsxindex e6dd2cbde..7773bdd37 100644--- a/apps/start/src/components/report/sidebar/filters/FilterItem.tsx+++ b/apps/start/src/components/report/sidebar/filters/FilterItem.tsx@@ -23,7 +23,8 @@ import { usePropertyValues } from '@/hooks/use-property-values';import { useDispatch } from '@/redux';// Client-side sanity check: can this raw value possibly match the chosen cast-// type? Mirrors the SQL casts in packages/db filter-cast.ts. Returns an error+// type? Mirrors the SQL casts in+// packages/core/src/modules/chart/src/filter-cast.ts. Returns an error// message to show inline, or undefined when valid (or empty / untyped).function validateFilterValue(value: string,diff --git a/apps/start/src/components/widget-table.tsx b/apps/start/src/components/widget-table.tsxindex 801d5bfdb..515d692f6 100644--- a/apps/start/src/components/widget-table.tsx+++ b/apps/start/src/components/widget-table.tsx@@ -71,7 +71,6 @@ export const WidgetTableHead = ({* Priority 10 = hidden first (lowest priority)*/function getResponsiveClass(priority: ColumnPriority): string {- // Priority 1 = always visible (no hiding)if (priority === 1) {return '';}@@ -89,10 +88,7 @@ function getResponsiveStyle(}const minWidth = (priority - 1) * 100 + 100;- return {- // Use CSS custom property for container query- // Will be handled by inline style with container query- } as React.CSSProperties;+ return {} as React.CSSProperties;}/**@@ -126,7 +122,6 @@ export function WidgetTable<T>({const reactId = React.useId();const containerId = `widget-table-${reactId.replace(/:/g, '')}`;- // Generate CSS for container queriesconst containerQueryStyles = React.useMemo(() => {const styles: string[] = [];@@ -188,7 +183,6 @@ export function WidgetTable<T>({dataAttrs['data-min-width'] = String(column.responsive.minWidth);}- // Use column.key if available, otherwise try to extract string from name, fallback to indexconst columnKey =column.key ??(typeof column.name === 'string'@@ -249,7 +243,6 @@ export function WidgetTable<T>({);}- // Use column.key if available, otherwise try to extract string from name, fallback to indexconst columnKey =column.key ??(typeof column.name === 'string'diff --git a/apps/start/src/modals/insight-details.tsx b/apps/start/src/modals/insight-details.tsxindex 4123e1494..68d09f22c 100644--- a/apps/start/src/modals/insight-details.tsx+++ b/apps/start/src/modals/insight-details.tsx@@ -86,8 +86,8 @@ function buildInsightReport(insight: Insight): IReportInput | null {}/**- * Phase 5: the insight detail sheet — the full insight, its primary metric, a- * trend chart, and the on-demand AI "why" explanation. Opened via+ * The insight detail sheet — the full insight, its primary metric, a trend+ * chart, and the on-demand AI "why" explanation. Opened via* `pushModal('InsightDetails', { insight })`; the explanation is fetched once* on open.*/@@ -101,7 +101,6 @@ export default function InsightDetails({ insight }: { insight: Insight }) {}));- // Fetch the explanation once when the sheet opens.// biome-ignore lint/correctness/useExhaustiveDependencies: run once on mountuseEffect(() => {mutation.mutate({ insightId: insight.id });diff --git a/apps/start/src/modals/view-chart-users.tsx b/apps/start/src/modals/view-chart-users.tsxindex 4fc78b8cc..eb267070b 100644--- a/apps/start/src/modals/view-chart-users.tsx+++ b/apps/start/src/modals/view-chart-users.tsx@@ -69,7 +69,6 @@ const ProfileItem = ({ profile }: { profile: any }) => {</ProjectLink>);};-// Shared profile list componentfunction ProfileList({ profiles }: { profiles: any[] }) {const ITEM_HEIGHT = 74;const CONTAINER_PADDING = 20;@@ -77,7 +76,6 @@ function ProfileList({ profiles }: { profiles: any[] }) {const { scrollAreaRef } = useScrollableModal();const [isScrollReady, setIsScrollReady] = useState(false);- // Check if scroll container is readyuseEffect(() => {if (scrollAreaRef.current) {setIsScrollReady(true);@@ -95,7 +93,6 @@ function ProfileList({ profiles }: { profiles: any[] }) {paddingEnd: CONTAINER_PADDING,});- // Re-measure when scroll container becomes available or profiles changeuseEffect(() => {if (isScrollReady && scrollAreaRef.current) {// Small delay to ensure DOM is ready@@ -183,7 +180,6 @@ function ProfileListState({return <ProfileList profiles={query.data ?? []} />;}-// Chart-specific props and componentinterface ChartUsersViewProps {chartData: IChartData;report: IReportInput;@@ -204,7 +200,6 @@ function ChartUsersView({ chartData, report, date }: ChartUsersViewProps) {[report.series, selectedSerieId]);- // Get all chart series that match the selected report serieconst matchingChartSeries = useMemo(() => {if (!(selectedSerieId && chartData)) {return [];@@ -315,7 +310,6 @@ function ChartUsersView({ chartData, report, date }: ChartUsersViewProps) {);}-// Funnel-specific props and componentinterface FunnelUsersViewProps {report: IReportInput;stepIndex: number;@@ -416,7 +410,6 @@ function FunnelUsersView({);}-// Union type for propstype ViewChartUsersProps =| {type: 'chart';@@ -431,7 +424,6 @@ type ViewChartUsersProps =breakdownValues?: string[];};-// Main component that routes to the appropriate viewexport default function ViewChartUsers(props: ViewChartUsersProps) {if (props.type === 'funnel') {return (diff --git a/apps/start/src/utils/title.ts b/apps/start/src/utils/title.tsindex a282639ed..c05bac4a6 100644--- a/apps/start/src/utils/title.ts+++ b/apps/start/src/utils/title.ts@@ -1,12 +1,5 @@-/**- * Utility functions for generating page titles- */-const BASE_TITLE = 'OpenPanel.dev';-/**- * Creates a hierarchical title with the format: "Page Title | Section | OpenPanel.dev"- */export function createTitle(pageTitle: string,section?: string,@@ -20,9 +13,6 @@ export function createTitle(return parts.join(' | ');}-/**- * Creates a title for organization-level pages- */export function createOrganizationTitle(pageTitle: string,organizationName?: string@@ -33,9 +23,6 @@ export function createOrganizationTitle(return createTitle(pageTitle, 'Organization');}-/**- * Creates a title for project-level pages- */export function createProjectTitle(pageTitle: string,projectName?: string,@@ -52,9 +39,6 @@ export function createProjectTitle(return parts.join(' | ');}-/**- * Creates a title for specific entity pages (reports, sessions, etc.)- */export function createEntityTitle(entityName: string,entityType: string,@@ -72,9 +56,6 @@ export function createEntityTitle(return parts.join(' | ');}-/**- * Common page titles- */export const PAGE_TITLES = {// Main sectionsDASHBOARD: 'Dashboard',diff --git a/packages/core/scripts/get-bots.ts b/packages/core/scripts/get-bots.tsindex a36eeb4e8..82bd775dc 100644--- a/packages/core/scripts/get-bots.ts+++ b/packages/core/scripts/get-bots.ts@@ -51,16 +51,13 @@ function transformBots(bots: any[]): any[] {const hasRegexChars = regexSpecialChars.test(regex);if (hasRegexChars) {- // Keep as regexreturn { regex, ...rest };}- // Convert to includesreturn { includes: regex, ...rest };});}async function main() {- // Get document, or throw exception on errortry {const data = await fetch('https://raw.githubusercontent.com/matomo-org/device-detector/master/regexes/bots.yml'diff --git a/packages/core/src/buffers/base-buffer.ts b/packages/core/src/buffers/base-buffer.tsindex eec6508ca..c4d521604 100644--- a/packages/core/src/buffers/base-buffer.ts+++ b/packages/core/src/buffers/base-buffer.ts@@ -15,26 +15,18 @@ import type { ServiceDeps } from '../services';export interface BufferDeps {/*** Each buffer logs under its own name. Injected rather than built here so- * core instantiates no pino (ADR-007 layout) and a test hands in a silent- * stub instead of spawning one transport worker thread per buffer.+ * core instantiates no pino and a test hands in a silent stub instead of+ * spawning one transport worker thread per buffer.*/createLogger(name: string): Logger;/**- * The boot scope's ClickHouse client — the same round-robin/retry proxy every- * service reaches as `deps.ch`. M10-009: the buffers used to lazily- * `import('@openpanel/db/src/clickhouse/client')` for it, which constructed a- * second client (and a second pino transport) outside any scope. M15-004 made- * it required: the one caller that had none- * (`apps/api/e2e/legacy-job-proof.ts`, a BullMQ-keys-only proof that never- * flushes to ClickHouse) already passes the field, so the unscoped fallback- * behind it had no live path left.+ * The boot scope's ClickHouse client — the same round-robin/retry proxy+ * every service reaches as `deps.ch`.*/ch: ServiceDeps['ch'];/**- * Asked before every flush. ADR-005's `ProducerHandle.bullQueues` escape- * hatch, narrowed to the one thing the buffers ask BullMQ directly: pausing- * `cron` from bull-board halts ALL buffer flushing, preserved deliberately- * as an accepted trade-off.+ * Asked before every flush. Pausing `cron` from bull-board halts ALL+ * buffer flushing, preserved deliberately as an accepted trade-off.*/isCronPaused(): Promise<boolean>;/**@@ -327,8 +319,7 @@ export class BaseBuffer {* Ground-truth size of the buffer (LLEN of the Redis list). O(1). The* previous implementation kept a shadow counter to "avoid" LLEN — but* LLEN and GET are both O(1) single-roundtrip ops in Redis, so the- * counter was free complexity that silently drifted (see incident- * 2026-05-20). Always use this.+ * counter was free complexity that silently drifted. Always use this.*/async getBufferSize(): Promise<number> {return await getRedisCache().llen(this.getRedisListKey());diff --git a/packages/core/src/buffers/buffer.metrics.ts b/packages/core/src/buffers/buffer.metrics.tsindex cdfb16963..988a6a373 100644--- a/packages/core/src/buffers/buffer.metrics.ts+++ b/packages/core/src/buffers/buffer.metrics.ts@@ -1,8 +1,7 @@-// The twelve `buffer_*` series, moved verbatim from apps/worker/src/metrics.ts-// (TARGET_ARCHITECTURE §18: names and labels reproduced exactly). Registered-// per boot rather than per import, because the buffers themselves are per boot-// — and only where a role consumes queues, since the LLEN gauges cost one-// Redis round trip per buffer per scrape.+// The twelve `buffer_*` series (names and labels reproduced exactly).+// Registered per boot rather than per import, because the buffers themselves+// are per boot — and only where a role consumes queues, since the LLEN+// gauges cost one Redis round trip per buffer per scrape.import client from 'prom-client';import { registry } from '../metrics';@@ -24,8 +23,8 @@ const ADD_DURATION_BUCKETS_MS = [];/**- * Registration order is V1's, because it is the order the series appear in the- * `/metrics` body.+ * Registration order matches the order the series appear in the `/metrics`+ * body.*/function allBuffers(buffers: Buffers) {return [@@ -43,9 +42,6 @@ function allBuffers(buffers: Buffers) {* Registers the buffer metrics and installs the flush/add observers on the* given buffers. Call once per process: prom-client throws on a duplicate* series name, and each buffer holds exactly one observer slot.- *- * `register` defaults to the one core registry; V1's worker passes its own- * dying registry so its `/metrics` body is unchanged (M8-001 delegation).*/export function registerBufferMetrics(buffers: Buffers,diff --git a/packages/core/src/buffers/clickhouse-failover.test.ts b/packages/core/src/buffers/clickhouse-failover.test.tsindex ea74bc8e7..fb520f188 100644--- a/packages/core/src/buffers/clickhouse-failover.test.ts+++ b/packages/core/src/buffers/clickhouse-failover.test.ts@@ -1,22 +1,20 @@import { afterAll, describe, expect, it } from 'bun:test';-// The buffers take the boot scope's client as `BufferDeps.ch` now, so the-// `loadClickHouse` seam this file used to call through is gone. What it proves-// is unchanged — the round-robin/retry client the buffers are handed (`ch` /-// `chQuery`, `@openpanel/db`'s exports) must survive a dead node — so the-// subject is imported directly here. This is a test file, which-// `core-uses-ctx-not-db-internals` exempts.+// This is a test file, which the `core-uses-ctx-not-db-internals` lint rule+// exempts: the round-robin/retry client the buffers are handed (`ch` /+// `chQuery`, `@openpanel/db`'s exports) must survive a dead node, so the+// subject is imported directly here rather than through `BufferDeps.ch`.function loadClickHouse() {return import('@openpanel/db/src/clickhouse/client');}/**- * / M8-006: the deliberate ECONNREFUSED to a dead ClickHouse node must be- * caught and retried (sin-binning) on the client the buffers are handed as+ * The deliberate ECONNREFUSED to a dead ClickHouse node must be caught and+ * retried (sin-binning) on the client the buffers are handed as* `BufferDeps.ch`, exactly as packages/db's* `sql.round-robin.clickhouse.test.ts` proves for `chQuery`/`chQueryWithMeta`- * directly. That file is NOT touched here; this extends the same proof onto the- * path M8-001 moved: `ch.insert` reached via the core buffer seam.+ * directly. That file is NOT touched here; this extends the same proof onto+ * `ch.insert` reached via the core buffer seam.** Setup mirrors that file exactly: a two-node `CLICKHOUSE_URL` whose first node* (port 1, privileged and unbindable without root) is reliably refused. The@@ -67,14 +65,13 @@ async function deadNodeIsRefused(): Promise<boolean> {const clickhouseReachable = await bootstrapTestDatabase();const failoverIsReal = await deadNodeIsRefused();-// bare `bun test` (the configured verifier — AGENTS.md) shares one process-// and one `process.env` across every file in the run, unlike vitest's-// per-file env reset. Whichever file first calls `loadClickHouse()` pins-// `@openpanel/db/src/clickhouse/client`'s picker for the rest of the run-// regardless of env set here, but OTHER files that read `CLICKHOUSE_URL`-// directly (e.g. test fixtures building their own throwaway client) are not-// protected by that — an unrestored mutation here leaks into them. Snapshot-// and restore, exactly like `mock.module` must be (AGENTS.md).+// `bun test` shares one process and one `process.env` across every file in+// the run, unlike vitest's per-file env reset. Whichever file first calls+// `loadClickHouse()` pins `@openpanel/db/src/clickhouse/client`'s picker for+// the rest of the run regardless of env set here, but OTHER files that read+// `CLICKHOUSE_URL` directly (e.g. test fixtures building their own throwaway+// client) are not protected by that — an unrestored mutation here leaks into+// them. Snapshot and restore, exactly like `mock.module` must be.const originalClickhouseEnv = {CLICKHOUSE_URL: process.env.CLICKHOUSE_URL,CLICKHOUSE_REQUEST_TIMEOUT_MS: process.env.CLICKHOUSE_REQUEST_TIMEOUT_MS,diff --git a/packages/core/src/buffers/event-buffer.test.ts b/packages/core/src/buffers/event-buffer.test.tsindex 18d4b7670..193afc0b9 100644--- a/packages/core/src/buffers/event-buffer.test.ts+++ b/packages/core/src/buffers/event-buffer.test.ts@@ -58,7 +58,7 @@ beforeEach(async () => {// The shared `getRedisCache()` client is deliberately NOT quit here: bun runs// every file in one process, and closing the singleton takes it away from the-// files that run next (V1's vitest isolated per file, so it could).+// files that run next.afterAll(() => {mock.module('../ch-query', () => realChQuery);});@@ -335,10 +335,10 @@ describe('EventBuffer', () => {expect(await eventBuffer.getBufferSize()).toBe(5);});- // / drill 03: the shutdown path has to be able to SEE a failed rpush, because- // it decides whether to commit the Kafka offsets on the answer. `flush`- // deliberately swallows one (the micro-batch timer retries while the process- // lives); `flushPendingOrThrow` does not.+ // The shutdown path has to be able to see a failed rpush, because it+ // decides whether to commit the Kafka offsets on the answer. `flush`+ // deliberately swallows one (the micro-batch timer retries while the+ // process lives); `flushPendingOrThrow` does not.describe('flushPendingOrThrow', () => {// A failed flush re-queues its events AND arms the micro-batch timer, so// without this the retry lands in whichever test runs next.@@ -428,15 +428,15 @@ describe('EventBuffer', () => {});});- // / drill 03 re-run: the gate has to answer "are my events in Redis?", not- // "did I start the write?". Answering the second question made 221 durability- // failures in 5.5 minutes on a HEALTHY stack and turned 16.9% of accepted- // events into duplicates, because a caller that lost the race to start a- // write was told its already-durable events were not durable.+ // The gate has to answer "are my events in Redis?", not "did I start the+ // write?". Answering the second question caused real durability failures+ // on a healthy stack and turned accepted events into duplicates, because a+ // caller that lost the race to start a write was told its already-durable+ // events were not durable.describe('flushPendingOrThrow under concurrency', () => {- // 24 partitions is what drill 03 ran; the callers are its `eachBatch`- // handlers, and the background producer stands in for the HTTP path and- // the session-end job adding events underneath them.+ // 24 mirrors the number of Kafka partitions; the callers stand in for its+ // `eachBatch` handlers, and the background producer stands in for the+ // HTTP path and the session-end job adding events underneath them.const CONCURRENT_CALLERS = 24;const ROUNDS_PER_CALLER = 25;const EVENTS_PER_ROUND = 5;@@ -539,10 +539,10 @@ describe('EventBuffer', () => {});});- // / drill 02 re-run: a failed flush leaves the batch's Kafka offsets- // unresolved and the fail-fast cache client brings the redelivery back in- // ~90ms. Re-queueing the failed events then holds one copy per lap — 4,759- // ClickHouse rows for 230 events, measured.+ // A failed flush leaves the batch's Kafka offsets unresolved and the+ // fail-fast cache client brings the redelivery back quickly. Re-queueing+ // the failed events then holds one copy per lap — a single outage can turn+ // a handful of events into thousands of duplicate ClickHouse rows.describe('events a redelivery will produce again', () => {const REDELIVERY_LAPS = 5;diff --git a/packages/core/src/buffers/event-buffer.ts b/packages/core/src/buffers/event-buffer.tsindex 131690e5f..2aae5b27e 100644--- a/packages/core/src/buffers/event-buffer.ts+++ b/packages/core/src/buffers/event-buffer.ts@@ -80,7 +80,7 @@ export class EventBuffer extends BaseBuffer {* `lastDurableSeq` reaches the sequence of its last event — whoever wrote* them. That is the question the Kafka batch handler and shutdown need* answered ("are my events in Redis?"), and it is not the same question as- * "did I start the write?" (drill 03 re-run).+ * "did I start the write?".*/private lastQueuedSeq = 0;private lastDurableSeq = 0;@@ -186,8 +186,7 @@ export class EventBuffer extends BaseBuffer {* next attempt: the Kafka batch handler is about to resolve offsets that* kafkajs commits as soon as it returns, and shutdown is about to exit. Both* must be able to SEE the failure and decline to commit — a redelivered- * duplicate is recoverable, a dropped `pendingEvents` array is not (drill- * 03).+ * duplicate is recoverable, a dropped `pendingEvents` array is not.*/public async flushPendingOrThrow(sinceSeq: number = this.droppedThroughSeq@@ -240,8 +239,8 @@ export class EventBuffer extends BaseBuffer {* Such an event is not re-queued by a failed write. Re-queueing it was right* while the buffer owned the retry, and became harmful the moment Kafka took* that ownership over: the redelivery buffers a fresh copy, so the old one is- * a SECOND copy of one event, and every further redelivery adds another.- * Drill 02's re-run measured 4,759 ClickHouse rows for 230 events that way.+ * a SECOND copy of one event, and every further redelivery adds another+ * (a real run once saw 4,759 ClickHouse rows for 230 events this way).** Producers Kafka does not redeliver — the session-end job, whose Redis `SET* NX` claim makes a job retry a no-op — keep the safety net by using plain@@ -427,21 +426,11 @@ export class EventBuffer extends BaseBuffer {return;}- // We don't need to JSON.parse the events at all — they're already- // valid JSONEachRow lines (one stringified event per Redis entry).- // The client's custom `json.stringify` (set in CLICKHOUSE_OPTIONS)- // passes strings through unchanged, so the bytes go straight from- // Redis → CH HTTP body. This skips:- // - JSON.parse × N (50–300ms for N=100k)- // - The @clickhouse/client's internal JSON.stringify × N (same)- // - All the intermediate object allocations (saves ~200MB heap)- //- // We still need `project_id` per row for the per-project pub/sub.- // extractProjectId() does an indexOf-based fast path that's ~50×- // faster than JSON.parse, and falls back to a real parse on the- // rare line where `project_id` appears more than once (e.g. a- // user-supplied `properties.project_id`) — so the count is always- // attributed to the top-level field, never a nested one.+ // The queued lines are already valid JSONEachRow (one stringified event+ // per Redis entry), and the client's custom `json.stringify`+ // (CLICKHOUSE_OPTIONS) passes strings through unchanged — so skipping+ // JSON.parse here sends the bytes straight from Redis to the CH HTTP+ // body, with no parse, no re-stringify and no intermediate allocations.const countByProject = new Map<string, number>();const yieldEvery = this.getYieldInterval(queueEvents.length, {min: 1000,diff --git a/packages/core/src/buffers/profile-buffer.ts b/packages/core/src/buffers/profile-buffer.tsindex 421e00372..26a2fc46c 100644--- a/packages/core/src/buffers/profile-buffer.ts+++ b/packages/core/src/buffers/profile-buffer.ts@@ -295,7 +295,6 @@ export class ProfileBuffer extends BaseBuffer {const uniqueProfiles = Array.from(mergedInBatch.values());- // Check Redis cache for all unique profiles in a single MGETconst cacheKeys = uniqueProfiles.map((p) =>this.getProfileCacheKey({ profileId: p.id, projectId: p.project_id }));diff --git a/packages/core/src/buffers/session-buffer.test.ts b/packages/core/src/buffers/session-buffer.test.tsindex f3c52cded..216299ef8 100644--- a/packages/core/src/buffers/session-buffer.test.ts+++ b/packages/core/src/buffers/session-buffer.test.ts@@ -75,8 +75,7 @@ beforeEach(async () => {// No `afterAll` on purpose: the shared `getRedisCache()` client must NOT be// quit, because bun runs every file in one process and closing the singleton-// takes it away from the files that run next (V1's vitest isolated per file,-// so it could).+// takes it away from the files that run next.describe('SessionBuffer', () => {let sessionBuffer: SessionBuffer;diff --git a/packages/core/src/buffers/session-buffer.ts b/packages/core/src/buffers/session-buffer.tsindex ad20c616a..20e14ada5 100644--- a/packages/core/src/buffers/session-buffer.ts+++ b/packages/core/src/buffers/session-buffer.ts@@ -174,17 +174,10 @@ export class SessionBuffer extends BaseBuffer {}/**- * Ingest one event into the session lifecycle.- *- * Reads the device's current session (if any), decides whether the event- * extends it, opens a brand-new one, or boundaries (gap > 30min) → close- * the old session and start a fresh one. Writes the updated session blob,- * updates the wall-clock index, and queues CollapsingMergeTree rows for- * ClickHouse.- *- * Returns the action taken so the caller can drive session_start /- * session_end event emission. `session_start` / `session_end` events- * themselves are skipped — they are derived signals, not session activity.+ * Ingest one event into the session lifecycle. Returns the action taken so+ * the caller can drive session_start / session_end event emission —+ * `session_start` / `session_end` events themselves are skipped here, since+ * they are derived signals, not session activity.*/async ingest(payload: IServiceCreateEventPayloaddiff --git a/packages/core/src/cacheable-per-deps.ts b/packages/core/src/cacheable-per-deps.tsindex f3bb8e0a8..56821f873 100644--- a/packages/core/src/cacheable-per-deps.ts+++ b/packages/core/src/cacheable-per-deps.ts@@ -87,9 +87,9 @@ export type CacheablePerDb<A extends unknown[], R> = ((* `cacheablePerDeps` for a cache that must be PROCESS-lived, not scope-lived.** The three ingest-path caches (`getClientByIdCached`, `getProjectByIdCached`,- * `getSalts`) used to live inside a factory that was only ever built once, in- * the deleted V1 compat seam. Keying them on the scope like `cacheablePerDeps`- * does would hand every request a fresh, empty L1 LRU and split `.clear()`+ * `getSalts`) used to live inside a factory that was only ever built once.+ * Keying them on the scope like `cacheablePerDeps` does would hand every+ * request a fresh, empty L1 LRU and split `.clear()`* across as many instances as there are requests. Keying on `deps.db` — one* Postgres client per process — keeps one instance to read and one to* invalidate under any scope.diff --git a/packages/core/src/ch-query.ts b/packages/core/src/ch-query.tsindex 198d44198..293875bc8 100644--- a/packages/core/src/ch-query.ts+++ b/packages/core/src/ch-query.ts@@ -1,24 +1,18 @@// Core's ClickHouse read path, bound to the scope's client.//-// The six modules on the runtime path used to reach ClickHouse through `await-// import('@openpanel/db/src/clickhouse/client')` and call that package's-// `chQuery`. That client has no request scope, so the requestId minted at the-// edge stopped there. These two functions are `chQuery` / `chQueryWithMeta`-// over `deps.ch` — the same round-robin/retry proxy `main.ts` builds and hands-// to every scope — and `deps.logger`, so the `query info` line carries the-// request's id.+// `chQuery` / `chQueryWithMeta` wrap `deps.ch` — the same round-robin/retry+// proxy `main.ts` builds and hands to every scope — and log through+// `deps.logger`, so the `query info` line carries the request's id.//-// Behaviour is @openpanel/db's, unchanged: `deps.ch.query` IS `withRetry-// (client => client.query(...))`, the same transport, and the Int-meta coercion-// below is the same one — ClickHouse's JSON format returns every Int*/UInt*-// column as a string, so a caller's `count: number` only holds if it is parsed-// back out here. The one field that cannot survive the move is `host`: the-// retry proxy does not report which replica served the query.-// chart/src/run-query.ts made the same trade.+// `deps.ch.query` IS `withRetry(client => client.query(...))`. The Int-meta+// coercion below exists because ClickHouse's JSON format returns every+// Int*/UInt* column as a string, so a caller's `count: number` only holds if+// it is parsed back out here. The one field that cannot survive the retry+// proxy is `host`: it does not report which replica served the query.+// chart/src/run-query.ts makes the same trade.//-// `@openpanel/db/src/clickhouse/sql` is a value import and stays one: ADR-013-// puts the `sql` tag in packages/db by name, and it is a compile-time template-// tag with no client and no request scope.+// `@openpanel/db/src/clickhouse/sql` is a value import and stays one: it is a+// compile-time template tag with no client and no request scope.import type { ClickHouseSettings, ResponseJSON } from '@clickhouse/client';import {@@ -31,7 +25,7 @@ import type { ServiceDeps } from './services';* buffers, whose `BufferDeps` is not a `ServiceDeps`, can call them too. */export type ChScope = Pick<ServiceDeps, 'ch' | 'logger'>;-/** A raw statement or an ADR-013 fragment carrying its own bound params. */+/** A raw statement or a SqlFragment carrying its own bound params. */export type ChQueryInput = string | SqlFragment;const NEWLINES = /\n/g;diff --git a/packages/core/src/clients/create-clients.ts b/packages/core/src/clients/create-clients.tsindex 77a6ea494..6dfde7884 100644--- a/packages/core/src/clients/create-clients.ts+++ b/packages/core/src/clients/create-clients.ts@@ -1,18 +1,13 @@-// The `clients` handle on `AppDeps` (TARGET_ARCHITECTURE §7: "AppDeps is built-// ONCE in main.ts (db, ch, redis, clients, buffers, producers, base logger,-// config flags)"), built at M9-004 when main.ts became the only entrypoint.+// The `clients` handle on `AppDeps`: a NAMING of what already exists under+// `src/clients/`, not a new abstraction — every member below is the exact+// function this package already exports, gathered so a service can reach an+// outbound client through its scoped `Ctx` instead of importing the module+// directly. Nothing is constructed here — the geo readers open their mmdb+// lazily and the email / Discord transports read their own credentials — so+// building it costs one object literal per process.//-// It is a NAMING of what already exists under `src/clients/`, not a new-// abstraction: every member below is the exact function this package already-// exports, gathered so a service can reach an outbound client through its-// scoped `Ctx` instead of importing the module directly. Nothing is constructed-// here — the geo readers open their mmdb lazily and the email / Discord-// transports read their own credentials — so building it costs one object-// literal per process.-//-// Removed the `slack` and `ai` members: those transports moved into the single-// module that calls each (ADR-022 A2), and a client handle cannot reach up into-// a module. Nothing read either member.+// No `slack` or `ai` member here: a client handle cannot reach up into a+// module, and those transports live in the single module that calls each.import { sendEmail } from './email';import { getAsnInfo, getGeoLocation } from './geo';diff --git a/packages/core/src/clients/email.ts b/packages/core/src/clients/email.tsindex 0d0c51058..dba64c0a3 100644--- a/packages/core/src/clients/email.ts+++ b/packages/core/src/clients/email.ts@@ -1,15 +1,14 @@// @openpanel/email stays its own package — the react-email JSX toolchain-// doesn't belong in core (TARGET_ARCHITECTURE §7: "email (react-email JSX stays-// out of core; core wraps it as clients/email)").+// doesn't belong in core; core wraps it as clients/email.//// Loaded lazily, deliberately: @openpanel/email depends on @openpanel/db (to-// check email-unsubscribe rows before sending), and @openpanel/db still depends-// on @openpanel/core for shared crypto/logging utilities that haven't moved yet-// (mid-P4 state). A static top-level import here would make core's own barrel-// eagerly load @openpanel/db while core is still mid-evaluation — the cycle-// resolves core's own exports as undefined partway through. Deferring the-// import to call time sidesteps it: by the time anything actually sends an-// email, core has finished loading.+// check email-unsubscribe rows before sending), and @openpanel/db still+// depends on @openpanel/core for shared crypto/logging utilities that+// haven't moved yet. A static top-level import here would make core's own+// barrel eagerly load @openpanel/db while core is still mid-evaluation — the+// cycle resolves core's own exports as undefined partway through. Deferring+// the import to call time sidesteps it: by the time anything actually sends+// an email, core has finished loading.//// No `ProviderError`: `@openpanel/email` swallows every Resend and SMTP failure// itself and returns `null`, so nothing reaches this wrapper to classify.diff --git a/packages/core/src/clients/geo.ts b/packages/core/src/clients/geo.tsindex 7394dac9f..383e12dbe 100644--- a/packages/core/src/clients/geo.ts+++ b/packages/core/src/clients/geo.ts@@ -1,8 +1,6 @@-// Ported from @openpanel/geo (dissolved into core — M4-004).-//// The one client with no `ProviderError`: there is no third party on the other// end. Both lookups read a bundled MaxMind `.mmdb`, so an IP the database does-// not carry is a missing thing and comes back as the default value (R9), and a+// not carry is a missing thing and comes back as the default value, and a// database that will not load fails identically on every retry.// `ingest.service.ts` therefore has no failure to classify — it reads a value,// never a throw.@@ -20,12 +18,12 @@ const __dirname = dirname(__filename);// Resolve a bundled `.mmdb` file, trying the bundled-dist layout first and the// local package layout second (mirrors how the file ships via `pnpm codegen`).-// apps/api's V1 build still bundles every `@openpanel/*` package into one file+// apps/api's build still bundles every `@openpanel/*` package into one file// (tsdown `noExternal`), so `import.meta.url` there resolves to// `apps/api/dist/index.js` regardless of this file's nesting under// `src/clients/` — three levels up from dist is the repo root.async function loadDatabase(filename: string): Promise<ReaderModel | null> {- // From api or worker dist bundle+ // From the api dist bundleconst dbPath = path.join(__dirname, `../../../packages/core/${filename}`);// From local package (e.g. running core's own tests, unbundled)const dbPathLocal = path.join(__dirname, `../../${filename}`);diff --git a/packages/core/src/clients/integrations/fetcher.ts b/packages/core/src/clients/integrations/fetcher.tsindex c5977af34..276543bd1 100644--- a/packages/core/src/clients/integrations/fetcher.ts+++ b/packages/core/src/clients/integrations/fetcher.ts@@ -1,4 +1,3 @@-// Ported from @openpanel/integrations (dissolved into core — M4-005)./*** Webhook delivery is reachable from two very different places:*@@ -31,7 +30,7 @@ export interface WebhookResult {ok: boolean;status: number;/**- * R19, classified once here so no caller re-derives it: 429 and 5xx are worth+ * Classified once here so no caller re-derives it: 429 and 5xx are worth* another delivery attempt, every other 4xx is the destination refusing this* exact request. A transport failure that produced no response (DNS, connect,* TLS, timeout) is retryable — nothing about the request was rejected.diff --git a/packages/core/src/clients/provider-error.ts b/packages/core/src/clients/provider-error.tsindex fb609406b..526893960 100644--- a/packages/core/src/clients/provider-error.ts+++ b/packages/core/src/clients/provider-error.ts@@ -1,4 +1,4 @@-// / A4: the one failure type every outbound client raises.+// The one failure type every outbound client raises.//// A client classifies ONCE, at the edge where it still holds the provider's own// status code; a handler then reads `retryable` instead of re-deriving it from@@ -111,9 +111,9 @@ export function providerErrorFrom(}/**- * Run one outbound call and classify whatever it throws. This is the "classify- * once" of R19: every `catch` upstream of it can read `retryable` instead of- * inspecting an SDK-specific error shape.+ * Run one outbound call and classify whatever it throws. Every `catch`+ * upstream of it can then read `retryable` instead of inspecting an+ * SDK-specific error shape.*/export async function callProvider<T>(provider: string,diff --git a/packages/core/src/config.ts b/packages/core/src/config.tsindex d381aa22a..b5d15a9a2 100644--- a/packages/core/src/config.ts+++ b/packages/core/src/config.ts@@ -1,8 +1,8 @@-// The shape of everything core needs from the environment (ADR-022 R7: only the-// config loader reads `process.env`). `apps/api/src/config/env.ts` is that-// loader; it parses, validates and derives, and hands the result down as-// `AppDeps.config` / `Ctx.config`, so nothing below this file re-derives a-// value or reaches for `process.env` again.+// The shape of everything core needs from the environment; only the config+// loader (`apps/api/src/config/env.ts`) reads `process.env` — it parses,+// validates and derives, and hands the result down as `AppDeps.config` /+// `Ctx.config`, so nothing below this file re-derives a value or reaches for+// `process.env` again.//// Two conventions hold throughout: - `undefined` means "not set", never// "blank". A blank `KEY=` is absent. - a field that only ever had one spellingdiff --git a/packages/core/src/context.ts b/packages/core/src/context.tsindex 56d8d3fab..8d291e3d3 100644--- a/packages/core/src/context.ts+++ b/packages/core/src/context.ts@@ -1,8 +1,7 @@// One boot scope, one work scope, one builder. HTTP routes, tRPC procedures,// job handlers and the Kafka consumer all extend the same `Ctx`, so a service-// written once works under every transport and the requestId minted at the edge-// reaches the query, the enqueue and the job that enqueue causes (ADR-007-// decision 18).+// written once works under every transport and the requestId minted at the+// edge reaches the query, the enqueue and the job that enqueue causes.import type { Buffers } from './buffers/create-buffers';import { bindReadsToSignal } from './ch-abortable';@@ -13,11 +12,10 @@ import type { SessionValidationResult } from './modules/auth/src/login-session';import { createServices, type Services } from './services';import type { CookieJar, CookieOptions } from './shared/cookie';-// The four boot handles, landed at M9-004 when main.ts became the only-// entrypoint and had to build a real `AppDeps` for the mounted route surfaces.-// Each is a TYPE QUERY over the module that constructs the client, so the alias-// cannot drift from what `main.ts` actually passes; all four are type-only, so-// core still imports no database at runtime and `bun test` still runs offline.+// The four boot handles. Each is a TYPE QUERY over the module that+// constructs the client, so the alias cannot drift from what `main.ts`+// actually passes; all four are type-only, so core still imports no database+// at runtime and `bun test` still runs offline.export type Db = typeof import('@openpanel/db/src/prisma-client').db;export type ClickHouseClient =typeof import('@openpanel/db/src/clickhouse/client').ch;@@ -42,9 +40,8 @@ export type PrismaNamespace =* Prisma's JSON sentinels (`DbNull`, `JsonNull`): frozen constants that write* an explicit SQL NULL — or a JSON `null` — onto a nullable `Json?` column.* They are values on the namespace, not a client, so nothing about them is- * per-request — but they are still `@openpanel/db` VALUES, and the four modules- * that write a `Json?` column each reached them through a lazy `load*` back- * into this file. ADR-022 R6 has one answer for that: the scope carries it.+ * per-request — but they are still `@openpanel/db` VALUES, so the scope+ * carries them rather than each writer reaching the namespace directly:* `main.ts` reads the two off the namespace once and puts them on `AppDeps`;* every writer reads `deps.prisma.DbNull`. Two named fields, not the namespace* itself — nothing else on it belongs in a request scope, and `Prisma` is a@@ -59,18 +56,15 @@ export interface PrismaSentinels {* The process's Postgres client, for the one path that cannot be handed a* scope: `shared/access-lookups.ts`. Its lookups are `cacheable` on their* ARGUMENTS, so they cannot take a leading `deps`, and their bare signature is- * pinned by the protected wire contract- * `verification/contracts/auth/group-b-project-access.mts`, which imports them- * through `packages/db/src/services/access.service.ts` with no app boot at- * all. It is the same client `main.ts` puts on `AppDeps.db`. Every other- * caller in core reaches Postgres as `deps.db`.+ * pinned by imports through `packages/db/src/services/access.service.ts` with+ * no app boot at all. It is the same client `main.ts` puts on `AppDeps.db`.+ * Every other caller in core reaches Postgres as `deps.db`.*/export function unscopedDb(): Promise<Db> {return import('@openpanel/db/src/prisma-client').then((m) => m.db);}-// Landed at M8-001: built once by `createBuffers(deps)` in main.ts, never a-// module singleton.+// Built once by `createBuffers(deps)` in main.ts, never a module singleton.export type { Buffers } from './buffers/create-buffers';// The resolved session. `SessionValidationResult` is Prisma-shaped (Session +@@ -83,8 +77,8 @@ export type { Buffers } from './buffers/create-buffers';export type Session = SessionValidationResult;// The parsed environment. `apps/api`'s config/env.ts is the sole reader of-// process.env and core reads none (made true at M15-006), so the shape of what-// core needs is declared in `./config.ts` and arrives here.+// process.env and core reads none, so the shape of what core needs is+// declared in `./config.ts` and arrives here.export type { CoreConfig } from './config';/** Boot scope. Built once in apps/api's main.ts, closed once in shutdown. */diff --git a/packages/core/src/http/auth.ts b/packages/core/src/http/auth.tsindex 1bb21dd6a..96ae1eba0 100644--- a/packages/core/src/http/auth.ts+++ b/packages/core/src/http/auth.ts@@ -1,41 +1,12 @@-// Caller authentication, declared once and requested per route (ADR-011 A-i).+// Caller authentication, declared once and requested per route. A macro+// authenticates the CALLER and stops — a missing authorization check is+// silent: a broken chart throws, a dropped access check returns 200 with+// somebody else's data.//-// A macro authenticates the CALLER and stops. Everything below it is preserved-// verbatim by whichever wave ports the router, and is listed here because a-// missing authorization check is silent: a broken chart throws, a dropped-// access check returns 200 with somebody else's data.-//-// A-iii invariants, binding: 1. Macros authenticate the caller only. A route or-// procedure holding a-// reportId/dashboardId/cohortId/importId/referenceId/ruleId/insightId/-// integrationId/conversationId/clientId does its own check in the handler.-// Porting a router NEVER deletes an in-handler check. 2. `enforceAccess`-// triggers on the RAW pre-zod input, top-level keys only, so `{projectId:-// null}` still reaches the project lookup and fails closed. 3. `needsWrite =-// mutation && !meta.readOnlyMutation`; the opt-out stays on exactly-// `conversation.rename` and `overview.runFilterCommand`. 4. The organizationId-// check is membership only, never admin. The 12 `org:admin` gates stay-// hand-written. 5. `getProjectAccess`: zero ProjectAccess rows in the org =>-// write; one row anywhere in the org => every unlisted project is null; all-// exceptions swallowed => null (fail-closed). 6. `canWriteProject` = level in-// {write, admin}; admin stays a superset. 7. 5-minute Redis cache + 60s-// in-process LRU on both access lookups; removeMember/updateMemberAccess do not-// clear them. Sessions survive revocation, which is accepted. 8.-// The nine cross-object binding checks in DISC-011 §4.4. 9. chartProcedure's-// share branch overwrites the caller's projectId with the report's — explicit-// in the builder, not an accident of spread order. 10.-// `/live/visitors/:projectId` stays unauthenticated; the other three /live-// routes keep session + access, and all four keep reject-after-upgrade. 11.-// Invites stay bearer tokens: no invite.email vs user.email comparison. 12.-// `resolveClientProjectId` is the single client->project resolution point. 13.-// Public-API routes never see a session cookie, however the scopes compose.-//-// Elysia 1.4.30 carries the option-bearing macro shape, so ADR-011's-// `requireClient(ctx, opts)` fallback is NOT taken: `clientAuth: { allow: [...]-// }` types the resolved client onto the handler, and a route that does not-// request the macro has no `client` binding at all — "did this route-// authenticate?" is a type question. Verified by http/auth.test.ts and by `tsc-// --noEmit`.+// Elysia's option-bearing macro shape makes `clientAuth: { allow: [...] }`+// type the resolved client onto the handler, so a route that skips the+// macro has no `client` binding at all — "did this route authenticate?" is+// a type question, verified by http/auth.test.ts and `tsc --noEmit`.import { Elysia } from 'elysia';import type { AppDeps } from '../context';@@ -44,8 +15,8 @@ import { authenticateClient, type ClientAuthOptions } from './client-auth';import { requestContext } from './context';const UNAUTHORIZED = 401;-/** V1's allow-list routers answered a 401 with this JSON envelope; its ingest- * routers answered with the refusal message as plain text. Both port. */+/** Allow-list routes answer a 401 with a JSON envelope; ingest routes answer+ * with the refusal message as plain text — both forms are intentional. */const UNAUTHORIZED_ERROR = 'Unauthorized';/**diff --git a/packages/core/src/http/bull-board.ts b/packages/core/src/http/bull-board.tsindex 433788c9c..9e24a23c0 100644--- a/packages/core/src/http/bull-board.ts+++ b/packages/core/src/http/bull-board.ts@@ -1,17 +1,14 @@-// Bull-board, on the main port, behind the dashboard session guard (ADR-005-// recommendation 6). What dies with it is `@bull-board/express` and the-// worker's second express server — nothing named `@bull-board/fastify` ever-// existed. `@bull-board/api` + `@bull-board/elysia` are both pinned exact 9.6.0-// (ADR-017 register row 4 grants the bump+swap at P9).+// Bull-board is mounted on the main port, behind the dashboard session+// guard. This avoids `@bull-board/express` and a second express server —+// nothing named `@bull-board/fastify` ever existed. `@bull-board/api` ++// `@bull-board/elysia` are both pinned exact at 9.6.0.//// TWO things a reader must not mistake for accidents://-// 1. **The base path moved.** V1 served bull-board at `/` on the worker's own-// express server (apps/worker/src/index.ts, `setBasePath('/')`). V2 has one-// port for everything, so `/` would shadow every other route. It is-// `/bullboard`; that is a deploy-note, written up in-// `packages/core/docs/OPS_GRAFANA_MIGRATION.md`. 2. **Pausing `cron` from this-// UI halts ALL buffer flushing.** Preserved deliberately.+// 1. **The base path is `/bullboard`, not `/`.** One port serves everything+// here, so `/` would shadow every other route; the deploy-note is+// `packages/core/docs/OPS_GRAFANA_MIGRATION.md`. 2. **Pausing `cron` from+// this UI halts ALL buffer flushing.** Preserved deliberately.import type { Queue as BullQueue } from 'bullmq';import { Elysia } from 'elysia';diff --git a/packages/core/src/http/client-auth.ts b/packages/core/src/http/client-auth.tsindex 32730c25d..250882690 100644--- a/packages/core/src/http/client-auth.ts+++ b/packages/core/src/http/client-auth.ts@@ -1,37 +1,28 @@// Where API/SDK credentials become a client principal.//-// V1 has five near-identical validators — `validateSdkRequest`,-// `validateExportRequest`, `validateImportRequest`, `validateManageRequest` and-// the MCP copy — that differ only by the accepted `ClientType` set and by the-// ingest extension. They collapse into this one function (ADR-011 A-i).+// The ingest tier's rules live in `modules/ingest/src/client-auth.ts`; since+// transport may not deep-import a module, the route that wants the ingest+// tier hands its own validator down as `clientAuth: { ingest:+// validateIngestRequest }`.//-// Filled in the INGEST branch — `modules/ingest/src/client-auth.ts` holds V1's-// `validateSdkRequest` verbatim, and this file adapts it onto the principal.-// M15-009 inverted how it gets there: transport may not deep-import a module,-// so the route that wants the ingest tier hands its own validator down as-// `clientAuth: { ingest: validateIngestRequest }`.-//-// Filled in the `allow`-list tier, which is the one V1 spells three times-// (`validateExportRequest`, `validateImportRequest`, `validateManageRequest`):-// identical bodies differing only by the accepted `ClientType` set and by the-// prefix on their error strings. `allow` carries that difference and the three-// collapse into `authenticateAllowedClient` below. MCP is NOT here — it-// authenticates its own `token` form inside `modules/mcp/src/auth.ts`, exactly-// as V1's mcp router did.+// The `allow`-list tier covers export, import and manage clients: identical+// checks differing only by the accepted `ClientType` set and by the prefix on+// their error strings, collapsed into `authenticateAllowedClient` below. MCP+// is NOT here — it authenticates its own `token` form inside+// `modules/mcp/src/auth.ts`.import type { DbScope } from '../cacheable-per-deps';import type { HttpCtx } from '../context';import { verifyClientSecret } from '../shared/client-secret';import { headerValue, type IngestHeaders } from '../shared/headers';-/** V1 refuses a client id that is not a UUID before it ever queries- * (utils/auth.ts's three validators). Same regex, same order. */+/** Refuses a client id that is not a UUID before it ever queries. */const CLIENT_ID_UUID_REGEX =/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;const CLIENT_ID_HEADER = 'openpanel-client-id';const CLIENT_SECRET_HEADER = 'openpanel-client-secret';-/** Prisma's `ClientType` enum, by value. Moves to client.constants.ts in P7. */+/** Prisma's `ClientType` enum, by value. */export type ClientType = 'read' | 'write' | 'root';export interface AuthenticatedClient {@@ -44,17 +35,15 @@ export interface AuthenticatedClient {/*** Whether the supplied client secret VERIFIED against the stored hash.* `isBotHook` reads it as "this is a server-side SDK, never a bot", so it- * follows the verification result, not the presence of a secret string (main- * #481). The side-channel survives as a field on the principal (ADR-011 A-i).+ * follows the verification result, not the presence of a secret string.*/secretVerified: boolean;}/**- * The surface's name in a refusal message. V1's three validators are the same- * function with a different prefix — `Export: Invalid client secret` — and- * those strings are the 401 BODY on `/export`, `/insights`, `/import` and- * `/manage`, so they are a wire contract, not decoration.+ * The surface's name in a refusal message — e.g. `Export: Invalid client+ * secret`. These strings are the 401 BODY on `/export`, `/insights`,+ * `/import` and `/manage`, so they are a wire contract, not decoration.*/export type ClientAuthLabel = 'Export' | 'Import' | 'Manage';@@ -85,9 +74,9 @@ export type ValidateIngestRequest = (args: {}) => Promise<IngestTierOutcome>;export interface ClientAuthOptions {- /** Which client types may pass. Omitted means any, as `validateSdkRequest`. */+ /** Which client types may pass. Omitted means any. */allow?: ClientType[];- /** Which of V1's three validators this route was served by. */+ /** Which allow-list surface this route is. */label?: ClientAuthLabel;/** The ingest extension described above, supplied by the ingest module. */ingest?: ValidateIngestRequest;@@ -97,15 +86,15 @@ export interface ClientAuthOptions {/*** A refusal is returned, never thrown — same reason- * `modules/ingest/src/client-auth.ts` gives, and it keeps the two 401 BODIES- * V1 has (plain text on the ingest routes, `{error, message}` JSON on the- * allow-list ones) a decision of the macro rather than of this function.+ * `modules/ingest/src/client-auth.ts` gives, and it keeps the choice of 401+ * body shape (plain text on the ingest routes, `{error, message}` JSON on+ * the allow-list ones) a decision of the macro rather than of this function.*/export type ClientAuthResult =| { ok: true; client: AuthenticatedClient }| { ok: false; ingest: boolean; message: string };-/** What the ingest tier needs beyond the headers: V1 reads the attribution ip+/** What the ingest tier needs beyond the headers: the attribution ip* and the body (credential fallback, profile filter, `__revenue` gate). */export interface ClientAuthRequest {ip: string;@@ -153,7 +142,7 @@ export async function authenticateClient(};}-/** V1's per-validator "wrong type" message; every other refusal differs only+/** The per-surface "wrong type" message; every other refusal differs only* by the label prefix. */const FORBIDDEN_TYPE_MESSAGE: Record<ClientAuthLabel, string> = {Export: 'Export: Client is not allowed to export',@@ -161,15 +150,15 @@ const FORBIDDEN_TYPE_MESSAGE: Record<ClientAuthLabel, string> = {Manage: 'Manage: Only root clients are allowed to manage resources',};-/** V1 mapped a Prisma lookup failure onto its own message, unprefixed. */+/** A Prisma lookup failure maps onto its own message, unprefixed. */const MALFORMED_CLIENT_ID_MESSAGE = 'Client ID seems to be malformed';const PRISMA_KNOWN_REQUEST_ERROR = 'PrismaClientKnownRequestError';const UNEXPECTED_MESSAGE = 'Unexpected error';/**- * The `allow`-list tier: V1's `validateExportRequest` / `validateImportRequest`- * / `validateManageRequest`, which differ only by the accepted `ClientType`- * set and by the label their messages carry.+ * The `allow`-list tier: covers export, import and manage clients, which+ * differ only by the accepted `ClientType` set and by the label their+ * messages carry.** `secretVerified` is true on success by construction: this tier verifies the* secret, so reaching the return means one was presented and matched.diff --git a/packages/core/src/http/context.test.ts b/packages/core/src/http/context.test.tsindex fc73511db..cc80da477 100644--- a/packages/core/src/http/context.test.ts+++ b/packages/core/src/http/context.test.ts@@ -55,8 +55,8 @@ beforeEach(() => {// its way out, which is the point of logging there.const settled = () => new Promise((resolve) => setTimeout(resolve, 0));-// The claim ADR-002 and ADR-007 both rest on: thirty modules may each start-// from `.use(requestContext(deps))` and one request still builds one Ctx.+// One request builds exactly one Ctx no matter how many modules each start+// from `.use(requestContext(deps))`.test('derives one ctx per request however many modules use the plugin', async () => {const { deps, scopeCalls, childCalls } = stubAppDeps();const seen: HttpCtx[] = [];diff --git a/packages/core/src/http/context.ts b/packages/core/src/http/context.tsindex f124bafce..d7404ca4a 100644--- a/packages/core/src/http/context.ts+++ b/packages/core/src/http/context.ts@@ -21,7 +21,6 @@ import type { CookieJar, CookieOptions } from '../shared/cookie';import { clientIpHook, requestIdHook, timestampHook } from './hooks';import { resolveSession } from './session';-/** Ported from V1's requestLoggingHook (apps/api/src/hooks/request-logging.hook.ts). */const UNLOGGED_PATH_PREFIXES = ['/healthcheck','/healthz',@@ -29,7 +28,7 @@ const UNLOGGED_PATH_PREFIXES = ['/misc',];const UNLOGGED_METHODS = ['OPTIONS'];-/** A write keeps running to completion without its client, as it always did. */+/** A write keeps running to completion without its client. */const CANCELLABLE_METHODS = new Set(['GET', 'HEAD']);const LOGGED_INGEST_HEADERS = ['openpanel-client-id',@@ -81,16 +80,15 @@ export function requestContext(deps: AppDeps) {export interface RequestLoggingOptions {/**- * V1 read `ENABLE_VERBOSE_LOGGING` here; core reads no environment, so the- * parsed client-id list arrives from `apps/api`'s config.+ * Core reads no environment; the parsed client-id list arrives from+ * `apps/api`'s config instead.*/verboseClientIds?: string[];}/**- * V1's `onResponse` requestLoggingHook. One `info` line per request, named- * `request done` — the `requestId` field rides in from the child logger,- * replacing V1's `reqId`.+ * One `info` line per request, named `request done` — the `requestId`+ * field rides in from the child logger.*/export function requestLogging(deps: AppDeps,@@ -140,8 +138,6 @@ export function requestLogging(method: request.method,elapsed,headers: pickHeaders(request.headers, LOGGED_INGEST_HEADERS),- // V1 logs the whole /track body here; ADR-018 R6's budget for it is- // P9's call, not this port's.body: path.startsWith('/track') ? body : undefined,clientIp: verbose ? ctx.ip : '',clientIpHeader: verbose ? clientIpHeader : '',@@ -175,8 +171,9 @@ function wrapCookies(cookie: ElysiaCookies): CookieJar {}// `signed` is deliberately not forwarded: Elysia signs by app-level-// `cookie: { secrets, sign: [...] }` config, not per write, so app.ts lists-// the signed names (P3). Everything else maps one-to-one.+// `cookie: { secrets, sign: [...] }` config, not per write, so+// apps/api/src/main.ts lists the signed names. Everything else maps+// one-to-one.function writeCookie(cookie: ElysiaCookies,name: string,diff --git a/packages/core/src/http/cors.ts b/packages/core/src/http/cors.tsindex c4fcf324d..3be039b0d 100644--- a/packages/core/src/http/cors.ts+++ b/packages/core/src/http/cors.ts@@ -1,31 +1,25 @@-// The CORS delegator, ported from apps/api/src/app.ts:107-131 (ADR-002-// "behaviour that must be preserved explicitly" 4).+// The CORS delegator.//// Two halves, and BOTH are the contract://-// 1. `CORS_PRIVATE_PATHS` is V1's `corsPaths` allowlist verbatim. A request-// under one of those prefixes is only allowed from a configured dashboard-// origin; everything else — `/track`, `/export`, `/insights`, `/import`,-// `/manage`, `/profile`, `/event`, `/tools` — is open to any origin. 2. The-// quirk that `/gsc` and `/mcp` are dashboard-scope routes ABSENT from the list,-// and therefore open. Ported, not fixed.+// 1. `CORS_PRIVATE_PATHS` is the allowlist: a request under one of those+// prefixes is only allowed from a configured dashboard origin; everything+// else — `/track`, `/export`, `/insights`, `/import`, `/manage`, `/profile`,+// `/event`, `/tools` — is open to any origin. 2. `/gsc` and `/mcp` are+// dashboard-scope routes ABSENT from the list, and therefore open.//-// The origins come from `apps/api`'s config, not from `process.env`: core reads-// no environment.+// The origins come from `apps/api`'s config, not from an environment read.//-// ONE deliberate delta from V1, forced by the plugin substitution ADR-002-// mandates (`@fastify/cors`'s per-request delegate -> `@elysiajs/cors`, whose-// `credentials` and `maxAge` are static while only `origin` is per-request): on-// an open path that DOES send an `Origin` header, V2 echoes that origin with-// `vary: Origin` where V1 answered `*`, and carries-// `access-control-allow-credentials: true`. Both forms permit exactly the same-// set of cross-origin requests; a browser treats an echoed origin plus `Vary`-// as it treats `*`. A request with no `Origin` header — every server-side SDK,-// every golden replay — still gets `*`.+// On an open path that DOES send an `Origin` header, that origin is echoed+// back with `vary: Origin` and `access-control-allow-credentials: true`,+// rather than answering `*`. A browser treats an echoed origin plus `Vary`+// exactly as it treats `*`, so this permits the same set of cross-origin+// requests. A request with no `Origin` header — every server-side SDK, every+// golden replay — still gets `*`.import { cors } from '@elysiajs/cors';-/** V1's `corsPaths` (apps/api/src/app.ts:111), byte-for-byte. */+/** The allowlist of private-route prefixes. */export const CORS_PRIVATE_PATHS = ['/trpc','/live',@@ -35,7 +29,7 @@ export const CORS_PRIVATE_PATHS = ['/ai',] as const;-/** V1's `maxAge: 86_400 * 7` on the open paths. */+/** Preflight cache duration for the open paths (7 days). */const CORS_MAX_AGE_SECONDS = 86_400 * 7;export interface CorsOptions {diff --git a/packages/core/src/http/debug.routes.ts b/packages/core/src/http/debug.routes.tsindex 2c37a92d7..b7b601719 100644--- a/packages/core/src/http/debug.routes.ts+++ b/packages/core/src/http/debug.routes.ts@@ -1,23 +1,17 @@-// V1's `apps/worker/src/boot-debug.ts`, ported onto Elysia and onto the ONE-// port. Local-only: `main.ts` mounts this surface only outside production AND-// only in a consuming role — the same two facts that were true of V1, where the-// routes lived in the worker behind `NODE_ENV !== 'production'`. They are what-// keeps an unauthenticated "run any cron job now" endpoint off a production-// box.+// Local-only: `main.ts` mounts this surface only outside production AND only+// in a consuming role. Those two facts are what keep an unauthenticated "run+// any cron job now" endpoint off a production box.//-// Three things changed on the way over, all deliberate:+// The job list is the `cron` queue's own `jobs`, not a hand-written array of+// cron type strings — the array could drift from the registry; the registry+// cannot drift from itself. The queue arrives as an argument (`rest.routes.ts`+// binds it) because transport may not import a registry.//-// * The job list is the `cron` queue's own `jobs`, not a hand-written array of-// the 20 `CronQueueType` strings. The array could drift from the registry; the-// registry cannot drift from itself. The queue arrives as an argument —-// `rest.routes.ts` binds it — because transport may not import a registry. * A-// trigger runs through `runJob` with V1's `{ type }` data — the same entry-// point the real worker uses, compat hook included — so what this exercises is-// the production path and not a second dispatcher. *-// `/debug/insights/:projectId?inline=1` summarises with the insight service's-// own `listAllInsights` instead of V1's ad-hoc `projectInsight.groupBy`,-// because core reaches Postgres through its services, not through a Prisma-// client of its own.+// A trigger runs through `runJob` with `{ type }` data — the same entry point+// the real worker uses — so what this exercises is the production path, not a+// second dispatcher. `/debug/insights/:projectId?inline=1` summarises with the+// insight service's own `listAllInsights`, because core reaches Postgres+// through its services, not through a Prisma client of its own.import { z } from 'zod';import type { AnyJob, QueueDefinition } from '../jobs/define';@@ -44,8 +38,7 @@ function escapeHtml(value: string): string {}// Browsers send an explicit `text/html` accept header; curl sends the-// wildcard, which falls through to JSON — V1's `req.accepts(['json','html'])`-// ordering, kept.+// wildcard, which falls through to JSON.function wantsHtml(headers: Headers): boolean {return (headers.get('accept') ?? '').includes('text/html');}@@ -103,8 +96,7 @@ export const createDebugRoutes = (cronQueue: CronQueue) => {jobs,};},- // Hidden from the OpenAPI document, like every other ops-surface route:- // in V1 these lived on the worker's own server and were never in it.+ // Hidden from the OpenAPI document, like every other ops-surface route.{ detail: HIDDEN }).all(@@ -127,7 +119,6 @@ export const createDebugRoutes = (cronQueue: CronQueue) => {ctx.logger.info({ type }, 'Manually triggering cron job');try {- // V1's wire data, so this goes through the `cron` compat hook.await runJob(cronQueue,{ name: type, data: { type }, attemptsMade: 0 },diff --git a/packages/core/src/http/errors.ts b/packages/core/src/http/errors.tsindex e7f01740f..7467ccb3c 100644--- a/packages/core/src/http/errors.ts+++ b/packages/core/src/http/errors.ts@@ -1,16 +1,13 @@-// The one error handler, ported from apps/api/src/app.ts:408-460 (ADR-002-// "behaviour that must be preserved explicitly" 6: "the error handler's shape,-// including the absence of a not-found handler").+// The one error handler for the whole app.//-// The body is V1's `{status, error, message}` — ADR-003 lists that shape under-// "behaviour that must be re-implemented deliberately", because V1 produced it-// as a side effect of the Fastify error handler and nothing reproduces it on-// its own. Elysia's own `VALIDATION` failures are mapped onto it too, at 400:-// that is the status V1's zod compilers threw with, and a caller that sends a-// bad `/track` body must keep seeing 400 rather than Elysia's 422.+// The response body is the `{status, error, message}` shape API consumers+// already parse, so it is preserved deliberately rather than left to+// whatever Elysia would produce on its own. Elysia's own `VALIDATION`+// failures are mapped onto it too, at 400 — a caller sending a bad `/track`+// body must keep seeing 400, not Elysia's own 422.//-// There is deliberately NO not-found handler: V1 had none, so an unmatched-// route keeps whatever the framework answers.+// There is deliberately NO not-found handler: an unmatched route keeps+// whatever the framework answers.import { Elysia } from 'elysia';import type { AppDeps } from '../context';@@ -20,8 +17,6 @@ import { requestContext } from './context';const RATE_LIMITED_STATUS = 429;const SERVER_ERROR_STATUS = 500;-/** V1's SKIP_LOG_ERRORS. `FST_ERR_CTP_INVALID_MEDIA_TYPE` is Fastify's and can- * no longer occur; it stays so the list is recognisably the same one. */const SKIP_LOG_ERROR_CODES = ['UNAUTHORIZED','FORBIDDEN',@@ -32,8 +27,9 @@ const SKIP_LOG_ERROR_CODES = [];const VALIDATION_STATUS = 400;-/** V1's zod compilers threw a plain `Error`, so `normalizeError` reported- * `Error` as the name and the body carried `"error":"Error"`. */+/** The validation error name callers see is the literal string `'Error'` in+ * the response body — a stable part of the API contract regardless of what+ * actually threw. */const VALIDATION_ERROR_NAME = 'Error';/**@@ -119,10 +115,10 @@ export function errorHandler(deps: AppDeps, options: ErrorHandlerOptions) {}/**- * V1's validation message, `"<slot>/<path> <zod message>"` — produced by- * `fastify-zod-openapi`'s compilers, and part of the response body on- * `/export` and `/insights`. Elysia's own message is a multi-line JSON dump,- * which is why this reads the structured error rather than reformatting it.+ * Produces the `"<slot>/<path> <zod message>"` format that's part of the+ * response body on `/export` and `/insights` — an established part of the API+ * contract. Elysia's own message is a multi-line JSON dump, which is why this+ * reads the structured error fields instead of reformatting it.*/function validationMessage(error: unknown): string {// Measured on Elysia 1.4.30 with a zod (Standard Schema) validator: thediff --git a/packages/core/src/http/hooks.ts b/packages/core/src/http/hooks.tsindex 04c02031c..ef1db7a3f 100644--- a/packages/core/src/http/hooks.ts+++ b/packages/core/src/http/hooks.ts@@ -1,15 +1,15 @@// The root chain, as named Elysia plugins.//-// V1's order is cors -> requestId -> timestamp -> ip, and it precedes every-// route-level hook including the rate limiters (apps/api/src/app.ts:130-133;-// ADR-002 "behaviour that must be preserved explicitly" 2). Here it is `.use`-// order: `requestContext` composes these three in that order and `app.ts`-// mounts `@elysiajs/cors` ahead of it. The cors position is structural rather-// than conventional — it runs at `onRequest`, a strictly earlier lifecycle-// phase than `derive`, so it cannot be reordered by accident.+// The order is cors -> requestId -> timestamp -> ip, and it precedes every+// route-level hook including the rate limiters. `requestContext` composes+// these three in that order, and `main.ts` mounts `@elysiajs/cors` ahead of+// it. The cors position is structural rather than conventional — it runs at+// `onRequest`, a strictly earlier lifecycle phase than `derive`, so it cannot+// be reordered by accident.//-// The request-logging hook lives with `requestContext` in./context.ts: it reads-// the request logger off `ctx` and would otherwise import this file's consumer.+// The request-logging hook lives with `requestContext` in ./context.ts: it+// reads the request logger off `ctx` and would otherwise import this file's+// consumer.import { generateId } from '@openpanel/shared';import { Elysia } from 'elysia';@@ -19,8 +19,8 @@ import { getClientIpFromHeaders } from '../shared/get-client-ip';import { sanitizeRequestId } from '../shared/request-id';/**- * First of the three. `requestIdFromCaller` is not decoration: ADR-018 R6 keeps- * a caller-supplied id out of per-event log sampling, so the support case that+ * First of the three. `requestIdFromCaller` is not decoration: it keeps a+ * caller-supplied id out of per-event log sampling, so the support case that* supplied one still resolves.*/export function requestIdHook() {@@ -38,7 +38,7 @@ export function requestIdHook() {);}-/** V1's timestampHook. `/track` ages an event against arrival with it. */+/** `/track` ages an event against arrival with this timestamp. */export function timestampHook() {return new Elysia({ name: 'core/http/timestamp' }).derive({ as: 'global' },@@ -47,12 +47,10 @@ export function timestampHook() {}/**- * V1's ipHook, including the empty-string fallback.- *- * This is the *attribution* ip: it prefers client-forwarded headers, which is- * right for analytics and fatal for a rate-limit bucket. The limiter keys on- * `openpanel-client-id` and then `getTrustedIpFromHeaders`, and must never read- * this (ADR-002 "behaviour that must be preserved explicitly" 2).+ * Resolves the *attribution* ip, including the empty-string fallback: it+ * prefers client-forwarded headers, which is right for analytics and fatal+ * for a rate-limit bucket. The limiter keys on `openpanel-client-id` and then+ * `getTrustedIpFromHeaders`, and must never read this.*/export function clientIpHook(ipHeaders: IpHeaderConfig) {return new Elysia({ name: 'core/http/client-ip' }).derive(diff --git a/packages/core/src/http/http.metrics.ts b/packages/core/src/http/http.metrics.tsindex cd673bbae..51ae68628 100644--- a/packages/core/src/http/http.metrics.ts+++ b/packages/core/src/http/http.metrics.ts@@ -1,7 +1,6 @@-// `fastify-metrics`'s two route series, re-created on Elysia-// (TARGET_ARCHITECTURE §18 / ADR-018's metrics-continuity register: "kept, name-// and labels reproduced exactly"). The plugin itself dies with Fastify-// (ADR-002's deleted-plugin list), so these are ours now.+// `fastify-metrics`'s two route series, re-created on Elysia so the metric+// names, help text and labels are reproduced exactly. The plugin itself dies+// with Fastify, so these are ours now.//// What "reproduced exactly" pins, from fastify-metrics 12.1.0's own source// (dist/fastify-metrics.js:181-210, 258-290):diff --git a/packages/core/src/http/query.ts b/packages/core/src/http/query.tsindex 91f113fd0..59cb97a51 100644--- a/packages/core/src/http/query.ts+++ b/packages/core/src/http/query.ts@@ -1,14 +1,11 @@-// The querystring pre-pass, ported from-// apps/api/src/utils/parse-zod-query-string.ts ("behaviour that must be-// re-implemented deliberately": the `parseQueryString` pre-pass as an Elysia+// The querystring pre-pass: the `parseQueryString` pre-pass as an Elysia// lifecycle hook running BEFORE schema validation on `/export` and-// `/insights`).+// `/insights`.//-// It exists because ~31 query schemas on those two surfaces are written against-// already-coerced values — `z.number`, `z.boolean`, `z.array(...)` — while a-// querystring only ever carries strings. V1 coerced in a Fastify-// `preValidation` hook; rewriting those schemas with `z.coerce` instead would-// change the contract, which is why the ADR names the hook.+// It exists because ~31 query schemas on those two surfaces are written+// against already-coerced values — `z.number`, `z.boolean`, `z.array(...)` —+// while a querystring only ever carries strings. Rewriting those schemas with+// `z.coerce` instead would change the contract.//// `transform` is Elysia's pre-validation phase, and the hook MUTATES `query` in// place: reassigning the destructured binding would not reach the object the@@ -49,7 +46,7 @@ export function parseQueryString(}/** The `transform` hook itself. Registered LOCAL on the two route surfaces- * that had it in V1 — never globally, or `/track` and `/manage` would start+ * that need it — never globally, or `/track` and `/manage` would start* coercing values their handlers read as strings. */export function parseQueryStringTransform({query,diff --git a/packages/core/src/http/rate-limit.ts b/packages/core/src/http/rate-limit.tsindex 22bb29740..781f9f348 100644--- a/packages/core/src/http/rate-limit.ts+++ b/packages/core/src/http/rate-limit.ts@@ -1,10 +1,6 @@-// The HTTP limiter, ported from apps/api/src/utils/rate-limiter.ts (V1),-// which used @fastify/rate-limit. Deliberately simpler than the tRPC one in-// rpc/rate-limit.ts: a fixed window with no escalation, because that is what-// V1 ran and what docs/api-reference/rate-limits.mdx publishes.-//-// The rewrite shipped without it, so the limits that page advertises were not-// enforced anywhere (ISSUES.md H4).+// The HTTP limiter. Deliberately simpler than the tRPC one in+// rpc/rate-limit.ts: a fixed window with no escalation, matching what+// docs/api-reference/rate-limits.mdx publishes (ISSUES.md H4).import { getRedisCache } from '@openpanel/redis';import { Elysia } from 'elysia';@@ -17,7 +13,7 @@ const TOO_MANY_REQUESTS = 429;const KEY_MISSING = -2;const KEY_WITHOUT_EXPIRY = -1;-/** V1's body, byte for byte. */+/** Exact response body, matching what api-reference/rate-limits.mdx documents. */const TOO_MANY_REQUESTS_BODY = {statusCode: TOO_MANY_REQUESTS,error: 'Too Many Requests',@@ -25,7 +21,7 @@ const TOO_MANY_REQUESTS_BODY = {} as const;/**- * As in V1: the API client if there is one, otherwise the TRUSTED ip.+ * The API client if there is one, otherwise the TRUSTED ip.* `x-client-ip` and `x-forwarded-for` are caller-set, so keying on the* attribution address would hand out a fresh bucket per request.*/@@ -45,14 +41,14 @@ export interface HttpRateLimit {/** Requests allowed per window. */max: number;windowMs: number;- /** Groups every route under one bucket, as V1's per-router plugin did. */+ /** Groups every route under one bucket. */scope: string;}/*** `true` when the caller is over its limit and the request must be refused.* A Redis failure allows the request: this guards a documented quota, not a- * credential, and V1 behaved the same way.+ * credential.*/export async function isRateLimited({ max, windowMs, scope }: HttpRateLimit,@@ -86,9 +82,8 @@ export async function isRateLimited(}/**- * V1's limits, router for router (apps/api/src/routes/*.router.ts). The first- * matching prefix wins, so order matters only where one prefix contains- * another — none do today.+ * The first matching prefix wins, so order matters only where one prefix+ * contains another — none do today.** `/export`, `/insights` and `/manage` are what* docs/api-reference/rate-limits.mdx publishes. `/track`, `/profile` and@@ -109,8 +104,8 @@ export function limitFor(pathname: string): HttpRateLimit | undefined {/*** Mounted once per route surface rather than per module, so a new `/manage`- * route cannot quietly arrive without a limit. V1 registered the plugin per- * router; the prefix table above is that same mapping in one place.+ * route cannot quietly arrive without a limit. The prefix table above is+ * that mapping in one place.*/export function httpRateLimit(deps: AppDeps) {return new Elysia({ name: 'core/http/rate-limit' })diff --git a/packages/core/src/http/session.ts b/packages/core/src/http/session.tsindex d5eaf2c11..882392b19 100644--- a/packages/core/src/http/session.ts+++ b/packages/core/src/http/session.ts@@ -2,13 +2,11 @@//// `HttpCtx.session` memoizes this call, so a request that asks twice pays once,// and the cookie is read through `HttpCtx` rather than through a plugin whose-// registration order could put it after the guard that needs it (ADR-002-// "behaviour that must be preserved explicitly" 1).+// registration order could put it after the guard that needs it.//-// Filled the body in, porting apps/api/src/app.ts's dashboard-scope `onRequest`-// hook: decode, `runWithAlsSession`, validate, and V1's DEMO_USER_ID branch —-// which lives inside `validateSessionToken` itself, so the no-cookie path still-// goes through it rather than short-circuiting here.+// The flow is: decode, `runWithAlsSession`, validate. The `DEMO_USER_ID`+// branch lives inside `validateSessionToken` itself, so the no-cookie path+// still goes through it rather than short-circuiting here.//// Both halves arrive as `ctx.services.auth`, not as a deep import of// `modules/auth/src/*`. The derive in `http/context.ts` builds the `Ctx` before@@ -18,7 +16,7 @@//// `null` means "nobody is signed in", NOT `EMPTY_SESSION`: the `session` macro,// the bull-board guard and the four `/live` handlers all treat the resolved-// value as truthy-means-authenticated. tRPC is the one caller that wants V1's+// value as truthy-means-authenticated. tRPC is the one caller that wants the// empty shape instead, and `makeTrpcContext` maps `null` back to// `EMPTY_SESSION` there.@@ -28,7 +26,7 @@ import type { CookieJar } from '../shared/cookie';export const SESSION_COOKIE_NAME = 'session';-/** V1's ALS scope for the demo branch (apps/api/src/app.ts:163). */+/** ALS scope for the demo branch. */const DEMO_ALS_SESSION_ID = '1';export async function resolveSession(@@ -46,7 +44,7 @@ export async function resolveSession();return result.userId === null ? null : result;} catch {- // V1 swallowed a malformed cookie into EMPTY_SESSION rather than a 500.+ // A malformed cookie resolves to null (nobody signed in) rather than a 500.return null;}}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex b3d501ae8..26e87ae14 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -84,7 +84,7 @@ export { createCtx, extendCtx } from './context';export { BULL_BOARD_BASE_PATH, bullBoardRoutes } from './http/bull-board';export { requestContext, requestLogging } from './http/context';// The root chain `main.ts` hangs every surface on. Both take their-// deployment-derived values as arguments — core reads no environment.+// deployment-derived values as arguments.export { corsDelegator } from './http/cors';export { errorHandler } from './http/errors';// The two runtime seams over the registry. `main.ts` builds producers in every@@ -120,7 +120,7 @@ export {} from './logger';// The one registry's own boot-time registrars. `registry` itself is NOT// exported: a caller that can reach it can start a second collector graph-// somewhere other than a module, which is the thing §18 forbids.+// outside a module.export { registerDefaultMetrics } from './metrics';// The chat app, the run context and the filter command take the API's `deps`,// so the barrel carries the factory and the types only; `assistant.routes.ts`@@ -188,8 +188,8 @@ export type {// calls, small enough to live inline in `email.rpc.ts` rather than a dedicated// `email.service.ts` — see that file's header.export { emailCategories } from './modules/email/email.constants';-// Shared by the onboarding module and, since M9-003, the organization module's-// wind-down track.+// Shared by the onboarding module and the organization module's wind-down+// track.export type {SequenceStep,SequenceSubject,@@ -230,9 +230,7 @@ export {validateIngestRequest,} from './modules/ingest/ingest.service';// The Kafka consumer and its per-message handler, which take the kafkajs-// client, the topic/group names and the retry bounds as arguments — the-// injection seam that used to cross a package boundary and now just crosses two-// files.+// client, the topic/group names and the retry bounds as arguments.export type {DeadLetterMessage,EventsBatchHandlerDeps,@@ -278,8 +276,7 @@ export { explainInsight } from './modules/insight/insight.service';// Slack's OAuth token-exchange wire contract — not integration config (stays// out of the `*.constants` subpath, see// modules/integration/src/slack-contract.ts's header), but apps/api's webhook-// controller still needs it to validate Slack's `oauth.v2.access` response, the-// same way it reaches slackInstaller above.+// controller still needs it to validate Slack's `oauth.v2.access` response.export { zSlackAuthResponse } from './modules/integration/src/slack-contract';// Stateless-only, so there is no SessionManager to manage. The barrel carries// the factory and the two types; `handleStatelessMcpRequest` needs the API's@@ -457,6 +454,6 @@ export {TRUSTED_IP_HEADER_ORDER,} from './shared/get-client-ip';export { getReferrerWithQuery, parseReferrer } from './shared/parse-referrer';-// Below the transports since M15-007: `rpc/base.ts` needs the empty shape and-// may not deep-import a module to get it.+// Below the transports: `rpc/base.ts` needs the empty shape and may not+// deep-import a module to get it.export { EMPTY_SESSION } from './shared/session';diff --git a/packages/core/src/jobs.registry.test.ts b/packages/core/src/jobs.registry.test.tsindex 61833861c..7dafe1e5b 100644--- a/packages/core/src/jobs.registry.test.ts+++ b/packages/core/src/jobs.registry.test.ts@@ -2,9 +2,8 @@ import { expect, test } from 'bun:test';import { PING_SCHEDULE, schedulersFromRegistry } from './jobs/schedulers';import { queues } from './jobs.registry';-// Byte-identity snapshot, mirroring-// `verification/golden/queue-keys/scheduler-ids.json` — see-// `jobs/schedulers.test.ts` for the matching id-level check.+// Byte-identity snapshot — see `jobs/schedulers.test.ts` for the matching+// id-level check.const GOLDEN_SCHEDULER_IDS = ['cohortRefresh','dataHealth',@@ -28,9 +27,8 @@ const GOLDEN_SCHEDULER_IDS = ['windDown',].sort();-// V1's `defaultJobOptions`, verbatim from packages/queue/src/queues.ts.-// ADR-005's acceptance note: retry and retention values port as-is, defects-// included — five queues that never retry, four with unbounded failed sets.+// Retry and retention values kept as-is, defects included — five queues+// that never retry, four with unbounded failed sets.const V1_DEFAULTS = {sessions: { removeOnComplete: true },cron: { removeOnComplete: 10 },@@ -46,7 +44,6 @@ const V1_DEFAULTS = {},} as const;-// apps/worker/src/boot-workers.ts:209-277 — `getConcurrencyFor(name, default)`.const V1_CONCURRENCY = {sessions: 1,cron: 1,@@ -104,18 +101,11 @@ test('the insights queue carries the insight module job', () => {});});-// The insight module's cron fragment (insight.jobs.ts), spread into the ONE-// cron queue (ADR-005: "no cron module"). legacyCompat.cron maps a legacy job's-// `type` straight onto its name, so these three ids double as job names. `ping`-// (misc.jobs.ts) is the twentieth and only conditional one — its scheduler is+// The insight module's cron fragment (insight.jobs.ts), spread into the one+// cron queue. `ping` (misc.jobs.ts) is the only conditional scheduler — it's// added by `startSchedulers` only when SELF_HOSTED && production-// (jobs/schedulers.ts's `PING_SCHEDULE`), but the job HANDLER is always-// registered here so a scheduled run always has somewhere to land. `salt`-// (salt.jobs.ts) and the six `flush*` jobs (event/profile/session/-// group.jobs.ts) join the list at M8-004; `dataHealth` (misc.jobs.ts),-// `windDown` (organization.jobs.ts) and `flushExports` (integration.jobs.ts) at-// M9-003, which completes the set — all 20 V1 scheduler ids now have a handler-// here.+// (jobs/schedulers.ts's `PING_SCHEDULE`), but its job HANDLER is always+// registered here so a scheduled run always has somewhere to land.test('the cron queue carries the insight module cron fragment', () => {expect(Object.keys(queues.cron.jobs).sort()).toEqual([@@ -187,8 +177,7 @@ test('the cron queue carries the cohort module cron fragment', () => {});});-// The organization module's `delete` cron fragment (folded in from-// packages/db/src/services/delete.service.ts).+// The organization module's `delete` cron fragment.test('the cron queue carries the organization module cron fragment', () => {expect(queues.cron.jobs.delete).toMatchObject({queue: 'cron',@@ -204,9 +193,9 @@ test('the cron queue carries the onboarding module cron fragment', () => {});});-// The session module's own job (legacyCompat.sessions maps V1's-// `createSessionEnd` onto this exact name) and its reaper/vacuum cron fragment-// — the scheduler ids double as the job names.+// The session module's own job (legacyCompat.sessions maps the legacy+// `createSessionEnd` job onto this exact name) and its reaper/vacuum cron+// fragment — the scheduler ids double as the job names.test('the sessions queue carries the session module job', () => {expect(Object.keys(queues.sessions.jobs)).toEqual(['session']);expect(queues.sessions.jobs.session).toMatchObject({@@ -247,13 +236,11 @@ test('the notification queue carries the notification module job', () => {});});-// Shrinks M9-001's bidirectional "every scheduler id has a handler, and vice-// versa" test to this single derivation-vs-golden comparison: the join between-// a cron job and its schedule is now enforced by the type system-// (`defineQueue`'s overload for the `cron` queue requires every job on it to-// declare `cron`, a schedule or explicit `null`), so the property that test-// policed can no longer drift — it is true by construction, not by a test-// walking both registries.+// The join between a cron job and its schedule is enforced by the type+// system (`defineQueue`'s overload for the `cron` queue requires every job+// on it to declare `cron`, a schedule or explicit `null`), so this property+// can no longer drift — it is true by construction, not by a test walking+// both registries.test('the cron queue derives the golden 20 scheduler ids', () => {const derivedIds = [...schedulersFromRegistry(queues.cron).map((s) => s.id),diff --git a/packages/core/src/jobs.registry.ts b/packages/core/src/jobs.registry.tsindex 400a74078..d34d7ffb5 100644--- a/packages/core/src/jobs.registry.ts+++ b/packages/core/src/jobs.registry.ts@@ -2,13 +2,13 @@// spread into the queue that owns them; there is no auto-discovery, because// static composition is what keeps `QueueProducers` typed.//-// Registry key === Redis name for all seven, `cohortCompute` included:-// ADR-005's acceptance note refuses the rename, so `COHORTCOMPUTE_CONCURRENCY`-// keeps working. `queueKey` decides what actually reaches Redis.+// Registry key === Redis name for all seven, `cohortCompute` included: the key+// is deliberately not renamed, so `COHORTCOMPUTE_CONCURRENCY` keeps working.+// `queueKey` decides what actually reaches Redis.//-// Retry and retention values are V1's, verbatim, defects included — five queues-// that never retry, four whose failed sets are unbounded. Changing them is a-// behaviour change and a separate decision (ADR-005 acceptance note).+// Retry and retention values are preserved as-is, defects included — five+// queues that never retry, four whose failed sets are unbounded. Changing+// them is a behaviour change, not a cleanup, and is a separate decision.import { legacyCompat } from './jobs/compat';import type { Producers } from './jobs/define';@@ -44,8 +44,7 @@ const DAY_IN_SECONDS = 86_400;const COHORT_BACKOFF_MS = 5000;const COHORT_ATTEMPTS = 3;-// Defaults from apps/worker/src/boot-workers.ts; `<KEY>_CONCURRENCY`-// overrides one at boot.+// `<KEY>_CONCURRENCY` overrides one of these at boot.const CONCURRENCY = {sessions: 1,cron: 1,@@ -72,7 +71,8 @@ const cron = defineQueue('cron', {defaults: { removeOnComplete: 10 },worker: { concurrency: CONCURRENCY.cron },compat: legacyCompat.cron,- // Every module's cron fragment spreads in here (ADR-005: "no cron module").+ // Every module's cron fragment spreads in here — there is no separate cron+ // module.jobs: {...saltCronJobs,...eventCronJobs,@@ -153,12 +153,11 @@ export const queues = {export type Queues = typeof queues;-// V1's exact 19 always-on scheduler ids and cadences-// (apps/worker/src/boot-cron.ts), derived from the `cron` queue's own jobs so a-// job and its schedule cannot drift apart. It is computed HERE, in the-// registry, and not in `jobs/schedulers.ts`: that file is transport-// infrastructure and may not import a registry. `ping` is the 20th and is-// conditional — see `PING_SCHEDULE` and `startSchedulers`.+// Derived from the `cron` queue's own jobs so a job and its schedule cannot+// drift apart. It is computed HERE, in the registry, and not in+// `jobs/schedulers.ts`: that file is transport infrastructure and may not+// import a registry. `ping` is conditional — see `PING_SCHEDULE` and+// `startSchedulers`.export const CRON_SCHEDULES: readonly SchedulerDefinition[] =schedulersFromRegistry(cron);diff --git a/packages/core/src/jobs/compat.ts b/packages/core/src/jobs/compat.tsindex 60c7b7734..3f20adec6 100644--- a/packages/core/src/jobs/compat.ts+++ b/packages/core/src/jobs/compat.ts@@ -1,13 +1,13 @@-// The whole of the P9 cutover. There is no dual-write window, no drain and no-// queue rename: a job enqueued by V1 is read back by V2 through these hooks. A-// wrong one is silent job loss, which is why the tests next to this file were-// written before it.+// There is no dual-write window, no drain and no queue rename: a legacy job+// already in the queue is read back through these hooks. A wrong one is+// silent job loss, which is why the tests next to this file were written+// before it.import type { CompatHook } from './define';import { isEnvelope, type JobMeta } from './envelope';export interface ResolvedJob {- /** The V2 job name — a key in the queue definition's `jobs`. */+ /** The job name — a key in the queue definition's `jobs`. */job: string;payload: unknown;meta: JobMeta;@@ -16,9 +16,8 @@ export interface ResolvedJob {const NO_META: JobMeta = {};/**- * Envelope or legacy, one answer. Throws on anything neither path recognises:- * V1's cron `switch` had no `default` and completed an unknown type having done- * nothing, which is the failure mode this replaces (ADR-005 risk 2).+ * Envelope or legacy, one answer. Throws on anything neither path recognises,+ * rather than silently completing an unknown type having done nothing.*/export function resolveJob(definition: { name: string; compat?: CompatHook },@@ -57,9 +56,9 @@ function discriminatedByType(types: readonly string[]): CompatHook {}/**- * One hook per queue, keyed by registry key. Each is deletable on its own — but- * not until no legacy-shaped job can still be replayed, and four queues have no- * `removeOnFail` at all, so their failed sets never lapse (ADR-005 risk 1).+ * One hook per queue, keyed by registry key. Each is deletable on its own —+ * but not until no legacy-shaped job can still be replayed, and four queues+ * have no `removeOnFail` at all, so their failed sets never lapse.*/export const legacyCompat = {// Job name `'session'`, payload type `'createSessionEnd'` — the one queue@@ -88,7 +87,7 @@ export const legacyCompat = {insights: discriminatedByType(['insightsProject']),gsc: discriminatedByType(['gscProjectSync', 'gscProjectBackfill']),- // The only V1 payload with no discriminant at all.+ // The only legacy payload with no discriminant at all.cohortCompute: ((data) => {const record = asRecord(data);return typeof record?.cohortId === 'string'diff --git a/packages/core/src/jobs/define.ts b/packages/core/src/jobs/define.tsindex 05e18c821..8f002cbdf 100644--- a/packages/core/src/jobs/define.ts+++ b/packages/core/src/jobs/define.ts@@ -119,11 +119,10 @@ export type PayloadOf<TJob> = TJob extends { payload: infer TSchema }: never;/**- * Translates one V1 job's raw data into the (job name, payload) pair V2 speaks.- *- * Returns `undefined` for a shape it does not recognise, which `resolveJob`- * turns into a throw. The BullMQ job *name* on the wire is not authoritative —- * V1 dispatched on `data.type`, and `sessions` is named `'session'` while its+ * Translates one legacy-shaped job's raw data into the (job name, payload)+ * pair this queue speaks. Returns `undefined` for a shape it does not+ * recognise, which `resolveJob` turns into a throw. The BullMQ job *name* on+ * the wire is not authoritative — `sessions` is named `'session'` while its* type is `'createSessionEnd'` — so the hook decides the name too.*/export type CompatHook = (@@ -136,7 +135,7 @@ export interface QueueDefinition<name: string;defaults?: QueueDefaults;worker?: WorkerSettings;- /** Deletable once no legacy-shaped job can still be replayed — see ADR-005 risk 1. */+ /** Deletable once no legacy-shaped job can still be replayed. */compat?: CompatHook;jobs: { [K in keyof TJobs]: TJobs[K] & JobBinding };}@@ -186,7 +185,7 @@ export function defineJob<** `TJobs`'s bound depends on `TName`: on the `cron` queue every job must carry* a `cron` field (a schedule, or `null` for on-demand) — the three-state rule- * ADR-021 requires enforced at the type level, not by a registry test.+ * enforced at the type level, not by a registry test.*/export function defineQueue<TName extends string,diff --git a/packages/core/src/jobs/envelope.ts b/packages/core/src/jobs/envelope.tsindex 2790b3ee1..a59ec71b4 100644--- a/packages/core/src/jobs/envelope.ts+++ b/packages/core/src/jobs/envelope.ts@@ -36,8 +36,9 @@ export function wrap<TPayload>(}/**- * Both keys, not just `payload`: five of the seven V1 shapes carry a `payload`- * of their own, so `meta` is the half that tells an envelope from a legacy job.+ * Both keys, not just `payload`: most legacy job shapes also carry a+ * `payload` of their own, so `meta` is the half that tells an envelope from+ * a legacy job.*/export function isEnvelope(data: unknown): data is JobEnvelope {return (diff --git a/packages/core/src/jobs/jobs.metrics.ts b/packages/core/src/jobs/jobs.metrics.tsindex b23d34fae..34ee16e9e 100644--- a/packages/core/src/jobs/jobs.metrics.ts+++ b/packages/core/src/jobs/jobs.metrics.ts@@ -1,20 +1,17 @@-// The queue-side collectors, moved from apps/worker/src/metrics.ts onto the one-// core registry (TARGET_ARCHITECTURE §18). Names, labels and buckets are V1's;-// the worker-side copies died with apps/worker.+// The queue-side collectors, on the one core registry.//// Three deliberate differences from the metric set this replaces, written up// for dashboard owners in `packages/core/docs/OPS_GRAFANA_MIGRATION.md`://-// 1. V1 registered the five `<queue>_*_count` gauges for TWO queues-// (`sessionsQueue`, `cronQueue`). V2 registers them for all seven, which-// ADR-018's continuity register asks for ("kept for the 7 BullMQ queues"). Ten-// new series appear; none of the existing ten changes. 2. They register only-// where the role consumes (main.ts), because each gauge is one Redis round trip-// per scrape and ten api replicas exposing them would multiply that for no new-// information. 3. A gauge whose Redis read throws is skipped rather than-// failing the whole scrape. V1 let it reject `registry.metrics`, which turns-// one Redis blip into a 500 on /metrics and a gap in every panel; core's buffer-// gauges already swallow the same way (buffers/buffer.metrics.ts).+// 1. Registers the five `<queue>_*_count` gauges for all seven BullMQ+// queues, not just two — ten new series appear; none of the existing ten+// changes. 2. They register only where the role consumes (main.ts), because+// each gauge is one Redis round trip per scrape and ten api replicas+// exposing them would multiply that for no new information. 3. A gauge whose+// Redis read throws is skipped rather than failing the whole scrape, so one+// Redis blip does not turn into a 500 on /metrics and a gap in every panel;+// core's buffer gauges already swallow the same way+// (buffers/buffer.metrics.ts).import type { Queue as BullQueue } from 'bullmq';import client from 'prom-client';@@ -26,9 +23,8 @@ const JOB_DURATION_BUCKETS_MS = [// A Redis queue key is not a legal prom-client metric name: `{cron}`'s braces// and a `QUEUE_NAMESPACE`'s `-` are both rejected by prom-client, which throws-// at construction and takes boot down. V1 stripped the braces the same way-// (apps/worker/src/metrics.ts); the `_` substitution is the namespace half,-// and it changes nothing for a deployment that sets no namespace.+// at construction and takes boot down. The `_` substitution is the namespace+// half, and it changes nothing for a deployment that sets no namespace.const QUEUE_BRACES = /[{}]/g;const NON_METRIC_NAME_CHARS = /[^a-zA-Z0-9_]/g;@@ -39,11 +35,9 @@ function metricPrefix(queueName: string): string {}/**- * FAILURE-ONLY, deliberately. V1 observed this exclusively in the workers'- * `failed` listener (apps/worker/src/boot-workers.ts), so every percentile ever- * computed from it is a percentile of failures. Success timings, if wanted, get- * a NEW series name — emitting them here silently rewrites every existing panel- * (ADR-018 risk 7).+ * FAILURE-ONLY, deliberately: every percentile ever computed from it is a+ * percentile of failures. Success timings, if wanted, get a NEW series name —+ * emitting them here silently rewrites every existing panel.*/export const jobDurationMs = new client.Histogram({name: 'job_duration_ms',@@ -96,8 +90,8 @@ const COUNTS: {];/**- * Five scrape-time gauges per queue, named from the queue's Redis key exactly- * as V1 named them. Call once per process, only where the role consumes.+ * Five scrape-time gauges per queue, named from the queue's Redis key. Call+ * once per process, only where the role consumes.** `register` defaults to the one core registry; it is a parameter so a test* can assert on an isolated one.diff --git a/packages/core/src/jobs/producers.ts b/packages/core/src/jobs/producers.tsindex 0d5c5bdb6..272f1229c 100644--- a/packages/core/src/jobs/producers.ts+++ b/packages/core/src/jobs/producers.ts@@ -52,8 +52,8 @@ export interface CreateProducersOptions {/*** Where a queue's connection errors go. BullMQ re-emits ioredis errors on* every `Queue`, and an `'error'` event with no listener is an uncaught- * exception that kills the process — V1 lost the api roughly daily to idle- * ECONNRESETs before `guardQueue` was added (packages/queue/src/queues.ts).+ * exception that kills the process — production lost the api roughly daily+ * to idle ECONNRESETs before a listener was added here.* A listener is attached either way; this decides whether it says anything.*/logger?: Logger;diff --git a/packages/core/src/jobs/schedulers.ts b/packages/core/src/jobs/schedulers.tsindex 44f467493..4e998e96f 100644--- a/packages/core/src/jobs/schedulers.ts+++ b/packages/core/src/jobs/schedulers.ts@@ -1,13 +1,12 @@-// Ports apps/worker/src/boot-cron.ts onto BullMQ's job-scheduler API. Upsert is-// keyed on job name — the V1 scheduler id — which is what makes it idempotent-// across replicas: two processes upserting the same id with the same repeat-// options at boot converge on one scheduler, with no locking of our own needed.+// Upsert is keyed on job name, which is what makes it idempotent across+// replicas: two processes upserting the same id with the same repeat+// options at boot converge on one scheduler, with no locking of our own+// needed.//-// The scheduler list is no longer a second, hand-maintained registry — it is-// derived from the `cron` queue's own jobs, so a job and its schedule cannot-// drift apart. `schedulersFromRegistry` takes the registry's `cron` queue as-// data; the registry itself calls it and exports the result as-// `CRON_SCHEDULES`, so this file imports nothing above it.+// The scheduler list is derived from the `cron` queue's own jobs, so a job+// and its schedule cannot drift apart. `schedulersFromRegistry` takes the+// registry's `cron` queue as data; the registry itself calls it and exports+// the result as `CRON_SCHEDULES`, so this file imports nothing above it.import type { Logger } from '../logger';import type { AnyJob, QueueDefinition, RepeatSchedule } from './define';@@ -16,7 +15,7 @@ import { wrap } from './envelope';export type { RepeatSchedule } from './define';export interface SchedulerDefinition {- /** V1 scheduler id: the job-scheduler key, and — via BullMQ's own default+ /** The job-scheduler key, and — via BullMQ's own default* (`jobName ?? jobSchedulerId`) — the job name each run dispatches on. */id: string;schedule: RepeatSchedule;@@ -83,9 +82,8 @@ export function schedulersFromRegistry(return schedulers.sort((a, b) => a.id.localeCompare(b.id));}-// V1 gated this on `SELF_HOSTED && NODE_ENV === 'production'`-// (apps/worker/src/boot-cron.ts:133). `misc.jobs.ts`'s `ping` job declares-// `cron: null` for exactly this reason — it is never in `CRON_SCHEDULES`.+// `misc.jobs.ts`'s `ping` job declares `cron: null` for exactly this+// reason — it is never in `CRON_SCHEDULES`.export const PING_SCHEDULE: SchedulerDefinition = {id: 'ping',schedule: { pattern: '0 0 * * *' },@@ -193,9 +191,7 @@ function upsert(scheduler: SchedulerDefinition): Promise<unknown> {// Envelope-shaped for every scheduler-created job — these are freshly- // enqueued, never a replay of a V1-shaped job, so there is nothing for the- // `cron` compat hook to do here (ADR-005: new data only, old shape read back- // through `resolveJob`).+ // enqueued, so there is nothing for the `cron` compat hook to do here.return queue.upsertJobScheduler(scheduler.id, scheduler.schedule, {data: wrap(null, {}),});@@ -226,7 +222,8 @@ async function removeConflictingJobs(}}} catch {- // Ignored during cleanup — V1's behaviour (boot-cron.ts:24-26).+ // Ignored during cleanup — a failure here should not block the retry+ // that follows.}}}diff --git a/packages/core/src/jobs/workers.ts b/packages/core/src/jobs/workers.tsindex e0fb71b24..8ed85ce3e 100644--- a/packages/core/src/jobs/workers.ts+++ b/packages/core/src/jobs/workers.ts@@ -76,8 +76,9 @@ export function startWorkers<TQueues extends QueueMap>({}),});- // Fires on the connection itself, not on any one job. V1 lost the api- // process roughly daily to unlistened ioredis ECONNRESETs re-emitted here.+ // Fires on the connection itself, not on any one job — an unlistened+ // 'error' event on this emitter crashes the process (ioredis ECONNRESET+ // etc.), so it must always have a listener.worker.on('error', (error) => logger.error({ err: error }, 'worker error'));// A stall means the job was taken and then its lock lapsed: the process@@ -92,9 +93,8 @@ export function startWorkers<TQueues extends QueueMap>({return;}- // FAILURE-ONLY, and the label is the Redis key, both V1's- // (apps/worker/src/boot-workers.ts's `failed` listener). See- // jobs.metrics.ts for why a success timing may not join this series.+ // FAILURE-ONLY, and the label is the Redis key. See jobs.metrics.ts for+ // why a success timing may not join this series.if (job.processedOn) {jobDurationMs.observe({ name: key, status: 'failed' },@@ -142,8 +142,8 @@ export interface RunnableJob {/*** Exported for the worker tests, and it is what the `BullWorker` processor- * above calls. Throws on a job it cannot resolve or does not declare — V1- * completed those having done nothing (ADR-005 risk 2).+ * above calls. Throws on a job it cannot resolve or does not declare, rather+ * than completing it having done nothing.*/export async function runJob(definition: QueueDefinition,@@ -194,9 +194,8 @@ export async function runJob(}) => Promise<void>;// `debug`, not `info`: `sessions` runs one of these per session close.- // `legacy` is the cutover's own signal — while it is still ever true, a- // V1-shaped job is still being replayed and the compat hooks cannot go- // (ADR-005 risk 1).+ // `legacy` tracks whether this job predates the envelope format — while it+ // is ever true, the compat hooks that translate it cannot be removed.const legacy = !isEnvelope(job.data);logger.debug({ legacy }, 'job started');const startedAt = performance.now();diff --git a/packages/core/src/metrics.ts b/packages/core/src/metrics.tsindex f15f36a14..ef2aaf636 100644--- a/packages/core/src/metrics.ts+++ b/packages/core/src/metrics.ts@@ -1,11 +1,6 @@-// The one prom-client registry for the whole process (this package's AGENTS.md-// layout; TARGET_ARCHITECTURE §18: "One `prom-client` registry built by-// `core/src/metrics.ts`, served at `/metrics` from the ops scope in every-// role"). `apps/api/src/metrics.ts` and `apps/worker/src/metrics.ts` are-// V1-side registries that die with the apps they live in (ADR-007 package-// fates: `worker` dies, `api` becomes a shell over this package) — core neither-// reads nor extends either one. Every collector a core module registers from-// here on registers on THIS registry, and only this one.+// The one prom-client registry for the whole process. Every collector a core+// module registers from here on registers on THIS registry, and only this+// one.import client from 'prom-client';@@ -17,12 +12,7 @@ let defaultMetricsRegistered = false;/*** prom-client's Node-derived process/GC collectors, on the one registry.- *- * V1 registered these twice — `fastify-metrics` did it for the api- * (`defaultMetrics.enabled` defaults true) and `apps/worker/src/index.ts`- * called `collectDefaultMetrics` itself. V2 has one registry per process and- * calls this once, in every role (TARGET_ARCHITECTURE §18: "HTTP and default- * metrics register everywhere").+ * Called once per process, in every role.*/export function registerDefaultMetrics(): void {if (defaultMetricsRegistered) {diff --git a/packages/core/src/modules/assistant/assistant.routes.ts b/packages/core/src/modules/assistant/assistant.routes.tsindex 2fb6a2fa8..100972240 100644--- a/packages/core/src/modules/assistant/assistant.routes.ts+++ b/packages/core/src/modules/assistant/assistant.routes.ts@@ -14,8 +14,7 @@//// This route is where `deps` lives, so everything below it reaches// Postgres/ClickHouse through `ctx` — the chat app, the conversation lookup and-// the access check included. That is what removed the four lazy loaders this-// file used to open with.+// the access check included.import { defineRoutes } from '../../http/define';import { getProjectAccess } from '../../shared/access-lookups';diff --git a/packages/core/src/modules/assistant/src/app.ts b/packages/core/src/modules/assistant/src/app.tsindex 4ae7d2149..ec4d11656 100644--- a/packages/core/src/modules/assistant/src/app.ts+++ b/packages/core/src/modules/assistant/src/app.ts@@ -1,5 +1,5 @@-// The app is BUILT from the `deps` `assistant.routes.ts` already holds, not-// constructed at module scope (R15). Importing this file now opens nothing — no+// The app is built from the `deps` `assistant.routes.ts` already holds, not+// constructed at module scope. Importing this file opens nothing — no// provider client, no agent, no conversation store — and every tool handler// closes over the same `deps`, which is what `@better-agent/core`'s// context-free tool-handler signature ruled out doing as an argument.diff --git a/packages/core/src/modules/assistant/src/persistence.ts b/packages/core/src/modules/assistant/src/persistence.tsindex d1d1bece9..388c5248d 100644--- a/packages/core/src/modules/assistant/src/persistence.ts+++ b/packages/core/src/modules/assistant/src/persistence.ts@@ -6,7 +6,7 @@ import { chatRunContext } from './run-context';// `ConversationStore`'s `load`/`save` signatures are @better-agent/core's own// interface — betterAgent calls them with no `Ctx`/`ServiceDeps` to thread// through, so the store is BUILT from the deps the route already holds and-// closes over them (R15).+// closes over them./*** Prisma-backed `ConversationStore` for Better Agent.diff --git a/packages/core/src/modules/assistant/src/providers.ts b/packages/core/src/modules/assistant/src/providers.tsindex cac647ce4..92a99964e 100644--- a/packages/core/src/modules/assistant/src/providers.ts+++ b/packages/core/src/modules/assistant/src/providers.ts@@ -1,13 +1,7 @@-// Ported from @openpanel/ai (dissolved into core — M4-005). Moved out of-// `clients/ai/` by M15-008: the assistant is its only consumer, so ADR-022 A2-// puts it in this module's `src/` — which is also what removes its upward edge-// onto `assistant.constants`.-//-// SERVER-ONLY. This module instantiates `@better-agent/providers` clients from-// the credentials the config loader parsed (ADR-022 R9: config in). Never-// value-import it from the browser (apps/start) — import the model-// catalog/types from `@openpanel/core/modules/assistant/assistant.constants`-// instead.+// SERVER-ONLY. This module instantiates `@better-agent/providers` clients+// from the credentials the config loader parsed. Never value-import it from+// the browser (apps/start) — import the model catalog/types from+// `@openpanel/core/modules/assistant/assistant.constants` instead.import { createAnthropic } from '@better-agent/providers/anthropic';import { createOpenAI } from '@better-agent/providers/openai';import type { CoreConfig } from '../../../config';@@ -16,17 +10,17 @@ import type { ChatModelEntry } from '../assistant.constants';export type { ChatModelEntry } from '../assistant.constants';export { CHAT_MODELS as ALLOWED_MODELS } from '../assistant.constants';-// A provider client is memoized per `CoreConfig`, not per process (ADR-022 R16:-// what a thing owns dies with its owner, and nothing outlives the thing that-// opened it). `loadConfig` runs once per boot, so a running API still builds-// each client exactly once; a second config in the same process — a test, a+// A provider client is memoized per `CoreConfig`, not per process: what a+// thing owns dies with its owner, and nothing outlives the thing that opened+// it. `loadConfig` runs once per boot, so a running API still builds each+// client exactly once; a second config in the same process — a test, a// second boot — gets a client carrying ITS credentials rather than the first// config's, and both are collected with the config that produced them.//// There is nothing here to close: `createOpenAI`/`createAnthropic` return a-// closure over a base URL and a header set that calls the global `fetch`. They-// hold no socket, so R16's "whoever opens a connection closes it" has no-// connection to name — only a lifetime, which is what the key fixes.+// closure over a base URL and a header set that calls the global `fetch`.+// They hold no socket, so there is no connection to close — only a lifetime,+// which is what the WeakMap key fixes.const openaiClients = new WeakMap<CoreConfig,ReturnType<typeof createOpenAI>diff --git a/packages/core/src/modules/assistant/src/report-runner.ts b/packages/core/src/modules/assistant/src/report-runner.tsindex cd1f031ee..4fc6fc1cc 100644--- a/packages/core/src/modules/assistant/src/report-runner.ts+++ b/packages/core/src/modules/assistant/src/report-runner.ts@@ -2,11 +2,9 @@// `modules/mcp/src/tools/analytics/reports.ts` keeps its own copy of this// dispatch — reaching into another module's tool tree is not the fix.//-// The result is a second copy of this dispatch logic, which is exactly the-// "four independent wrapper layers over the same 34 *Core functions"-// TARGET_ARCHITECTURE already records as accepted technical debt — this becomes-// a third layer, not a new problem. Both copies call the same @openpanel/db-// primitives and must be kept in sync by hand until that debt is paid down.+// The result is a second copy of this dispatch logic, kept as an accepted+// trade-off: both copies call the same @openpanel/db primitives and must be+// kept in sync by hand.import type { CoreConfig } from '../../../config';import type { ServiceDeps } from '../../../services';diff --git a/packages/core/src/modules/assistant/src/tools/base.ts b/packages/core/src/modules/assistant/src/tools/base.tsindex aa0373c81..1d64e2f7c 100644--- a/packages/core/src/modules/assistant/src/tools/base.ts+++ b/packages/core/src/modules/assistant/src/tools/base.ts@@ -40,8 +40,7 @@ import {/** Series label for `get_rolling_active_users`' chart — always daily uniques. */const DAILY_ACTIVE_USERS_SERIES_LABEL = 'Daily active users';-// Helper, not vocabulary — ADR-008's ruling on objectToZodEnums: copy locally-// rather than import from a module.+// Helper, not vocabulary — copied locally rather than imported from a module.function objectToZodEnums<K extends string>(obj: Record<K, unknown>): [K, ...K[]] {diff --git a/packages/core/src/modules/assistant/src/tools/helpers.ts b/packages/core/src/modules/assistant/src/tools/helpers.tsindex cf2e7e3c7..e5079ad7d 100644--- a/packages/core/src/modules/assistant/src/tools/helpers.ts+++ b/packages/core/src/modules/assistant/src/tools/helpers.ts@@ -99,29 +99,17 @@ export function truncateRows<T>(/*** Compact output from `listEventPropertiesCore` for consumption by the LLM.*- * Two buckets come back:+ * `columns` are top-level event columns, used bare in filters/breakdowns.+ * `properties` are custom keys from the JSON `properties` map, used as+ * `properties.<key>`.*- * - `columns`: top-level event columns (path, referrer, country, …).- * Apply to every event. Use the bare name in filters/breakdowns.- * - `properties`: custom keys from the JSON `properties` map. Use- * prefixed as `properties.<key>` in filters/breakdowns.- *- * The raw `properties` rows are ordered alphabetically and capped at 500.- * That shape has three token-hungry problems when passed back:- *- * 1. Dotted sub-keys explode. A single property like `__query` or `data`- * with dynamic sub-paths surfaces as hundreds of rows- * (`__query.foo`, `__query.bar`, `__query.<uuid>`, …). They flood- * alphabetically-first — 300 of them before `country` appears.- * 2. `event_name` is repeated on every row. When the caller passed an- * `eventName` filter it's a constant string; we only need it once.- * 3. The full 500-row dump is rarely necessary — the model uses this- * list for filter/breakdown discovery, which is satisfied by the- * top ~50 distinct roots.- *- * This helper collapses dotted keys to their root segment, dedupes, orders- * by frequency (how many original sub-keys fell under each root — a decent- * "how prominent is this property" signal), and caps the list.+ * The raw `properties` rows are ordered alphabetically and capped at 500,+ * which is token-hungry: a property with dynamic sub-paths (`__query.foo`,+ * `__query.<uuid>`, …) can flood the list with hundreds of rows before an+ * unrelated property like `country` appears, and `event_name` repeats on+ * every row even when it's a filter-supplied constant. This collapses+ * dotted keys to their root, dedupes, orders by frequency, and caps the+ * list to the ~50 roots the model needs for filter/breakdown discovery.*/export function compactEventProperties(raw: {@@ -233,9 +221,6 @@ export function pageContextFilters();}-/**- * Compute the immediately-preceding period given a (start, end) range.- */export function previousPeriod(startDate: string, endDate: string) {const start = new Date(startDate).getTime();const end = new Date(endDate).getTime();@@ -249,9 +234,6 @@ export function previousPeriod(startDate: string, endDate: string) {/** Where a dev box's dashboard runs when DASHBOARD_URL is not set. */const DEFAULT_DASHBOARD_URL = 'http://localhost:3000';-/**- * Build a clickable dashboard URL for a tool result.- */export function dashboardUrl(config: CoreConfig,organizationId: string,diff --git a/packages/core/src/modules/assistant/src/tools/index.ts b/packages/core/src/modules/assistant/src/tools/index.tsindex 48e100842..9710c54e2 100644--- a/packages/core/src/modules/assistant/src/tools/index.ts+++ b/packages/core/src/modules/assistant/src/tools/index.ts@@ -16,7 +16,7 @@ import * as ui from './ui';// A tool is BUILT per unit of work, from the `deps` the route already holds:// `@better-agent/core`'s tool-handler signature has no context parameter, so-// each handler closes over them instead (R15). The lists are typed loosely as+// each handler closes over them instead. The lists are typed loosely as// `(deps) => AgentToolDefinition` — without the cast, TypeScript tries to// compute the union of every tool's schema + result type and hits its// instantiation depth limit.diff --git a/packages/core/src/modules/auth/auth.rpc.ts b/packages/core/src/modules/auth/auth.rpc.tsindex 52067589b..d3cda9dac 100644--- a/packages/core/src/modules/auth/auth.rpc.ts+++ b/packages/core/src/modules/auth/auth.rpc.ts@@ -3,10 +3,9 @@// only sees a TOP-LEVEL `projectId` / `organizationId`, so anything resolved// from another id needs its own.//-// V1's `rateLimitMiddleware` wrappers are mounted below through-// `createRateLimitMiddleware` (rpc/base.ts) with V1's own limits, procedure for-// procedure. Blocks are keyed per procedure and per trusted IP, and escalate on-// repeat offence — see rpc/rate-limit.ts.+// Rate limits are mounted below through `createRateLimitMiddleware`+// (rpc/base.ts), procedure for procedure. Blocks are keyed per procedure and+// per trusted IP, and escalate on repeat offence — see rpc/rate-limit.ts.//// This module has no queue/cron of its own, so there is no `ctx.services.auth`// entry here — same shape as `user`/`project`.diff --git a/packages/core/src/modules/auth/auth.service.access.test.ts b/packages/core/src/modules/auth/auth.service.access.test.tsindex d98c1ef1f..0385bd701 100644--- a/packages/core/src/modules/auth/auth.service.access.test.ts+++ b/packages/core/src/modules/auth/auth.service.access.test.ts@@ -1,9 +1,9 @@-// Auth.service.ts is now the ONLY place the ladder is bound to real lookups,-// via the lazy, memoized `getAccessChecks`. This proves that seam still takes a+// Auth.service.ts is the only place the ladder is bound to real lookups, via+// the lazy, memoized `getAccessChecks`. This proves that seam still takes a// fake `AccessLookups` cleanly — mocking `../../shared/access-lookups`, which-// auth.service.ts reaches only through a dynamic import and which owns all four-// lookups since M15-005 — and that ADR-011's fail-closed ordering, messages and-// write-level gate are unchanged.+// auth.service.ts reaches only through a dynamic import and which owns all+// four lookups — and that the fail-closed ordering, messages and write-level+// gate are unchanged.import { afterAll, beforeAll, expect, mock, test } from 'bun:test';import { testServices } from '../../../test/service-deps';@@ -56,9 +56,8 @@ afterAll(() => {});function authService() {- // Both arguments are ignored by `createAuthService` — it takes them so the- // composition root stays a flat list. Every member reaches the mocked lookups- // above.+ // Both arguments are ignored by `createAuthService`. Every member reaches+ // the mocked lookups above.return createAuthService({} as import('../../services').ServiceDeps,testServices()diff --git a/packages/core/src/modules/auth/auth.service.ts b/packages/core/src/modules/auth/auth.service.tsindex e63ad2195..9dffacfe5 100644--- a/packages/core/src/modules/auth/auth.service.ts+++ b/packages/core/src/modules/auth/auth.service.ts@@ -6,13 +6,6 @@// lookups exactly here, once, instead of once per module in a// `modules/*/src/access.ts` copy — see `getAccessChecks` below for the binding// itself.-//-// Every module in this wave, INCLUDING auth's own remaining lazy imports, moves-// to `ServiceDeps`. `signUpWithEmail`/`signInWithEmail`/TOTP/-// password-reset/OAuth-callback all take `deps` now and reach Postgres as-// `deps.db`; `./src/login-session.ts` and `./src/registration.ts` do the same-// and are plain static imports here (neither cycles back to this file).-// `auth.rpc.ts` already carries a `Ctx` and passes it straight through.import { z } from 'zod';import type { CoreConfig } from '../../config';@@ -101,8 +94,7 @@ let accessChecksPromise: Promise<ProjectAccessChecks> | undefined;* is built on the first actual check. An earlier attempt bound it at module* scope and hung `bun test` for 30 minutes.*- * Still a `Promise` because the contract is awaited at every call site and was- * what each module's own access file used to resolve lazily.+ * Still a `Promise` because the contract is awaited at every call site.** `integration.service.ts` and `subscription.service.ts` import this directly* instead of going through `ctx.services.auth`: both are called with a bare@@ -142,8 +134,7 @@ export function resetAccessChecksForTests(): void {* nothing here. This is for the paths the builder cannot decide: the* share-aware `chartProcedure` / `overviewProcedure`, which are public because* a valid share link is an alternative to being signed in, and only demand a- * user when no share was presented. Until M15-007 it was copied, unexported,- * into 28 `*.rpc.ts` files.+ * user when no share was presented.*/export function requireLogin(userId: string | null | undefined): string {if (!userId) {@@ -153,8 +144,7 @@ export function requireLogin(userId: string | null | undefined): string {}/**- * Registered in `services.ts`. Ignores BOTH arguments, and takes them only- * because ADR-022 R3 keeps the composition root a flat list: every member here+ * Registered in `services.ts`. Ignores BOTH arguments: every member here* is either pure, reads its own env, or — for the access checks — reaches the* shared, memoized `getAccessChecks` above, whose lookups are `cacheable`* (their key is derived from the call's arguments, so they cannot take a@@ -271,13 +261,8 @@ export function createAuthService(}// ---------------------------------------------------------------------- The-// Prisma-touching half: sign-up/sign-in, TOTP challenges, password reset, share-// unlock and the github/google OAuth callback. This is the logic-// packages/trpc/src/routers/auth.ts and-// apps/api/src/controllers/oauth-callback.controller.tsx held inline — neither-// ever had a `packages/db/src/services/*` home to move from, unlike every other-// M5/M6 module, so it is written directly here (DELEGATE PATTERN: both V1's-// trpc router and this package's own auth.rpc.ts call these same functions).+// Prisma-touching half: sign-up/sign-in, TOTP challenges, password reset,+// share unlock and the github/google OAuth callback.//// Session/registration access is `deps.db`, via static imports of// `./src/login-session` and `./src/registration` — neither cycles back to this@@ -317,7 +302,6 @@ import { getIsRegistrationAllowed } from './src/registration';const TWO_FACTOR_COOKIE = '2fa_challenge';const TWO_FACTOR_CHALLENGE_TTL_SECONDS = 5 * 60;const INVITE_COOKIE = 'inviteId';-// V1's reset-password token: 10 minutes.const RESET_PASSWORD_TTL_MS = 1000 * 60 * 10;export type AuthProvider = 'email' | 'google' | 'github';@@ -508,9 +492,9 @@ export async function signInWithEmail(throw new TRPCNotFoundError('User does not exists');}- // If the password starts with $argon2 we use the new password hashing,- // otherwise it's legacy from Clerk which used bcrypt (ADR-011: no legacy- // branch — those rows are nulled, so this is now just a generic reject).+ // If the password starts with $argon2 we use the new password hashing;+ // any other value is a legacy bcrypt row (from Clerk) that has been+ // nulled, so this is now just a generic reject.if (!user.account.password?.startsWith('$argon2')) {throw new TRPCAccessError('Reset your password, old password has expired');}@@ -873,10 +857,9 @@ export interface SignInShareInput {shareType?: 'overview' | 'dashboard' | 'report';}-/** Share's three lookups arrive through the composition root's thunk+/** Share's three lookups arrive through the composition root's thunk.* Not a dynamic import: `share.service.ts` statically imports this file's* `hashPassword`, so a static edge back would be a real cycle. */-/** A week, as V1's `maxAge` was. */const SHARE_ACCESS_MAX_AGE_SECONDS = 60 * 60 * 24 * 7;export async function signInToShare(@@ -930,11 +913,10 @@ export async function signInToShare(}// ------------------------------------------------------------------------// The github/google OAuth callback (apps/api's /oauth/{github,google}/callback-// — DELEGATE PATTERN, same shape as gsc.service.ts#completeGscOAuthCallback).-// State/query parsing and cookie reads stay in each transport (Fastify's-// controller, this package's own auth.routes.ts): only the token exchange,-// user lookup/creation and session issuance live here.+// The github/google OAuth callback (apps/api's /oauth/{github,google}/callback,+// same shape as gsc.service.ts#completeGscOAuthCallback). State/query parsing+// and cookie reads stay in each transport: only the token exchange, user+// lookup/creation and session issuance live here.export interface OAuthUser {id: string;@@ -944,8 +926,8 @@ export interface OAuthUser {}/** Raised for every *expected* failure — the caller shows `.message` verbatim- * in the `/login?error=` redirect, same as V1's `LogError`. Anything else- * thrown is an unexpected bug and the caller shows a generic message. */+ * in the `/login?error=` redirect. Anything else thrown is an unexpected bug+ * and the caller shows a generic message. */export class OAuthCallbackError extends Error {constructor(message: string,@@ -1059,9 +1041,8 @@ export async function fetchGoogleOAuthUser(}/**- * Checked by the caller BEFORE exchanging `code` for tokens — same ordering- * as V1's `validateOAuthCallback`, so a forged `state` never costs an IdP- * round-trip.+ * Checked by the caller BEFORE exchanging `code` for tokens, so a forged+ * `state` never costs an IdP round-trip.*/export function assertOAuthState(provider: 'github' | 'google',diff --git a/packages/core/src/modules/auth/src/access.ts b/packages/core/src/modules/auth/src/access.tsindex cf2038a5d..0e5533aed 100644--- a/packages/core/src/modules/auth/src/access.ts+++ b/packages/core/src/modules/auth/src/access.ts@@ -1,20 +1,15 @@-// The permission ladder. M15-009 (R22): it lives in the auth module, not in-// `shared/` — it threw a transport error (`TRPCForbiddenError`) from the bottom-// layer, and R10 puts every access check in the auth service and the procedure+// The permission ladder. It lives in the auth module, not in `shared/` — it+// throws a transport error (`TRPCForbiddenError`) from the bottom layer, and+// R10 puts every access check in the auth service and the procedure// builders.//-// Ported verbatim from packages/trpc/src/access.ts — the rules, the fail-closed-// ordering and the messages are unchanged, and ADR-011 invariants 5 and 6 bind-// them. What changed is the shape: the four data lookups arrive as an injected-// `AccessLookups` instead of being imported from `@openpanel/db`.-//-// That injection is not decoration. Core must stay importable without a-// database — `bun test` loads this package with no DATABASE_URL and no Prisma-// client — and it is the same seam `createCacheMiddleware` and-// `createRateLimitMiddleware` already use in rpc/base.ts. `auth.service.ts`'s-// `createAccessChecks` call binds it to the real services; V1's now-deleted-// `@openpanel/trpc` used to bind it the same way; a test binds it to two-// functions.+// The four data lookups arrive as an injected `AccessLookups` instead of+// being imported from `@openpanel/db`. That injection is not decoration:+// core must stay importable without a database — `bun test` loads this+// package with no DATABASE_URL and no Prisma client — and it is the same+// seam `createCacheMiddleware` and `createRateLimitMiddleware` already use+// in rpc/base.ts. `auth.service.ts`'s `createAccessChecks` call binds it to+// the real services; a test binds it to two functions.import { TRPCForbiddenError } from '../../../rpc/errors';@@ -28,10 +23,10 @@ export interface OrganizationAccessLike {}/**- * The four reads the ladder needs. Deliberately the *service* functions, not a- * Prisma client: `getProjectAccess` carries the 5-minute Redis cache and the- * fail-closed swallow (ADR-011 invariant 5, 7), and reimplementing it here- * would be a second, diverging copy of the rule this file exists to enforce.+ * The four reads the ladder needs. Deliberately the *service* functions, not+ * a Prisma client: `getProjectAccess` carries the 5-minute Redis cache and+ * the fail-closed swallow, and reimplementing it here would be a second,+ * diverging copy of the rule this file exists to enforce.*/export interface AccessLookups<TProjectAccess extends ProjectAccessLike = ProjectAccessLike,@@ -41,7 +36,7 @@ export interface AccessLookups<userId: string;projectId: string;}): Promise<TProjectAccess | null>;- /** ADR-011 invariant 6: level in {write, admin}; admin stays a superset. */+ /** level in {write, admin}; admin stays a superset. */canWriteProject(access: TProjectAccess | null): boolean;getOrganizationAccess(args: {userId: string;diff --git a/packages/core/src/modules/auth/src/registration.ts b/packages/core/src/modules/auth/src/registration.tsindex 651e197da..1da439bec 100644--- a/packages/core/src/modules/auth/src/registration.ts+++ b/packages/core/src/modules/auth/src/registration.ts@@ -1,5 +1,3 @@-// Reaches Postgres as `deps.db`; the `loadDb` lazy loader is gone.-import type { ServiceDeps } from '../../../services';/** Only Postgres — narrowed so any of this module's several callers, none ofdiff --git a/packages/core/src/modules/chart/chart.constants.ts b/packages/core/src/modules/chart/chart.constants.tsindex 732849c34..40b47bad5 100644--- a/packages/core/src/modules/chart/chart.constants.ts+++ b/packages/core/src/modules/chart/chart.constants.ts@@ -1,16 +1,14 @@// The chart module's isomorphic surface: limits, zod schemas and the column-// allow-lists shared by more than one file here. Imports zod and sibling-// `*.constants.ts` only — anything needing `sql`, `deps` or a ClickHouse type-// belongs in a service or a `src/` file.+// allow-lists shared by more than one file here.import { z } from 'zod';import { zChartEvent } from '../report/report.constants';/*** Window the REST retention routes (`/insights/:projectId/retention`,- * `/engagement`) read when the caller names none; M31-003's default for the- * same fix, wider than engagement's 60-day churn bucket. Not applied to callers- * of the service that pass no dates: those still read all time.+ * `/engagement`) read when the caller names none, wider than engagement's+ * 60-day churn bucket. Not applied to callers of the service that pass no+ * dates: those still read all time.*/export const RETENTION_SERIES_DEFAULT_RANGE = '3m';@@ -21,13 +19,11 @@ export const DEFAULT_SANKEY_STEPS = 5;* Longest window `chart.sankey` will answer, in days.** Both of its statements scan every event in the range and hold one- * `groupArray` per session, so cost is linear in the window and `steps` bounds- * the answer rather than the work. Measured on the local production copy- * (2026-09-16, `bayse`, mode `after`, 3 steps, `use_query_condition_cache=0`),- * per statement: 871 ms / 515 MiB at 7 days, 2,361 ms / 1,329 MiB at 30,- * 3,832 ms / 2,060 MiB at 56 - about 60 ms and 31 MiB per day. The range- * picker offers `12m` and `lastYear`, which extrapolates to ~22 s and- * ~11.8 GiB per statement, twice per call: past what a node can answer at all.+ * `groupArray` per session, so cost is linear in the window and `steps`+ * bounds the answer rather than the work (~60ms and ~31MiB per day,+ * measured on the local production copy). The range picker's `12m` and+ * `lastYear` options would extrapolate to ~22s and ~11.8GiB per statement,+ * twice per call — past what a node can answer at all.** 93 is the widest span the picker's `3m` option can produce - the 92-day* June-August quarter plus the half-open end-of-day boundary@@ -61,10 +57,10 @@ export type IGetSankeyInput = z.infer<typeof zGetSankeyInput> & {};/**- * Top-level `profiles` columns a `profile.<field>` reference may resolve to,- * in V1's order. Both halves of the chart path read this one list: the SELECT- * side (`getProfilePropertySelect`, src/field-resolution.ts) and the filter- * side (`profileColumnSql`, src/table-filter-where.ts). Anything outside it is+ * Top-level `profiles` columns a `profile.<field>` reference may resolve to.+ * Both halves of the chart path read this one list: the SELECT side+ * (`getProfilePropertySelect`, src/field-resolution.ts) and the filter side+ * (`profileColumnSql`, src/table-filter-where.ts). Anything outside it is* not a column name and must never reach the SQL text.*/export const PROFILE_SELECT_COLUMNS = [diff --git a/packages/core/src/modules/chart/chart.rpc.ts b/packages/core/src/modules/chart/chart.rpc.tsindex 7d27a4b37..45f154374 100644--- a/packages/core/src/modules/chart/chart.rpc.ts+++ b/packages/core/src/modules/chart/chart.rpc.ts@@ -1,13 +1,12 @@-// The seven member-only procedures are back on `protectedProcedure`, so-// `enforceAccess` reads the top-level `projectId` before the input is parsed,-// exactly as V1 does.+// The seven member-only procedures use `protectedProcedure`, so+// `enforceAccess` reads the top-level `projectId` before the input is parsed.//-// `chartProcedure` (funnel, conversion, chart, aggregate, cohort) is V1's+// `chartProcedure` (funnel, conversion, chart, aggregate, cohort) is the// share-aware builder: `publicProcedure` plus one middleware that admits an// anonymous caller holding a valid share — `shareId` + `id` resolve the saved// report, and the request renders that report (the caller may only move the-// date window). The resolved report rides on `ctx.report`, as in V1, so a-// handler cannot forget to resolve it.+// date window). The resolved report rides on `ctx.report`, so a handler+// cannot forget to resolve it.import { z } from 'zod';import {@@ -74,9 +73,9 @@ async function resolveShare(}/**- * V1's `chartProcedure`. The share/membership decision runs BEFORE the input- * is parsed and puts the resolved report on the context, so a handler reads- * `ctx.report` instead of re-deciding who may see it.+ * The share/membership decision runs BEFORE the input is parsed and puts+ * the resolved report on the context, so a handler reads `ctx.report`+ * instead of re-deciding who may see it.*/const chartProcedure = publicProcedure.use(async ({ ctx, next, getRawInput }) => {diff --git a/packages/core/src/modules/chart/chart.service.test.ts b/packages/core/src/modules/chart/chart.service.test.tsindex 9d0ea04fc..28a97da4c 100644--- a/packages/core/src/modules/chart/chart.service.test.ts+++ b/packages/core/src/modules/chart/chart.service.test.ts@@ -5,7 +5,7 @@* all-cohorts paths run against seeded `cohort_members` + a Postgres cohort.** Fixture (test/fixtures.ts, seeded per suite under its own project id so it- * can run concurrently with V1's suites, with the clock pinned to+ * can run concurrently with other suites, with the clock pinned to* test/fixture-clock.ts's 12:00 UTC anchor): Alice — 3 events 2 days ago* (Chrome, page_view /home); Charlie — 5 events 5 days ago (Firefox,* screen_view + page_view /shop, purchase 9900); Bob — no events. This suite@@ -205,7 +205,7 @@ describe('executeChart', () => {// Alice is outside the cohort, Charlie inside — both rows must survive.expect(single.metrics.sum).toBe(2);expect(single.series).toHaveLength(2);- // All-cohorts is an INNER JOIN on membership (V1): non-members drop out.+ // All-cohorts is an INNER JOIN on membership: non-members drop out.expect(all.series.map((serie) => [serie.names, serie.metrics.sum])).toEqual([[['page_view', COHORT_NAME], 1]]);diff --git a/packages/core/src/modules/chart/chart.service.ts b/packages/core/src/modules/chart/chart.service.tsindex daadade7c..99189c813 100644--- a/packages/core/src/modules/chart/chart.service.ts+++ b/packages/core/src/modules/chart/chart.service.ts@@ -1,9 +1,9 @@// Every ClickHouse statement this module runs is a `sql` fragment from// src/sql.ts. Funnel, conversion, sankey and retention are dispatched to the// sibling `*.service.ts` files. The one thing still value-imported from-// `@openpanel/db` under `./src/` is ADR-013's `sql` tag, which ADR-007 keeps in-// `packages/db` by name: a compile-time template tag, no client and no request-// scope.+// `@openpanel/db` under `./src/` is the `sql` tag, which stays in+// `packages/db` by name: a compile-time template tag, no client and no+// request scope.import { getChartPrevStartEndDate } from '@openpanel/shared';import { flatten, map, pipe, prop, sort, uniq } from 'ramda';@@ -112,7 +112,7 @@ export {} from './src/sql';// Types only: `packages/core/src/index.ts` re-exports these two. The four// statement functions beside them had no consumer through this file — the-// engine and the sibling services import ./src/statement directly (R13).+// engine and the sibling services import ./src/statement directly.export type {AggregateChartSqlInput,ChartSqlInput,@@ -640,7 +640,7 @@ export interface ChartBucketProfilesRequest {breakdowns?: Record<string, string>;}-/** Profiles behind one data point of a time-series chart (V1 `getProfiles`). */+/** Profiles behind one data point of a time-series chart. */export async function getChartBucketProfiles(deps: ServiceDeps,input: ChartBucketProfilesRequest@@ -739,12 +739,11 @@ export async function getFunnelStepProfiles(// --- service -----------------------------------------------------------------// The funnel, conversion, sankey and retention services live in this module's-// own sibling files, not in modules of their own (ADR-007 gives one service per-// module), so they FOLD INTO `chart` rather than becoming four more `Services`-// members: chart.service.ts is already the dispatcher every caller goes through-// (`getFunnelChart` / `getConversionChart` / `getSankeyChart` /-// `getRetentionChart`), and a `Services` key per file would name four things-// that are not modules.+// own sibling files rather than in modules of their own, so they FOLD INTO+// `chart` rather than becoming four more `Services` members: chart.service.ts+// is already the dispatcher every caller goes through (`getFunnelChart` /+// `getConversionChart` / `getSankeyChart` / `getRetentionChart`), and a+// `Services` key per file would name four things that are not modules.export function createChartService(deps: ServiceDeps,diff --git a/packages/core/src/modules/chart/funnel.service.ts b/packages/core/src/modules/chart/funnel.service.tsindex 3e97a60a1..159ad3ef0 100644--- a/packages/core/src/modules/chart/funnel.service.ts+++ b/packages/core/src/modules/chart/funnel.service.ts@@ -433,10 +433,10 @@ export async function getFunnelProfileIds(}/**- * `ctx.services.chart`'s funnel half, as its own module factory (ADR-007: "each- * service is `createXService(deps)`"). `createChartService` composes this- * rather than re-binding these functions itself, so the chart module keeps one- * registry key while every `*.service.ts` file exposes its own factory.+ * `ctx.services.chart`'s funnel half, as its own module factory.+ * `createChartService` composes this rather than re-binding these functions+ * itself, so the chart module keeps one registry key while this file exposes+ * its own factory.*/export function createFunnelService(deps: ServiceDeps,diff --git a/packages/core/src/modules/chart/retention.service.ts b/packages/core/src/modules/chart/retention.service.tsindex 1c13d40d7..b687ab605 100644--- a/packages/core/src/modules/chart/retention.service.ts+++ b/packages/core/src/modules/chart/retention.service.ts@@ -93,7 +93,6 @@ export function getRetentionSeries(}// https://medium.com/@andre_bodro/how-to-fast-calculating-mau-in-clickhouse-fd793559b229-// Rolling active usersexport function getRollingActiveUsers(deps: ServiceDeps,{ projectId, days }: { projectId: string; days: number }diff --git a/packages/core/src/modules/chart/sankey.service.test.ts b/packages/core/src/modules/chart/sankey.service.test.tsindex 29c9147de..ee68860cd 100644--- a/packages/core/src/modules/chart/sankey.service.test.ts+++ b/packages/core/src/modules/chart/sankey.service.test.ts@@ -1,5 +1,5 @@/**- * `chart.sankey`'s window bound (M25 Group C fix 9, §12 fix 9).+ * `chart.sankey`'s window bound.** Both sankey statements scan every event in the range and hold one* `groupArray` per session, so the `12m`/`lastYear` the range picker offers@@ -9,8 +9,7 @@* The bound belongs to the `chart.sankey` procedure specifically, so the* endpoint case below drives `getSankeyChart` rather than `getSankey`: the* REST, MCP and assistant surfaces reach `getSankey` through- * `getUserFlowCore` with caller-supplied dates and are outside fix 9's- * endpoint list.+ * `getUserFlowCore` with caller-supplied dates and are outside this bound.*/import { describe, expect, it } from 'bun:test';diff --git a/packages/core/src/modules/chart/sankey.service.ts b/packages/core/src/modules/chart/sankey.service.tsindex 8c78a7863..6230a5f3a 100644--- a/packages/core/src/modules/chart/sankey.service.ts+++ b/packages/core/src/modules/chart/sankey.service.ts@@ -36,7 +36,7 @@ const PERCENT = 100;const FIRST_STEP = 1;// `packages/core/src/index.ts` names this file as the schema's source; the-// schema itself lives in chart.constants.ts (R8).+// schema itself lives in chart.constants.ts.export { type IGetSankeyInput, zGetSankeyInput } from './chart.constants';export interface SankeyNode {@@ -59,7 +59,7 @@ export interface SankeyResult {links: SankeyLink[];}-/** Every node the builder emits carries all three; the public type keeps V1's optionals. */+/** Every node the builder emits carries all three; the public type keeps them optional for other callers. */type ResolvedSankeyNode = SankeyNode & {percentage: number;value: number;@@ -132,8 +132,8 @@ function toSankeyEvent(* malformed range is rejected.** Applied by `getSankeyChart`, the `chart.sankey` entry point, and not by- * `getSankey` itself: §12 fix 9 bounds that procedure specifically, because it- * is the range picker that offers `12m`/`lastYear`. The REST+ * `getSankey` itself: it bounds that procedure specifically, because it is+ * the range picker that offers `12m`/`lastYear`. The REST* `/insights/:projectId/user_flow` route, the MCP `get_user_flow` tool and the* assistant tool take caller-supplied dates, so they are not covered by the* range picker's cap.diff --git a/packages/core/src/modules/chart/src/compiled.ts b/packages/core/src/modules/chart/src/compiled.tsindex 7df111f05..03999a158 100644--- a/packages/core/src/modules/chart/src/compiled.ts+++ b/packages/core/src/modules/chart/src/compiled.ts@@ -1,11 +1,10 @@-// The ONE place the chart module splices pre-compiled SQL text, and the home-// of V1's profile-property-ref rewrite.+// The ONE place the chart module splices pre-compiled SQL text.//// Both filter compilers (./filter-where.ts, ./table-filter-where.ts) and the-// field resolver (./field-resolution.ts) return `SqlFragment`s now, so nothing-// crosses `compiledText` from them any more. What is left are the places the-// chart builders splice a name they generated themselves — CTE names, `b_<n>`-// / `label_<n>` aliases, a `toStartOf*` keyword, the backtick-quoted+// field resolver (./field-resolution.ts) return `SqlFragment`s, so nothing+// crosses `compiledText` from them. What is left are the places the chart+// builders splice a name they generated themselves — CTE names, `b_<n>` /+// `label_<n>` aliases, a `toStartOf*` keyword, the backtick-quoted// `profile.properties.<key>` CTE alias — none of which is a value and none of// which `sql.id` can express. It stays a named export in one file, not a// `sql.raw()`, so the census is a grep.@@ -30,8 +29,8 @@ function narrowedProfileColumn(key: string): string {/*** Rewrite `profile.properties['<key>']` -> `` `profile.properties.<key>` ``- * for the narrowed keys. V1 ran this over the finished query TEXT; it never- * matched a value, because an escaped literal cannot contain `['`.+ * for the narrowed keys. This never matches a value, because an escaped+ * literal cannot contain `['`.*/export function rewriteProfilePropertyRefs(sql: string,diff --git a/packages/core/src/modules/chart/src/conversion.sql.ts b/packages/core/src/modules/chart/src/conversion.sql.tsindex df239ec73..dced41210 100644--- a/packages/core/src/modules/chart/src/conversion.sql.ts+++ b/packages/core/src/modules/chart/src/conversion.sql.ts@@ -22,7 +22,6 @@ const CONVERSION_RATE_DECIMALS = 2;const CONVERSION_GROUPS = ['session_id', 'profile_id'] as const;export type ConversionGroup = (typeof CONVERSION_GROUPS)[number];-/** V1 `clix.toStartOf(created_at, interval)` — no timezone argument. */function intervalBucket(interval: IInterval): SqlFragment {switch (interval) {case 'minute':@@ -86,7 +85,7 @@ function groupJoin(needed: boolean, projectId: string): SqlFragment {: sql.empty;}-/** V1 `ConversionService.getConversion`: one windowFunnel scan per bucket. */+/** One windowFunnel scan per bucket. */export function conversionQuery(input: ConversionQueryInput): SqlFragment {const {projectId,diff --git a/packages/core/src/modules/chart/src/engine/compute.ts b/packages/core/src/modules/chart/src/engine/compute.tsindex 634a76fa9..e3dd5a68a 100644--- a/packages/core/src/modules/chart/src/engine/compute.ts+++ b/packages/core/src/modules/chart/src/engine/compute.ts@@ -67,8 +67,8 @@ export function compute((a, b) => new Date(a).getTime() - new Date(b).getTime());- // Calculate total_count for the formula using the same formula applied to input series' total_count values- // total_count is constant across all dates for a breakdown group, so compute it once+ // total_count is constant across all dates for a breakdown group, so+ // it's computed once here rather than per date.const totalCountScope: Record<string, number> = {};definitions.slice(0, formulaIndex).forEach((_depDef, depIndex) => {const readableId = alphabetIds[depIndex];@@ -76,10 +76,8 @@ export function compute(return;}- // Find the series for this dependency in the current breakdown groupconst depSeries = seriesByIndex.get(depIndex);if (depSeries) {- // Get total_count from any data point (it's the same for all dates)const totalCount = depSeries.data.find((d) => d.total_count != null)?.total_count;@@ -104,7 +102,6 @@ export function compute(}});- // Evaluate formula for total_countconst totalCountResult = evaluateFormula(formula.formula,totalCountScope@@ -112,7 +109,6 @@ export function compute(const formulaTotalCount =totalCountResult === undefined ? undefined : round(totalCountResult, 2);- // Calculate formula for each dateconst formulaData = sortedDates.map((date) => {const scope: Record<string, number> = {};@@ -122,7 +118,6 @@ export function compute(return;}- // Find the series for this dependency in the current breakdown groupconst depSeries = seriesByIndex.get(depIndex);if (depSeries) {const dataPoint = depSeries.data.find((d) => d.date === date);diff --git a/packages/core/src/modules/chart/src/engine/format.ts b/packages/core/src/modules/chart/src/engine/format.tsindex 159e1af5d..50d8409e9 100644--- a/packages/core/src/modules/chart/src/engine/format.ts+++ b/packages/core/src/modules/chart/src/engine/format.ts@@ -48,28 +48,23 @@ export function format(: concreteSeries;const series = visibleConcreteSeries.map((cs) => {- // Find definition for this seriesconst definition = definitions[cs.definitionIndex];const alphaId = includeAlphaIds? alphabetIds[cs.definitionIndex]: undefined;- // Build display name with optional alpha IDlet displayName: string[];- // Replace the first name (which is the event name) with the display name if it existsconst names = cs.name.slice(0);if (cs.definition.displayName) {names.splice(0, 1, cs.definition.displayName);}- // Add the alpha ID to the first name if it existsif (alphaId) {displayName = [`(${alphaId}) ${names[0]}`, ...names.slice(1)];} else {displayName = names;}- // Calculate metrics for this seriesconst counts = cs.data.map((d) => d.count);const metrics = {sum: sum(counts),@@ -79,13 +74,11 @@ export function format(count: cs.data.find((item) => !!item.total_count)?.total_count,};- // Build event object for compatibilityconst eventName =definition?.type === 'formula'? definition.displayName || definition.formula || 'Formula': definition?.name || cs.context.event || 'unknown';- // Find matching previous seriesconst previousSerie = previousSeries?.find((ps) =>ps.definitionIndex === cs.definitionIndex &&@@ -152,7 +145,6 @@ export function format(};});- // Sort series by sum (biggest first)series.sort((a, b) => b.metrics.sum - a.metrics.sum);// Calculate global metrics (excluding hidden series)diff --git a/packages/core/src/modules/chart/src/field-resolution.test.ts b/packages/core/src/modules/chart/src/field-resolution.test.tsindex e2430c8c3..de44652a1 100644--- a/packages/core/src/modules/chart/src/field-resolution.test.ts+++ b/packages/core/src/modules/chart/src/field-resolution.test.ts@@ -11,8 +11,6 @@* without realising those live in the `properties` map on the events table; - a* saved report referenced a custom property (`temple_name`) as if it were a* top-level column.- *- * All five errors logged in HyperDX 2026-05-14 → 2026-05-17 are covered here.*/import { describe, expect, it } from 'bun:test';import { isKnownEventField, normalizeEventField } from './field-resolution';@@ -87,12 +85,11 @@ describe('isKnownEventField', () => {});it('rejects unknown identifiers — these used to leak into SQL', () => {- // HyperDX regression: psycalc-app funnel emitted `cohort as b_0` even- // though the funnel doesn't support all-cohorts. The funnel-side filter- // is what blocks it now; this asserts the breakdown-name check itself- // still distinguishes properties (`properties.foo`) from raw identifiers- // by accepting both — the funnel/chart drop logic relies on the cohort- // case being valid at this layer.+ // This check must still distinguish properties (`properties.foo`) from+ // raw identifiers by accepting both — the funnel/chart drop logic relies+ // on the cohort case being valid at this layer, even though a funnel+ // itself doesn't support all-cohorts (blocked by the funnel-side filter,+ // not here).expect(isKnownEventField('temple_name')).toBe(false);expect(isKnownEventField('totally_made_up_column')).toBe(false);expect(isKnownEventField('')).toBe(false);diff --git a/packages/core/src/modules/chart/src/field-resolution.ts b/packages/core/src/modules/chart/src/field-resolution.tsindex 618a0b871..787772595 100644--- a/packages/core/src/modules/chart/src/field-resolution.ts+++ b/packages/core/src/modules/chart/src/field-resolution.ts@@ -1,15 +1,12 @@/** biome-ignore-all lint/style/useDefaultSwitchClause: switch cases are exhaustive by design */-// V1's chart field resolution, moved verbatim from-// packages/db/src/services/chart.service.ts: how a report's field name-// (`referrerName`, `utm_source`, `properties.x.*`, `profile.email`,-// `group.name`, `cohort:<id>`, `has_profile`) becomes a ClickHouse expression,-// plus the profile-CTE narrowing helpers.+// Chart field resolution: how a report's field name (`referrerName`,+// `utm_source`, `properties.x.*`, `profile.email`, `group.name`,+// `cohort:<id>`, `has_profile`) becomes a ClickHouse expression, plus the+// profile-CTE narrowing helpers.//-// Converted every resolver onto the `sql` tag: each one returns a `SqlFragment`-// whose values — cohort ids, cohort labels, project ids and the-// `properties[...]` map keys — bind as `{pN:Type}` params, and whose-// identifiers go through `sql.id`. Callers interpolate the fragment directly;-// nothing wraps it in `compiledText` any more.+// Each resolver returns a `SqlFragment` whose values — cohort ids, cohort+// labels, project ids and the `properties[...]` map keys — bind as+// `{pN:Type}` params, and whose identifiers go through `sql.id`.//// The one piece of text this file still builds is the backtick-quoted CTE alias// `` `profile.properties.<key>` `` (see `profilePropertiesCteSelect`), which is@@ -260,8 +257,8 @@ export function cohortBreakdownLabelExpr(/*** The membership subselect both filter compilers use for `inCohort` /- * `notInCohort`. V1 wrote a plain `IN (subquery)` here; ADR-013 conversions- * never change `IN` / `GLOBAL IN` in either direction.+ * `notInCohort`. Uses a plain `IN (subquery)`, not `GLOBAL IN` — preserved+ * deliberately as an accepted trade-off, not an oversight.*/export function buildCohortMembersSubselect(cohortIds: string[],@@ -290,9 +287,9 @@ export function buildAllCohortsLabelExpr(/*** Cohort IDs that need a `cohort_<id>` JOIN alias to be wired up by the- * caller. After filter SQL became self-contained, only cohort *breakdowns*- * require the JOIN — they reference `cohort_<id>.profile_id` in their- * SELECT expression via `getSelectPropertyKey`.+ * caller. Only cohort *breakdowns* require the JOIN — they reference+ * `cohort_<id>.profile_id` in their SELECT expression via+ * `getSelectPropertyKey`. Filter SQL is self-contained and doesn't need it.*/export function collectBreakdownCohortIds(breakdowns: IChartBreakdown[]@@ -395,11 +392,11 @@ function matchPropertyMapPrefix(property: string): string | undefined {/*** True when `getSelectPropertyKey` renders an ARRAY expression rather than a- * scalar. V1 decided this by testing the rendered TEXT for a `%`, which is- * reachable two ways: the wildcard branch emits `transformPropertyKey`'s- * pattern, and a NON-wildcard key containing a literal `%` also matched. Both- * are reproduced here — including the second, which is a V1 defect- * (`properties.a%b` is treated as an array and fails at ClickHouse).+ * scalar, decided by testing the rendered TEXT for a `%`. That's reachable+ * two ways: the wildcard branch emits `transformPropertyKey`'s pattern, and a+ * NON-wildcard key containing a literal `%` also matches — a known defect+ * (`properties.a%b` is treated as an array and fails at ClickHouse), kept for+ * behavioral parity.*/export function isWildcardPropertyKey(rawProperty: string): boolean {const property = normalizeEventField(rawProperty);@@ -532,8 +529,8 @@ export function profilePropertiesCteSelect(/*** The top-level profiles columns a chart's `profile.*` references read —- * `id` always (the join key), then `properties` / the scalar columns V1's- * `getProfileFields` recognised, in first-seen order.+ * `id` always (the join key), then `properties` / the recognized scalar+ * columns, in first-seen order.*/export function collectProfileCteFields(refs: { name: string }[]): string[] {const fields = new Set<string>(['id']);diff --git a/packages/core/src/modules/chart/src/filter-cast.ts b/packages/core/src/modules/chart/src/filter-cast.tsindex a46ae57f3..4575dab19 100644--- a/packages/core/src/modules/chart/src/filter-cast.ts+++ b/packages/core/src/modules/chart/src/filter-cast.ts@@ -2,10 +2,8 @@// The typed-cast half of `buildFilterWhere` (./table-filter-where.ts) and of// `./filter-where.ts` (the event-property compiler).//-// Both filter compilers call the same pair now: `castFragment` and-// `buildTypedClauseFragment` bind every value as a `{name:Type}` param. The-// sqlstring-escaped text twins (`castSql` / `buildTypedClause`) died with-// `table-filter-where.ts`'s conversion in M12-003.+// Both filter compilers call the same pair: `castFragment` and+// `buildTypedClauseFragment` bind every value as a `{name:Type}` param.import {type SqlFragment,@@ -77,10 +75,10 @@ export function castFragment(}/**- * Bind one filter value the way `sqlstring.escape` rendered it: a string is a- * quoted literal, a number a numeric literal, a boolean `true`/`false`, and- * `null` the SQL keyword NULL — which only `Nullable` reproduces, since a- * `String` param bound to null arrives as the empty string.+ * Bind one filter value as its own typed SQL param: a string is a quoted+ * literal, a number a numeric literal, a boolean `true`/`false`, and `null`+ * the SQL keyword NULL — which only `Nullable` reproduces, since a `String`+ * param bound to null arrives as the empty string.*/function typedValueParam(value: IChartEventFilterValue): SqlSlot {if (value === null) {diff --git a/packages/core/src/modules/chart/src/filter-where.ts b/packages/core/src/modules/chart/src/filter-where.tsindex c1db10958..316b79455 100644--- a/packages/core/src/modules/chart/src/filter-where.ts+++ b/packages/core/src/modules/chart/src/filter-where.ts@@ -1,9 +1,9 @@/** biome-ignore-all lint/style/useDefaultSwitchClause: operator switches are exhaustive by design */-// V1's event filter compiler (`getEventFiltersWhereClause`), converted onto the+// The event filter compiler (`getEventFiltersWhereClause`), built on the// `sql` tag: every VALUE binds as a `{name:Type}` param and every identifier// goes through `sql.id` or a static fragment. The column expression for a// `properties.*` / `group.*` filter comes from field-resolution.ts, which-// returns a fragment of its own since M12-003 and is interpolated directly.+// returns a fragment of its own and is interpolated directly.import {type SqlFragment,@@ -31,24 +31,22 @@ import {export type FilterTableScope = 'events' | 'sessions';-/** One clause per surviving filter, keyed `f<index>` as V1 keyed them. */+/** One clause per surviving filter, keyed `f<index>`. */export type CompiledEventFilters = Record<string, SqlFragment>;// `sql.id`'s whitelist takes an array; the events branch has already rejected// anything outside the set by the time it gets here.const EVENT_COLUMN_ALLOWLIST = Array.from(EVENT_TOP_LEVEL_COLUMNS);-/** V1 stringified and trimmed every untyped value before escaping it. */function filterValue(value: unknown) {return sql.string(String(value).trim());}-/** V1's `(<a> OR <b>)` — the parenthesised disjunction. */function anyOf(clauses: SqlFragment[]): SqlFragment {return sql`(${sql.join(clauses, ' OR ')})`;}-/** V1's `arrayExists(x -> <a> OR <b>, <haystack>)` — no outer parentheses. */+/** No outer parentheses, unlike `anyOf` — `arrayExists` already wraps its predicate. */function anyItem(clauses: SqlFragment[], haystack: SqlSlot): SqlFragment {return sql`arrayExists(x -> ${sql.join(clauses, ' OR ')}, ${haystack})`;}diff --git a/packages/core/src/modules/chart/src/funnel.sql.test.ts b/packages/core/src/modules/chart/src/funnel.sql.test.tsindex 4a4a331c4..0ac5fa3a1 100644--- a/packages/core/src/modules/chart/src/funnel.sql.test.ts+++ b/packages/core/src/modules/chart/src/funnel.sql.test.ts@@ -84,9 +84,9 @@ interface Rendered {sql: string;params: Record<string, unknown>;/**- * `sql` with every placeholder substituted back to the literal V1 emitted.- * Since M12-003 the field resolver binds `properties[<key>]` keys and cohort- * labels too, so an assertion about the SHAPE of the expression reads this.+ * `sql` with every placeholder substituted back to its literal value. The+ * field resolver binds `properties[<key>]` keys and cohort labels too, so+ * an assertion about the SHAPE of the expression reads this.*/text: string;}diff --git a/packages/core/src/modules/chart/src/funnel.sql.ts b/packages/core/src/modules/chart/src/funnel.sql.tsindex e0efb69d2..4dbaad0ee 100644--- a/packages/core/src/modules/chart/src/funnel.sql.ts+++ b/packages/core/src/modules/chart/src/funnel.sql.ts@@ -103,10 +103,9 @@ export function knownFunnelBreakdowns(}/**- * V1 `getFunnelConditions`: one `<filters> AND events.name = <name>` per step.- * Exported because each step's complete condition has to appear twice — inside- * windowFunnel and in the row-level pre-filter — and funnel.sql.test.ts counts- * exactly that.+ * One `<filters> AND events.name = <name>` per step. Exported because each+ * step's complete condition has to appear twice — inside windowFunnel and in+ * the row-level pre-filter — and funnel.sql.test.ts counts exactly that.*/export function funnelStepConditions(eventSeries: IChartEvent[],@@ -182,8 +181,8 @@ function breakdownSelects(/*** The profiles columns this join may select, from the filter and breakdown* names the caller supplied. Both are user input, so both are matched against- * the allowlist — V1 split the filter names raw and spliced the result- * (main #512, GHSA-pc3q-gw7f-p2x2).+ * the allowlist — unsanitized splicing of a filter name into SQL was a real+ * vulnerability here (GHSA-pc3q-gw7f-p2x2).*/export function profileJoinFields(profileFilters: string[],@@ -222,7 +221,7 @@ function profileCteColumns(// Both the breakdown- and the filter-derived names are vetted above; the// allowlist here is the backstop that makes `sql.id` throw rather than// inline if either loop ever lets something else through (main #512,- // GHSA-pc3q-gw7f-p2x2). V1 spliced both unchecked.+ // GHSA-pc3q-gw7f-p2x2).const columns: SqlFragment[] = Array.from(fields).map((field) =>sql.id(field, FUNNEL_JOIN_COLUMNS));@@ -239,7 +238,7 @@ function profileCteColumns(return columns;}-/** V1 `getProfileFilters`: the `profile.`-prefixed filter names, unprefixed. */+/** The `profile.`-prefixed filter names, unprefixed. */function profileFilterNames(eventSeries: IChartEvent[]): string[] {return eventSeries.flatMap((event) =>@@ -353,7 +352,7 @@ export function funnelBase(input: FunnelBaseInput): FunnelBase {};}-/** V1 `FunnelService.getFunnel`: one row per (level, breakdown combination). */+/** One row per (level, breakdown combination). */export function funnelChartQuery(base: FunnelBase): SqlFragment {const aliases = base.breakdowns.map((_, index) => compiledText(`b_${index}`));const select = sql.join([sql`level`, ...aliases, sql`count() as count`]);@@ -387,7 +386,7 @@ function breakdownValueWhere(index: number, value: string): SqlFragment {return sql`${normalized} = ${sql.string(value)}`;}-/** V1 `getFunnelProfiles`: the distinct profiles at (or dropping off at) a step. */+/** The distinct profiles at (or dropping off at) a step. */export function funnelProfilesQuery(base: FunnelBase,input: FunnelProfilesInput@@ -407,8 +406,8 @@ export function funnelProfilesQuery(}/**- * Exported by V1 as `buildSessionsCte`; no in-repo caller. Reachable only- * through `packages/core/src/index.ts`, which still publishes the wrapper.+ * No in-repo caller. Reachable only through `packages/core/src/index.ts`,+ * which still publishes the wrapper.*/export function funnelSessionsQuery(input: {projectId: string;diff --git a/packages/core/src/modules/chart/src/property-key-escaping.test.ts b/packages/core/src/modules/chart/src/property-key-escaping.test.tsindex 3a8411b3e..f2e367280 100644--- a/packages/core/src/modules/chart/src/property-key-escaping.test.ts+++ b/packages/core/src/modules/chart/src/property-key-escaping.test.ts@@ -4,7 +4,7 @@* call. They end up inside a ClickHouse Map access, so a key carrying a* quote must stay one value — otherwise it closes the literal and the rest* of the key is parsed as SQL, next to the `project_id` predicate that scopes- * the query to one project (V1 #483).+ * the query to one project.** Here every key binds as a `{pN:String}` param, so the assertions are that* the rendered statement never carries the key's text, that the key comesdiff --git a/packages/core/src/modules/chart/src/retention.sql.ts b/packages/core/src/modules/chart/src/retention.sql.tsindex 94efa5392..c14c8610c 100644--- a/packages/core/src/modules/chart/src/retention.sql.ts+++ b/packages/core/src/modules/chart/src/retention.sql.ts@@ -41,8 +41,8 @@ const COUNT_CRITERIA: Record<IRetentionCriteria, string> = {};/**- * Without both dates the statement reads the project's whole lifetime, as V1- * did: the MCP tools pass none and their contracts rely on it.+ * Without both dates the statement reads the project's whole lifetime: the+ * MCP tools pass none and their contracts rely on it.*/export interface RetentionSeriesQueryInput {projectId: string;@@ -63,8 +63,8 @@ function createdAtWithin({/*** Week-over-week active-user retention, one row per week, within the window- * when one is given (Group C fix 8); a week whose following week falls- * outside it reports zero retained users.+ * when one is given; a week whose following week falls outside it reports+ * zero retained users.*/export function retentionSeriesQuery(input: RetentionSeriesQueryInput@@ -127,8 +127,8 @@ export function rollingActiveUsersQuery(}/**- * Days-since-last-seen distribution over identified profiles; with a window, a- * profile last seen before it is no longer counted (fix 8).+ * Days-since-last-seen distribution over identified profiles; with a window,+ * a profile last seen before it is no longer counted.*/export function retentionLastSeenSeriesQuery(input: RetentionSeriesQueryInput@@ -166,7 +166,7 @@ export interface RetentionCohortQueryInput {filters: IChartEventFilter[];}-/** V1's `name = …` / `name IN (…)`; `sql.empty` means "any event". */+/** `name = …` / `name IN (…)`; `sql.empty` means "any event". */function eventNameWhere(events: string[] | undefined): SqlFragment {if (!events || events.length === 0) {return sql.empty;@@ -178,7 +178,7 @@ function eventNameWhere(events: string[] | undefined): SqlFragment {}/**- * The cohort retention matrix (V1 `getRetentionCohort`'s five-CTE query).+ * The cohort retention matrix: a five-CTE query.** Source table is a closed two-way choice, not a caller input: cohort* membership filters stay on the skinny `cohort_events_mv`, anything reading adiff --git a/packages/core/src/modules/chart/src/run-query.ts b/packages/core/src/modules/chart/src/run-query.tsindex 8edcffe02..c4b6408a3 100644--- a/packages/core/src/modules/chart/src/run-query.ts+++ b/packages/core/src/modules/chart/src/run-query.ts@@ -18,7 +18,7 @@ import {} from '@openpanel/db/src/clickhouse/sql';import type { ServiceDeps } from '../../../services';-/** `timezone` travels as `session_timezone`, exactly as clix sent it. */+/** `timezone` travels as ClickHouse's `session_timezone` setting. */export async function runQuery<T extends object>(deps: ServiceDeps,statement: SqlFragment,diff --git a/packages/core/src/modules/chart/src/sankey.sql.ts b/packages/core/src/modules/chart/src/sankey.sql.tsindex 47d61c8ac..5277705a1 100644--- a/packages/core/src/modules/chart/src/sankey.sql.ts+++ b/packages/core/src/modules/chart/src/sankey.sql.ts@@ -19,12 +19,12 @@ export type SankeyMode = 'after' | 'before' | 'between';export const TOP_ENTRY_EVENTS = 3;/**- * Consecutive-repeat dedup, shared by every mode. V1 spelled it as an- * `arrayFilter` whose lambda indexed its own captured `groupArray`, which- * ClickHouse re-materialises once per element: Theta(n^2) in the longest single- * session's event count, fatal on a tenant with one very long session- * `arrayCompact` is the built-in- * for exactly this and is linear; the result is byte-identical.+ * Consecutive-repeat dedup, shared by every mode. An `arrayFilter` whose+ * lambda indexes its own captured `groupArray` is Theta(n^2) in the longest+ * session's event count — ClickHouse re-materialises the array once per+ * element, which is fatal for a tenant with one very long session.+ * `arrayCompact` is the built-in for exactly this and is linear; the result+ * is byte-identical.*/const DEDUPE_CONSECUTIVE = compiledText('arrayCompact(groupArray(event_name)) as events_deduped'@@ -74,8 +74,8 @@ function dateRange(input: SankeyPathsInput): SqlFragment {}/**- * V1 `buildEventNameFilter`: an include list wins over an exclude list, and it- * always carries the start/end events so the flow's anchors survive it.+ * An include list wins over an exclude list, and it always carries the+ * start/end events so the flow's anchors survive it.*/function eventNameFilter(input: SankeyPathsInput): SqlFragment {if (input.include && input.include.length > 0) {@@ -104,7 +104,7 @@ function sessionEventCte(}interface ModeConfig {- /** `null` when the mode has no session restriction (V1's `1 = 1`). */+ /** `null` when the mode has no session restriction (rendered as `1 = 1`). */sessionFilter: SqlFragment | null;eventsSlice: SqlFragment;}@@ -148,8 +148,8 @@ function modeConfig(input: SankeyPathsInput): ModeConfig {}/**- * V1's `sessionPathsQuery`: one row per session carrying its deduped, sliced- * event path and that path's entry event.+ * One row per session carrying its deduped, sliced event path and that+ * path's entry event.*/export function sankeySessionPathsQuery(input: SankeyPathsInput): SqlFragment {const { sessionFilter, eventsSlice } = modeConfig(input);diff --git a/packages/core/src/modules/chart/src/sql.test.ts b/packages/core/src/modules/chart/src/sql.test.tsindex a34cd292f..e47f58514 100644--- a/packages/core/src/modules/chart/src/sql.test.ts+++ b/packages/core/src/modules/chart/src/sql.test.ts@@ -9,8 +9,8 @@* check, so it is covered by a plain string assertion instead.** Text assertions look at the rendered `query`; chart-level values are- * `{pN:Type}` placeholders there, filter/breakdown expressions are the verbatim- * V1 text (see field-resolution.ts's header).+ * `{pN:Type}` placeholders there, filter/breakdown expressions are inlined+ * verbatim (see field-resolution.ts's header).** The statements' only Postgres read (the project's cohorts, for the* all-cohorts breakdown) is stubbed to "no cohorts": that is the precondition@@ -68,10 +68,10 @@ interface Rendered {sql: string;params: Record<string, unknown>;/**- * `sql` with every `{pN:Type}` substituted back to the literal V1 emitted.- * Since M12-003 the field resolver binds `properties[<key>]` keys too, so an- * assertion about the SHAPE of a map access reads this; an assertion about- * what is bound reads `sql`/`params`.+ * `sql` with every `{pN:Type}` substituted back to the literal value. The+ * field resolver binds `properties[<key>]` keys too, so an assertion about+ * the SHAPE of a map access reads this; an assertion about what is bound+ * reads `sql`/`params`.*/text: string;}@@ -334,9 +334,9 @@ describe('getChartSql', () => {await explain(rendered);});- // Regressions from HyperDX 2026-05-14 → 2026-05-17 ClickHouse error log.- // Saved reports / older clients send field names that don't match the events- // schema; the chart service used to inline them verbatim, crashing parse.+ // Saved reports / older clients can send field names that don't match the+ // events schema; the chart service used to inline them verbatim, crashing+ // parse.it('normalizes camelCase filter alias (referrerName → referrer_name)', async () => {const rendered = await getChartSql({event: event({diff --git a/packages/core/src/modules/chart/src/sql.ts b/packages/core/src/modules/chart/src/sql.tsindex 159c94555..9d75b47c5 100644--- a/packages/core/src/modules/chart/src/sql.ts+++ b/packages/core/src/modules/chart/src/sql.ts@@ -45,7 +45,7 @@ import { getEventFiltersWhereClause } from './filter-where';const EVENTS_ALIAS = 'e';const ALL_COHORTS_ALIAS = '_all_cohorts';// Cohort ids are Postgres uuids; they also name a CTE and a join alias, so-// anything else is refused rather than inlined (V1 inlined it unchecked).+// anything else is refused rather than inlined.const COHORT_ID_PATTERN = /^[A-Za-z0-9_-]+$/;const MATH_FUNCTION_BY_SEGMENT: Record<string, string> = {@@ -56,7 +56,7 @@ const MATH_FUNCTION_BY_SEGMENT: Record<string, string> = {};export const PROPERTY_VALUES_LIMIT = 100_000;-/** `profiles` columns a `profile.<field>` reference may select (ADR-013 R3). */+/** `profiles` columns a `profile.<field>` reference may select. */const PROFILE_COLUMNS = ['id','is_external',@@ -239,7 +239,7 @@ interface ChartBody {}/**- * The CTEs, JOINs, WHERE and `label_0` both chart shapes share, in V1's+ * The CTEs, JOINs, WHERE and `label_0` both chart shapes share, in a fixed* clause order: cohort CTEs/joins, filters + project + event name, group* ARRAY JOIN, profile CTE.*/@@ -385,7 +385,7 @@ function addBreakdownLabels(function countExpression(event: ChartQueryEvent,body: ChartBody,- /** V1's aggregate shape resolved the metric property against the project; the series shape did not. */+ /** The aggregate shape resolves the metric property against the project; the series shape does not. */metricProjectId: string | undefined): SqlFragment {if (event.segment === 'user') {@@ -427,8 +427,7 @@ function countExpression(// with the events alias, so `e.properties` was out of scope in the outer// query and any chart combining this segment with a property breakdown failed// with UNKNOWN_IDENTIFIER. The subquery already does `SELECT * FROM events e`,-// so every `e.`-qualified reference outside it resolves unchanged-// (main a2cbf2e8).+// so every `e.`-qualified reference outside it resolves unchanged.function oneEventPerUserFrom(body: ChartBody): SqlFragment {return sql`(SELECT DISTINCT ON (profile_id) * from ${sql.id(CHART_TABLE.events)} e ${joinsClause(body.joins)} WHERE ${sql.join(clauses(body.where), ' AND ')}@@ -492,7 +491,7 @@ function intervalBucket(}}-/** V1 `getChartSql`: one series, bucketed by interval, with a windowed unique total. */+/** One series, bucketed by interval, with a windowed unique total. */export function chartSeriesQuery(input: ChartSeriesQueryInput): SqlFragment {const { event, interval, startDate, endDate, timezone } = input;const body = chartBody(input);@@ -541,7 +540,7 @@ export function chartSeriesQuery(input: ChartSeriesQueryInput): SqlFragment {// --- aggregate chart ---------------------------------------------------------/** V1 `getAggregateChartSql`: one row per breakdown combination over the whole range. */+/** One row per breakdown combination over the whole range. */export function aggregateChartQuery(input: AggregateChartQueryInput): SqlFragment {@@ -564,7 +563,7 @@ export function aggregateChartQuery(// The filters were applied inside the subquery; re-emitting the outer// WHERE made it reference aliases the subquery dropped (a profile or// group filter, or the ARRAY JOIN's _group_id). Same shape as the series- // branch below (main a2cbf2e8).+ // branch below.const from = oneEventPerUserFrom(body);return sql`${head} FROM ${from} ${groupByClause(groupBy)}`;}@@ -579,7 +578,7 @@ export function aggregateChartQuery(/*** projectCard: three months of daily unique visitors + revenue, filled.* The timezone travels as `clickhouse_settings.session_timezone` (the caller- * passes it) instead of V1's inline `SETTINGS` clause — same setting, same+ * passes it) rather than an inline `SETTINGS` clause — same setting, same* query scope, and a bindable position.*/export function projectCardChartQuery(projectId: string): SqlFragment {@@ -652,7 +651,7 @@ export function groupPropertyValuesQuery(export interface ChartBucketProfilesInput {projectId: string;- /** Bucket start as V1's `YYYY-MM-DD HH:mm:ss` string. */+ /** Bucket start as a `YYYY-MM-DD HH:mm:ss` string. */bucketDate: string;interval: IInterval;event: Pick<IChartEvent, 'name' | 'filters'>;@@ -688,11 +687,11 @@ function profileFieldsToSelect(refs: string[]): SqlFragment[] {fields.push(field);}}- // V1 spliced these unchecked (trpc chart.ts:781).+ // `sql.id` refuses any field not in PROFILE_COLUMNS rather than splicing it.return fields.map((field) => sql.id(field, PROFILE_COLUMNS));}-/** Distinct profile ids behind one chart data point (V1 `getProfiles`). */+/** Distinct profile ids behind one chart data point. */export function chartBucketProfilesQuery(input: ChartBucketProfilesInput): SqlFragment {diff --git a/packages/core/src/modules/chart/src/table-filter-where.test.ts b/packages/core/src/modules/chart/src/table-filter-where.test.tsindex 2f3363c80..432c904bb 100644--- a/packages/core/src/modules/chart/src/table-filter-where.test.ts+++ b/packages/core/src/modules/chart/src/table-filter-where.test.ts@@ -1,10 +1,10 @@/*** Unit tests for `buildFilterWhere`.*- * No ClickHouse needed. Since M12-003 the compiler returns bound- * `SqlFragment`s, so each clause is rendered through `toStatement` and its- * params substituted back in: what the assertions say is unchanged, a value- * that used to appear as an escaped literal now appears in `query_params`. The+ * No ClickHouse needed. The compiler returns bound `SqlFragment`s, so each+ * clause is rendered through `toStatement` and its params substituted back+ * in: what the assertions say is unchanged, a value that used to appear as+ * an escaped literal now appears in `query_params`. The* interesting part is the `profile.*` branch: the field name arrives from the* caller (saved report, URL state, raw API call) and used to be concatenated* into the SQL text as-is, so a name that was not a column produced whateverdiff --git a/packages/core/src/modules/chart/src/table-filter-where.ts b/packages/core/src/modules/chart/src/table-filter-where.tsindex 617cddf47..fb939c919 100644--- a/packages/core/src/modules/chart/src/table-filter-where.ts+++ b/packages/core/src/modules/chart/src/table-filter-where.ts@@ -47,7 +47,7 @@ export interface FilterTableContext {endDate?: Date;}-/** One clause per surviving filter, keyed `f<index>` as V1 keyed them. */+/** One clause per surviving filter, keyed `f<index>`. */export type CompiledTableFilters = Record<string, SqlFragment>;/** Sentinel sessions columns that the UI may filter on directly. */@@ -136,7 +136,7 @@ function valueParam(value: IChartEventFilterValue) {return sql.string(value.trim());}-/** V1's `trimVal` — what a LIKE pattern is built from. */+/** What a LIKE pattern is built from. */function trimVal(value: IChartEventFilterValue): string {return typeof value === 'string' ? value.trim() : String(value);}@@ -146,7 +146,7 @@ function valueArray(value: IChartEventFilterValue[]) {return sql.array('String', value.map(trimVal));}-/** V1's `(<a> OR <b>)` / `(<a> AND <b>)` — the parenthesised join. */+/** `(<a> OR <b>)` / `(<a> AND <b>)` — the parenthesised join. */function joined(clauses: SqlFragment[], separator: ' OR ' | ' AND ') {return sql`(${sql.join(clauses, separator)})`;}@@ -173,7 +173,7 @@ function compileScalarClause(}const numeric = options.numeric === true;- // V1 wrapped BOTH sides in toFloat64 on a numeric column; the quoted+ // Both sides are wrapped in toFloat64 on a numeric column; the quoted// comparand fed to toFloat64 is the behaviour, so the value stays a String.const left = numeric ? sql`toFloat64(${column})` : column;const right = (val: IChartEventFilterValue) =>diff --git a/packages/core/src/modules/client/client.routes.ts b/packages/core/src/modules/client/client.routes.tsindex 26e3ad09a..4318c0705 100644--- a/packages/core/src/modules/client/client.routes.ts+++ b/packages/core/src/modules/client/client.routes.ts@@ -1,18 +1,14 @@// The /manage/clients REST surface, delegating its CRUD bodies to// client.service.ts's createClientForOrganization/updateClientForOrganization/// etc — the same functions the tRPC router (client.rpc.ts) calls. Response-// envelopes (`{ data }` / `{ success }`) match V1's `reply.send(...)` shape-// (byte-unchanged URL surface).+// envelopes (`{ data }` / `{ success }`) keep a byte-unchanged URL surface.//-// Body schemas are local, not a client.constants.ts file: the module map gives-// client "R,H,S" only, no "C" (unlike project, whose zCreateProject /-// zUpdateProject moved with ProjectTypeNames).+// Body schemas are local, not in a client.constants.ts file: unlike project,+// whose zCreateProject / zUpdateProject moved with ProjectTypeNames, this+// module has no rpc-shared constants to publish.//-// `authenticateAllowedClient` (http/client-auth.ts) is filled in and-// `publicApiRoutes` is mounted in main.ts, so this route is live. `allow:-// ['root']` mirrors V1's rule: only root clients may manage resources. (A-// client minted through client.service.ts cannot currently authenticate at all-// — see that file's FIXME on `createClientForOrganization`.)+// Auth goes through `authenticateAllowedClient` (http/client-auth.ts);+// `allow: ['root']` means only root clients may manage resources.import { z } from 'zod';import { defineRoutes } from '../../http/define';diff --git a/packages/core/src/modules/client/client.rpc.ts b/packages/core/src/modules/client/client.rpc.tsindex ad830285f..727b62eeb 100644--- a/packages/core/src/modules/client/client.rpc.ts+++ b/packages/core/src/modules/client/client.rpc.ts@@ -17,8 +17,8 @@ export const clientRouter = createTRPCRouter({list: protectedProcedure.input(z.object({ projectId: z.string() })).query(async ({ input, ctx }) => {- // Ported verbatim: V1's `client.list` reads by projectId with no- // access check of its own (V1's client router).+ // No access check beyond authentication: this reads any project's+ // clients by projectId alone.return ctx.services.client.getClientsByProjectId(input.projectId);}),diff --git a/packages/core/src/modules/client/client.service.ts b/packages/core/src/modules/client/client.service.tsindex 20d66ceeb..bb3080179 100644--- a/packages/core/src/modules/client/client.service.ts+++ b/packages/core/src/modules/client/client.service.ts@@ -1,21 +1,17 @@-// Client CRUD lives only here now; no packages/db re-export shim exists in this-// tree.-//// The /manage REST CRUD bodies (client.routes.ts's listClients/getClient/// createClient/updateClient/deleteClient) call the same// create/update/delete/list functions the tRPC router (client.rpc.ts) does.//-// Every function takes `ServiceDeps` and reaches Postgres as `deps.db`; the-// `loadDb` lazy loader is gone. No dependency on project.service.ts here (the-// reverse direction exists, for cache invalidation) — project-ownership checks-// below query `db.project` directly.+// Every function takes `ServiceDeps` and reaches Postgres as `deps.db`. No+// dependency on project.service.ts here (the reverse direction exists, for+// cache invalidation) — project-ownership checks below query `db.project`+// directly.//// `getClientByIdCached` is a module-scope `cacheablePerDb`, keyed on the// Postgres client rather than on the scope. Its L1 LRU has to survive across// calls to be worth anything, and the ingest hot path-// (`ingest/src/client-auth.ts`, `http/client-auth.ts`) now passes the scope it-// holds instead of reading a boot-scoped singleton through the deleted compat-// seam. One instance per process to read, one to invalidate.+// (`ingest/src/client-auth.ts`, `http/client-auth.ts`) passes the scope it+// holds on each call. One instance per process to read, one to invalidate.import crypto from 'node:crypto';import type { Client, Prisma } from '@openpanel/db/src/prisma-client';@@ -68,7 +64,7 @@ export async function getClientsByOrganizationId(});}-/** trpc client.list — no access check of its own, ported verbatim. */+/** No access check of its own; callers must authorize before calling. */export async function getClientsByProjectId(deps: ServiceDeps,projectId: stringdiff --git a/packages/core/src/modules/cohort/cohort.rpc.ts b/packages/core/src/modules/cohort/cohort.rpc.tsindex 0109060a5..6dd2f09b3 100644--- a/packages/core/src/modules/cohort/cohort.rpc.ts+++ b/packages/core/src/modules/cohort/cohort.rpc.ts@@ -7,16 +7,13 @@// procedure here reaches it through `ctx.services.auth`.//// CRUD (list/get/create/update/delete) reads/writes Prisma's `cohort` table-// directly, matching V1's router — cohort.service.ts owns only the-// compute-heavy and ClickHouse-touching operations, same split as V1.+// directly — cohort.service.ts owns only the compute-heavy and+// ClickHouse-touching operations.import { z } from 'zod';import { createTRPCRouter, protectedProcedure } from '../../rpc/base';import { TRPCNotFoundError } from '../../rpc/errors';import { getSettingsForProject } from '../organization/organization.service';-// The canonical zChartEventFilter, not cohort.constants.ts's private-// TDZ-workaround copy — matches V1's router, which imports it from-// packages/validation's barrel rather than from cohort.validation.ts.import { zChartEventFilter, zRange } from '../report/report.constants';import { getChartStartEndDate } from '../report/src/chart-dates';import {@@ -108,10 +105,9 @@ export const cohortRouter = createTRPCRouter({return cohort;}),- // No project-access check here, matching V1 (packages/trpc/src/routers/- // cohort.ts) exactly — protectedProcedure's session check is the only gate- // today. Preserved as found: ADR-011 invariant 1 forbids deleting an- // in-handler check, and this router does not serve live traffic yet.+ // No project-access check here — protectedProcedure's session check is the+ // only gate today. Preserved as found rather than silently added or+ // removed; this router does not yet serve live traffic.create: protectedProcedure.input(zCohortInput).mutation(async ({ input, ctx }) => {diff --git a/packages/core/src/modules/cohort/cohort.service.test.ts b/packages/core/src/modules/cohort/cohort.service.test.tsindex 1acb3ef4d..c450e676b 100644--- a/packages/core/src/modules/cohort/cohort.service.test.ts+++ b/packages/core/src/modules/cohort/cohort.service.test.ts@@ -1,8 +1,6 @@-// Every function under test takes `ServiceDeps`, so `deps.db` and `deps.ch` ARE-// the fakes below — the two `@openpanel/db` module mocks this file used to-// install (and had to carefully restore, because `mock.module` has no per-file-// scope without `--isolate`) are gone. The one module still mocked is core's-// own `ch-query`, which is what the subject now calls.+// Every function under test takes `ServiceDeps`, so `deps.db` and `deps.ch`+// ARE the fakes below. The one module still mocked is core's own+// `ch-query`, which is what the subject calls.//// The pure SQL-shape builders (buildEventCriteriaQuery,// buildPropertyBasedCohortQuery, deriveCohortQuerySettings) have their owndiff --git a/packages/core/src/modules/cohort/cohort.service.ts b/packages/core/src/modules/cohort/cohort.service.tsindex 3c3dac7e8..ff1b13903 100644--- a/packages/core/src/modules/cohort/cohort.service.ts+++ b/packages/core/src/modules/cohort/cohort.service.ts@@ -67,15 +67,10 @@ export function cohortMaterializeLimit(config: CoreConfig): number {// by default, which is how these queries OOM'd instead of spilling). When only// the limit is set — or the pair is inverted — the threshold derives as// limit/3. Spilling early costs little: the volume spilled is set by the data,-// not the threshold (measured on 8.3M profiles, ~281MB spilled whether the-// threshold was 300, 512 or 768MB, at 6.9s/6.7s/6.0s, while peak memory climbed-// 410/695/893MiB).+// not the threshold.//// A standalone function of its two parsed inputs (not a module-level read), so-// a test can exercise every branch by calling it directly — bun:test shares one-// module registry per file even under --isolate, so vitest's-// vi.resetModules-per-case porting has no equivalent (see AGENTS.md; this was-// the one vi.resetModules site in the suite, ADR-010's tail table).+// a test can exercise every branch by calling it directly.export function deriveCohortQuerySettings({memoryLimitBytes,spillBytes: spillBytesParsed,@@ -112,8 +107,7 @@ export function profileCohortQuerySettings(}// The column is a parameter rather than a post-hoc `.replace('created_at',-// 'event_date')` on finished text: V1 rewrote the clause that way at all four-// call sites below, and a fragment has no text to rewrite.+// 'event_date')` on finished text — a fragment has no text to rewrite.function buildTimeConstraint(timeframe: Timeframe,column: SqlFragment@@ -148,15 +142,14 @@ function getFrequencyOperator(frequency: Frequency): SqlFragment {}}-/** The trimmed string form V1 escaped for every filter comparand. */+/** The trimmed string form used for every filter comparand. */function trimmedComparand(value: unknown): string {return String(value).trim();}// One event-property filter. Values bind; the property key is a Map key, so it// binds as a value too. An `IN`/`NOT IN` list becomes one `Array(String)`-// param — V1's `IN ()` on an empty list and `IN {p:Array(String)}` on an empty-// array both match nothing.+// param; an empty list matches nothing.function eventPropertyCondition(filter: IChartEventFilter): SqlFragment {const propertyKey = sql.string(filter.name.replace('properties.', ''));const { value, operator } = filter;@@ -350,10 +343,7 @@ function normalizeProfileColumn(name: string): string {// column, qualified with the table name. Cohort definitions come from the API,// so both halves are user-controlled: the Map key is a *value* and binds as// one, and the plain column goes through `sql.id`, which throws rather than-// inlining anything that is not a bare (once-qualified) identifier. V1 inlined-// it verbatim — the one input class whose behaviour changes is a non-identifier-// column name, which V1 turned into a ClickHouse `UNKNOWN_IDENTIFIER` and V2-// rejects before the round trip.+// inlining anything that is not a bare (once-qualified) identifier.function profileColumnAccess(normalizedName: string): SqlFragment {if (normalizedName.startsWith('profiles.properties.')) {const propKey = normalizedName.replace('profiles.properties.', '');@@ -374,10 +364,9 @@ function buildProfileCohortHavingClause(// a hash of every referenced column — makes all aggregates pick their// value from the same winning row, deterministically. The hash (rather// than the raw value tuple) keeps the per-group comparison state at a- // fixed 8 bytes: measured on 8.8M profiles, the raw-tuple key cost ~40%- // extra query time while the hashed key is free. A wrong tie-break would- // need a version tie AND a 64-bit collision between different rows — and- // even then every aggregate in the query still elects the same row.+ // fixed 8 bytes, cheaper than comparing the raw tuple. A wrong tie-break+ // would need a version tie AND a 64-bit collision between different rows —+ // and even then every aggregate in the query still elects the same row.const referencedColumns = Array.from(new Set(properties.map((f) => normalizeProfileColumn(f.name)))).map(profileColumnAccess);@@ -421,8 +410,7 @@ export function buildPropertyBasedCohortQuery(}// `INTERSECT` / `UNION DISTINCT` are not `sql.join` separators (that set is-// closed on purpose), so the criteria fold left — the same associativity-// `queries.join(' INTERSECT ')` produced.+// closed on purpose), so the criteria fold left.function combineCriteriaQueries(queries: SqlFragment[],operator: 'and' | 'or'@@ -932,8 +920,6 @@ export async function listCohortMemberProfiles(? sql`AND ${sql.join(extraConditions, ' AND ')}`: sql.empty;- // Converted with `buildFilterWhere`, which now returns fragments. V1's plain- // `IN (subquery)` on the Distributed `cohort_members` is kept as written.const rows = await chQuery<{ id: string; total_count: number }>(deps,sql`@@ -1003,8 +989,8 @@ export function cohortMemberEventsQuery(window: CohortActivityWindow,limit: number): SqlFragment {- // V1's plain `IN (subquery)` on the Distributed `cohort_members` is kept as- // written — a conversion changes the binding of values and nothing about the+ // This plain `IN (subquery)` on `cohort_members` is left as-is — changing+ // how the subquery binds its values would not change anything about// distribution semantics.return sql`SELECT name, count() AS count@@ -1038,7 +1024,6 @@ export async function getCohortEventsPerDay(cohortId: string,days = 30): Promise<{ date: string; count: number }[]> {- // `IN (subquery)` on the Distributed `cohort_members`: kept as V1 wrote it.const lookbackDays = sql.uint64(days);const rows = await chQuery<{ date: string; count: number }>(deps,@@ -1071,7 +1056,6 @@ export function cohortMemberRoutesQuery(window: CohortActivityWindow,limit: number): SqlFragment {- // `IN (subquery)` on the Distributed `cohort_members`: kept as V1 wrote it.return sql`SELECT path, count() AS countFROM ${sql.id(TABLE.events)}@@ -1121,8 +1105,7 @@ export function createCohortService(* the completed record is still there, and the record is never collected* because nothing gets added. `deduplicationId`, in contrast, is released by* `moveToFinished` on both completion and terminal failure, so it only- * collapses a compute that is genuinely still in flight (ADR-005: "cohort- * must NOT be normalised onto jobId").+ * collapses a compute that is genuinely still in flight.*/async function enqueueCompute(cohortId: string): Promise<void> {await deps.queues.cohortCompute.cohortCompute.add(diff --git a/packages/core/src/modules/cohort/src/cohort-sql.test.ts b/packages/core/src/modules/cohort/src/cohort-sql.test.tsindex 98f10b4b8..4a68b9fc7 100644--- a/packages/core/src/modules/cohort/src/cohort-sql.test.ts+++ b/packages/core/src/modules/cohort/src/cohort-sql.test.ts@@ -5,25 +5,21 @@// silently replace this file's "real" import too, making a reachability check// meaningless. No module in core's suite ports that pattern for the same// reason; the generated SQL was verified against local ClickHouse by hand-// instead (see the M5-003 task summary).+// instead.//// String assertions need no mocking at all: cohort.service.ts's db/ch access is// lazy, and buildPropertyBasedCohortQuery / deriveCohortQuerySettings touch// neither — see cohort.service.ts's header.//-// The builders return `SqlFragment`s now, so every assertion below runs against-// the RENDERED statement plus its bound params rather than a finished string.-// The assertions themselves are unchanged in what they claim, except the one-// about quotes in a user-controlled property key: a quote no longer needs-// escaping because the key is not in the SQL text at all, so that test asserts-// the binding instead.+// The builders return `SqlFragment`s, so every assertion below runs against+// the rendered statement plus its bound params rather than a finished+// string. The property-key quoting test below asserts a binding, not+// escaped text, because the key never appears in the SQL text at all.//-// V1's `PROFILE_COHORT_QUERY_SETTINGS` test used `vi.resetModules` +-// `vi.stubEnv` to re-import the module under different env vars — the suite's-// only `vi.resetModules` site (ADR-010's tail table). bun:test shares one-// module registry per file even under `--isolate`, so re-importing would not-// re-evaluate a module-level const. `deriveCohortQuerySettings` exists so this-// ports as direct calls instead.+// bun:test shares one module registry per file even under `--isolate`, so+// re-importing under different env vars would not re-evaluate a+// module-level const. `deriveCohortQuerySettings` exists so the different+// settings combinations below are exercised as direct calls instead.import { expect, test } from 'bun:test';import {@@ -272,4 +268,4 @@ test('deriveCohortQuerySettings never derives a zero spill threshold (0 would DI});// A malformed COHORT_QUERY_* value is rejected by the config loader now, not-// here — `apps/api/src/config/env.test.ts` owns that case since M15-006.+// here — `apps/api/src/config/env.test.ts` owns that case.diff --git a/packages/core/src/modules/conversation/conversation.rpc.ts b/packages/core/src/modules/conversation/conversation.rpc.tsindex 9094a845b..b8172ebc8 100644--- a/packages/core/src/modules/conversation/conversation.rpc.ts+++ b/packages/core/src/modules/conversation/conversation.rpc.ts@@ -1,17 +1,13 @@-// Every procedure is on its V1 twin's builder. `protectedProcedure` runs-// `enforceUserIsAuthed` + `enforceAccess` BEFORE the input parser, exactly as-// V1 does. `enforceAccess` reads the raw, pre-zod input and only a TOP-LEVEL-// `projectId` — `list` and `rename` both take one, so their project access is-// already enforced before the handler runs. `get` and `delete` take only `id`,-// invisible to `enforceAccess`, so their ownership check stays in the handler.-// `get` denies with NOT_FOUND rather than FORBIDDEN — the documented exception-// the ADR-011 auth benchmark is built around (controller-// verification/contracts/auth/README.md).+// `protectedProcedure` runs `enforceUserIsAuthed` + `enforceAccess` BEFORE the+// input parser. `enforceAccess` reads the raw, pre-zod input and only a+// TOP-LEVEL `projectId` — `list` and `rename` both take one, so their project+// access is already enforced before the handler runs. `get` and `delete` take+// only `id`, invisible to `enforceAccess`, so their ownership check stays in+// the handler. `get` denies with NOT_FOUND rather than FORBIDDEN — a+// deliberate choice, not an oversight.//-// `ctx.services.conversation` carries this module's factory.-//-// The per-project access ladder itself is bound once, in auth.service.ts; every-// procedure here reaches it through `ctx.services.auth`.+// The per-project access ladder itself is bound once, in auth.service.ts;+// every procedure here reaches it through `ctx.services.auth`.import { z } from 'zod';import { createTRPCRouter, protectedProcedure } from '../../rpc/base';diff --git a/packages/core/src/modules/conversation/conversation.service.ts b/packages/core/src/modules/conversation/conversation.service.tsindex e8f723ec6..57b6748a7 100644--- a/packages/core/src/modules/conversation/conversation.service.ts+++ b/packages/core/src/modules/conversation/conversation.service.ts@@ -1,5 +1,4 @@-// Every function takes `ServiceDeps` and reaches Postgres as `deps.db`; the-// `loadDb` lazy loader is gone.+// Every function takes `ServiceDeps` and reaches Postgres as `deps.db`.import type {ChatMessage,@@ -32,8 +31,7 @@ async function getConversationByIdImpl(}// Overloaded so a caller's static type matches what it actually asked for,-// instead of the three-way union every call used to get regardless of-// `options` (docs/review/conversation.md, "Not covered by any rule" #4).+// instead of a three-way union regardless of `options`.export function getConversationById(deps: ServiceDeps,id: string,diff --git a/packages/core/src/modules/email/email.rpc.ts b/packages/core/src/modules/email/email.rpc.tsindex d4dda152f..84c932b44 100644--- a/packages/core/src/modules/email/email.rpc.ts+++ b/packages/core/src/modules/email/email.rpc.ts@@ -1,9 +1,8 @@// Deliberately R + C only (no `email.service.ts`): the three procedures' bodies// are three small `db.emailUnsubscribe` calls, inlined here the same way// conversation.rpc.ts inlines its organization lookup. Sending/templates stay-// in @openpanel/email (TARGET_ARCHITECTURE §7); core's `clients/email.ts`-// already wraps that package for the one thing this module doesn't need —-// sending.+// in @openpanel/email; core's `clients/email.ts` already wraps that package+// for the one thing this module doesn't need — sending.//// `protectedProcedure` runs `enforceUserIsAuthed` + `enforceAccess` BEFORE the// input parser. The explicit checks in the handlers below stay: `enforceAccess`diff --git a/packages/core/src/modules/email/src/sequence.ts b/packages/core/src/modules/email/src/sequence.tsindex de1f5e4ba..ce74a5752 100644--- a/packages/core/src/modules/email/src/sequence.ts+++ b/packages/core/src/modules/email/src/sequence.ts@@ -9,18 +9,19 @@// resolves the next step, checks the day gate and the step's own guard, sends,// then advances the pointer.//-// Three deliberate differences from the original inline implementation in-// cron.onboarding.ts, all of which matter once a sequence ends in deletion:+// Three invariants matter once a sequence ends in deletion://-// 1. The pointer resolves by step name and an *unknown* name completes the-// sequence rather than restarting it. The old `findIndex` returned -1 for a-// renamed or removed step, which silently sent the subject back to step 0. 2.-// `'skip'` advances past a step; `false` only defers it. The old code had one-// value for both, so a step that should be passed over stalled the sequence-// permanently. 3. `requireDelivery` refuses to advance unless the email-// actually went out. `sendEmail` returns null instead of throwing when a send-// is suppressed or misconfigured, so a step with side effects could otherwise-// fire on an email nobody received.+// The pointer resolves by step name, and an *unknown* name completes the+// sequence rather than restarting it — a renamed or removed step must not+// silently send the subject back to step 0.+//+// `'skip'` advances past a step; `false` only defers it — conflating the two+// would stall a step that should be passed over.+//+// `requireDelivery` refuses to advance unless the email actually went out.+// `sendEmail` returns null instead of throwing when a send is suppressed or+// misconfigured, so a step with side effects could otherwise fire on an+// email nobody received.import { differenceInDays } from 'date-fns';import {diff --git a/packages/core/src/modules/event/event.constants.ts b/packages/core/src/modules/event/event.constants.tsindex 975bb2c3d..9f444a05e 100644--- a/packages/core/src/modules/event/event.constants.ts+++ b/packages/core/src/modules/event/event.constants.ts@@ -1,8 +1,3 @@-// Isomorphic vocabulary for the event module. These are column whitelists, not-// query logic — moved here from event.service.ts / src/sql.ts so a value-import-// (mcp's property-values tool today; a future dashboard form tomorrow) has a-// `*.constants.ts` to reach instead of a service or query-builder file.-/*** Top-level filterable columns on the `events` table. These apply to* every event regardless of name and can be passed straight to@@ -39,7 +34,7 @@ export const EVENT_COLUMNS = [export type IEventColumn = (typeof EVENT_COLUMNS)[number];-/** Every column `getEventList` can project, in V1's select order. */+/** Every column `getEventList` can project. */export const EVENT_LIST_COLUMNS = ['created_at','project_id',@@ -75,7 +70,7 @@ export const EVENT_LIST_COLUMNS = [export type EventListColumn = (typeof EVENT_LIST_COLUMNS)[number];-/** The `= value` columns `queryEventsCore` accepts, in V1's clause order. */+/** The `= value` columns `queryEventsCore` accepts. */export const QUERY_EVENTS_EQUALITY_COLUMNS = ['path','referrer',diff --git a/packages/core/src/modules/event/event.rpc.ts b/packages/core/src/modules/event/event.rpc.tsindex 9535c29de..e58699854 100644--- a/packages/core/src/modules/event/event.rpc.ts+++ b/packages/core/src/modules/event/event.rpc.ts@@ -3,13 +3,8 @@// only sees a TOP-LEVEL `projectId` / `organizationId`, so anything resolved// from another id needs its own.//-// `bots` was V1's only `publicProcedure` here (anonymous callers were let in-// when a share-overview row existed); ADR-011 makes it protected.-//// `pages` / `pagesTimeseries` / `previousPages` / `pageTimeseries` read the-// overview module's pages service; since M10-005 that is `ctx.services.pages`,-// so the three-way lazy `import('@openpanel/core')` hop this file used to make-// for it is gone.+// overview module's pages service via `ctx.services.pages`.import { z } from 'zod';import { createTRPCRouter, protectedProcedure } from '../../rpc/base';diff --git a/packages/core/src/modules/event/event.service.ts b/packages/core/src/modules/event/event.service.tsindex 9930073e1..8b1a3c081 100644--- a/packages/core/src/modules/event/event.service.ts+++ b/packages/core/src/modules/event/event.service.ts@@ -55,8 +55,7 @@ export {} from './event.constants';const EVENT_METAS_CACHE_SECONDS = 60 * 5;-// V1's `cacheable(getEventMetas, ...)` derived this from the function's own-// name; naming it keeps the Redis key `cachable:getEventMetas:<projectId>`.+// Named explicitly so the Redis key stays `cachable:getEventMetas:<projectId>`.const EVENT_METAS_CACHE_NAME = 'getEventMetas';const TOP_EVENT_NAMES_CACHE_SECONDS = 60 * 10;const EVENT_LIST_DEFAULT_LOOKBACK_DAYS = 0.5;@@ -72,8 +71,8 @@ const PROFILE_FILTER_PREFIX = 'profile.';const GROUP_FILTER_PREFIX = 'group.';const LOCALHOST_ORIGIN_MARKER = 'localhost:';-// clix always sent `session_timezone: 'UTC'`; the queries converted from clix-// keep sending it so their result sets stay identical.+// Always sent as `session_timezone: 'UTC'` to keep these queries' result+// sets consistent.const CLIX_SESSION_TIMEZONE = { session_timezone: 'UTC' } as const;const QUERY_EVENTS_FILTER_TARGET = {@@ -546,13 +545,10 @@ export async function createEvent(// `isFromEvent=true` activates profile-buffer's cache shortcut: if the// profile is in the 1h Redis cache (i.e. recently flushed), the add is// skipped. Trade-off: profile.last_seen_at granularity is capped at the- // cache TTL (~1h) rather than per-session. We accept this because- // (a) profile-buffer was the leading indicator in the 2026-05-20 buildup- // and was processing ~2 writes per session per anonymous user;- // (b) the bulk of those writes carried no new information (anonymous- // profile data is event-derived and stable across a session);- // (c) recency queries should derive from event timestamps, not from- // profile.last_seen_at.+ // cache TTL (~1h) rather than per-session. Accepted because (a) the bulk+ // of those writes carry no new information (anonymous profile data is+ // event-derived and stable across a session), and (b) recency queries+ // should derive from event timestamps, not from profile.last_seen_at.if (payload.name === 'session_start' || payload.name === 'session_end') {promises.push(upsertProfile(deps, profile, true));}@@ -583,7 +579,7 @@ export interface GetEventListOptions {dateIntervalInDays?: number;}-/** V1's default projection, merged under whatever the caller asks for. */+/** Default projection, merged under whatever the caller asks for. */const DEFAULT_EVENT_LIST_SELECT: EventListSelect = {id: true,name: true,@@ -600,7 +596,6 @@ const DEFAULT_EVENT_LIST_SELECT: EventListSelect = {browser: true,};-// V1 emitted these in this order, `created_at` and `project_id` always first.const SELECT_TO_COLUMN: readonly [keyof EventListSelect, EventListColumn][] = [['id', 'id'],['name', 'name'],@@ -742,7 +737,6 @@ export async function getEventList(meta: select.meta ?? true,});- // If we dont get any events, try without the cursor windowif (data.length === 0 && hasLookback && lookbackDays < maxLookbackDays) {return getEventList(deps, {...options,@@ -836,7 +830,6 @@ export async function getTopPages();}-/** V1's `eventService.getById`. */export async function getEventById(deps: ServiceDeps,{@@ -1038,8 +1031,6 @@ export async function queryEventsCore();}-// ---- packages/trpc/src/routers/event.ts bodies-export interface UpdateEventMetaInput {projectId: string;name: string;@@ -1065,9 +1056,9 @@ export async function updateEventMeta(});}-/** The session half arrives through the composition root's thunk (ADR-022 R3):- * `session.service` → `session-end` → this module is a static chain, so an- * import back would be a plain cycle evaluated in the wrong order. */+/** The session half arrives through the composition root's thunk:+ * `session.service` → `session-end` → this module is a static import chain,+ * so an import back would be a cycle evaluated in the wrong order. */export async function getEventDetails(deps: ServiceDeps,services: () => Services,diff --git a/packages/core/src/modules/event/src/sql.ts b/packages/core/src/modules/event/src/sql.tsindex a84fcc144..175c0450a 100644--- a/packages/core/src/modules/event/src/sql.ts+++ b/packages/core/src/modules/event/src/sql.ts@@ -7,10 +7,9 @@// Cluster note: `events`, `profiles`, `groups` and `cohort_members` are// Distributed on Cloud. The identity-stitching and cohort `IN (SELECT...)`// subqueries, the profile/group LEFT ANY JOINs and any `IN (SELECT...)` a-// filter compiles keep V1's exact shape and run under the client's-// `distributed_product_mode: 'allow'` as before — converting a query is not the-// place to change its cluster semantics. Every `IN` list binds as-// `Array(String)`, a literal list to the planner.+// filter compiles all run under the client's `distributed_product_mode:+// 'allow'`. Every `IN` list binds as `Array(String)`, a literal list to the+// planner.import { type SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';import {@@ -88,7 +87,7 @@ export const NO_FILTER_JOINS: EventFilterJoins = {groups: false,};-/** The joins the compiled filters need, with V1's leading space; empty = none. */+/** The joins the compiled filters need; empty = none. */function filterJoins(projectId: string, joins: EventFilterJoins): SqlFragment {const parts: SqlFragment[] = [];if (joins.profileColumns.length > 0) {@@ -118,7 +117,7 @@ export interface EventListQuery {projectId: string;columns: readonly EventListColumn[];take: number;- /** Numeric cursor pages: `OFFSET` only when non-zero, as V1. */+ /** Numeric cursor pages: `OFFSET` only when non-zero. */offset?: number;/** Date cursor pages: strict upper bound plus the lookback window. */cursor?: Date;@@ -133,11 +132,11 @@ export interface EventListQuery {events?: readonly string[];filterClauses: CompiledFilterClauses;joins: EventFilterJoins;- /** `event.conversions`' extra `name IN (..)`, appended after the filters as V1 did. */+ /** `event.conversions`' extra `name IN (..)`, appended after the filters. */conversionNames?: readonly string[];}-/** V1's `sb.where` in insertion order — the text has to match a cached V1 plan byte for byte. */+/** Conditions in a fixed insertion order — the text has to match a cached query plan byte for byte. */function eventListConditions(query: EventListQuery): SqlFragment[] {const conditions: SqlFragment[] = [];const projectId = sql.string(query.projectId);@@ -387,8 +386,6 @@ export function queryEventsQuery(query: QueryEventsQuery): SqlFragment {)} ORDER BY created_at DESC LIMIT ${sql.uint64(query.limit)}`;}-// ---- packages/trpc/src/routers/event.ts's inline queries-export function botEventsQuery(query: {projectId: string;limit: number;diff --git a/packages/core/src/modules/export/export.routes.ts b/packages/core/src/modules/export/export.routes.tsindex 0823efa71..8c317bcf3 100644--- a/packages/core/src/modules/export/export.routes.ts+++ b/packages/core/src/modules/export/export.routes.ts@@ -1,29 +1,13 @@-// Ported from apps/api/src/routes/export.router.ts + insights.router.ts and-// their controllers. V1's Fastify routes stay the LIVE surface (DELEGATE-// PATTERN) and already call these same `@openpanel/db`-re-exported `*Core`-// functions (M7-001..006 moved the implementations; the V1 controllers were-// updated to delegate as each module landed). This file is the same surface-// rebuilt on Elysia, so the target port has somewhere to land at P8 without-// redesigning the API it replaces — no new query logic, every call below is the-// same function V1's controller calls.+// `allow: ['read', 'root']`: a `write`-type client may not read analytics+// back out.//-// `allow: ['read', 'root']` mirrors V1's rule (utils/auth.ts's-// `validateExportRequest`, shared by both `/export` and `/insights`: a-// `write`-type client may not read analytics back out).+// `http/query.ts`'s `parseQueryString` transform hook is registered LOCAL on+// both surfaces below; every zod schema here validates AFTER that hook runs,+// so without it a plain `?limit=5` fails validation.//-// Mounted this surface and landed the missing half: V1's `parseQueryString`-// pre-pass is now `http/query.ts`'s `transform` hook, registered LOCAL on both-// surfaces below. Every zod schema here is the one V1 validates AFTER that hook-// runs, so without it a plain `?limit=5` fails validation.-//-// `listDashboards`/`listReports` (insights.controller.ts) are mounted under-// `/manage/projects/:projectId/dashboards[...]` in V1 (manage.router.ts) — that-// surface belongs to the project module, not here.-//-// The 18 `overviewColumns` routes are written out rather than looped: a mutable-// reassignment of the Elysia chain inside a `for` loop widens past what-// `defineRoutes`'s `const T` inference can carry, same reason every other-// module here writes its routes as one static `.get`/`.post` chain.+// The 18 `overviewColumns` routes are written out rather than looped: a+// mutable reassignment of the Elysia chain inside a `for` loop widens past+// what `defineRoutes`'s `const T` inference can carry.import { DateTime } from '@openpanel/shared';import { z } from 'zod';@@ -97,8 +81,7 @@ const CLIENT_ALLOW: { allow: ClientType[]; label: 'Export' } = {};// REST querystrings can't carry arrays of objects natively. Callers pass-// `filters` as a URL-encoded JSON string; decoded here (ported verbatim from-// insights.controller.ts's `zFiltersParam`).+// `filters` as a URL-encoded JSON string; decoded here.const zFiltersParam = z.preprocess((value) => {if (value == null || value === '') {@@ -196,9 +179,8 @@ export const exportRoutes = defineRoutes((app) =>async ({ query, client, ctx }) => {const resolved = await resolveExportProjectId(ctx, client, query);if (!resolved.ok) {- // V1's controller threw an `HttpError` and let the error handler- // shape it; the body is `{status, message}` because `HttpError.error`- // is undefined and JSON drops it.+ // The body is `{status, message}` because `HttpError.error` is+ // undefined and JSON drops it.throw new HttpError(resolved.message, { status: resolved.status });}const {@@ -261,9 +243,8 @@ export const exportRoutes = defineRoutes((app) =>async ({ query, client, ctx }) => {const resolved = await resolveExportProjectId(ctx, client, query);if (!resolved.ok) {- // V1's controller threw an `HttpError` and let the error handler- // shape it; the body is `{status, message}` because `HttpError.error`- // is undefined and JSON drops it.+ // The body is `{status, message}` because `HttpError.error` is+ // undefined and JSON drops it.throw new HttpError(resolved.message, { status: resolved.status });}const { timezone } = await getSettingsForProject(@@ -343,7 +324,7 @@ type OverviewGenericQuery = z.infer<typeof zOverviewGenericQuerystring>;type InsightsProjectParam = z.infer<typeof projectIdParam>;type InsightsClient = Parameters<typeof resolveInsightsProjectId>[1];-/** Shared body of the 18 `overviewColumns` routes below (V1's `getOverviewGeneric(column)`). */+/** Shared body of the 18 `overviewColumns` routes below. */async function getOverviewGeneric(ctx: Ctx,column: IGetTopGenericInput['column'],diff --git a/packages/core/src/modules/export/export.service.ts b/packages/core/src/modules/export/export.service.tsindex ea92575e4..14c72329f 100644--- a/packages/core/src/modules/export/export.service.ts+++ b/packages/core/src/modules/export/export.service.ts@@ -1,16 +1,12 @@// The export module owns no data of its own — it is the public read API-// (`/export` + `/insights`, 56 GET routes, TARGET_ARCHITECTURE §7). Every-// handler in `export.routes.ts` is a thin delegate onto the overview/chart/-// event/session/profile/group/gsc/report services already ported to core-// (M7-001..006). This file holds only the plumbing every route shares —-// resolving a project id and a date range — ported verbatim from-// apps/api/src/controllers/{export,insights}.controller.ts. No new query logic:-// every resolution here already existed in V1's controllers.+// (`/export` + `/insights`). Every handler in `export.routes.ts` is a thin+// delegate onto the overview/chart/event/session/profile/group/gsc/report+// services. This file holds only the plumbing every route shares — resolving+// a project id and a date range.//-// `loadDb` and `loadCore` are gone. Postgres is `deps.db`, and the sibling-// services these routes delegate to are imported by RELATIVE path — the hazard-// the old `loadCore` guarded against was re-entering this package's own barrel-// (`@openpanel/core`) mid-evaluation, which a relative import cannot do.+// The sibling services these routes delegate to are imported by RELATIVE+// path rather than through this package's own barrel (`@openpanel/core`), to+// avoid re-entering it mid-evaluation, which a relative import cannot do.import { resolveDateRange } from '@openpanel/shared';import type { AuthenticatedClient } from '../../http/client-auth';@@ -25,12 +21,11 @@ export type ProjectIdResolution =| { ok: false; status: 400 | 403 | 404; message: string };/**- * `/export/*`'s own project-id resolution (apps/api's export.controller.ts- * `getProjectId`): the project id travels in the QUERYSTRING- * (`project_id`/`projectId`), not a path param, and a `read` client may pass- * one as long as it matches their own — a different shape than `/insights`'s- * path-param resolution below, so it stays its own function rather than- * being folded into `resolveClientProjectId`.+ * `/export/*`'s own project-id resolution: the project id travels in the+ * QUERYSTRING (`project_id`/`projectId`), not a path param, and a `read`+ * client may pass one as long as it matches their own — a different shape+ * than `/insights`'s path-param resolution below, so it stays its own+ * function rather than being folded into `resolveClientProjectId`.*/export async function resolveExportProjectId(deps: ServiceDeps,@@ -72,8 +67,7 @@ export async function resolveExportProjectId(/*** `/insights/:projectId/*`'s project-id resolution — `resolveClientProjectId`- * is the single client->project resolution point (ADR-011 A-iii invariant 12),- * already what apps/api's insights.controller.ts `getProjectId` calls.+ * is the single client->project resolution point.*/export async function resolveInsightsProjectId(deps: ServiceDeps,@@ -89,8 +83,8 @@ export async function resolveInsightsProjectId(}/**- * Ported verbatim from insights.controller.ts's `resolveDates`: a `range`- * needs the project's timezone to resolve; an explicit `startDate` does not.+ * A `range` needs the project's timezone to resolve; an explicit `startDate`+ * does not.*/export async function resolveInsightsDateRange(deps: ServiceDeps,@@ -115,8 +109,7 @@ const DATE_ONLY_LENGTH = 10;* searchAnalytics API takes `YYYY-MM-DD`, so the datetime bounds the event and* session tables need are wrong for both: ClickHouse refuses* `'2026-08-07 00:00:00'` with "Cannot convert string ... to type Date", which- * failed every /insights/:projectId/gsc/* route for a named `range`- * (main a0e122e8).+ * failed every /insights/:projectId/gsc/* route for a named `range`.*/export async function resolveGscInsightsDateRange(deps: ServiceDeps,diff --git a/packages/core/src/modules/group/src/sql.ts b/packages/core/src/modules/group/src/sql.tsindex 6b70424a8..e74b60e7d 100644--- a/packages/core/src/modules/group/src/sql.ts+++ b/packages/core/src/modules/group/src/sql.ts@@ -24,7 +24,6 @@ function optional(return condition ? fragment() : sql.empty;}-/** V1's `WHERE project_id = .. AND deleted = 0 [AND type = ..] [AND (name|id ILIKE ..)]`. */function liveGroupsCondition(query: {projectId: string;type?: string;@@ -169,8 +168,6 @@ export function groupMemberProfilesQuery(`;}-// ---- packages/trpc/src/routers/group.ts's inline queries-export function groupEventMetricsQuery(query: {projectId: string;groupId: string;diff --git a/packages/core/src/modules/gsc/gsc.service.test.ts b/packages/core/src/modules/gsc/gsc.service.test.tsindex e01a892f4..768af87ae 100644--- a/packages/core/src/modules/gsc/gsc.service.test.ts+++ b/packages/core/src/modules/gsc/gsc.service.test.ts@@ -151,12 +151,10 @@ const validateAuthorizationCode = mock(async () => ({refreshToken: () => 'google-refresh-token',accessTokenExpiresAt: () => new Date('2026-09-04T00:00:00.000Z'),}));-// Spread the real module — see the clickhouse/client mock above for why a-// partial factory here is a process-wide hazard, not a local one. Surfaced by-// M6-001: @openpanel/db's organization.service.ts shim (imported below) now-// re-exports from @openpanel/core's full barrel, which reaches this same-// auth.service.ts for createAuthService — a partial replacement here used to be-// invisible because nothing else in this file's chain needed it.+// Spread the real module: a partial factory here is a process-wide hazard,+// not a local one — under bare `bun test` (AGENTS.md) it silently breaks any+// other code path that imports this same module for an export this file's+// chain doesn't happen to need.const actualAuthService = await import('../auth/auth.service');mock.module('../auth/auth.service', () => ({...actualAuthService,diff --git a/packages/core/src/modules/gsc/gsc.service.ts b/packages/core/src/modules/gsc/gsc.service.tsindex 63cf4e83d..517d3cf33 100644--- a/packages/core/src/modules/gsc/gsc.service.ts+++ b/packages/core/src/modules/gsc/gsc.service.ts@@ -1,26 +1,20 @@// The GSC OAuth token lifecycle, the Search Console API client, ClickHouse// read/write, the AI-tool wrapper functions and the-// gscProjectSync/gscProjectBackfill job bodies. packages/db/src/gsc.ts and-// packages/db/src/services/gsc.service.ts become re-export shims of this file-// (same shape as packages/db/src/encryption.ts since M4-006).+// gscProjectSync/gscProjectBackfill job bodies.//-// Every exported function takes `ServiceDeps` and reaches Postgres as `deps.db`-// and ClickHouse as `deps.ch`; the `loadDb`/`loadChClient` lazy loaders are-// gone, so the requestId minted at the edge reaches the query.-// `getGscCannibalization` is `cacheablePerDeps`: `cacheable` keys on the call's-// ARGUMENTS (packages/redis/cachable.ts), so the caller's deps travel beside-// the key rather than inside it and the Redis key stays byte-identical.+// Every exported function takes `ServiceDeps` and reaches Postgres as+// `deps.db` and ClickHouse as `deps.ch`, so the requestId minted at the edge+// reaches the query. `getGscCannibalization` is `cacheablePerDeps`:+// `cacheable` keys on the call's ARGUMENTS, so the caller's deps travel+// beside the key rather than inside it and the Redis key stays+// byte-identical.//-// DELIBERATE BEHAVIOUR CHANGE, recorded: the reads and the four sync inserts-// used @openpanel/db's `originalCh` (the first configured node, no retry).-// `deps.ch` is the round-robin/retry proxy every other core module already-// uses, which also applies the shared INSERT_DEFAULT_SETTINGS-// (`wait_end_of_query`, insert block size) to those inserts. Same rows, same-// tables; strictly more failover.+// `deps.ch` is the round-robin/retry proxy every other core module uses,+// which also applies the shared INSERT_DEFAULT_SETTINGS+// (`wait_end_of_query`, insert block size) to the four sync inserts here.//-// ClickHouse queries here still go through raw SQL strings, 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.+// ClickHouse queries here still go through raw SQL strings, not the `sql`+// tag — this module's queries haven't been converted yet.import type { ClickHouseSettings } from '@clickhouse/client';import { decrypt, encrypt } from '@openpanel/shared/server';@@ -717,8 +711,7 @@ export async function getGscQueries(}// ---------------------------------------------------------------------------// Connection CRUD — moved from packages/trpc/src/routers/gsc.ts's-// getConnection/selectSite/disconnect handler bodies.+// Connection CRUD.// ---------------------------------------------------------------------------export interface GscConnectionSummary {@@ -778,9 +771,8 @@ export async function disconnectGscConnection(}// ---------------------------------------------------------------------------// Dashboard aggregate queries — moved from packages/trpc/src/routers/gsc.ts.-// The trpc router itself stays on V1 (DELEGATE PATTERN); this is its-// date-resolution and search/AI-engine breakdown logic.+// Dashboard aggregate queries — date resolution and search/AI-engine+// breakdown logic.// ---------------------------------------------------------------------------export interface GscDateRangeInput {@@ -1045,9 +1037,8 @@ export async function getGscPreviousOverview(}// ----------------------------------------------------------------------------// AI-tool wrappers — moved from packages/db/src/services/gsc.service.ts.-// Consumed by apps/api's assistant SEO tools and the /insights REST surface-// (both still reach @openpanel/db, which re-exports these unchanged).+// AI-tool wrappers — consumed by apps/api's assistant SEO tools and the+// /insights REST surface.// ---------------------------------------------------------------------------export interface GscQueryOpportunity {@@ -1281,8 +1272,8 @@ export async function gscGetCannibalizationCore(}// ---------------------------------------------------------------------------// Job bodies — moved from apps/worker/src/jobs/gsc.ts. Each fully owns its-// status-update bookkeeping so the worker file is a bare dispatch.+// Job bodies. Each fully owns its status-update bookkeeping so the worker+// file is a bare dispatch.// ---------------------------------------------------------------------------/** The `gscSync` cron fan-out: every project with a connected GSC site. */@@ -1369,7 +1360,6 @@ export async function runGscProjectBackfill(const startDate = new Date(endDate);startDate.setMonth(startDate.getMonth() - BACKFILL_MONTHS);- // Process in chunks to avoid timeouts and respect API limitslet chunkEnd = new Date(endDate);while (chunkEnd > startDate) {const chunkStart = new Date(chunkEnd);@@ -1419,10 +1409,8 @@ export async function runGscProjectBackfill(}// ---------------------------------------------------------------------------// OAuth callback — moved from apps/api/src/controllers/gsc-oauth-callback.-// controller.ts's business logic. Cookie reading/signing and the redirect stay-// with each transport (Fastify today, Elysia's gsc.routes.ts once it is live) —-// this is the part that is transport-agnostic.+// OAuth callback business logic. Cookie reading/signing and the redirect+// stay with the transport route; this is the transport-agnostic part.// ---------------------------------------------------------------------------export interface GscOAuthCallbackInput {@@ -1527,7 +1515,7 @@ export function createGscService(deps: ServiceDeps, _services: () => Services) {getGscConnection(deps, projectId),listSites: (projectId: string): Promise<GscSite[]> =>listGscSites(deps, projectId),- /** Also enqueues the `gscProjectBackfill` job — same as V1's router. */+ /** Also enqueues the `gscProjectBackfill` job. */selectSite: async (projectId: string, siteUrl: string): Promise<void> => {await selectGscSite(deps, projectId, siteUrl);await deps.queues.gsc.gscProjectBackfill.add({ projectId });diff --git a/packages/core/src/modules/health/health.routes.ts b/packages/core/src/modules/health/health.routes.tsindex 0d6a24b88..aabbe8b53 100644--- a/packages/core/src/modules/health/health.routes.ts+++ b/packages/core/src/modules/health/health.routes.ts@@ -1,14 +1,11 @@// Kubernetes liveness and readiness.//-// `/healthcheck` — the deep db/ch/redis probe — landed at M9-004, when-// `AppDeps` started carrying the real clients; before that, porting it would-// have been a fake check rather than a deferred one. `/healthz/ready` never-// waited for them: its two inputs are the shutdown flag and the events-consumer-// heartbeat, both real from P9, and a readiness probe that ignores a draining-// process is the one that actually loses requests.+// `/healthcheck` — the deep db/ch/redis probe — needs `AppDeps` carrying the+// real clients. `/healthz/ready` never waits for them: its two inputs are the+// shutdown flag and the events-consumer heartbeat, and a readiness probe that+// ignores a draining process is the one that actually loses requests.//-// `GET /` lands here too: V1 served it from the public-API scope-// (apps/api/src/app.ts:400), hidden from the OpenAPI document like the probes,+// `GET /` lands here too, hidden from the OpenAPI document like the probes,// and self-hosters use it as a "is this thing on" check.import { tryCatch } from '@openpanel/shared';@@ -21,10 +18,10 @@ import { currentReadiness } from './src/readiness';// with `io: 'output'`, which is what zod 4's native Standard Schema JSON// conversion does by default for the `response` slot — no `mapJsonSchema`// override needed, and none is added, because that hook gets no `io` argument-// and would collapse the input/output split the ADR requires.+// and would collapse the input/output split this schema relies on.const healthLiveResponseSchema = z.object({ live: z.literal(true) });-// V1's two readiness bodies, verbatim: `{ready:true}` at 200, and+// Two readiness bodies: `{ready:true}` at 200, and// `{ready:false, reason, idleMs?, thresholdMs?}` at 503.const healthReadyResponseSchema = z.object({ready: z.boolean(),@@ -45,7 +42,6 @@ const healthCheckResponseSchema = z.object({const SERVICE_UNAVAILABLE = 503;const OK = 200;-/** V1's `GET /` body, byte-for-byte (apps/api/src/app.ts:401-404). */const ROOT_BODY = {status: 'ok',message: 'Successfully running OpenPanel.dev API',@@ -56,11 +52,8 @@ const rootResponseSchema = z.object({message: z.literal(ROOT_BODY.message),});-// Hidden from the OpenAPI document — ported from V1's `schema: { hide: true }`-// on `/healthz/live`, `/healthz/ready` and `/healthcheck`-// (healthcheck.controller.ts): liveness probes are not part of the public API-// contract. See verification/golden/openapi's migrated-route gate, which pins-// `/healthz` to an empty `paths` object against V1's golden document.+// Hidden from the OpenAPI document: liveness probes are not part of the+// public API contract.export const healthRoutes = defineRoutes((app) =>app.get('/healthz/live', () => ({ live: true as const }), {diff --git a/packages/core/src/modules/import/import.routes.ts b/packages/core/src/modules/import/import.routes.tsindex 5a83626d1..a53cdfc4f 100644--- a/packages/core/src/modules/import/import.routes.ts+++ b/packages/core/src/modules/import/import.routes.ts@@ -1,24 +1,12 @@-// Ported from apps/api/src/routes/import.router.ts +-// apps/api/src/controllers/import.controller.ts's business logic. V1's Fastify-// controller stays the LIVE route (DELEGATE PATTERN) and delegates its-// ClickHouse insert to import.service.ts's `insertRawEventsBatch` — the same-// function this route calls.+// This route delegates its ClickHouse insert to import.service.ts's+// `insertRawEventsBatch`.//-// NAMED GAP, same as gsc.routes.ts: this route is not yet reachable.-// `authenticateClient` (http/client-auth.ts) is a P8 stub that always returns-// null, so `clientAuth` 401s every request until it is filled in; main.ts also-// does not mount `publicApiRoutes` until a real `AppDeps` exists. `allow:-// ['read', 'root']` mirrors V1's rule (utils/auth.ts's `validateImportRequest`:-// a `write`-type client may not import).+// `allow: ['read', 'root']`: a `write`-type client may not import.//-// V1 has no request-body schema for this route (ADR-003: "/profile, /import,-// /event and /tools have no request schemas today, and adding them would be a-// behaviour change"), so the body is typed but not shape-validated.+// The body is typed but not shape-validated for this route.//-// `client.projectId` is `null` for a root client (M6-002 widened-// AuthenticatedClient to match IServiceClientWithProject); V1's controller-// guards on exactly this (apps/api/src/controllers/import.controller.ts:17-18),-// ported verbatim.+// `client.projectId` is `null` for a root client, which is why the handler+// guards on it explicitly before importing.import { z } from 'zod';import { defineRoutes } from '../../http/define';diff --git a/packages/core/src/modules/import/import.service.ts b/packages/core/src/modules/import/import.service.tsindex b081ffd26..ec5d958db 100644--- a/packages/core/src/modules/import/import.service.ts+++ b/packages/core/src/modules/import/import.service.ts@@ -1,14 +1,10 @@-// Db/ch access is LAZY (`load*` below), not a static top-level import — see-// gsc.service.ts's header for the full reasoning (jobs.registry.ts and-// services.ts pull this module into the eager barrel chain nearly every core-// test file reaches). The provider classes are behind a dynamic `import` for-// the same reason: they eagerly import `formatClickhouseDate` from-// @openpanel/db's clickhouse client, which constructs a real pino transport at-// import time.+// The provider classes are behind a dynamic `import`: they eagerly import+// `formatClickhouseDate` from @openpanel/db's clickhouse client, which+// constructs a real pino transport at import time. See gsc.service.ts's+// header for the full reasoning.//// ClickHouse queries here still go through raw `ch`/`chQuery` calls, 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.+// `sql` tag — this module's queries haven't been converted yet.import { createHash } from 'node:crypto';import type { Prisma } from '@openpanel/db/src/prisma-client';@@ -41,8 +37,7 @@ function yieldToEventLoop(): Promise<void> {}// ----------------------------------------------------------------------------// ClickHouse staging pipeline — moved from packages/db/src/services/-// import.service.ts.+// ClickHouse staging pipeline// ---------------------------------------------------------------------------export interface ImportStageResult {@@ -51,9 +46,6 @@ export interface ImportStageResult {insertedEvents: number;}-/**- * Insert a batch of events into the imports staging table- */export async function insertImportBatch(deps: ServiceDeps,events: IClickhouseEvent[],@@ -86,10 +78,7 @@ export async function insertImportBatch(};}-/**- * Insert a batch of profiles into the production profiles table.- * Used by Mixpanel (and other providers) to import user profiles during an import job.- */+/** Used by Mixpanel (and other providers) to import user profiles during an import job. */export async function insertProfilesBatch(deps: ServiceDeps,profiles: IClickhouseProfile[],@@ -126,11 +115,6 @@ export async function insertProfilesBatch(return { inserted: normalized.length };}-/**- * Generate gap-based session IDs for events that have none.- * Streams events from staging (sorted by device_id, created_at), assigns a new- * session when gap > 30 min, re-inserts with session_id, then deletes old rows.- */const SESSION_GAP_MS = 30 * 60 * 1000; // 30 minutesexport async function generateGapBasedSessionIds(@@ -215,10 +199,7 @@ export async function generateGapBasedSessionIds(});}-/**- * Delete all staging data for an import. Used to get a clean slate on retry- * when the failure happened before moving data to production.- */+/** Used to get a clean slate on retry when the failure happened before moving data to production. */export async function cleanupStagingData(deps: ServiceDeps,importId: string@@ -262,12 +243,8 @@ export async function cleanupSessionStartEndEvents(}/**- * Reconstruct sessions across ALL dates for the import.- * Each session_id gets exactly one session_start and one session_end,- * even if the session spans midnight.- *- * Batches by fetching distinct session_ids first, then running the- * heavy aggregation only for that batch of IDs.+ * Runs across ALL dates for the import, so each session_id gets exactly one+ * session_start and one session_end even when the session spans midnight.*/export async function createSessionsStartEndEvents(deps: ServiceDeps,@@ -488,10 +465,6 @@ export async function createSessionsStartEndEvents(}}-/**- * Move events from staging to production events table.- * Batched per-day using a simple date filter.- */export async function moveImportsToProduction(deps: ServiceDeps,importId: string,@@ -535,7 +508,6 @@ export async function moveImportsToProduction(}/**- * Aggregate sessions from staging into the sessions table.* Runs across all dates so cross-midnight sessions become one row.* Batches by session_ids to bound ClickHouse memory.*/@@ -645,9 +617,6 @@ export async function backfillSessionsToProduction(}}-/**- * Get min/max created_at for an import's staging data.- */export async function getImportDateBounds(deps: ServiceDeps,importId: string,@@ -678,12 +647,10 @@ export async function getImportDateBounds(}/**- * Reports progress on a running import. Wraps V1's `job.updateProgress` — a- * BullMQ `Job` satisfies this structurally, so the V1 worker delegate passes- * its real job straight through. Core's own job runner (import.jobs.ts) has- * no BullMQ job object to hand over (`JobCtx.job` is the erased- * `{id, attempt, queue, name}`, not the live BullMQ handle), so it falls back- * to the no-op default.+ * Reports progress on a running import. A BullMQ `Job` satisfies this+ * structurally. Core's own job runner (import.jobs.ts) has no BullMQ job+ * object to hand over (`JobCtx.job` is the erased `{id, attempt, queue,+ * name}`, not the live BullMQ handle), so it falls back to the no-op default.*/export interface ImportJobProgress {updateProgress(progress: Record<string, unknown>): unknown;@@ -804,7 +771,7 @@ export async function updateImportStatus(}// ----------------------------------------------------------------------------// Provider dispatch + job body — moved from apps/worker/src/jobs/import.ts.+// Provider dispatch + job body// ---------------------------------------------------------------------------/**@@ -880,10 +847,9 @@ async function createImportProvider(}/**- * The `import` queue job body. Ported verbatim from apps/worker/src/jobs/- * import.ts's `importJob`, with the BullMQ `Job` split into `importId` +- * `progress` (see `ImportJobProgress`'s header) so the same body serves V1's- * worker delegate and core's own (not yet live) `import` queue worker.+ * The `import` queue job body. Takes `importId` + `progress` rather than a+ * BullMQ `Job` directly (see `ImportJobProgress`'s header) so it can run+ * under either a real BullMQ job or core's own job runner.*/export async function runImportJob(deps: ServiceDeps,@@ -963,8 +929,8 @@ export async function runImportJob(const transformed = providerInstance.transformEvent(rawEvent);- // Session IDs for providers that need them (e.g. Mixpanel) are generated- // in generateGapBasedSessionIds after loading, using gap-based logic.+ // Session IDs for providers that need them (e.g. Mixpanel) are+ // generated in generateGapBasedSessionIds after loading.eventBatch.push(transformed);if (canProfileFromEvents) {@@ -1185,10 +1151,9 @@ export async function runImportJob(}// ----------------------------------------------------------------------------// /import/events — moved from apps/api/src/controllers/import.controller.ts.-// Bulk-inserts already-shaped events straight into production; unrelated to-// the provider/staging pipeline above (no Import record, no ClickHouse-// staging table).+// /import/events — bulk-inserts already-shaped events straight into+// production; unrelated to the provider/staging pipeline above (no Import+// record, no ClickHouse staging table).// ---------------------------------------------------------------------------export interface InsertRawEventsResult {diff --git a/packages/core/src/modules/import/src/base-provider.ts b/packages/core/src/modules/import/src/base-provider.tsindex 4e58766ba..8c2127493 100644--- a/packages/core/src/modules/import/src/base-provider.ts+++ b/packages/core/src/modules/import/src/base-provider.ts@@ -15,19 +15,10 @@ export abstract class BaseImportProvider<overrideFrom?: string): AsyncGenerator<TRawEvent, void, unknown>;- /**- * Convert provider format → IClickhouseEvent- */abstract transformEvent(rawEvent: TRawEvent): IClickhouseEvent;- /**- * Validate raw event structure- */abstract validate(rawEvent: TRawEvent): boolean;- /**- * Returns how many events will be imported- */abstract getTotalEventsCount(): Promise<number>;/**@@ -37,12 +28,11 @@ export abstract class BaseImportProvider<* If false, assumes the provider already generates session IDs during streaming*/shouldGenerateSessionIds(): boolean {- return false; // Default: assume provider handles it+ return false;}/**- * Utility: Split a date range into chunks to avoid timeout issues with large imports- * Returns array of [from, to] date pairs in YYYY-MM-DD format+ * Utility: Split a date range into chunks to avoid timeout issues with large imports.** @param from - Start date in YYYY-MM-DD format* @param to - End date in YYYY-MM-DD format@@ -61,7 +51,6 @@ export abstract class BaseImportProvider<const endDate = new Date(to);const chunkSizeDays = options?.chunkSizeDays ?? 1;- // Handle case where from and to are the same dateif (startDate.getTime() === endDate.getTime()) {return [[from, to]];}@@ -75,7 +64,6 @@ export abstract class BaseImportProvider<const chunkEndDate = new Date(cursor);chunkEndDate.setDate(chunkEndDate.getDate() + (chunkSizeDays - 1));- // Don't go past the end dateconst chunkEnd =chunkEndDate > endDate? endDate.toISOString().split('T')[0]!@@ -83,7 +71,6 @@ export abstract class BaseImportProvider<chunks.push([chunkStart, chunkEnd]);- // Move cursor to the next chunk start (after the current chunk)cursor.setDate(cursor.getDate() + chunkSizeDays);if (cursor > endDate) {diff --git a/packages/core/src/modules/import/src/providers/mixpanel.ts b/packages/core/src/modules/import/src/providers/mixpanel.tsindex b7d0c1b96..812e85e6e 100644--- a/packages/core/src/modules/import/src/providers/mixpanel.ts+++ b/packages/core/src/modules/import/src/providers/mixpanel.ts@@ -82,19 +82,16 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {const now = Date.now();const oneHourAgo = now - 60 * 60 * 1000;- // Prune timestamps older than 1 hourthis.requestTimestamps = this.requestTimestamps.filter((t) => t > oneHourAgo);- // Enforce per-second limit (3 QPS → min 334ms gap)const timeSinceLast = now - this.lastRequestTime;if (timeSinceLast < MixpanelProvider.MIN_REQUEST_INTERVAL_MS) {const delay = MixpanelProvider.MIN_REQUEST_INTERVAL_MS - timeSinceLast;await new Promise((resolve) => setTimeout(resolve, delay));}- // Enforce hourly limitif (this.requestTimestamps.length >= MixpanelProvider.MAX_REQUESTS_PER_HOUR) {@@ -111,7 +108,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {`Rate limit: ${this.requestTimestamps.length} requests in the last hour, waiting ${Math.ceil(waitMs / 1000)}s`);await new Promise((resolve) => setTimeout(resolve, waitMs));- // Prune again after waitingthis.requestTimestamps = this.requestTimestamps.filter((t) => t > Date.now() - 60 * 60 * 1000);@@ -165,7 +161,7 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {chunkFrom,chunkTo);- break; // Success, move to next chunk+ break;} catch (error) {retries++;const isRateLimit =@@ -270,7 +266,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {throw new Error('No response body from Mixpanel API');}- // Stream the response line by lineconst reader = response.body.getReader();const decoder = new TextDecoder();let buffer = '';@@ -285,7 +280,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {buffer += decoder.decode(value, { stream: true });- // Process complete linesconst lines = buffer.split('\n');buffer = lines.pop() || ''; // Keep the last incomplete line in buffer@@ -304,7 +298,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {}}- // Process any remaining line in bufferif (buffer.trim()) {try {const event = JSON.parse(buffer);@@ -321,10 +314,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {}}- /**- * Stream user profiles from Mixpanel Engage API.- * Paginates with page/page_size (5k per page) and yields each profile.- */async *streamProfiles(): AsyncGenerator<MixpanelRawProfile, void, unknown> {const { serviceAccount, serviceSecret, projectId } = this.config;const pageSize = 5000;@@ -399,9 +388,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {}}- /**- * Map Mixpanel Engage profile to OpenPanel IClickhouseProfile.- */transformProfile(raw: MixpanelRawProfile): IClickhouseProfile {const parsed = zMixpanelRawProfile.parse(raw);const props = (parsed.$properties || {}) as Record<string, unknown>;@@ -481,7 +467,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {// Check for UTM referrer in query params (web only)const utmReferrer = getReferrerWithQuery(query);- // Extract location dataconst country = props.$country || props.mp_country_code || '';const city = props.$city || '';const region = props.$region || '';@@ -498,13 +483,11 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {eventName = 'screen_view';}- // Build properties object - strip Mixpanel-specific propertiesconst properties = this.stripMixpanelProperties(props, query);if (props.$insert_id) {properties.__source_insert_id = String(props.$insert_id);}- // Add useful propertiesif (props.$screen_width && props.$screen_height) {properties.__screen = `${props.$screen_width}x${props.$screen_height}`;}@@ -607,7 +590,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {uaInfo: UserAgentInfo,props: Record<string, any>) {- // Normalize lib/os/browser dataconst lib = (mp_lib || '').toLowerCase();const os = String(props.$os || uaInfo.os || '').toLowerCase();const browser = String(@@ -646,7 +628,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {return 'tablet';}- // Default to desktopreturn this.isServerEvent(mp_lib) ? 'server' : 'desktop';}@@ -666,7 +647,6 @@ export class MixpanelProvider extends BaseImportProvider<MixpanelRawEvent> {}private parseServerDeviceInfo(props: Record<string, any>): UserAgentInfo {- // For mobile events, extract device information from Mixpanel propertiesconst os = props.$os || props.os || '';const osVersion = props.$os_version || props.osVersion || '';const brand = props.$brand || props.phoneBrand || '';diff --git a/packages/core/src/modules/import/src/providers/umami.ts b/packages/core/src/modules/import/src/providers/umami.tsindex 267d837f2..39d14700f 100644--- a/packages/core/src/modules/import/src/providers/umami.ts+++ b/packages/core/src/modules/import/src/providers/umami.ts@@ -11,8 +11,8 @@ import type { Logger } from '../../../../logger';// Core's own date helper, not @openpanel/db's — importing// `@openpanel/db/src/clickhouse/client` constructs a ClickHouse client and a// pino-pretty transport at import time (fatal under bun:test's `--isolate`-// worker threads, AGENTS.md's eager-barrel-chain hazard) and is a value import-// of `@openpanel/db` from core. See shared/ch-dates.ts's header.+// worker threads) and is a value import of `@openpanel/db` from core. See+// shared/ch-dates.ts's header.import { formatClickhouseDate } from '../../../../shared/ch-dates';import {getReferrerWithQuery,@@ -158,7 +158,6 @@ export class UmamiProvider extends BaseImportProvider<UmamiRawEvent> {);}- // WHATWG -> Node streamconst rawBody = Readable.fromWeb(res.body as any);// Detect gzip by peeking the first chunk's magic bytes (0x1f 0x8b) rather@@ -200,7 +199,6 @@ export class UmamiProvider extends BaseImportProvider<UmamiRawEvent> {}const body = Readable.from(sourceChunks());- // Build decode chain (gzip/brotli -> CSV parser)const decompress = isGzip? createGunzip(): isBrotli@@ -264,7 +262,6 @@ export class UmamiProvider extends BaseImportProvider<UmamiRawEvent> {)?.to || this.projectId;const rawEvent = zUmamiRawEvent.parse(_rawEvent);- // Extract device/profile ID - use visit_id as device_id, session_id for session trackingconst deviceId =rawEvent.visit_id ||generateDeviceId({@@ -275,32 +272,26 @@ export class UmamiProvider extends BaseImportProvider<UmamiRawEvent> {});const profileId = rawEvent.distinct_id || deviceId;- // Parse URL if available - use same logic as real-time eventsconst url = rawEvent.url_path? `https://${[rawEvent.hostname, rawEvent.url_path, rawEvent.url_query].filter(Boolean).join('')}`: '';const { path, query, origin } = parsePath(url);- // Extract referrer information - use same logic as real-time eventsconst referrerUrl = rawEvent.referrer_domain? `https://${rawEvent.referrer_domain}${rawEvent.referrer_path || ''}`: '';- // Check if referrer is from same domain (like real-time events do)const referrer = isSameDomain(referrerUrl, url)? null: parseReferrer(referrerUrl);- // Check for UTM referrer in query params (like real-time events do)const utmReferrer = getReferrerWithQuery(query);- // Extract location dataconst country = rawEvent.country || '';const city = rawEvent.city || '';const region = rawEvent.region || '';- // Extract browser/device infoconst browser = rawEvent.browser || '';const browserVersion = ''; // Not available in Umami CSVconst os = rawEvent.os || '';@@ -315,7 +306,6 @@ export class UmamiProvider extends BaseImportProvider<UmamiRawEvent> {properties.__query = query;}- // Add useful properties from Umami dataif (rawEvent.page_title) {properties.__title = rawEvent.page_title;}diff --git a/packages/core/src/modules/ingest/ingest.constants.ts b/packages/core/src/modules/ingest/ingest.constants.tsindex 52f9b3511..f852c34ce 100644--- a/packages/core/src/modules/ingest/ingest.constants.ts+++ b/packages/core/src/modules/ingest/ingest.constants.ts@@ -1,6 +1,6 @@-// The ingestion wire contract (ADR-008's module map: ingest owns "C"). All-// three enforce the same thing (what a caller may name an event and what a-// track body may contain), so they are one file here.+// The ingestion wire contract. All three enforce the same thing (what a+// caller may name an event and what a track body may contain), so they are+// one file here.import { z } from 'zod';@@ -108,23 +108,21 @@ const PATH_SCAN_PATTERNS = [* @returns true if the event name should be blocked, false otherwise*/export function isBlockedEventName(name: string): boolean {- // Length check - attack payloads are often very long+ // Attack payloads are often very long.if (name.length > MAX_EVENT_LENGTH) {return true;}- // Contains newlines (always suspicious for event names)+ // Newlines are always suspicious for event names.if (name.includes('\n') || name.includes('\r')) {return true;}- // Substring blocklist (case-insensitive)const lower = name.toLowerCase();if (BLOCKED_SUBSTRINGS.some((blocked) => lower.includes(blocked))) {return true;}- // Path scanning patternsif (PATH_SCAN_PATTERNS.some((pattern) => pattern.test(name))) {return true;}diff --git a/packages/core/src/modules/ingest/ingest.routes.ts b/packages/core/src/modules/ingest/ingest.routes.tsindex 1fbb7fa46..d01f17ad5 100644--- a/packages/core/src/modules/ingest/ingest.routes.ts+++ b/packages/core/src/modules/ingest/ingest.routes.ts@@ -1,31 +1,20 @@-// Ported from apps/api/src/routes/track.router.ts + track.controller.ts. V1's-// Fastify router stays the LIVE route (DELEGATE PATTERN) and its controller and-// hooks delegate into ingest.service.ts — the same functions this file calls.+// THE HOOK ORDER IS THE CONTRACT: duplicate -> clientAuth -> isBot ->+// subscription. It holds by lifecycle phase rather than by registration order+// — verified against Elysia 1.4.30, where a route declaring all three runs+// `derive -> transform -> macro resolve -> beforeHandle`. So the duplicate+// check is a `transform`, `clientAuth` is the macro, and the bot check is a+// `beforeHandle`, which is what lets it read `client.secretVerified` after+// the macro resolves the principal.//-// THE HOOK ORDER IS THE CONTRACT (ADR-002 "behaviour that must be preserved-// explicitly" 5): duplicate -> clientAuth -> isBot. Here it holds by lifecycle-// phase rather than by registration luck — measured on Elysia 1.4.30, a route-// declaring all three runs `derive -> transform -> macro resolve ->-// beforeHandle`. So the duplicate check is a `transform` (V1's-// `preValidation`), `clientAuth` is the macro, and the bot check is a-// `beforeHandle`, which is what lets it read `client.secretVerified` the way-// V1's `isBotHook` reads the `req.clientSecretAuth` side channel-// `validateSdkRequest` sets.+// Both routes carry the duplicate check because the guard wrapping them below+// is scoped to both, so `GET /track/device-id` goes through it too.//-// Both routes carry the whole chain because V1's `fastify.addHook` calls are-// plugin-scoped, so `GET /track/device-id` goes through it too.-//-// Mounted this surface and closed the two gaps its header used to record. V1's-// `subscriptionHook` (the wind-down gate) is now the last link in the chain —-// `duplicate -> clientAuth -> isBot -> subscription`, V1's registration order-// exactly — with `selfHosted` read off `AppDeps.config` instead of-// `process.env`. And `POST /event`, the legacy compat route ADR-015 entry 1 was-// reversed to KEEP, is here beside `/track`: same hook chain plus the-// per-client usage counter the deferred removal decision needs, recorded after-// authentication (so a label can only ever be a client id that exists) and-// before the hooks that can short-circuit (so a client whose events are dropped-// as bot/wind-down traffic still counts as a client that would break if-// `/event` disappeared).+// `POST /event` — a legacy compat route kept because production still posts+// to it — sits beside `/track` with the same hook chain, plus a per-client+// usage counter recorded after authentication (so a label can only ever be a+// client id that exists) and before the hooks that can short-circuit (so a+// client whose events are dropped as bot/wind-down traffic still counts as+// one that would break if `/event` disappeared).import type { AppDeps, HttpCtx } from '../../context';import { defineRoutes } from '../../http/define';@@ -51,7 +40,7 @@ import { produceIncomingEvent } from './src/kafka';const TAGS = ['Track'];const LEGACY_EVENT_TAGS = ['Event'];const DUPLICATE_BODY = 'Duplicate event';-/** V1 answers 202 with `{blocked:true}` rather than 402/403 — see+/** Wind-down answers 202 with `{blocked:true}` rather than 402/403 — see* `isIngestionWoundDown`. */const WIND_DOWN_STATUS = 202;const ACCEPTED_STATUS = 202;@@ -88,9 +77,8 @@ function refuseOversizedBody({});}-// V1's error handler turns each thrown HttpError into this body; core has no-// such handler, so the mapping is explicit and the codes and messages are-// V1's.+// There is no thrown-HttpError handler here, so the outcome-to-response+// mapping is explicit.function respondToOutcome(outcome: TrackOutcome, status: StatusFn) {switch (outcome.status) {case 'ok':@@ -130,9 +118,8 @@ function respondToOutcome(outcome: TrackOutcome, status: StatusFn) {}}-// V1's `isBotHook`: a `preHandler` registered after `clientHook`, so it can-// read the `clientSecretAuth` side channel. Here it is a route-level-// `beforeHandle`, which runs after the macro resolved the principal.+// A route-level `beforeHandle`, which runs after the macro resolved the+// principal, so it can read `client.secretVerified`.async function botGuard({body,client,@@ -155,7 +142,7 @@ async function botGuard({}}-/** V1's `subscriptionHook`, the last `preHandler` on both ingest routers. */+/** The wind-down gate: the last `beforeHandle` on both ingest routers. */function windDownGuard(deps: AppDeps) {return async ({client,@@ -184,11 +171,10 @@ export const ingestRoutes = defineRoutes((app, deps: AppDeps) => {return app.guard({- // V1's `duplicateHook`, registered on `preValidation` so it answers- // before the client is ever authenticated. A guard hook runs ahead of- // the `clientAuth` macro's resolve and is scoped to the two routes- // below — measured on Elysia 1.4.30:- // derive -> guard beforeHandle -> macro resolve -> route beforeHandle.+ // Answers before the client is ever authenticated. A guard hook runs+ // ahead of the `clientAuth` macro's resolve and is scoped to the two+ // routes below: derive -> guard beforeHandle -> macro resolve -> route+ // beforeHandle.async beforeHandle({ body, ctx, request, status }) {if (await isDuplicateIngestRequest({@@ -304,8 +290,8 @@ export const ingestRoutes = defineRoutes((app, deps: AppDeps) => {},{clientAuth: { ingest: validateIngestRequest },- // V1's own order: the usage metric is a `preHandler` registered- // after `clientHook` and before `isBotHook`/`subscriptionHook`.+ // Recorded after `clientAuth` resolves the client and before the+ // hooks that can short-circuit, so a dropped event still counts.beforeHandle: [({ client }: { client: { id: string } }) => {recordLegacyEventRequest(client.id);diff --git a/packages/core/src/modules/ingest/ingest.service.test.ts b/packages/core/src/modules/ingest/ingest.service.test.tsindex 269efe0c0..108ecf177 100644--- a/packages/core/src/modules/ingest/ingest.service.test.ts+++ b/packages/core/src/modules/ingest/ingest.service.test.ts@@ -8,10 +8,7 @@* goes to Kafka via the injected producer, with no branch and no fallback* queue.*- * Moved from apps/api/src/controllers/track.controller.test.ts with M8-002. The- * producer and the buffers are arguments now, so V1's `vi.mock` of- * @openpanel/queue and its `vi.spyOn(replayBuffer)` become plain stubs — same- * assertions. Geo/ASN and the salts are still module-level, so those keep a+ * Geo/ASN and the salts are still module-level, so those keep a* `mock.module` (unhoisted, hence the `await import` in `beforeAll`).*/diff --git a/packages/core/src/modules/ingest/ingest.service.ts b/packages/core/src/modules/ingest/ingest.service.tsindex ca25b1722..78cd5d548 100644--- a/packages/core/src/modules/ingest/ingest.service.ts+++ b/packages/core/src/modules/ingest/ingest.service.ts@@ -1,16 +1,10 @@-// The ingestion pipeline. Ported from apps/api's track.controller.ts, its three-// route hooks (duplicate / client / is-bot) and utils/ids.ts. V1's Fastify-// controller and hooks stay the LIVE route (DELEGATE PATTERN) and call the-// functions below; ingest.routes.ts is the V2 half over the same functions.+// The ingestion pipeline for POST /track and POST /event.//// Nothing here throws for a caller error: each transport owns its own status-// codes and bodies, so the pipeline returns a `TrackOutcome` and V1 maps it-// back onto the exact `HttpError`s and replies it produced before.+// codes and bodies, so the pipeline returns a `TrackOutcome` instead.//-// The Kafka producer is INJECTED. Since M11-003 `produceIncomingEvent` is a-// sibling (./src/kafka.ts), so the injection is no longer a package-cycle-// workaround and no longer travels through `AppDeps` — it stays an argument-// only so a test can assert on what was produced without a broker.+// The Kafka producer is injected as an argument, not read from a module+// singleton, so a test can assert on what was produced without a broker.import { generateId } from '@openpanel/shared';import { parseUserAgent } from '@openpanel/shared/server';@@ -86,8 +80,8 @@ export type IngestBuffers = Pick<Buffers, 'session' | 'replay' | 'group'>;export interface IngestTransport {buffers: IngestBuffers;produceIncomingEvent: IncomingEventProducer;- /** M10-005: the profile writes below reach ClickHouse and the profile- * buffer through the scope, not a module singleton. */+ /** The profile writes below reach ClickHouse and the profile buffer+ * through the scope, not a module singleton. */deps: ServiceDeps;}@@ -188,8 +182,6 @@ export function getTimestamp(const clientTimestamp = new Date(userDefinedTimestamp);const clientTimestampNumber = clientTimestamp.getTime();- // Use safeTimestamp if invalid, implausibly old, or more than 1 minute- // in the futureif (Number.isNaN(clientTimestampNumber) ||clientTimestampNumber < EARLIEST_ACCEPTED_TIMESTAMP_MS ||@@ -198,7 +190,6 @@ export function getTimestamp(return { timestamp: safeTimestamp, isTimestampFromThePast: false };}- // isTimestampFromThePast is true only if timestamp is older than 15 minutesconst isTimestampFromThePast =clientTimestampNumber < safeTimestamp - FIFTEEN_MINUTES_MS;@@ -229,7 +220,7 @@ export interface TrackRequest {clientIp: string;headers: IngestHeaders;clientSecretAuth: boolean;- /** The request-arrival timestamp (V1's `timestampHook`). */+ /** The request-arrival timestamp. */timestamp: number | undefined;body: ITrackHandlerPayload;}@@ -329,8 +320,6 @@ async function handleTrack(: deviceId;const promises: Promise<unknown>[] = [];- // If we have more than one property in the identity object, we should identify the user- // Otherwise its only a profileId and we should not identify the userif (context.identity && Object.keys(context.identity).length > 1) {promises.push(handleIdentify(transport.deps, context.identity, context));}@@ -469,8 +458,8 @@ async function handleAssignGroup(});}-/** `POST /track`. The dispatch order is V1's, including that an unknown type- * still resolves geo/device before it is refused. */+/** `POST /track`. An unknown type still resolves geo/device before it is+ * refused. */export async function ingestTrack(request: TrackRequest,transport: IngestTransport@@ -555,10 +544,7 @@ export async function ingestTrack(}/**- * V1's `subscriptionHook` (apps/api/src/hooks/subscription.hook.ts), ported- * for both ingestion routes.- *- * Two things worth knowing about the shape of this, both V1's:+ * Two things worth knowing about the shape of this:** It gates on `windDownStep`, not on `subscriptionState`. Every expired trial* is already in `trial_expired`, so gating on the state would block thousands@@ -567,9 +553,6 @@ export async function ingestTrack(* It answers 202, not 402 or 403 (the caller does; this returns the verdict).* The SDKs treat only 401 and 2xx as terminal, so a "correct" status code* would multiply traffic from exactly the clients we are trying to quiet down.- *- * `selfHosted` arrives from `AppDeps.config` — V1 read `process.env` here and- * core reads none.*/const WIND_DOWN_BLOCKED_STEPS = new Set(['blocked', 'final_warning']);@@ -625,15 +608,13 @@ export async function isIngestionWoundDown(}/**- * `POST /event` — the legacy compat route (ADR-015 entry 1, REVERSED: kept, not- * deleted, because production still has projects posting to it). Ported from- * apps/api/src/controllers/event.controller.ts.+ * `POST /event` — the legacy compat route, kept because production still has+ * projects posting to it.** It is NOT `ingestTrack` with a different body: the legacy payload carries a* client-supplied ISO `timestamp`, has no `type` discriminator, no schema, and- * no identify/increment/replay branches — so it builds its own queue payload- * exactly as V1's controller did, minting the event id at the producer like- * `/track` does.+ * no identify/increment/replay branches, so it builds its own queue payload+ * and mints the event id at the producer like `/track` does.*/export type LegacyEventOutcome =| { status: 'ok' }@@ -645,7 +626,7 @@ export async function ingestLegacyEvent(clientIp: string;headers: IngestHeaders;clientSecretAuth: boolean;- /** The request-arrival timestamp (V1's `timestampHook`). */+ /** The request-arrival timestamp. */timestamp: number | undefined;body: DeprecatedPostEventPayload | null | undefined;},@@ -656,17 +637,17 @@ export async function ingestLegacyEvent(return { status: 'missing-project-id' };}- // An event with no name is not an event. V1 answered 202 and wrote a row with- // `name = ''`, which then shows up in every picker and breakdown. The status- // stays 202 — this route has no body schema and the HTTP contract must not- // change — but nothing is written.+ // An event with no name is not an event. Writing one with `name = ''` shows+ // up in every picker and breakdown. The status stays 202 — this route has+ // no body schema and the HTTP contract must not change — but nothing is+ // written.const name = (request.body as { name?: unknown } | null | undefined)?.name;if (typeof name !== 'string' || name.trim() === '') {return { status: 'ok' };}- // The cast is V1's own call (event.controller.ts:26): `/event` has no body- // schema, so `getTimestamp` reads `properties` off whatever arrived.+ // `/event` has no body schema, so `getTimestamp` reads `properties` off+ // whatever arrived.const { timestamp, isTimestampFromThePast } = getTimestamp(request.timestamp,request.body as ITrackHandlerPayload['payload']@@ -824,7 +805,7 @@ export async function fetchDeviceIdentity(};}-/** The `duplicateHook`: the web SDK can fire the same event twice. */+/** The web SDK can fire the same event twice; this catches the duplicate. */export async function isDuplicateIngestRequest(request: {method: string;clientIp: string | undefined;@@ -868,8 +849,8 @@ function isTrackBody(request: {export type BotVerdict = { name: string; type: string } | null;/**- * The `isBotHook`. Requests authenticated with a client secret come from- * server-side SDKs (node, php, go, rust, java, python, …). That auth is a far+ * Requests authenticated with a client secret come from server-side SDKs+ * (node, php, go, rust, java, python, …). That auth is a far* stronger signal of legitimate first-party traffic than the user agent, so* never treat them as bots — bot detection is for public/frontend* (origin-authenticated) traffic.diff --git a/packages/core/src/modules/ingest/legacy-event.test.ts b/packages/core/src/modules/ingest/legacy-event.test.tsindex 09415b4b6..7a0ed0179 100644--- a/packages/core/src/modules/ingest/legacy-event.test.ts+++ b/packages/core/src/modules/ingest/legacy-event.test.ts@@ -1,13 +1,7 @@/**- * Tests for the legacy `POST /event` compat route (ADR-015 entry 1, reversed:- * the route is KEPT, produces to Kafka exactly like /track, and is measured per- * client so the deferred removal decision has data).- *- * Ported from apps/api/src/controllers/event.controller.test.ts with M9-004,- * when the controller and its usage hook moved into this module. The producer- * is an argument now, so V1's `vi.mock` of @openpanel/queue becomes a plain- * stub, and the counter lives on core's one registry rather than prom-client's- * global one — same assertions.+ * Tests for the legacy `POST /event` compat route: the route is KEPT,+ * produces to Kafka exactly like /track, and is measured per client so a+ * future removal decision has data.** The `mixan-*` header fallback moved with the validator itself — see* `src/client-auth.test.ts`.diff --git a/packages/core/src/modules/ingest/src/client-auth.test.ts b/packages/core/src/modules/ingest/src/client-auth.test.tsindex 738433719..dc6fe5adb 100644--- a/packages/core/src/modules/ingest/src/client-auth.test.ts+++ b/packages/core/src/modules/ingest/src/client-auth.test.ts@@ -1,17 +1,13 @@/**- * Tests for validateIngestRequest — V1's `validateSdkRequest`, moved with- * M8-002.+ * Tests for validateIngestRequest.*- * The `mixan-*` case comes from- * apps/api/src/controllers/event.controller.test.ts: ADR-015 entry 5 is pending- * the `/event` usage metric, so the legacy header fallback stays.- * `secretVerified` is what V1 exposed as `request.clientSecretAuth` — the side- * channel the bot check reads — and since main #481 it is true only when the- * secret verified.+ * The `mixan-*` case is a legacy header fallback, kept deliberately until a+ * usage metric confirms `/event` callers have moved off it.*- * The `secret verification` block guards main #481: `secretVerified` and- * revenue ingestion follow whether the secret verified against the stored hash,- * not whether a secret string was on the request.+ * `secretVerified` is the side channel the bot check reads. The `secret+ * verification` block guards main #481: `secretVerified` and revenue+ * ingestion follow whether the secret verified against the stored hash, not+ * whether a secret string was on the request.*/import {diff --git a/packages/core/src/modules/ingest/src/client-auth.ts b/packages/core/src/modules/ingest/src/client-auth.tsindex 7e14d5ca4..cefb88ff2 100644--- a/packages/core/src/modules/ingest/src/client-auth.ts+++ b/packages/core/src/modules/ingest/src/client-auth.ts@@ -1,17 +1,13 @@-// The ingest tier of caller authentication (ADR-011 A-i's "ingest extension",-// ported verbatim from apps/api/src/utils/auth.ts's `validateSdkRequest`).-// apps/api's `clientHook` is a thin delegate over this; core's `clientAuth`-// macro reaches it through http/client-auth.ts, which a route hands this-// function to as `clientAuth: { ingest: validateIngestRequest }` (ADR-022 R22:-// transport never deep-imports a module).+// The ingest tier of caller authentication. Core's `clientAuth` macro reaches+// it through http/client-auth.ts, which a route hands this function to as+// `clientAuth: { ingest: validateIngestRequest }`.//-// Everything here is behaviour V1 relies on and none of it is decoration: the-// `ignoreCorsAndSecret` short-circuit, the unanchored wildcard origin regex,-// CORS-before-secret ordering, the ip and profile_id project filters, the-// `__revenue` gate, the body-field credential fallback, the `mixan-*` header-// fallback (ADR-015 entry 5 is deferred, not taken) and the 5-minute verify-// cache whose key holds base64(<plaintext secret>) — a recorded finding ADR-011-// leaves to Carl, not to a port.+// None of the behaviour below is decoration: the `ignoreCorsAndSecret`+// short-circuit, the unanchored wildcard origin regex, CORS-before-secret+// ordering, the ip and profile_id project filters, the `__revenue` gate, the+// body-field credential fallback, the `mixan-*` header fallback, and the+// 5-minute verify cache whose key holds base64(<plaintext secret>) are all+// deliberate.import { getRedisCache } from '@openpanel/redis';import { path } from 'ramda';@@ -60,10 +56,9 @@ export type IngestAuthOutcome =ok: true;client: IServiceClientWithProject;/**- * Whether the supplied client secret VERIFIED against the stored hash- * (main #481). The bot hook reads it as "this is a server-side SDK, never- * a bot", so it must not be true for any string a browser happens to send- * — the side channel survives as a field on the outcome (ADR-011 A-i).+ * Whether the supplied client secret VERIFIED against the stored hash.+ * The bot hook reads it as "this is a server-side SDK, never a bot", so+ * it must not be true for any string a browser happens to send.*/secretVerified: boolean;}@@ -203,7 +198,6 @@ export async function validateIngestRequest({client.secret);- // Filter out blocked IPsconst ipFilter = client.project.filters.filter((filter): filter is IProjectFilterIp => filter.type === 'ip');@@ -214,7 +208,6 @@ export async function validateIngestRequest({);}- // Filter out blocked profile idsconst profileFilter = client.project.filters.filter((filter): filter is IProjectFilterProfileId => filter.type === 'profile_id');diff --git a/packages/core/src/modules/ingest/src/consumer-handler.ts b/packages/core/src/modules/ingest/src/consumer-handler.tsindex 35562e02e..a73400543 100644--- a/packages/core/src/modules/ingest/src/consumer-handler.ts+++ b/packages/core/src/modules/ingest/src/consumer-handler.ts@@ -2,12 +2,8 @@// of work scope an HTTP request or a job run is.//// The requestId comes out of the envelope's `headers` map — the copy `/track`-// puts there, which ADR-018 R3 keeps as the consumer's source — and is-// sanitised exactly as an inbound HTTP `request-id` is, because it lands in the-// same log storage. Before M10-006 the handler read it only to bind a `reqId`-// log field: the ClickHouse writes, the buffer writes and the session-end-// enqueue the message caused all ran on boot-scoped clients, so the chain ended-// at the log line.+// puts there — and is sanitised exactly as an inbound HTTP `request-id` is,+// because it lands in the same log storage.import { type AppDeps, createCtx } from '../../../context';import { REQUEST_ID_HEADER, REQUEST_ID_LOG_FIELD } from '../../../logger';diff --git a/packages/core/src/modules/ingest/src/consumer.test.ts b/packages/core/src/modules/ingest/src/consumer.test.tsindex b28fe8886..a94f420ac 100644--- a/packages/core/src/modules/ingest/src/consumer.test.ts+++ b/packages/core/src/modules/ingest/src/consumer.test.ts@@ -322,8 +322,8 @@ describe('handler failure', () => {await handler.eachBatch(payload);- // Dropped WITHOUT being recorded — and still acked. Holding the offset back- // here is what rebuilt the redelivery loop (gate M20).+ // Dropped WITHOUT being recorded — and still acked. Holding the offset+ // back here is what rebuilds the redelivery loop.expect(metrics.deadLetterFailed).toHaveBeenCalledWith(String(PARTITION));expect(metrics.deadLettered).not.toHaveBeenCalled();expect(resolvedOffsets(resolveOffset)).toEqual(['0', '1', '2']);@@ -372,8 +372,8 @@ describe('unparseable messages', () => {/*** Deleted the offset watermark, whose only outputs were the `reprocessed`- * counter and a warn line — drill 08 measured 161 real duplicates and 0 of- * those lines, because `resetWatermarks` fired on GROUP_JOIN and a failed+ * counter and a warn line — live duplicates occurred but none of those lines+ * fired, because `resetWatermarks` fired on GROUP_JOIN and a failed* durability flush never advanced it.** These are the regression tests for the half of that claim that matters: the@@ -440,15 +440,16 @@ describe('a redelivery after the watermark was deleted', () => {});/**- * The regression test for drill 03's loss.+ * The regression test for a real data-loss incident: a graceful restart lost+ * 2 of 44,075 events.** The event a handler accepted lives in an in-process array until the buffer* pushes it to Redis, and kafkajs commits whatever `resolveOffset` marked the* moment `eachBatch` returns — `autoCommit` is on and this consumer never turns* it off, so `consumer.stop` is NOT the commit point. Resolving an offset for- * an event that is still only in memory is exactly how a graceful restart lost- * 2 of 44,075 events: the offsets were committed, the process exited, and- * nothing was redelivered.+ * an event that is still only in memory is exactly how those events were+ * lost: the offsets were committed, the process exited, and nothing was+ * redelivered.** `resolveOffset` is therefore the commit in these tests. It is the only thing* that decides what gets committed.@@ -563,10 +564,10 @@ describe('durability before commit', () => {});test('a failed flush resolves NOTHING, so a redelivery is guaranteed', async () => {- // Asserted directly rather than left to the drill. With the re-queue gone- // the only thing standing between a failed flush and a lost batch is that- // its offsets are never resolved — every message, not just the tail, and- // regardless of how many of them the handlers finished.+ // Asserted directly: with the re-queue gone, the only thing standing+ // between a failed flush and a lost batch is that its offsets are never+ // resolved — every message, not just the tail, and regardless of how+ // many of them the handlers finished.const { deps, handleEvent } = makeDeps({flushBufferedEvents: mock(() =>Promise.reject(new Error('redis is unreachable'))@@ -588,7 +589,7 @@ describe('durability before commit', () => {test('backs off before the redelivery, and the wait grows and then caps', async () => {// Observable as a growing delay, not as a fixed attempt count: the point// is that a ~15s outage costs single-digit redeliveries instead of the- // ~162 laps drill 02's re-run measured at ~90ms each.+ // ~162 laps an unbacked retry loop would cost at ~90ms each.const OUTAGE_LAPS = 8;const { deps, sleep } = makeDeps({flushBufferedEvents: mock(() =>@@ -661,9 +662,9 @@ describe('durability before commit', () => {});test('flushes what a shutdown-truncated batch handled, before resolving it', async () => {- // Drill 03's shape: SIGTERM lands mid-batch, `isRunning` goes false, and- // the handler resolves only the prefix it finished. That prefix must be- // durable too — it is the window the graceful restart used to lose.+ // SIGTERM lands mid-batch, `isRunning` goes false, and the handler+ // resolves only the prefix it finished. That prefix must be durable too —+ // it is the window a graceful restart used to lose.let handled = 0;const flushBufferedEvents = mock(async () => undefined);const { deps } = makeDeps({@@ -778,9 +779,9 @@ describe('dead letter to a capped redis list', () => {});test('a DEAD REDIS still resolves the offset and records nothing', async () => {- // Drill 02's scenario exactly: the dependency that fails the handler is- // the dependency the dead letter is written to. If this offset is left- // unresolved the redelivery loop is back, in a new place.+ // The dependency that fails the handler is the same dependency the dead+ // letter is written to. If this offset is left unresolved the+ // redelivery loop is back, in a new place.const { deps, handleEvent, metrics, redis } = makeRecordingDeps(new Error("Stream isn't writeable and enableOfflineQueue options is false"@@ -803,7 +804,7 @@ describe('dead letter to a capped redis list', () => {});test('a per-command error inside the MULTI counts as not recorded', async () => {- // WRONGTYPE is drill 08's own fault shape, and a MULTI reports it in+ // WRONGTYPE is a real Redis fault shape, and a MULTI reports it in// `exec()`'s results rather than by rejecting.const redis = fakeRedis();const wrongType: [Error | null, unknown] = [diff --git a/packages/core/src/modules/ingest/src/consumer.ts b/packages/core/src/modules/ingest/src/consumer.tsindex 770feb050..2988c74b7 100644--- a/packages/core/src/modules/ingest/src/consumer.ts+++ b/packages/core/src/modules/ingest/src/consumer.ts@@ -1,14 +1,11 @@-// The delivery contract is ADR-004's and is unchanged line for line: per-key-// serial groups, the ascending contiguous-prefix offset walk, at-least-once,-// bounded in-consumer retry, and a dead-letter on exhaustion. Only the-// dead-letter DESTINATION and its failure behaviour changed: the record goes to-// a capped Redis list, and the event is dropped whether or not that write-// lands.+// Delivery contract: per-key serial groups, the ascending contiguous-prefix+// offset walk, at-least-once, bounded in-consumer retry, and a dead-letter on+// exhaustion. The dead-letter destination is a capped Redis list, and the+// event is dropped whether or not that write lands.//// The kafkajs client, the topic/consumer-group names, the DLQ producer and the-// retry bounds are all INJECTED, and stay so now that they live one directory-// away in./kafka.ts: injection is what keeps those names byte-identical,-// because this file never spells one.+// retry bounds are all injected — this file never spells any of them, which is+// what keeps them testable without a broker.import type {Consumer,@@ -23,9 +20,8 @@ export interface KafkaConsumerHandle {* Stop fetching, then wait for the in-flight `eachBatch` to finish. Split out* from `stop` so a graceful shutdown has a point where nothing new can enter* the event buffer but the consumer has not been torn down yet — that is- * where shutdown flushes whatever was buffered OUTSIDE a Kafka batch (drill- * 03). Events buffered inside one are already durable: see- * `flushBufferedEvents` below.+ * where shutdown flushes whatever was buffered OUTSIDE a Kafka batch. Events+ * buffered inside one are already durable.*/stopConsuming: () => Promise<void>;/** Disconnect. Safe to call after `stopConsuming`, and without it. */@@ -47,10 +43,10 @@ const RETRY_BACKOFF_FACTOR = 2;* failure — the consumer's own retry convention — but it is capped HERE rather* than at `maxRetryMs`, which is sized for a flaky handler (1s by default) and* not for a dependency that is down. Without any cap a failed flush redelivers- * in ~90ms and spins: drill 02's re-run measured ~162 laps per message in one- * 96s outage, hammering Redis and Kafka at the worst possible moment. 5s keeps- * a ~15s outage to single-digit redeliveries and stays well below the 30s- * session timeout, so waiting cannot cost the consumer its group membership.+ * in ~90ms and spins, hammering Redis and Kafka at the worst possible moment.+ * 5s keeps a ~15s outage to single-digit redeliveries and stays well below the+ * 30s session timeout, so waiting cannot cost the consumer its group+ * membership.*/const DURABILITY_RETRY_MAX_MS = 5000;@@ -63,10 +59,9 @@ export type DeadLetterReason = 'parse_error' | 'handler_error';** Two implementations satisfy this, and the seam exists so the choice is one* line in `apps/api`'s wiring: `@openpanel/redis`'s `createDeadLetterRecorder`- * (the capped list, in use since M20-001) and./kafka.ts's- * `produceDeadLetterEvent` (the DLQ topic, kept because Carl's decision was- * explicitly "for now"; a DLQ message produced from these bytes is replayable- * onto the events topic unchanged).+ * (the capped list) and `./kafka.ts`'s `produceDeadLetterEvent` (the DLQ+ * topic, kept as an explicit "for now" choice; a DLQ message produced from+ * these bytes is replayable onto the events topic unchanged).*/export interface DeadLetterMessage {key: Buffer | null;@@ -116,12 +111,12 @@ export interface EventsBatchHandlerDeps {* (`autoCommit` defaults to true and this consumer does not turn it off) —* not at `consumer.stop`.*- * The gate MUST reject when the events THIS batch buffered are not in Redis:- * drill 03 lost 2 of 44,075 events on a graceful restart because the offsets- * of events that existed only in the event buffer's in-process array were- * committed anyway. The window is what makes "this batch's" answerable at- * all, now that a failed write drops the events it knows the broker will- * redeliver instead of keeping them.+ * The gate MUST reject when the events THIS batch buffered are not in+ * Redis: a graceful restart previously lost events whose offsets were+ * committed even though the events existed only in the event buffer's+ * in-process array. The window is what makes "this batch's events are+ * durable" answerable at all, now that a failed write drops the events+ * instead of keeping them for the broker to redeliver.*/openDurabilityWindow: () => () => Promise<void>;logger: ConsumerLogger;@@ -157,10 +152,10 @@ export interface EventsBatchHandler {** Delivery contract: at-least-once. An offset is resolved only once its message* has been handled, dead-lettered, or deliberately skipped — never merely- * because it failed. Since M20-001 a dead-letter always counts as finished,- * because the message is dropped either way; the one place an unresolved offset- * is still correct is a failed DURABILITY flush, which leaves the whole batch- * for redelivery.+ * because it failed. A dead-letter always counts as finished, because the+ * message is dropped either way; the one place an unresolved offset is still+ * correct is a failed DURABILITY flush, which leaves the whole batch for+ * redelivery.*/export function createEventsBatchHandler(deps: EventsBatchHandlerDeps@@ -170,16 +165,13 @@ export function createEventsBatchHandler(/*** Park the message and DROP it. The drop is unconditional: whether the record* was stored or not, this message's offset is resolved by the caller and the- * event is gone from the pipeline (gate M20).+ * event is gone from the pipeline.** There is deliberately no retry, no backoff and no unresolved offset here.* The dead-letter destination is Redis, and Redis being unavailable is* exactly when handlers fail — so a failed write that held the offset back- * would rebuild the very redelivery loop this replaced (drill 02's re-run 2:- * 78-79 laps per message at ~0.62 s, no backoff; drill 08: 1,592 failed- * dead-letters, 0 successes). Same lesson as M18-007's `pendingEvents`- * re-queue: once something else owns the outcome, the safety net underneath- * it is the bug.+ * would rebuild the redelivery loop this replaced: once something else owns+ * the outcome, a safety net underneath it is the bug.** The two counters are what carry the volume, since a capped list makes* 50,000 drops look like 12: `deadLettered` = recorded and dropped,@@ -485,8 +477,8 @@ export async function startKafkaEventsConsumer(consumer.on(consumer.events.HEARTBEAT, deps.batch.onActivity);// ---- Lifecycle / rebalance ("re-election") visibility ----- // We had no logging for partition reassignment before; without it a rebalance- // storm (a common source of at-least-once duplicates) is invisible.+ // Without this logging, a rebalance storm (a common source of+ // at-least-once duplicates) would be invisible.consumer.on(consumer.events.GROUP_JOIN, ({ payload }) => {// A new assignment means partitions may have moved between members, so a// consecutive-failure count carried over from the old one would pick thediff --git a/packages/core/src/modules/ingest/src/device-id.test.ts b/packages/core/src/modules/ingest/src/device-id.test.tsindex e0f89b64c..e5b3c1cdc 100644--- a/packages/core/src/modules/ingest/src/device-id.test.ts+++ b/packages/core/src/modules/ingest/src/device-id.test.ts@@ -4,10 +4,6 @@* window; a lingering (past-window) blob must NOT be reused — see the guard in* device-id.ts. Override device ids resolve through the same path with a single* read.- *- * Moved from apps/api/src/utils/ids.test.ts with M8-002. The buffer is now an- * argument, so the stub replaces V1's spy on the module singleton — same- * assertions, and no Redis either way.*/import { afterEach, describe, expect, it, mock } from 'bun:test';diff --git a/packages/core/src/modules/ingest/src/device-id.ts b/packages/core/src/modules/ingest/src/device-id.tsindex af5dfa358..26672459c 100644--- a/packages/core/src/modules/ingest/src/device-id.ts+++ b/packages/core/src/modules/ingest/src/device-id.ts@@ -1,6 +1,6 @@-// Ported from apps/api/src/utils/ids.ts. Device and session identity for an-// incoming event: the salted device id, and the session id the API answers with-// synchronously while the worker persists the blob async.+// Device and session identity for an incoming event: the salted device id,+// and the session id the API answers with synchronously while the worker+// persists the blob async.import crypto from 'node:crypto';import type { SessionBuffer } from '../../../buffers/session-buffer';diff --git a/packages/core/src/modules/ingest/src/incoming-event-handler.test.ts b/packages/core/src/modules/ingest/src/incoming-event-handler.test.tsindex c4bc9aa49..4aa8e4573 100644--- a/packages/core/src/modules/ingest/src/incoming-event-handler.test.ts+++ b/packages/core/src/modules/ingest/src/incoming-event-handler.test.ts@@ -1,12 +1,9 @@-// What changed is the seam: V1 reached the session buffer, `createEvent` and-// the sessions queue through `vi.mock('@openpanel/db')` /-// `vi.mock('@openpanel/queue')`; here they are recording doubles handed in as-// `IncomingEventDeps`, so the assertions are on calls the code under test-// actually made and no `mock.module` is needed.+// The session buffer, `createEvent` and the sessions queue are recording+// doubles handed in as `IncomingEventDeps`, so the assertions are on calls+// the code under test actually made and no `mock.module` is needed.//-// The session_end enqueue is asserted through the real `sessionEndJobPayload` /-// `sessionEndEnqueueOptions` — the same functions V1's producer-// (`enqueueSessionEndV2`) calls — so the jobId and the `{payload, snapshot}`+// The session_end enqueue is asserted through the real `sessionEndJobPayload`+// / `sessionEndEnqueueOptions`, so the jobId and the `{payload, snapshot}`// mapping are still pinned here, not re-implemented by the test.import { beforeEach, describe, expect, mock, test } from 'bun:test';@@ -241,7 +238,7 @@ describe('incomingEvent', () => {expect(enqueueSessionEnd).toHaveBeenCalledTimes(1);const input = enqueueSessionEnd.mock.calls[0]![0];- // The wire payload V1's producer builds from this input, through the same+ // The wire payload the producer builds from this input, through the same// core functions it calls.const { event, snapshot } = sessionEndJobPayload(input);expect(event.sessionId).toBe('old-session-id');@@ -470,9 +467,9 @@ describe('incomingEvent', () => {});/**- * M21-001. The marker replaces the offset watermark, which drill 08 showed- * could not see any of the 161 duplicates it measured. MARK MEANS COUNT AND- * LOG: every test below asserts the event was still INSERTED.+ * The marker replaces the offset watermark, which cannot see every+ * duplicate. MARK MEANS COUNT AND LOG: every test below asserts the event+ * was still INSERTED.*/describe('duplicate marker', () => {const TTL_MS = 120_000;@@ -574,10 +571,10 @@ describe('duplicate marker', () => {});/**- * THE REGRESSION TEST THAT MATTERS. A blocking Redis call in this path is how- * drill 02's consumer was evicted past its 30 s session timeout, and M19- * proved an eviction is the only reassignment that costs duplicate rows.- * M18-003 removed that trigger; this must not put it back.+ * THE REGRESSION TEST THAT MATTERS. A blocking Redis call in this path+ * previously evicted the consumer past its 30s session timeout — an+ * eviction is the only reassignment that costs duplicate rows. This must+ * not happen again.*/test('Redis unavailable: the event is processed normally and nothing throws', async () => {const { deps, createEvent, ingest, markDuplicate, duplicateMarked } = ctx;@@ -608,7 +605,7 @@ describe('duplicate marker', () => {// marker is started BEFORE the handler's own Redis work and awaited AFTER// it, so a slow marker overlaps a slow session read instead of adding to// it. A serial check would give mark:start, mark:end, ingest:start — which- // is the shape that would put M18-003's eviction trigger back.+ // is the shape that would put the eviction trigger back.const timeline: string[] = [];const slow = () => new Promise((resolve) => setTimeout(resolve, 20));const { deps, ingest, markDuplicate } = ctx;diff --git a/packages/core/src/modules/ingest/src/incoming-event-handler.ts b/packages/core/src/modules/ingest/src/incoming-event-handler.tsindex 153af1b37..4f025365e 100644--- a/packages/core/src/modules/ingest/src/incoming-event-handler.ts+++ b/packages/core/src/modules/ingest/src/incoming-event-handler.ts@@ -66,14 +66,10 @@ export interface IncomingEventSessions {): Promise<SessionIngestResult | null>;}-/**- * Injected so V1's worker keeps incrementing its own registry's counters- * while core's registry owns the V2 ones (ingest.metrics.ts).- */export interface IncomingEventMetrics {sessionStarted(kind: 'new' | 'boundary'): void;sessionEndEnqueued(source: 'boundary'): void;- /** One event whose producer-minted id had already been seen (M21-001). */+ /** One event whose producer-minted id had already been seen. */duplicateMarked(): void;}@@ -107,11 +103,10 @@ export interface IncomingEventDeps {/*** The one lookup a work scope cannot supply, resolved once at the composition- * root (`apps/api`'s main.ts) rather than per message.- *- * Removed the other two: `getProjectByIdCached` is now a module-scope- * `cacheablePerDb` keyed on the Postgres client, so the message's own scope- * reaches the same process-lived cache ingest, http and mcp read.+ * root (`apps/api`'s main.ts) rather than per message. `getProjectByIdCached`+ * is a module-scope `cacheablePerDb` keyed on the Postgres client, so the+ * message's own scope reaches the same process-lived cache ingest, http and+ * mcp read.*/export interface IncomingEventBindings {/**@@ -126,10 +121,8 @@ export interface IncomingEventBindings {): Promise<unknown>;/*** `@openpanel/redis`'s `createDuplicateEventMarker`, already bound to the TTL- * `apps/api` parsed. Injected rather than built here because the TTL is- * configuration and `packages/core` reads no environment, and because- * building it once at the composition root keeps the key prefix and the TTL- * out of the per-message path.+ * `apps/api` parsed. Injected rather than built here so the key prefix and+ * TTL stay out of the per-message path.*/markDuplicateEvent(eventId: string): Promise<boolean>;}@@ -253,17 +246,15 @@ const parseRevenue = (revenue: unknown): number | undefined => {* loss, and whether the events table ever gets dedupe is not decided here.** It replaces the offset watermark, which could not see a duplicate across a- * rebalance, an eviction, a durability redelivery or a restart — drill 08- * measured 161 real duplicates and 0 of them flagged. It catches redeliveries- * of the SAME id: crash, eviction, durability redelivery. It does NOT catch- * drill 06's lost ACK, where the SDK re-sends and the producer mints a fresh- * id per request; SDK-supplied ids are what closes that, later.+ * rebalance, an eviction, a durability redelivery or a restart. It catches+ * redeliveries of the SAME id: crash, eviction, durability redelivery. It+ * does NOT catch a lost ACK, where the SDK re-sends and the producer mints a+ * fresh id per request; SDK-supplied ids are what closes that, later.** FAILS OPEN, AND NEVER REJECTS. Redis being away is exactly when redeliveries* happen, so an observability counter must not be the thing that delays or- * loses an event — and a handler blocked on Redis is how drill 02's consumer- * was evicted past its session timeout, which is the one reassignment M19- * measured costing duplicate rows.+ * loses an event — a handler blocked on Redis risks being evicted past its+ * session timeout, which itself causes duplicate rows.*/function startDuplicateMark(eventId: string | undefined,@@ -302,8 +293,7 @@ export async function incomingEvent(meta?: IncomingEventDelivery) {// `requestId` rides in on `deps.logger`, which the consumer scopes to this- // envelope's id (ADR-018 R1 renames V1's `reqId`); only the delivery- // coordinates are per-message news.+ // envelope's id; only the delivery coordinates are per-message news.const logger = meta? deps.logger.child({kafkaPartition: meta.partition,@@ -462,7 +452,7 @@ async function ingestIncomingEvent(// The single source of truth for session lifecycle. Reads the current// session, decides extend/new/boundary, writes back. The returned// `current` is the canonical session — use its referrer fields for- // inheritance, just like the previous behavior.+ // inheritance.const session = await deps.sessions.ingest(baseEvent);if (session?.kind === 'boundary') {diff --git a/packages/core/src/modules/ingest/src/ingest.metrics.ts b/packages/core/src/modules/ingest/src/ingest.metrics.tsindex 0e30d5335..4518fec72 100644--- a/packages/core/src/modules/ingest/src/ingest.metrics.ts+++ b/packages/core/src/modules/ingest/src/ingest.metrics.ts@@ -1,8 +1,4 @@-// The ingest-path collectors, moved from apps/worker/src/metrics.ts onto core's-// one registry. Names, labels and help strings are V1's; the worker-side copies-// die with apps/worker (P9). Until then V1's consumer and incoming-event-// delegate inject their own counters (both take `metrics` as a dependency), so-// V1's `/metrics` body is unchanged and these are the V2 bindings.+// The ingest-path collectors, on core's one registry.import client from 'prom-client';import { registry } from '../../../metrics';@@ -12,8 +8,8 @@ import type { ConsumerMetrics, DeadLetterReason } from './consumer';// a dedupe: the event is inserted either way and this counter is the whole// point of the check. It replaces `kafka_events_reprocessed_total`, which was// keyed on a Kafka offset in one process's heap and therefore blind to every-// duplicate that mattered — drill 08 measured 161 real duplicates and 0-// reprocessed increments.+// duplicate that mattered (measured: 161 real duplicates, 0 reprocessed+// increments).//// It UNDERCOUNTS by design: a duplicate whose marker could not be written// (Redis away) is not counted, because the check fails open rather than@@ -49,7 +45,7 @@ export const kafkaDeadLetteredTotal = new client.Counter({// The dead-letter write itself failed, so the message was DROPPED WITHOUT being// recorded — Redis unreachable, most likely, which is also when handlers fail.// This is real loss, not a stuck partition: the offset is resolved anyway and-// nothing retries the message (gate M20).+// nothing retries the message.export const kafkaDeadLetterFailedTotal = new client.Counter({name: 'kafka_events_dead_letter_failed_total',help: 'Kafka event messages dropped without being recorded (dead-letter write failed)',@@ -81,15 +77,10 @@ export const ingestConsumerMetrics = {const LEGACY_EVENT_CLIENT_ID_LABEL = 'client_id';/**- * Entry 1 was reversed: `POST /event` is kept as a legacy compat route rather- * than deleted, because production still has projects posting to it. This- * counter is the evidence the deferred removal decision needs — when it reads- * zero for every client, `/event` and the `mixan-*` header fallback can both go- * (ADR-015 entry 5 is pending the same measurement).- *- * Moved from apps/api/src/metrics.ts, which registered on prom-client's global- * registry because `fastify-metrics` served that one. V2 has exactly one- * registry and it is this package's.+ * `POST /event` is kept as a legacy compat route rather than deleted, because+ * production still has projects posting to it. This counter is the evidence+ * for removing it later — when it reads zero for every client, `/event` and+ * the `mixan-*` header fallback can both go.*/export const legacyEventRequestsTotal = new client.Counter({name: 'openpanel_legacy_event_requests_total',diff --git a/packages/core/src/modules/ingest/src/kafka.ts b/packages/core/src/modules/ingest/src/kafka.tsindex e70088415..1d2510dcf 100644--- a/packages/core/src/modules/ingest/src/kafka.ts+++ b/packages/core/src/modules/ingest/src/kafka.ts@@ -1,10 +1,3 @@-// What kept it out of core was the import direction, not the code: it lived in-// @openpanel/queue, a package that imports @openpanel/core for its logger, so-// core could not import it back. Moving the file takes it out of that cycle —-// `createLogger` is a sibling now, and both the producer and the consumer sit-// in the module that owns the transport (ADR-004: Kafka is the sole events-// transport — no topic, group or envelope changes with the move).-//// NOTHING here constructs a Kafka client at import time: `getKafka` is lazy and// only `assertKafkaConfigured` reads the broker list eagerly, so core stays// importable with no broker and `bun test` still runs offline.@@ -20,7 +13,7 @@ import {import type { CoreConfig, KafkaConfig } from '../../../config';import { createLogger, type ILogger } from '../../../pino-logger';// One definition, not two: the consumer already declares the dead-letter-// message shape it hands to this producer, and both files are now siblings.+// message shape it hands to this producer.import type { DeadLetterMessage } from './consumer';import type { IncomingEventPayload } from './incoming-event';import {@@ -107,10 +100,11 @@ const getProducer = async (config: CoreConfig): Promise<Producer> => {// Stays 1 (not 5) to avoid in-flight reordering after a transient broker// hiccup: with idempotency on and low retries, reordered batches trip// OUT_OF_ORDER_SEQUENCE_NUMBER and stick the producer per-partition.- // ADR-023 measured raising it at +2-3% and rejected it; batching is what- // amortises the round-trip. KAFKA_PRODUCER_MAX_IN_FLIGHT still raises it- // for a measurement run — read docs/KAFKA_PRODUCER_OPTIONS.md first: it- // is coupled to the retry policy.+ // Raising it gained only a couple percent of throughput and was+ // rejected; batching is what amortises the round-trip.+ // KAFKA_PRODUCER_MAX_IN_FLIGHT still raises it for a measurement run —+ // read docs/KAFKA_PRODUCER_OPTIONS.md first: it is coupled to the retry+ // policy.maxInFlightRequests: tuning.maxInFlight,allowAutoTopicCreation: true,retry: {diff --git a/packages/core/src/modules/ingest/src/producer-batcher.test.ts b/packages/core/src/modules/ingest/src/producer-batcher.test.tsindex 7472fd388..81f604c8c 100644--- a/packages/core/src/modules/ingest/src/producer-batcher.test.ts+++ b/packages/core/src/modules/ingest/src/producer-batcher.test.ts@@ -1,6 +1,6 @@/**- * The batching accumulator's correctness contract (M16-002 deliverable 2b).- * Batching exists to amortise the produce round-trip, and it is only adoptable+ * The batching accumulator's correctness contract. Batching exists to+ * amortise the produce round-trip, and it is only adoptable* if it changes nothing a caller can observe:** (i) per-key ordering survives — same-key messages leave in produce order,diff --git a/packages/core/src/modules/ingest/src/producer-batcher.ts b/packages/core/src/modules/ingest/src/producer-batcher.tsindex 0d6ae384b..f2ac6aabd 100644--- a/packages/core/src/modules/ingest/src/producer-batcher.ts+++ b/packages/core/src/modules/ingest/src/producer-batcher.ts@@ -1,6 +1,6 @@-// Option 2 of the produce-path options: amortise the produce round-trip by-// accumulating messages and sending them as ONE `send` carrying MANY messages,-// instead of one awaited `send` per /track request.+// Amortises the produce round-trip: accumulates messages and sends them as+// ONE `send` carrying MANY messages, instead of one awaited `send` per+// /track request.//// It is OFF unless the config loader says otherwise — see `producer-tuning.ts`.//diff --git a/packages/core/src/modules/ingest/wind-down.test.ts b/packages/core/src/modules/ingest/wind-down.test.tsindex ef58a40c1..3f3cee81d 100644--- a/packages/core/src/modules/ingest/wind-down.test.ts+++ b/packages/core/src/modules/ingest/wind-down.test.ts@@ -6,8 +6,7 @@* subscription state (so an expired trial keeps ingesting until it has actually* been warned), the caller answers 202 rather than a 4xx (the SDKs retry* everything except 401 and 2xx), and it fails open. `SELF_HOSTED` is a- * `selfHosted` argument now — core reads no environment — so V1's `vi.stubEnv`- * becomes a parameter.+ * `selfHosted` argument now — core reads no environment.*/import {diff --git a/packages/core/src/modules/insight/insight.rpc.ts b/packages/core/src/modules/insight/insight.rpc.tsindex 2a2ee3a8b..f3d1f54d6 100644--- a/packages/core/src/modules/insight/insight.rpc.ts+++ b/packages/core/src/modules/insight/insight.rpc.ts@@ -49,23 +49,19 @@ export const insightRouter = createTRPCRouter({level: 'read',});- // Fetch more than needed to account for deduplication. AI- // relevanceScore leads (un-enriched insights sort last via+ // AI relevanceScore leads (un-enriched insights sort last via// nulls:last), with the statistical impactScore as the tiebreaker.const allInsights = await ctx.services.insight.listInsights({projectId,limit: limit * LIST_DEDUPE_OVERFETCH,});- // WindowKind priority: yesterday (1) > rolling_7d (2) > rolling_30d (3)const windowKindPriority: Record<string, number> = {yesterday: 1,rolling_7d: 2,rolling_30d: 3,};- // Group by moduleKey + dimensionKey, keep only the highest-priority- // windowKind.const deduplicated = new Map<string, (typeof allInsights)[0]>();for (const insight of allInsights) {const key = `${insight.moduleKey}:${insight.dimensionKey}`;@@ -113,10 +109,10 @@ export const insightRouter = createTRPCRouter({return ctx.services.insight.listAllInsights({ projectId, limit });}),- // Phase 5: the "why". Decompose the insight's change across referrer/- // country/device/utm (current vs baseline window), pull nearby references,- // and have the AI explain which sub-segment drove it. Cached per insight- // version so repeat clicks don't re-bill the LLM.+ // Decompose the insight's change across referrer/country/device/utm+ // (current vs baseline window), pull nearby references, and have the AI+ // explain which sub-segment drove it. Cached per insight version so repeat+ // clicks don't re-bill the LLM.explain: protectedProcedure.input(z.object({ insightId: z.string() })).mutation(async ({ input: { insightId }, ctx }) => {diff --git a/packages/core/src/modules/insight/insight.service.test.ts b/packages/core/src/modules/insight/insight.service.test.tsindex 0298dfa6b..d81dc12d0 100644--- a/packages/core/src/modules/insight/insight.service.test.ts+++ b/packages/core/src/modules/insight/insight.service.test.ts@@ -164,7 +164,7 @@ test('explainInsight is a cache-aside over the AI call, keyed by the caller-suppexpect(second).toEqual(first);// The cache it read and wrote is the one the scope handed it, not a- // module-level `getRedisCache()` connection nobody closes (R16).+ // module-level `getRedisCache()` connection nobody closes.expect(redis.setex).toHaveBeenCalledTimes(1);expect(redis.get).toHaveBeenCalledTimes(2);});diff --git a/packages/core/src/modules/insight/insight.service.ts b/packages/core/src/modules/insight/insight.service.tsindex 4a726d91a..0912e647b 100644--- a/packages/core/src/modules/insight/insight.service.ts+++ b/packages/core/src/modules/insight/insight.service.ts@@ -1,23 +1,15 @@-// ADR-007: "Moves to core: src/services/** (33 services + insights/)".-//// Plain exported functions, not only methods on `createInsightService`'s-// container — the same shape as modules/auth/auth.service.ts, because V1's-// worker (apps/worker, no core Ctx today) and V1's trpc router both need a-// direct call, not one that requires building a Ctx first.+// container: a caller with no Ctx yet still needs a direct call.// `createInsightService` is the `ctx.services.insight` binding for code that// already has a Ctx.//// Every exported function takes `ServiceDeps` and reaches Postgres as `deps.db`-// and ClickHouse as `deps.ch`; the `loadDb`/`loadCh` lazy loaders are gone, so-// the requestId minted at the edge reaches the query. M15-202 removed the last-// five `load*` functions here — engine, store, detection modules, referrer-// spikes and the legacy detector are all plain static imports of this module's-// own `src/`.+// and ClickHouse as `deps.ch`, so the requestId minted at the edge reaches the+// query.//// The engine and its five detection modules run on the `sql` tag;// `createEngine` therefore takes the scope's deps rather than a bare ClickHouse-// client, so the requestId reaches every module statement. `legacy-scan.ts` is-// the last clix holdout in this module.+// client, so the requestId reaches every module statement.//// The explain cache runs on `deps.redis` — the app shell owns that connection's// lifecycle; this module never opens one of its own.@@ -274,9 +266,8 @@ async function deleteInBatches(}/**- * Keeps the insights tables bounded (they otherwise grow forever — see the- * original packages/db/src/services/insights.service.ts header for the- * retention rules). The `insightCleanup` cron job body.+ * Keeps the insights tables bounded (they otherwise grow forever). The+ * `insightCleanup` cron job body.*/export async function cleanupStaleInsights(deps: ServiceDeps,@@ -667,7 +658,7 @@ export async function getReferrerSpikes(return getReferrerSpikesQuery(deps, input);}-/** Pre-engine detector, kept for parity with V1 — no live callers today. */+/** Legacy pre-engine detector — no live callers today. */export async function scanLegacyInsights(deps: ServiceDeps,projectId: stringdiff --git a/packages/core/src/modules/insight/src/cached-query.ts b/packages/core/src/modules/insight/src/cached-query.tsindex d0852d64d..24e3c3809 100644--- a/packages/core/src/modules/insight/src/cached-query.ts+++ b/packages/core/src/modules/insight/src/cached-query.ts@@ -1,25 +1,19 @@-// The replacement for `cached-clix.ts` (ADR-013 decision 21).+// The critical invariant: the `sql` tag renders `{pN:Type}` placeholders whose+// names come from a per-render counter, so two statements that differ only in+// their bound values render to the SAME text. The cache key must therefore+// carry the params as well as the query text, or one project's window would+// serve another's.//-// The wrapper it replaces memoised `clix`'s `execute` on `sha256(query.toSQL +-// '|' + timezone)` — safe only because clix inlined every value into the text-// it hashed. The `sql` tag renders `{pN:Type}` placeholders whose names come-// from a per-render counter, so two statements that differ only in their bound-// values render to the SAME text: the key must carry the params as well, or one-// project's window would serve another's.-//-// Everything else is deliberately unchanged from the clix wrapper: the `Map`-// belongs to the caller (per module+window, never module-level — it is keyed by-// nothing tenant-scoped), the timezone defaults to `'UTC'` exactly as-// `clix(client, timezone)` did (query-builder.ts:696) and travels as-// `session_timezone` in `clickhouse_settings` exactly as `.execute` sent it-// (query-builder.ts:562).+// The `Map` belongs to the caller (per module+window, never module-level — it+// is keyed by nothing tenant-scoped); the timezone defaults to `'UTC'` and+// travels as `session_timezone` in `clickhouse_settings`.import crypto from 'node:crypto';import type { ClickHouseSettings } from '@clickhouse/client';import type { SqlFragment } from '@openpanel/db/src/clickhouse/sql';import { type ChScope, chQuery } from '../../../ch-query';-/** clix's own default when a call site passed no timezone. */+/** Default timezone when the caller specifies none. */const DEFAULT_SESSION_TIMEZONE = 'UTC';/** Runs one bound statement, memoised per module+window context. */diff --git a/packages/core/src/modules/insight/src/engine.ts b/packages/core/src/modules/insight/src/engine.tsindex d6accb743..be84d1231 100644--- a/packages/core/src/modules/insight/src/engine.ts+++ b/packages/core/src/modules/insight/src/engine.ts@@ -139,8 +139,7 @@ export function createEngine(args: {) {continue;}- // Initialize cache for this module+window combination.- // Cache is automatically garbage collected when context goes out of scope.+ // Garbage collected automatically when this context goes out of scope.const cache = new Map<string, unknown>();ctx = {projectId,diff --git a/packages/core/src/modules/insight/src/enrich.ts b/packages/core/src/modules/insight/src/enrich.tsindex 1dd1f1b23..68f2ccdb5 100644--- a/packages/core/src/modules/insight/src/enrich.ts+++ b/packages/core/src/modules/insight/src/enrich.ts@@ -1,5 +1,3 @@-// Ported from @openpanel/ai (dissolved into core — M4-005).-//// Tier-1 insight enrichment: a one-shot OpenAI call that scores and summarizes// auto-detected analytics insights so the product can filter noise, select// email-worthy items, and flag chart-reference candidates. No persistence, nodiff --git a/packages/core/src/modules/insight/src/explain.ts b/packages/core/src/modules/insight/src/explain.tsindex f5133907d..1e5ab1ba7 100644--- a/packages/core/src/modules/insight/src/explain.ts+++ b/packages/core/src/modules/insight/src/explain.ts@@ -1,11 +1,9 @@-// Ported from @openpanel/ai (dissolved into core — M4-005).-//-// Phase 5 — the "why". Given an insight plus a deterministic decomposition of-// the change (current vs baseline breakdowns across referrer/country/device/-// utm) and any nearby references, produce an honest explanation: which-// sub-segment drove the delta, and which off-platform event (reference) might-// correlate. It explains the *internal decomposition*, not invented external-// causes. The caller gathers the data (DB/CH); this module just narrates.+// Given an insight plus a deterministic decomposition of the change (current+// vs baseline breakdowns across referrer/country/device/utm) and any nearby+// references, produce an honest explanation: which sub-segment drove the+// delta, and which off-platform event (reference) might correlate. It+// explains the *internal decomposition*, not invented external causes. The+// caller gathers the data (DB/CH); this module just narrates.import { betterAgent, defineAgent } from '@better-agent/core';import { z } from 'zod';import { callProvider } from '../../../clients/provider-error';diff --git a/packages/core/src/modules/insight/src/legacy-scan.ts b/packages/core/src/modules/insight/src/legacy-scan.tsindex 541c1f366..27200d7a7 100644--- a/packages/core/src/modules/insight/src/legacy-scan.ts+++ b/packages/core/src/modules/insight/src/legacy-scan.ts@@ -1,20 +1,15 @@-// The pre-engine insight detector, kept for V1 parity — no live callers today.+// The pre-engine insight detector — no live callers today, kept only so the+// defects below stay visible rather than silently dropped.//-// The ten statements moved off clix onto the ADR-013 `sql` tag. The conversion-// changes how values reach the server and nothing else: every statement below-// renders byte-identically to the clix output it replaces, with the project id-// and the computed window bound as `{pN:Type}` params. clix always sent-// `session_timezone` (query-builder.ts:562) and defaulted it to `'UTC'`-// (`:696`), so `chQuery` sends the same value.+// Nine of the ten statements are BROKEN AND WERE ALWAYS BROKEN: most compare+// a column against a quoted string literal threshold, so the comparison+// fails with TYPE_MISMATCH; three more read columns (`is_new`,+// `is_returning`, `event_name`, `status`) that no OpenPanel table has, and+// one puts a window function in HAVING. The defects are reproduced verbatim,+// not fixed — fixing behaviour is a product decision, and there is no+// caller to serve it.//-// Nine of the ten statements are BROKEN AND WERE ALWAYS BROKEN. clix's-// `having(column, operator, value)` escaped its comparand as a VALUE, so every-// `'<column> * <n>'` threshold below reaches ClickHouse as a quoted string and-// the comparison fails with TYPE_MISMATCH; three more read columns (`is_new`,-// `is_returning`, `event_name`, `status`) that no OpenPanel table has, and one-// puts a window function in HAVING. The defects are reproduced verbatim, not-// fixed: a conversion changes binding, not behaviour, and fixing them is a-// product decision with no caller to serve.+// Every statement sends `session_timezone`, defaulted to `'UTC'`.import {type SqlFragment,@@ -24,7 +19,7 @@ import {import { type ChScope, chQuery } from '../../../ch-query';import { formatClickhouseDate } from '../../../shared/ch-dates';-/** clix sent `session_timezone` on every `execute()`, defaulting to `'UTC'`. */+/** Sent on every query; defaults to `'UTC'`. */const CLIX_SESSION_TIMEZONE = { session_timezone: 'UTC' } as const;const MS_PER_DAY = 24 * 60 * 60 * 1000;@@ -42,8 +37,8 @@ const EVENT_COMPLETION_WINDOW_DAYS = 60;const TOP_CONTENT_LIMIT = 1;-// clix rendered each of these as a quoted STRING comparand, because they were-// passed to `having()` as values. Kept exactly, defect included.+// Rendered as a quoted STRING comparand — reaches ClickHouse as text, not a+// numeric threshold. Kept exactly, defect included.const TRAFFIC_SPIKE_THRESHOLD = 'avg_previous_7_days * 2';const EVENT_SURGE_THRESHOLD = 'avg_previous_7_days * 1.3';const NEW_VISITOR_THRESHOLD = 'prev_month_visitors * 1.2';@@ -147,7 +142,7 @@ interface EventCompletionResult {prev_month_count: number;}-/** clix escaped a `Date` value to `'YYYY-MM-DD HH:mm:ss'` (query-builder.ts:286). */+/** Formatted as `'YYYY-MM-DD HH:mm:ss'`. */function since(days: number): SqlParam {return sql.string(formatClickhouseDate(new Date(Date.now() - days * MS_PER_DAY))@@ -155,7 +150,7 @@ function since(days: number): SqlParam {}/**- * The pre-engine detector, kept for V1 parity — no live callers today.+ * No live callers today; kept only so the defects above stay visible.** The class is no longer exported; `createLegacyInsightsScanner(deps)` below is* the module's factory, so every service module in core is reached the same way@@ -327,7 +322,6 @@ class LegacyInsightsScanner {...geographicShifts,...eventCompletions,].sort((a, b) => {- // Sort by most recent data firstconst dateA = new Date(insightPeriod(a.data));const dateB = new Date(insightPeriod(b.data));return dateB.getTime() - dateA.getTime();diff --git a/packages/core/src/modules/insight/src/referrer-spikes.ts b/packages/core/src/modules/insight/src/referrer-spikes.tsindex 1c4e6e12c..08e7a51d3 100644--- a/packages/core/src/modules/insight/src/referrer-spikes.ts+++ b/packages/core/src/modules/insight/src/referrer-spikes.ts@@ -1,11 +1,9 @@-// The ClickHouse CLIENT is `deps.ch` (the boot scope's round-robin proxy), so+// The ClickHouse client is `deps.ch` (the boot scope's round-robin proxy), so// the requestId minted at the edge reaches these queries. Table names and the// date helper are core's own copies (shared/ch-tables.ts, shared/ch-dates.ts).//-// Converted these three queries off clix: `getRawWhereClause` now returns a-// `SqlFragment` carrying bound params, and clix's `.execute` has no-// `query_params` slot to carry them through. clix always sent-// `session_timezone` (query-builder.ts:562) — `chQuery` gets the same value.+// `getRawWhereClause` returns a `SqlFragment` carrying bound params;+// `chQuery` always sends `session_timezone` in its settings.import { type SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';import { chQuery } from '../../../ch-query';import type { ServiceDeps } from '../../../services';@@ -80,7 +78,6 @@ export interface GetReferrerSpikesInput {timezone: string;}-/** clix's `toStartOf` (query-builder.ts:717) — the timezone arg was unused. */function bucketStart(interval: IInterval): SqlFragment {switch (interval) {case 'minute':@@ -107,7 +104,6 @@ function sessionWindow(return sql`project_id = ${sql.string(projectId)} AND created_at BETWEEN toDateTime(${sql.string(startDate)}) AND toDateTime(${sql.string(endDate)})`;}-/** `getRawWhereClause`'s output, already bound — clix appended it the same way. */function andFilters(where: SqlFragment | null): SqlFragment {return where ? sql` AND ${where}` : sql.empty;}@@ -156,7 +152,6 @@ export async function getReferrerSpikes(),]);- // clix's `.transform({ date })` (query-builder.ts:546) ran per row.const spikeRows = spikeRowsRaw.map((row) => ({...row,date: convertClickhouseDateToJs(row.date).toISOString(),diff --git a/packages/core/src/modules/insight/src/store.ts b/packages/core/src/modules/insight/src/store.tsindex df59b75a1..31abe4265 100644--- a/packages/core/src/modules/insight/src/store.ts+++ b/packages/core/src/modules/insight/src/store.ts@@ -47,7 +47,7 @@ export function createInsightStore(deps: ServiceDeps): InsightStore {const { DbNull } = deps.prisma;return {// `cadence` isn't read — there is only one today ('daily') — but it stays- // on the signature because InsightStore's contract names it (V1 parity).+ // on the signature because InsightStore's contract names it.async listProjectIdsForCadence(_cadence: Cadence): Promise<string[]> {const projects = await db.project.findMany({where: {@@ -125,7 +125,6 @@ export function createInsightStore(deps: ServiceDeps): InsightStore {lastUpdatedAt: now,};- // Try to find existing insight firstconst existing = prev? await db.projectInsight.findFirst({where: {@@ -140,12 +139,11 @@ export function createInsightStore(deps: ServiceDeps): InsightStore {let insight: InsightRow;if (existing) {- // Update existinginsight = await db.projectInsight.update({where: { id: existing.id },data: {...baseData,- threadId: existing.threadId, // Preserve threadId+ threadId: existing.threadId,// Materially-changed insights need re-enrichment; clearing enrichedAt// re-queues them for the AI pass. Keep the old score/summary as a// fallback until then (don't null those).@@ -169,19 +167,17 @@ export function createInsightStore(deps: ServiceDeps): InsightStore {});if (closed) {- // Reopen and updateinsight = await db.projectInsight.update({where: { id: closed.id },data: {...baseData,state: 'active',- threadId: closed.threadId, // Preserve threadId+ threadId: closed.threadId,// Reopening is a material event — re-enrich it.enrichedAt: null,},});} else {- // Create newinsight = await db.projectInsight.create({data: {...baseData,@@ -196,8 +192,8 @@ export function createInsightStore(deps: ServiceDeps): InsightStore {// projectId/moduleKey/dimensionKey/windowKind aren't persisted here — the// insight_events row is scoped by insightId alone, they're derivable from- // the parent (V1 parity) — but the engine passes them for identity/logging- // symmetry with the store's other methods, so they stay on the signature.+ // the parent — but the engine passes them for identity/logging symmetry+ // with the store's other methods, so they stay on the signature.async insertEvent({insightId,eventKind,diff --git a/packages/core/src/modules/insight/src/types.ts b/packages/core/src/modules/insight/src/types.tsindex 620adca6b..a48d82d0e 100644--- a/packages/core/src/modules/insight/src/types.ts+++ b/packages/core/src/modules/insight/src/types.ts@@ -45,17 +45,7 @@ export interface ComputeResult {extra?: Record<string, unknown>; // share delta pp, rank, sparkline, etc.}-// Types imported from ../insight.constants:-// - InsightMetricKey-// - InsightMetricEntry-// - InsightDimension-// - InsightPayload--/**- * Render should be deterministic and safe to call multiple times.- * Returns the shape that matches ProjectInsight create input.- * The payload contains all metric data and display metadata.- */+/** Render should be deterministic and safe to call multiple times. */export interface RenderedCard {title: string;summary?: string;diff --git a/packages/core/src/modules/insight/src/utils.ts b/packages/core/src/modules/insight/src/utils.tsindex f061f79aa..62cf9fc7f 100644--- a/packages/core/src/modules/insight/src/utils.ts+++ b/packages/core/src/modules/insight/src/utils.ts@@ -2,16 +2,10 @@* Shared utilities for insight modules*/-/**- * Get UTC weekday (0 = Sunday, 6 = Saturday)- */export function getWeekday(date: Date): number {return date.getUTCDay();}-/**- * Compute median of a sorted array of numbers- */export function computeMedian(sortedValues: number[]): number {if (sortedValues.length === 0) {return 0;@@ -31,7 +25,6 @@ interface DailyCountRow {/*** Compute weekday medians from daily breakdown data.- * Groups by dimension, filters to matching weekday, computes median per dimension.** @param data - Array of { date, dimension, cnt } rows* @param targetWeekday - Weekday to filter to (0-6)@@ -43,7 +36,6 @@ export function computeWeekdayMedians<T extends DailyCountRow>(targetWeekday: number,getDimension: (row: T) => string): Map<string, number> {- // Group by dimension, filtered to target weekdayconst byDimension = new Map<string, number[]>();for (const row of data) {@@ -58,7 +50,6 @@ export function computeWeekdayMedians<T extends DailyCountRow>(byDimension.set(dim, values);}- // Compute median per dimensionconst result = new Map<string, number>();for (const [dim, values] of byDimension) {values.sort((a, b) => a - b);@@ -68,9 +59,6 @@ export function computeWeekdayMedians<T extends DailyCountRow>(return result;}-/**- * Compute change percentage between current and compare values- */export function computeChangePct(currentValue: number,compareValue: number@@ -82,9 +70,6 @@ export function computeChangePct(: 0;}-/**- * Determine direction based on change percentage- */export function computeDirection(changePct: number,threshold = 0.05@@ -96,10 +81,7 @@ export function computeDirection(: 'flat';}-/**- * Get end of day timestamp (23:59:59.999) for a given date.- * Used to ensure BETWEEN queries include the full day.- */+/** Used to ensure BETWEEN queries include the full day. */export function getEndOfDay(date: Date): Date {const end = new Date(date);end.setUTCHours(23, 59, 59, 999);@@ -107,8 +89,7 @@ export function getEndOfDay(date: Date): Date {}/**- * Build a lookup map from query results.- * Aggregates counts by key, handling duplicate keys by summing values.+ * Build a lookup map from query results, summing counts for duplicate keys.** @param results - Array of result rows* @param getKey - Function to extract the key from each row@@ -144,7 +125,6 @@ export function selectTopDimensions(baselineMap: Map<string, number>,maxDims: number): string[] {- // Merge all dimensions from both mapsconst allDims = new Set<string>();for (const dim of currentMap.keys()) {allDims.add(dim);@@ -153,7 +133,6 @@ export function selectTopDimensions(allDims.add(dim);}- // Rank by greatest(current, baseline)const ranked = Array.from(allDims).map((dim) => ({dim,diff --git a/packages/core/src/modules/integration/integration.constants.ts b/packages/core/src/modules/integration/integration.constants.tsindex 90623be49..8e8236770 100644--- a/packages/core/src/modules/integration/integration.constants.ts+++ b/packages/core/src/modules/integration/integration.constants.ts@@ -12,7 +12,7 @@ import { z } from 'zod';/*** Prefix marking an at-rest ciphertext. Mirrors ENCRYPTION_PREFIX in- * `@openpanel/core/encryption.ts`, duplicated because this package is+ * `@openpanel/shared/server/encryption.ts`, duplicated because this file is* bundled for the browser and must not pull in the node-only crypto module.** Credentials are WRITE-ONLY: the API redacts them on read, so a client never@@ -169,7 +169,6 @@ export const zEmailConfig = z.object({});export type IEmailConfig = z.infer<typeof zEmailConfig>;-// S3 Export Integration Config - Base fields shared by both auth modesconst zS3ExportConfigBase = z.object({type: z.literal('s3_export'),bucket: z.string().min(1, 'Bucket name is required'),@@ -179,7 +178,6 @@ const zS3ExportConfigBase = z.object({// Only jsonl_gzip is implemented; adding a format here without a// `createBatch` branch persists a config whose exports can never run.format: z.enum(['jsonl_gzip']).default('jsonl_gzip'),- // Optional encryption settings (S3-side encryption)encryption: z.enum(['SSE-S3', 'SSE-KMS', 'none']).default('SSE-S3'),kmsKeyId: z.string().optional(),});@@ -199,23 +197,19 @@ const zS3AuthAccessKey = z.object({secretAccessKey: zWriteOnlySecret('Secret Access Key'),});-// S3 config with IAM role authexport const zS3ExportConfigIamRole = zS3ExportConfigBase.merge(zS3AuthIamRole);export type IS3ExportConfigIamRole = z.infer<typeof zS3ExportConfigIamRole>;-// S3 config with access key authexport const zS3ExportConfigAccessKey =zS3ExportConfigBase.merge(zS3AuthAccessKey);export type IS3ExportConfigAccessKey = z.infer<typeof zS3ExportConfigAccessKey>;-// Combined discriminated unionexport const zS3ExportConfig = z.discriminatedUnion('authMode', [zS3ExportConfigIamRole,zS3ExportConfigAccessKey,]);export type IS3ExportConfig = z.infer<typeof zS3ExportConfig>;-// GCS Export Integration Configexport const zGCSExportConfig = z.object({type: z.literal('gcs_export'),bucket: z.string().min(1, 'Bucket name is required'),diff --git a/packages/core/src/modules/integration/integration.routes.ts b/packages/core/src/modules/integration/integration.routes.tsindex 5211fe787..a3339e358 100644--- a/packages/core/src/modules/integration/integration.routes.ts+++ b/packages/core/src/modules/integration/integration.routes.ts@@ -1,15 +1,6 @@-// The Slack OAuth callback, `GET /webhook/slack`. V1's Fastify controller-// (apps/api/src/controllers/webhook.controller.ts's `slackWebhook`) stays the-// LIVE route (DELEGATE PATTERN) and delegates its token-exchange/ upsert logic-// to integration.service.ts's `completeSlackOAuthCallback` — the same function-// this route calls, same shape as gsc.routes.ts / auth.routes.ts.-//-// NAMED GAP, same as those two: this route is not yet reachable — main.ts does-// not mount `publicApiRoutes` until a real `AppDeps` exists (P3/P4/P8). V1's-// controller also renders an HTML error page from a local `error.html` file on-// failure; this route redirects to `/login?error=...` instead (same-// simplification gsc.routes.ts/auth.routes.ts already made for their own OAuth-// callbacks) since it serves no traffic yet.+// The Slack OAuth callback, `GET /webhook/slack`. Delegates token-exchange+// and upsert logic to integration.service.ts's `completeSlackOAuthCallback`,+// same shape as gsc.routes.ts / auth.routes.ts's OAuth callbacks.import { redirect } from 'elysia';import { z } from 'zod';diff --git a/packages/core/src/modules/integration/integration.service.ts b/packages/core/src/modules/integration/integration.service.tsindex ff34aabbc..1d3852027 100644--- a/packages/core/src/modules/integration/integration.service.ts+++ b/packages/core/src/modules/integration/integration.service.ts@@ -1,23 +1,10 @@-// V1's router stays the LIVE route (DELEGATE PATTERN) and delegates every-// handler body to these functions, same as notification's router does.-//// Authorization here is data-dependent — an update must authorize against the-// EXISTING row's scope, not the attacker-controlled input — so, unlike the-// simple input-shape ladder checks project.rpc.ts/notification.rpc.ts do-// themselves, the access assertions travel WITH the business logic, ported-// verbatim from the router's own `assertProjectAccessAndGetOrg`/-// `assertIntegrationAccess` helpers. Every exported function here is still-// called directly by `packages/trpc`'s LIVE V1 router with nothing but a-// `userId` (DELEGATE PATTERN), so these can't take a `ctx`/`deps` the way a-// core-only module's checks would; `requireProjectAccess` /-// `requireOrganizationAdmin` come from auth.service.ts's single,-// lazily-memoized `getAccessChecks`; `getOrganizationAccess` is a raw lookup-// (no ladder involved), reached directly from the sibling-// `shared/access-lookups.ts`.+// EXISTING row's scope, not the attacker-controlled input — so, unlike a+// simple input-shape ladder check, the access assertions travel WITH the+// business logic.//// Every exported function takes `ServiceDeps` and reaches Postgres as-// `deps.db`; the `loadDb` lazy loader is gone, so a requestId minted at the-// edge reaches the query.+// `deps.db`, so a requestId minted at the edge reaches the query.import { z } from 'zod';import { TRPCBadRequestError, TRPCForbiddenError } from '../../rpc/errors';@@ -306,9 +293,8 @@ export async function createOrUpdateSlackIntegration(});// `getSlackInstallUrl` returns null when no Slack app is configured on this- // deployment (ADR-022 R9: the client reports a missing thing as null). The- // decision that a Slack integration is unusable without one is this- // service's, not the transport's.+ // deployment. The decision that a Slack integration is unusable without one+ // is this service's, not the transport's.const installUrl = await getSlackInstallUrl({config: deps.config,integrationId: res.id,@@ -392,11 +378,9 @@ export async function deleteIntegration(return { id };}-// - Slack OAuth callback ----------------------------------------------- Ported-// from apps/api/src/controllers/webhook.controller.ts's `slackWebhook`. V1's-// Fastify controller stays the LIVE route (DELEGATE PATTERN) and delegates the-// token-exchange/upsert logic here, the same function this module's own-// `/webhook/slack` route (integration.routes.ts) calls.+// - Slack OAuth callback ---------------------------------------------------+// The token-exchange/upsert logic behind this module's `/webhook/slack` route+// (integration.routes.ts).const slackOAuthMetadataSchema = z.object({organizationId: z.string(),@@ -448,7 +432,6 @@ export async function completeSlackOAuthCallback(throw new SlackOAuthCallbackError('Failed to parse slack auth response');}- // Send a notification first to confirm the connectionawait sendSlackNotification({fetcher: safeWebhookFetcher,webhookUrl: parsedJson.data.incoming_webhook.url,@@ -485,8 +468,6 @@ type WithoutDeps<T extends (deps: ServiceDeps, ...args: never[]) => unknown> =? (...args: A) => R: never;-/** M10-009: this module had no factory at all — the one `*.service.ts` file- * `services.ts` did not register. */export function createIntegrationService(deps: ServiceDeps,_services: () => Servicesdiff --git a/packages/core/src/modules/integration/src/export/batch-creator.ts b/packages/core/src/modules/integration/src/export/batch-creator.tsindex b349a10e1..f23957233 100644--- a/packages/core/src/modules/integration/src/export/batch-creator.ts+++ b/packages/core/src/modules/integration/src/export/batch-creator.ts@@ -5,14 +5,8 @@ import { generateSecureId } from '@openpanel/shared';import type { Logger } from '../../../../logger';import type { IExportEvent } from './export-event';-/**- * Supported export formats- */export type ExportFormat = 'jsonl_gzip';-/**- * Batch metadata for tracking- */export interface IBatchInfo {batchId: string;projectId: string;@@ -22,30 +16,22 @@ export interface IBatchInfo {minEventTime: string;maxEventTime: string;createdAt: string;- // Partition infopartitionDate: string; // YYYY-MM-DDpartitionHour: string; // HH}-/**- * Created batch file info- */export interface IBatchFile {filename: string;content: Buffer;contentType: string;}-/**- * Result of creating a batch- */export interface IBatchResult {info: IBatchInfo;files: IBatchFile[];}/**- * Generate the object path for a batch* Layout: {prefix}/project_id={projectId}/integration_id={integrationId}/dt=YYYY-MM-DD/hour=HH/batch_id={batchId}/*/export function generateBatchPath(@@ -68,9 +54,6 @@ export function generateBatchPath(].join('/');}-/**- * Get file extension for format- */export function getFileExtension(format: ExportFormat): string {switch (format) {case 'jsonl_gzip':@@ -78,9 +61,6 @@ export function getFileExtension(format: ExportFormat): string {}}-/**- * Get content type for format- */export function getContentType(format: ExportFormat): string {switch (format) {case 'jsonl_gzip':@@ -115,16 +95,10 @@ function eventTimeRange(events: IExportEvent[]): {};}-/**- * Create JSONL content from events- */function createJsonlContent(events: IExportEvent[]): string {return `${events.map((event) => JSON.stringify(event)).join('\n')}\n`;}-/**- * Gzip compress content- */async function gzipCompress(content: string): Promise<Buffer> {const chunks: Buffer[] = [];const gzip = createGzip({ level: 6 });@@ -139,9 +113,6 @@ async function gzipCompress(content: string): Promise<Buffer> {return Buffer.concat(chunks);}-/**- * Create a batch of events in the specified format- */export async function createBatch(logger: Logger,projectId: string,diff --git a/packages/core/src/modules/integration/src/export/export-event.ts b/packages/core/src/modules/integration/src/export/export-event.tsindex 6537174e3..35e2505f8 100644--- a/packages/core/src/modules/integration/src/export/export-event.ts+++ b/packages/core/src/modules/integration/src/export/export-event.ts@@ -2,7 +2,7 @@ import type { IClickhouseEvent } from '../../../event/event.service';// Local copy for the reason every modules/*/src/dates.ts gives: importing// @openpanel/db's clickhouse/client constructs a ClickHouse client at import-// time, and M9-003 put this module on jobs.registry.ts's eager import chain.+// time, and this module sits on jobs.registry.ts's eager import chain.function convertClickhouseDateToJs(date: string): Date {return new Date(`${date.replace(' ', 'T')}Z`);}diff --git a/packages/core/src/modules/integration/src/export/manifest.ts b/packages/core/src/modules/integration/src/export/manifest.tsindex 69f9734f1..170fa95ab 100644--- a/packages/core/src/modules/integration/src/export/manifest.ts+++ b/packages/core/src/modules/integration/src/export/manifest.ts@@ -15,16 +15,12 @@ export interface IManifest {max_event_time: string;schema_version: number;created_at: string;- // Partition info for easy discoverypartition_date: string; // YYYY-MM-DDpartition_hour: string; // HH}const CURRENT_SCHEMA_VERSION = 1;-/**- * Create a manifest for a batch- */export function createManifest(batchInfo: IBatchInfo,fileNames: string[]@@ -45,26 +41,14 @@ export function createManifest(};}-/**- * Serialize manifest to JSON- */export function serializeManifest(manifest: IManifest): string {return JSON.stringify(manifest, null, 2);}-/**- * Parse a manifest from JSON- */export function parseManifest(json: string): IManifest {return JSON.parse(json) as IManifest;}-/**- * Manifest filename (always the same)- */export const MANIFEST_FILENAME = 'manifest.json';-/**- * Manifest content type- */export const MANIFEST_CONTENT_TYPE = 'application/json';diff --git a/packages/core/src/modules/integration/src/flush-exports.ts b/packages/core/src/modules/integration/src/flush-exports.tsindex e724b4340..021c8ba54 100644--- a/packages/core/src/modules/integration/src/flush-exports.ts+++ b/packages/core/src/modules/integration/src/flush-exports.ts@@ -1,12 +1,10 @@-// ADR-005's acceptance note gives `flushExports` to the integration module.-// Behaviour is V1's, verbatim; Prisma, the ClickHouse client and the-// object-store adapter factory arrive as injected deps so the orchestration is-// testable without `mock.module` (same idiom as-// modules/session/src/runtime.ts).+// Prisma, the ClickHouse client and the object-store adapter factory arrive+// as injected deps so the orchestration is testable without `mock.module`+// (same idiom as modules/session/src/runtime.ts).//-// The window query is a MOVE, not an ADR-013 conversion: it already binds every-// value through ClickHouse's own `{name:Type}` params, and converting it to the-// `sql` tag would change the emitted statement. Kept byte-identical.+// The window query already binds every value through ClickHouse's own+// `{name:Type}` params; converting it to the `sql` tag would change the+// emitted statement, so it stays byte-identical.import { DateTime } from '@openpanel/shared';import { isProviderError } from '../../../clients/provider-error';@@ -122,9 +120,9 @@ const formatCh = (date: Date): string =>/*** Drain new ClickHouse events into each configured object-store export.*- * The Redis buffer + per-event hook are gone: ClickHouse is the single source of- * truth, so this job windows the events table by `inserted_at` and uploads- * batched files. Export never touches the ingestion path.+ * ClickHouse is the single source of truth: this job windows the events+ * table by `inserted_at` and uploads batched files. Export never touches the+ * ingestion path.*/export async function runFlushExportsCron(deps: FlushExportsDepsdiff --git a/packages/core/src/modules/integration/src/object-store/gcs-adapter.test.ts b/packages/core/src/modules/integration/src/object-store/gcs-adapter.test.tsindex 19a04e6e6..542a4c983 100644--- a/packages/core/src/modules/integration/src/object-store/gcs-adapter.test.ts+++ b/packages/core/src/modules/integration/src/object-store/gcs-adapter.test.ts@@ -63,7 +63,7 @@ async function readObject(bucket: string, key: string): Promise<Buffer> {// GCS_API_ENDPOINT and ENCRYPTION_KEY arrive as config, not as env. The// endpoint is set by the emulator block's `beforeAll` and left unset for the-// validation-only tests above it, exactly as the env write it replaces did.+// validation-only tests above it.let emulatorEndpoint: string | undefined;function coreConfig(diff --git a/packages/core/src/modules/integration/src/object-store/gcs-adapter.ts b/packages/core/src/modules/integration/src/object-store/gcs-adapter.tsindex e2343cec0..976bb31b9 100644--- a/packages/core/src/modules/integration/src/object-store/gcs-adapter.ts+++ b/packages/core/src/modules/integration/src/object-store/gcs-adapter.ts@@ -1,4 +1,3 @@-// Ported from @openpanel/integrations (dissolved into core — M4-005).import { Storage } from '@google-cloud/storage';import { decryptCredential } from '@openpanel/shared/server';import {@@ -16,7 +15,7 @@ import type {IUploadResult,} from './types';-/** ADR-022 R19: every failure that leaves this adapter is classified as this. */+/** Every failure that leaves this adapter is classified under this provider name. */const GCS_PROVIDER = 'gcs';// A credential this adapter refuses is a refusal no retry can change.@@ -25,10 +24,6 @@ const CREDENTIAL_REJECTED_RETRYABLE = false;/** Object written by `testConnection`; named so it is obvious in a bucket. */const CONNECTION_TEST_FILENAME = '.openpanel-connection-test';-/**- * GCS Adapter for uploading export batches to Google Cloud Storage- * Uses service account credentials for authentication- */export class GCSAdapter implements IObjectStoreAdapter {private config: IGCSExportConfig;private storage: Storage | null = null;@@ -37,7 +32,6 @@ export class GCSAdapter implements IObjectStoreAdapter {config: IGCSExportConfig,private readonly coreConfig: CoreConfig) {- // Decrypt the service account key if encryptedthis.config = {...config,serviceAccountKey: decryptCredential(@@ -47,9 +41,6 @@ export class GCSAdapter implements IObjectStoreAdapter {};}- /**- * Get or create a GCS Storage client- */private getStorage(): Storage {if (this.storage) {return this.storage;@@ -115,9 +106,6 @@ export class GCSAdapter implements IObjectStoreAdapter {}}- /**- * Upload a single file to GCS- */async upload(options: IUploadOptions): Promise<IUploadResult> {const storage = this.getStorage();const bucket = storage.bucket(options.bucket);@@ -150,9 +138,6 @@ export class GCSAdapter implements IObjectStoreAdapter {};}- /**- * Upload multiple files to GCS- */async uploadMany(options: Array<IUploadOptions>): Promise<Array<IUploadResult | Error>> {@@ -171,8 +156,6 @@ export class GCSAdapter implements IObjectStoreAdapter {}/**- * Test the connection by writing a probe object.- ** Deliberately not `bucket.exists()`: reading bucket metadata needs* `storage.buckets.get`, which the least-privilege grant for an export target* (roles/storage.objectCreator, roles/storage.objectAdmin) does NOT include.@@ -217,9 +200,6 @@ export class GCSAdapter implements IObjectStoreAdapter {}}-/**- * Create a GCS adapter from integration config- */export function createGCSAdapter(config: IGCSExportConfig,coreConfig: CoreConfigdiff --git a/packages/core/src/modules/integration/src/object-store/s3-adapter.ts b/packages/core/src/modules/integration/src/object-store/s3-adapter.tsindex fc11a1b66..ec47a751f 100644--- a/packages/core/src/modules/integration/src/object-store/s3-adapter.ts+++ b/packages/core/src/modules/integration/src/object-store/s3-adapter.ts@@ -1,4 +1,3 @@-// Ported from @openpanel/integrations (dissolved into core — M4-005).import { Agent as HttpAgent } from 'node:http';import { Agent as HttpsAgent } from 'node:https';import type { LookupFunction } from 'node:net';@@ -27,7 +26,7 @@ import type {IUploadResult,} from './types';-/** ADR-022 R19: every failure that leaves this adapter is classified as this. */+/** Every failure that leaves this adapter is classified under this provider name. */const S3_PROVIDER = 's3';// An endpoint the SSRF guard refuses is refused identically on every retry.@@ -50,12 +49,7 @@ function pinnedRequestHandler(address: string) {};}-/**- * S3 Adapter for uploading export batches to AWS S3 or S3-compatible storage- * Supports two authentication modes:- * - IAM role assumption (AWS best practice)- * - Access keys (for R2, MinIO, DigitalOcean Spaces, etc.)- */+/** S3 adapter for uploading export batches to AWS S3 or S3-compatible storage. */export class S3Adapter implements IObjectStoreAdapter {private config: IS3ExportConfig;private clientPromise: Promise<S3Client> | null = null;@@ -79,9 +73,6 @@ export class S3Adapter implements IObjectStoreAdapter {}}- /**- * Get or create an S3 client based on auth mode- */private async getClient(): Promise<S3Client> {if (this.config.authMode === 'iam_role') {// Assumed-role clients talk to the default AWS endpoint (see@@ -119,10 +110,6 @@ export class S3Adapter implements IObjectStoreAdapter {return this.getClientWithAccessKeys(addresses?.[0]);}- /**- * Get or create an S3 client using static access keys- * For R2, MinIO, DigitalOcean Spaces, etc.- */private async getClientWithAccessKeys(pinnedAddress?: string): Promise<S3Client> {@@ -161,9 +148,6 @@ export class S3Adapter implements IObjectStoreAdapter {return client;}- /**- * Get or create an S3 client with assumed role credentials- */private async getClientWithAssumedRole(): Promise<S3Client> {const now = Date.now();@@ -176,9 +160,6 @@ export class S3Adapter implements IObjectStoreAdapter {return this.clientPromise;}- /**- * Create an S3 client by assuming the customer's IAM role- */private async createClientWithAssumedRole(): Promise<S3Client> {if (this.config.authMode !== 'iam_role') {throw new Error(@@ -212,7 +193,6 @@ export class S3Adapter implements IObjectStoreAdapter {throw new Error('Failed to assume role: no credentials returned');}- // Track when credentials expirethis.clientExpiresAt =credentials.Expiration?.getTime() || Date.now() + 3600 * 1000;@@ -235,9 +215,6 @@ export class S3Adapter implements IObjectStoreAdapter {}}- /**- * Get encryption parameters based on config- */private getEncryptionParams(): Partial<PutObjectCommandInput> {const encryption = this.config.encryption || 'SSE-S3';@@ -260,9 +237,6 @@ export class S3Adapter implements IObjectStoreAdapter {}}- /**- * Upload a single file to S3- */async upload(options: IUploadOptions): Promise<IUploadResult> {const client = await this.getClient();@@ -286,9 +260,6 @@ export class S3Adapter implements IObjectStoreAdapter {};}- /**- * Upload multiple files to S3- */async uploadMany(options: Array<IUploadOptions>): Promise<Array<IUploadResult | Error>> {@@ -306,9 +277,6 @@ export class S3Adapter implements IObjectStoreAdapter {});}- /**- * Test the connection to S3 bucket- */async testConnection(): Promise<{ success: boolean; error?: string }> {try {const client = await this.getClient();@@ -353,9 +321,6 @@ export class S3Adapter implements IObjectStoreAdapter {}}-/**- * Create an S3 adapter from integration config- */export function createS3Adapter(config: IS3ExportConfig,coreConfig: CoreConfigdiff --git a/packages/core/src/modules/integration/src/object-store/types.ts b/packages/core/src/modules/integration/src/object-store/types.tsindex 8114cb6c4..75e80a7bb 100644--- a/packages/core/src/modules/integration/src/object-store/types.ts+++ b/packages/core/src/modules/integration/src/object-store/types.ts@@ -1,11 +1,3 @@-// Ported from @openpanel/integrations (dissolved into core — M4-005).-/**- * Common types for object store adapters- */--/**- * Upload options for object store adapters- */export interface IUploadOptions {bucket: string;key: string;@@ -13,9 +5,6 @@ export interface IUploadOptions {contentType: string;}-/**- * Result of an upload operation- */export interface IUploadResult {bucket: string;key: string;@@ -23,24 +12,12 @@ export interface IUploadResult {location?: string;}-/**- * Object store adapter interface- */export interface IObjectStoreAdapter {- /**- * Upload a file to object storage- */upload(options: IUploadOptions): Promise<IUploadResult>;- /**- * Upload multiple files to object storage- */uploadMany(options: Array<IUploadOptions>): Promise<Array<IUploadResult | Error>>;- /**- * Check if the adapter is properly configured and can connect- */testConnection(): Promise<{ success: boolean; error?: string }>;}diff --git a/packages/core/src/modules/integration/src/registry.ts b/packages/core/src/modules/integration/src/registry.tsindex e27a757e0..790baae93 100644--- a/packages/core/src/modules/integration/src/registry.ts+++ b/packages/core/src/modules/integration/src/registry.ts@@ -1,7 +1,5 @@-// Ported from @openpanel/integrations (dissolved into core — M4-005). Moved out-// of `clients/integrations/` by M15-008: it dispatches to this module's own-// transports, so leaving it below them would have made every one of those edges-// point upward (A2).+// This module dispatches to its own transports, so it lives above them in the+// layer graph — placing it below would have made those imports point upward.import {type EncryptionKey,@@ -62,9 +60,6 @@ export interface INotificationDeliverArgs<* integration adds one entry to SERVER_INTEGRATIONS — the `satisfies Record`* below forces an entry for every union member (a missing one is a compile* error, not a silent runtime gap).- *- * The notification capability is added in a later step (it needs the db payload- * type + js-runtime); export-only for now.*/export interface IServerIntegration<T extends IIntegrationConfig['type']> {type: T;@@ -72,7 +67,6 @@ export interface IServerIntegration<T extends IIntegrationConfig['type']> {notification?: {deliver(args: INotificationDeliverArgs<T>): Promise<unknown> | unknown;};- // Object-store export sink.export?: {createAdapter(config: ConfigOf<T>,diff --git a/packages/core/src/modules/integration/src/slack.ts b/packages/core/src/modules/integration/src/slack.tsindex a16fd2d9a..266ed46c4 100644--- a/packages/core/src/modules/integration/src/slack.ts+++ b/packages/core/src/modules/integration/src/slack.ts@@ -1,6 +1,4 @@-// Ported from @openpanel/integrations (dissolved into core — M4-005). Moved out-// of `clients/integrations/` by M15-008: this module is its only consumer-// (ADR-022 A2). Cred to (@c_alares)+// Credit to (@c_alares):// https://github.com/christianalares/seventy-seven/blob/main/packages/integrations/src/slack/index.tsimport * as Slack from '@slack/bolt';@@ -46,9 +44,8 @@ export function slackInstaller(config: CoreConfig): InstallProvider {}/**- * `null` when this deployment has no Slack app configured — ADR-022 R9: a- * missing thing is null, not an error. The caller decides what an absent- * install flow means for its own surface.+ * `null` when this deployment has no Slack app configured. The caller+ * decides what an absent install flow means for its own surface.*/export const getSlackInstallUrl = ({config,diff --git a/packages/core/src/modules/mcp/mcp.routes.ts b/packages/core/src/modules/mcp/mcp.routes.tsindex bf39f378b..de5df6373 100644--- a/packages/core/src/modules/mcp/mcp.routes.ts+++ b/packages/core/src/modules/mcp/mcp.routes.ts@@ -1,17 +1,11 @@-// MCP's stateless POST transport, mounted at `/mcp` (ADR-015 entry 2).+// MCP's stateless POST transport, mounted at `/mcp`.//-// `ctx.services.mcp` carries this module's factory the same as every other-// module now — `mcp.service.ts`'s own header explains why that file is now safe-// to reach through `ctx.services` instead of this route's former one-off-// `loadMcpService`.-//-// OPEN GAP: V1's 60/min rate limit (Fastify's activateRateLimiter) is still not-// ported, and the route IS live — `apps/api/src/main.ts` mounts-// `dashboardRoutes` for every non-worker role. So an unauthenticated caller can-// drive one argon2 verify per request: `src/auth.ts` caches a *correct* secret-// for 5 minutes under a key containing that secret's hash, which a wrong secret-// misses every time. Porting the limiter is a task for whoever owns the HTTP-// surface; nothing in this module can do it.+// OPEN GAP: this route has no rate limit, and it IS live — `apps/api/src/main.ts`+// mounts `dashboardRoutes` for every non-worker role. So an unauthenticated+// caller can drive one argon2 verify per request: `src/auth.ts` caches a+// *correct* secret for 5 minutes under a key containing that secret's hash,+// which a wrong secret misses every time. Adding a limiter is a task for+// whoever owns the HTTP surface; nothing in this module can do it.//// The JSON-RPC body comes off the CONTEXT, not from `request.json`: Elysia has// already consumed the stream by the time the handler runs, and reading itdiff --git a/packages/core/src/modules/mcp/mcp.service.test.ts b/packages/core/src/modules/mcp/mcp.service.test.tsindex 8f22073e7..4f71aaf31 100644--- a/packages/core/src/modules/mcp/mcp.service.test.ts+++ b/packages/core/src/modules/mcp/mcp.service.test.ts@@ -302,7 +302,7 @@ describe('handleStatelessMcpRequest — protocol', () => {});it('closes the ephemeral server — and with it the transport pair it opened', async () => {- // R16. `spyOn` calls through, so the close still really happens.+ // `spyOn` calls through, so the close still really happens.const closeSpy = spyOn(McpServer.prototype, 'close');try {const res = await post(VALID_TOKEN, {diff --git a/packages/core/src/modules/mcp/mcp.service.ts b/packages/core/src/modules/mcp/mcp.service.tsindex 916d592dd..b7e0ff41b 100644--- a/packages/core/src/modules/mcp/mcp.service.ts+++ b/packages/core/src/modules/mcp/mcp.service.ts@@ -1,22 +1,15 @@-// Stateless-POST MCP transport (ADR-015 entry 2). V1 kept a Redis session store-// (`mcp:session:<uuid>`, 30-min TTL) and a `Mcp-Session-Id` header that could-// stand in for the token on every request after the first — both removed here,-// along with GET/SSE (already an unconditional 405 — deletes nothing that ever-// worked) and DELETE. Every POST authenticates from scratch and gets its own-// ephemeral McpServer; nothing survives between requests, so there is no-// session to store, touch or close, and no cross-instance stickiness-// requirement.+// Stateless-POST MCP transport. Every POST authenticates from scratch and+// gets its own ephemeral McpServer; nothing survives between requests, so+// there is no session to store, touch or close, and no cross-instance+// stickiness requirement. GET/SSE and DELETE are not supported.//-// MCP is the one module the wave map allows to change its endpoint surface —-// every other module in this wave preserves its V1 contract byte-for-byte.-//-// MCP is NOT a separate process and has no dependency builder of its own.-// `rest.routes.ts` mounts it with `.use(mcpRoutes(deps))`, so the route already-// holds the API's connections; this factory closes over them and hands them to-// `createMcpServer` per request (R15, Carl's ruling). The-// `@modelcontextprotocol/sdk` tool-handler signature has no context parameter,-// which is a CLOSURE problem — solved by building the server where `deps` is in-// hand — not a context problem.+// MCP is not a separate process and has no dependency builder of its own.+// `rest.routes.ts` mounts it with `.use(mcpRoutes(deps))`, so the route+// already holds the API's connections; this factory closes over them and+// hands them to `createMcpServer` per request. The+// `@modelcontextprotocol/sdk` tool-handler signature has no context+// parameter, which is a CLOSURE problem — solved by building the server+// where `deps` is in hand — not a context problem.import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';import {@@ -81,9 +74,7 @@ function invalidRequest(body: unknown, message: string): McpHttpResult {** Auth failures resolve to a 401 result rather than throwing, so the caller* (an HTTP framework's route handler) needs only one catch block for- * everything else — matching the DELEGATE PATTERN's V1 controllers, which- * keep framework-specific concerns (rate limiting, generic 500s) and hand- * the protocol to this function.+ * everything else.*/export async function handleStatelessMcpRequest(deps: ServiceDeps,@@ -135,12 +126,10 @@ export async function handleStatelessMcpRequest(}/**- * Every request gets a fresh McpServer over an in-memory transport pair —- * the ephemeral-server design already used to be per-session in V1; here it- * is simply per-request, with nothing else changing. A real `initialize`- * request completes the handshake directly; anything else fast-forwards a- * synthetic handshake first, since a brand-new server has no other way to- * reach its ready state.+ * Every request gets a fresh McpServer over an in-memory transport pair. A+ * real `initialize` request completes the handshake directly; anything else+ * fast-forwards a synthetic handshake first, since a brand-new server has no+ * other way to reach its ready state.*/async function runOnEphemeralServer(tools: McpToolDeps,@@ -261,8 +250,7 @@ function logToolResult(/*** The MCP tool tree reaches Postgres and ClickHouse through the `deps` this- * factory closes over — there is no singleton and no "no context" path left.- * `extractToken` is pure and stays a bare re-export.+ * factory closes over. `extractToken` is pure and stays a bare re-export.*/export function createMcpService(deps: ServiceDeps, services: () => Services) {return {diff --git a/packages/core/src/modules/mcp/src/auth.test.ts b/packages/core/src/modules/mcp/src/auth.test.tsindex 3102b8423..a74f739ff 100644--- a/packages/core/src/modules/mcp/src/auth.test.ts+++ b/packages/core/src/modules/mcp/src/auth.test.ts@@ -4,24 +4,12 @@ const mockGetClientByIdCached = mock();const mockVerifyPassword = mock();const mockGetCache = mock();const noopLogger = {- fatal: () => {- // no-op- },- error: () => {- // no-op- },- warn: () => {- // no-op- },- info: () => {- // no-op- },- debug: () => {- // no-op- },- trace: () => {- // no-op- },+ fatal: () => {},+ error: () => {},+ warn: () => {},+ info: () => {},+ debug: () => {},+ trace: () => {},child: () => noopLogger,};diff --git a/packages/core/src/modules/mcp/src/integration/tools.test.ts b/packages/core/src/modules/mcp/src/integration/tools.test.tsindex c737acd6b..8574c8f5e 100644--- a/packages/core/src/modules/mcp/src/integration/tools.test.ts+++ b/packages/core/src/modules/mcp/src/integration/tools.test.ts@@ -2,11 +2,11 @@* Integration tests for MCP tools against a real ClickHouse instance.** `bunfig.toml`'s preload pins CLICKHOUSE_URL/DATABASE_URL to the isolated- * `openpanel_test` databases (never production, never V1's own dev DB) —- * bun:test has no vitest-style globalSetup, so this suite bootstraps and- * seeds its own fixture (test/fixtures.ts, the same helper V1's- * apps/api/src/routes/insights.router.test.ts uses) in beforeAll/afterAll,- * under its own project/org id so it can run concurrently with that suite.+ * `openpanel_test` databases (never production) — bun:test has no+ * vitest-style globalSetup, so this suite bootstraps and seeds its own+ * fixture (test/fixtures.ts) in beforeAll/afterAll, under its own+ * project/org id so it can run concurrently with other suites using the+ * same fixture helper.** Fixture data (test/fixtures.ts's FIXTURE), seeded and queried with the clock* pinned to test/fixture-clock.ts's 12:00 UTC anchor so "5 days ago" is one@@ -21,11 +21,8 @@* ClickHouse fixture.** The fixture import reaches SEVEN levels up, out of this package and into the- * repository root's `test/fixtures.ts`. That is deliberate and it is the one- * exception to `packages/core/test/preload.ts`'s "core does not import from the- * V1 root test directory" — which is a statement about `preload.ts` keeping- * `test/databases.ts` in step by hand, not a rule this suite breaks silently.- * Copying the seeder here would fork the schema the golden harness seeds from.+ * repository root's `test/fixtures.ts`. That is deliberate: copying the+ * seeder here would fork the schema the golden harness seeds from.*/import { afterAll, beforeAll, describe, expect, it, mock } from 'bun:test';diff --git a/packages/core/src/modules/mcp/src/tools/analytics/engagement.test.ts b/packages/core/src/modules/mcp/src/tools/analytics/engagement.test.tsindex 42c15d30e..d2119032f 100644--- a/packages/core/src/modules/mcp/src/tools/analytics/engagement.test.ts+++ b/packages/core/src/modules/mcp/src/tools/analytics/engagement.test.ts@@ -14,8 +14,7 @@ const mockGetRetentionLastSeenSeries = mock();// Mocked at the specifier the source imports resolve to — a whole-barrel// replacement would drop every other export those modules carry for any-// other file sharing this process (bun:test only isolates modules per file-// under `--isolate`; see AGENTS.md). Restored in `afterAll` from a+// other file sharing this process. Restored in `afterAll` from a// plain-object snapshot taken BEFORE the first `mock.module` call: restoring// via the live `await import(...)` binding is a no-op once mocked.const actualRetention = await import('../../../../chart/retention.service');@@ -70,8 +69,8 @@ const noopLogger = {child: () => noopLogger,};-// Helper: directly invoke the bucketing logic by importing it through a minimal mock server-// We test the bucketing by calling the tool handler directly via a test double McpServer.+// Minimal test double for McpServer — captures the registered tool's+// handler so it can be invoked directly.function makeServer() {let handler: ((input: unknown) => Promise<unknown>) | null = null;return {diff --git a/packages/core/src/modules/mcp/src/tools/analytics/page-performance.test.ts b/packages/core/src/modules/mcp/src/tools/analytics/page-performance.test.tsindex 3fc36b419..c5c3cd625 100644--- a/packages/core/src/modules/mcp/src/tools/analytics/page-performance.test.ts+++ b/packages/core/src/modules/mcp/src/tools/analytics/page-performance.test.ts@@ -18,12 +18,10 @@ const mockGetSettingsForProject = mock(() =>// The tool reads the pages service off the `services` graph handed in with// `deps`, so `getTopPages` is a plain stub on TOOLS below rather than a module// mock. Only the two sibling module functions this file drives are still-// replaced, each at the specifier the source imports resolve to — a-// whole-barrel replacement would drop every other export those modules carry-// for any other file sharing this process (bun:test only isolates modules per-// file under `--isolate`; see AGENTS.md) — and each is restored in `afterAll`-// from a plain-object snapshot taken BEFORE the first `mock.module` call, since-// restoring via the live `await import(...)` binding is a no-op once mocked.+// replaced, each at the specifier the source imports resolve to, and each is+// restored in `afterAll` from a plain-object snapshot taken BEFORE the first+// `mock.module` call, since restoring via the live `await import(...)`+// binding is a no-op once mocked.const actualOrganizationService = await import('../../../../organization/organization.service');diff --git a/packages/core/src/modules/mcp/src/tools/analytics/property-values.ts b/packages/core/src/modules/mcp/src/tools/analytics/property-values.tsindex 813b2c48b..d9a142abd 100644--- a/packages/core/src/modules/mcp/src/tools/analytics/property-values.ts+++ b/packages/core/src/modules/mcp/src/tools/analytics/property-values.ts@@ -17,14 +17,10 @@ const MAX_PROPERTY_LIMIT = 500;const DEFAULT_VALUE_LIMIT = 50;const MAX_VALUE_LIMIT = 500;/** Raw (property_key, name) pairs scanned before `compactPropertyKeys` ranks- * them — V1's `.limit(500)`. */+ * them. */const PROPERTY_KEY_SCAN_LIMIT = 500;-/** Raw MV rows scanned before de-duplication — V1's `.limit(2000)`. */+/** Raw MV rows scanned before de-duplication. */const PROPERTY_VALUE_SCAN_LIMIT = 2000;-// clix built both statements below with no timezone argument, and-// `clix(client)` defaults to `'UTC'` (query-builder.ts:696-697), sending it as-// `clickhouse_settings.session_timezone` on every `execute()` (:562). Both-// keep sending it so their result sets stay identical.const CLIX_SESSION_TIMEZONE = { session_timezone: 'UTC' } as const;/**diff --git a/packages/core/src/modules/mcp/src/tools/analytics/reports.ts b/packages/core/src/modules/mcp/src/tools/analytics/reports.tsindex 9f53d61b8..b075bc720 100644--- a/packages/core/src/modules/mcp/src/tools/analytics/reports.ts+++ b/packages/core/src/modules/mcp/src/tools/analytics/reports.ts@@ -294,15 +294,15 @@ export function registerReportTools(}/**- * Execute a saved report by ID. Dispatches on chart type: - funnel → getFunnel- * - metric → AggregateChartEngine.execute - others → ChartEngine.execute+ * Execute a saved report by ID. Dispatches on chart type: funnel → getFunnel,+ * metric → executeAggregateChart, others → executeChart.*- * The assistant module (`../../assistant/src/report-runner.ts`) carries its own- * copy of this dispatch for its in-app chat tools — ADR-007 explicitly defers- * unifying MCP's tool definitions with assistant's, so the two live as- * hand-synced copies rather than a shared helper. Deliberately returns the raw- * engine output here — the MCP tool reshapes it for LLM consumption, the chat- * renderer needs the full chart.+ * The assistant module (`../../assistant/src/report-runner.ts`) carries its+ * own copy of this dispatch for its in-app chat tools — MCP's tool+ * definitions and assistant's are deliberately not unified, so the two live+ * as hand-synced copies rather than a shared helper. Deliberately returns the+ * raw engine output here — the MCP tool reshapes it for LLM consumption, the+ * chat renderer needs the full chart.*/async function runReport(deps: ServiceDeps,diff --git a/packages/core/src/modules/mcp/src/tools/shared.ts b/packages/core/src/modules/mcp/src/tools/shared.tsindex 37a9cbc1c..7e977647e 100644--- a/packages/core/src/modules/mcp/src/tools/shared.ts+++ b/packages/core/src/modules/mcp/src/tools/shared.ts@@ -10,8 +10,7 @@ import type { McpAuthContext } from '../auth';* `@modelcontextprotocol/sdk`'s tool-handler signature has no context* parameter, so the API's connections cannot be threaded through it as an* argument. They are captured in a CLOSURE instead, when the per-request server- * is built from the `deps` the route already holds (R15, Carl's ruling:- * `createMcpServer(deps)`).+ * is built from the `deps` the route already holds.*/export interface McpToolDeps {/** The API's connections. Postgres and ClickHouse are reached from here. */@@ -81,9 +80,6 @@ export const zDateRange = {),};-/**- * Resolve a date range, defaulting to the last 30 days if not provided.- */export function resolveDateRange(startDate?: string,endDate?: stringdiff --git a/packages/core/src/modules/misc/misc.service.ts b/packages/core/src/modules/misc/misc.service.tsindex b8358194f..d4e63f7ef 100644--- a/packages/core/src/modules/misc/misc.service.ts+++ b/packages/core/src/modules/misc/misc.service.ts@@ -1,17 +1,11 @@-// V1's Fastify controller and the worker's `cron.ping.ts` stay the LIVE code-// paths (DELEGATE PATTERN) and call the functions below verbatim — no new-// behaviour.-//// `GET/POST /misc/og/clear` and `/misc/favicon/clear` are deliberately absent:// nothing proxies them.//-// The ClickHouse CLIENT is `deps.ch` — reads through ch-query.ts, the one write-// through `deps.ch.insert` — so the `loadCh` lazy import of `@openpanel/db` is-// gone. M15-005 dropped the last hop too: these three statements are raw-// strings, not `sql` fragments, so they still need `TABLE_NAMES` /-// `formatClickhouseDate`, and core owns its own parity-tested copies of both-// (shared/ch-tables.ts, shared/ch-dates.ts, guarded by their `.parity.test.ts`-// siblings). Converting the STATEMENTS is ADR-013's P7 work, not this wave's.+// The ClickHouse CLIENT is `deps.ch` — reads through ch-query.ts, the one+// write through `deps.ch.insert`. These three statements are raw strings, not+// `sql` fragments, so they still need `TABLE_NAMES` / `formatClickhouseDate`,+// and core owns its own parity-tested copies of both (shared/ch-tables.ts,+// shared/ch-dates.ts, guarded by their `.parity.test.ts` siblings).//// `getCache` is a plain static import. It was lazy to survive core tests that// partially mock `@openpanel/redis` without a `getCache` export; those mocks@@ -94,8 +88,7 @@ function validateUrl(raw?: string): URL | null {}}-// Unlike `loadCache` above, this reaches the redis singleton directly rather-// than through `deps`/`ctx` — a known R6 gap (docs/review/misc.md), left as+// Reaches the redis singleton directly rather than through `deps`/`ctx`:// nothing calling these two functions today holds a `deps`/`ctx` to thread.async function getFromCacheBinary(key: string@@ -254,8 +247,6 @@ export async function getFavicon(let { buffer, contentType } = await fetchImage(imageUrl, logger);- // If the direct favicon fetch failed and it's not from DuckDuckGo's- // service, try DuckDuckGo's favicon service as a fallbackif (buffer.length === 0 && !imageUrl.hostname.includes('duckduckgo.com')) {const duckduckgoUrl = new URL(`https://icons.duckduckgo.com/ip3/${url.hostname}.ico`@@ -457,9 +448,8 @@ export async function getGeoReport(/*** The outbound half of "ping": a self-hosted instance's own cron job,- * reporting its event count back to `api.openpanel.dev/misc/ping` (the H- * route above, on OUR side). Ported verbatim from- * apps/worker/src/jobs/cron.ping.ts.+ * reporting its event count back to `api.openpanel.dev/misc/ping` (the+ * route above, on OUR side).*/export async function runPingCron(deps: ServiceDeps): Promise<unknown> {if (deps.config.pingDisabled) {diff --git a/packages/core/src/modules/misc/src/data-health.ts b/packages/core/src/modules/misc/src/data-health.tsindex 7bb8f8b82..c3a9af854 100644--- a/packages/core/src/modules/misc/src/data-health.ts+++ b/packages/core/src/modules/misc/src/data-health.ts@@ -1,7 +1,6 @@-// ADR-005's acceptance note gives `dataHealth` to the misc module. Behaviour is-// V1's, verbatim; Prisma, the last-event lookup and `sendEmail` arrive as-// injected deps so the job is testable without `mock.module`. `misc.jobs.ts`-// binds them off the job's ctx.+// Prisma, the last-event lookup and `sendEmail` arrive as injected deps so+// the job is testable without `mock.module`. `misc.jobs.ts` binds them off+// the job's ctx.import type { CoreConfig } from '../../../config';import type { Logger } from '../../../logger';diff --git a/packages/core/src/modules/misc/src/image-proxy.ts b/packages/core/src/modules/misc/src/image-proxy.tsindex b2a7ac444..d8df32c90 100644--- a/packages/core/src/modules/misc/src/image-proxy.ts+++ b/packages/core/src/modules/misc/src/image-proxy.ts@@ -1,5 +1,3 @@-// Ported verbatim from apps/api/src/utils/image-proxy.ts.-//// These bytes come from a third-party server and are then served from the API// origin, which also serves the credentialed `/trpc` and `/oauth` endpoints.// Anything returned verbatim is therefore attacker-controlled content on a@@ -34,7 +32,6 @@ export function normalizeContentType(raw: string | null): string {return (raw ?? '').split(';')[0]!.trim().toLowerCase();}-/** Check if URL is an ICO file */export function isIcoFile(url: string, contentType?: string): boolean {return (url.toLowerCase().endsWith('.ico') ||@@ -58,7 +55,6 @@ export function hasIcoMagicBytes(buffer: Buffer): boolean {);}-/** Process image with Sharp (resize to 30x30 PNG) */export async function processImage(buffer: Buffer,originalUrl?: string,@@ -93,7 +89,6 @@ export async function processImage(}}-/** Process OG image with Sharp (resize to 300px width) */export async function processOgImage(buffer: Buffer,originalUrl?: string,diff --git a/packages/core/src/modules/notification/notification.jobs.ts b/packages/core/src/modules/notification/notification.jobs.tsindex 212f0560d..f752f263b 100644--- a/packages/core/src/modules/notification/notification.jobs.ts+++ b/packages/core/src/modules/notification/notification.jobs.ts@@ -1,7 +1,7 @@-// `sendNotification` is this module's own queue (`notification` in the registry-// — ADR-005's registry key). legacyCompat.notification already discriminates on-// this exact job name (jobs/compat.ts), so this pins the two in agreement. No-// cron fragment — notifications are always triggered by a rule match, never+// `sendNotification` is this module's own queue (`notification` in the+// registry). legacyCompat.notification already discriminates on this exact+// job name (jobs/compat.ts), so this pins the two in agreement. No cron+// fragment — notifications are always triggered by a rule match, never// scheduled.import type { Prisma } from '@openpanel/db/src/prisma-client';@@ -10,10 +10,9 @@ import { isProviderError } from '../../clients/provider-error';import { defineJob } from '../../jobs/define';// A loose mirror of `Prisma.NotificationUncheckedCreateInput` — the payload-// is a Prisma create input on the wire (packages/queue/src/queues.ts's-// `NotificationQueuePayload`), and BullMQ stores job data as JSON, so this-// only needs to survive that round-trip, not model every Prisma input-// variant.+// is a Prisma create input on the wire, and BullMQ stores job data as JSON,+// so this only needs to survive that round-trip, not model every Prisma+// input variant.const notificationPayload = z.object({id: z.string().optional(),projectId: z.string(),@@ -34,7 +33,7 @@ export const notificationQueueJobs = {try {// `payload.notification` round-tripped through BullMQ's JSON storage// and the loose wire schema above — the real shape is Prisma's create- // input, exactly what a V1 producer put on the queue.+ // input.await ctx.services.notification.dispatch(payload.notification as Prisma.NotificationUncheckedCreateInput);diff --git a/packages/core/src/modules/notification/notification.service.ts b/packages/core/src/modules/notification/notification.service.tsindex 1a428c9d5..4bea7daef 100644--- a/packages/core/src/modules/notification/notification.service.ts+++ b/packages/core/src/modules/notification/notification.service.ts@@ -1,13 +1,9 @@-// The delivery body moves here too, from apps/worker/src/jobs/notification.ts-// (DELEGATE PATTERN: that file becomes a thin wrapper calling-// `deliverNotification`).-//// `createNotification` / `triggerNotification` /// `checkNotificationRulesForEvent` / `checkNotificationRulesForSessionEnd` —-// the BullMQ-producer orchestration around a rule match — live in this module's-// own `src/notification-dispatch.ts` since M11-003, built on the rule matching,-// templates, cache and constants exported below. They are a separate file only-// so the enqueue side is not dragged into every import of this one.+// the BullMQ-producer orchestration around a rule match — live in this+// module's own `src/notification-dispatch.ts`, built on the rule matching,+// templates, cache and constants exported below. They are a separate file+// only so the enqueue side is not dragged into every import of this one.//// Postgres is `deps.db` and `Prisma.DbNull` is `deps.prisma.DbNull`: nothing// here imports @openpanel/db as a value, which is what keeps constructing a@@ -73,7 +69,7 @@ export type INotificationPayload =// `getNotificationRulesByProjectId` is `cacheablePerDeps` — `cacheable` keys on// the call's ARGUMENTS (packages/redis/cachable.ts), so the caller's deps// travel beside the key rather than inside it and the Redis key stays-// byte-identical. Every function in this file now reads `deps.db`.+// byte-identical. Every function in this file reads `deps.db`.// -- Rule cache --------------------------------------------------------@@ -330,10 +326,9 @@ export async function deliverNotification(// Returning rather than throwing here (and in the missing-config branch// below) resolves `notificationQueueJobs.sendNotification`'s promise// normally, so BullMQ records the job as completed instead of failed —- // the delivery is silently dropped. Left as-is: no test exercises either- // branch today, and flipping the job outcome from success to failure is a- // behavior change out of this task's scope (docs/review/notification.md,- // "Not covered by any rule" #1).+ // the delivery is silently dropped. Left as-is deliberately: flipping the+ // job outcome from success to failure is a behavior change, and no test+ // exercises either branch today.if (!isValidPayload<INotificationPayload>(payload,@@ -521,10 +516,7 @@ export async function deleteNotificationRule(deps: ServiceDeps, id: string) {// This wraps only `dispatch` (what notification.jobs.ts needs). Every other// function above and in ./src/notification-dispatch.ts is called directly —// by notification.rpc.ts, by session/ingest as siblings, and by index.ts's-// barrel — not through ctx.services.notification. Consolidating that would-// mean changing those other modules' call sites, out of this task's scope-// (docs/review/notification.md, "Not covered by any rule" #2; the same-// shape misc.md's MiscService finding describes for that module).+// barrel — not through ctx.services.notification.export function createNotificationService(deps: ServiceDeps,_services: () => Servicesdiff --git a/packages/core/src/modules/notification/src/notification-dispatch.ts b/packages/core/src/modules/notification/src/notification-dispatch.tsindex 715a24666..67b72d45e 100644Binary files a/packages/core/src/modules/notification/src/notification-dispatch.ts and b/packages/core/src/modules/notification/src/notification-dispatch.ts differdiff --git a/packages/core/src/modules/onboarding/onboarding.service.test.ts b/packages/core/src/modules/onboarding/onboarding.service.test.tsindex 713580dc3..f4a5891dc 100644--- a/packages/core/src/modules/onboarding/onboarding.service.test.ts+++ b/packages/core/src/modules/onboarding/onboarding.service.test.ts@@ -25,7 +25,7 @@ const getOrganizationEventsCount = mock();// Spread a plain-object SNAPSHOT of the real module, not a partial factory:// `mock.module` replaces this specifier process-wide under bare `bun test`-// (AGENTS.md), and since M10-009 every cross-module caller reaches+// (AGENTS.md), and every cross-module caller reaches// `getSettingsForProject` / `getOrganizationByProjectIdCached` through this// deep path rather than the package barrel — a partial factory here silently// deleted them for every file that ran afterwards.diff --git a/packages/core/src/modules/onboarding/onboarding.service.ts b/packages/core/src/modules/onboarding/onboarding.service.tsindex 817930200..7b4910422 100644--- a/packages/core/src/modules/onboarding/onboarding.service.ts+++ b/packages/core/src/modules/onboarding/onboarding.service.ts@@ -1,14 +1,5 @@-// New module: the onboarding-project mutation inline in-// packages/trpc/src/routers/onboarding.ts, plus the onboarding email drip-// inline in apps/worker/src/jobs/cron.onboarding.ts. Neither had a-// packages/db/src/services/* home to move from — written directly here, same-// shape as auth.service.ts's Prisma-touching half. DELEGATE PATTERN: V1's trpc-// router and cron job, and this package's own-// onboarding.rpc.ts/onboarding.jobs.ts, all call these same functions.-//// Every exported function takes `ServiceDeps` and reaches Postgres as-// `deps.db`; the `loadDb` lazy loader is gone, so the requestId minted at the-// edge reaches the query.+// `deps.db`, so the requestId minted at the edge reaches the query.import crypto from 'node:crypto';import { getRecommendedPlan } from '@openpanel/payments';@@ -46,9 +37,9 @@ export async function canSkipOnboarding(// Sequential, not Promise.all: the early return below skips the// projectAccess query entirely for any user with a membership, which a- // parallel fetch would give up (docs/review/onboarding.md, "Not covered- // by any rule" #2). Changing this trades a real memberships-found saving- // for the all-false path's latency — a behavior change, out of scope here.+ // parallel fetch would give up. Changing this trades a real+ // memberships-found saving for the all-false path's latency — a behavior+ // change, out of scope here.const db = deps.db;const members = await db.member.findMany({ where: { userId } });if (members.length > 0) {@@ -178,15 +169,14 @@ export async function createOnboardingProject(}// ------------------------------------------------------------------------// The onboarding email drip cron (apps/worker/src/jobs/cron.onboarding.ts —-// DELEGATE PATTERN). The `organization.onboarding` column stores the last-// sent step, and step names are equal to template names for historical-// reasons: in-flight orgs already hold those values. Renaming one strands-// every org sitting on it (the runner completes them rather than replaying-// the sequence, but they still stop early).+// The onboarding email drip cron. The `organization.onboarding` column+// stores the last sent step, and step names are equal to template names for+// historical reasons: in-flight orgs already hold those values. Renaming one+// strands every org sitting on it (the runner completes them rather than+// replaying the sequence, but they still stop early).//// Stops at day 26 — what happens after the trial expires belongs to the-// (not yet ported) wind-down cron, anchored on expiry rather than signup.+// wind-down cron, anchored on expiry rather than signup.interface OnboardingUsage {eventsCount: number;diff --git a/packages/core/src/modules/organization/organization.constants.ts b/packages/core/src/modules/organization/organization.constants.tsindex 70be0229d..03c893aa0 100644--- a/packages/core/src/modules/organization/organization.constants.ts+++ b/packages/core/src/modules/organization/organization.constants.ts@@ -2,7 +2,7 @@// organization-shaped (organization.rpc.ts's invite/access mutations), so it// lives here and `zInviteUser` embeds it without a cross-file constants import.// @openpanel/db's `code-migrations/constants.ts` keeps its own frozen copy of-// the schema (Carl's rulings) — it is not a consumer.+// the schema — it is not a consumer.import { z } from 'zod';diff --git a/packages/core/src/modules/organization/organization.jobs.ts b/packages/core/src/modules/organization/organization.jobs.tsindex ced52f20f..a236dd767 100644--- a/packages/core/src/modules/organization/organization.jobs.ts+++ b/packages/core/src/modules/organization/organization.jobs.ts@@ -1,8 +1,5 @@-// The schedules moved onto the jobs at ADR-021.-//// `delete` is this module's fragment of the ONE `cron` queue's jobs, spread-// into jobs.registry.ts. Scheduler id and cadence are V1's, unchanged-// (apps/worker/src/boot-cron.ts).+// into jobs.registry.ts.import { z } from 'zod';import type { Ctx } from '../../context';@@ -18,7 +15,7 @@ import {type WindDownDeps,} from './src/wind-down';-/** Hourly — V1's cadence (apps/worker/src/boot-cron.ts). */+/** Hourly. */const WIND_DOWN_CRON = '0 * * * *';/** This module's fragment of the `cron` queue's jobs. */@@ -48,9 +45,7 @@ export const organizationCronJobs = {* Two reaches stay dynamic. The sibling service's two ClickHouse counts are not* on `OrganizationService`, and `src/win-back-pitch.ts` pulls the agent runtime* — a static edge from here would drag either into jobs.registry.ts's eager- * import graph, which every core test file walks. M15-119 (R11) ruled this the- * ADR-022 "legitimate lazy asset load" exception, not the sibling- service- * defect R6 forbids: kept as is.+ * import graph, which every core test file walks.*/async function windDownDeps(ctx: Ctx, logger: Logger): Promise<WindDownDeps> {const [diff --git a/packages/core/src/modules/organization/organization.service.test.ts b/packages/core/src/modules/organization/organization.service.test.tsindex be07d1d65..87ea30387 100644--- a/packages/core/src/modules/organization/organization.service.test.ts+++ b/packages/core/src/modules/organization/organization.service.test.ts@@ -404,9 +404,7 @@ const projectAccess = {const $transaction = mock(async (ops: Promise<unknown>[]) => Promise.all(ops));// Every function under test takes `ServiceDeps`, so `deps.db` and `deps.ch` ARE-// the fakes below — the two `@openpanel/db` module mocks this file used to-// install are gone, and with them the process-wide leak they had to be restored-// from. `connectUserToOrganization` reaches `shared/access-lookups.ts`+// the fakes below. `connectUserToOrganization` reaches `shared/access-lookups.ts`// (cacheable, on the unscoped db), which is why the `@openpanel/redis` stand-in// below stays.const chCommand = mock(async () => undefined);@@ -447,11 +445,9 @@ function cacheableStub(set: () => async () => 'OK' as const,});}-// Spread the real module for the same reason the clickhouse/client mock above-// does: `mock.module` replaces this specifier process-wide. Surfaced by M8-001,-// which put `createBuffers` on core's barrel — event-buffer.ts value-imports-// `publishEvent` from here, so a partial factory turns this file's own barrel-// import into a SyntaxError.+// Spread the real module: `mock.module` replaces this specifier process-wide,+// and `event-buffer.ts` value-imports `publishEvent` from here, so a partial+// factory turns this file's own barrel import into a SyntaxError.const realRedis = { ...(await import('@openpanel/redis')) };mock.module('@openpanel/redis', () => ({...realRedis,@@ -469,10 +465,9 @@ afterAll(() => {// Mocks core's own clients/email.ts wrapper, not @openpanel/email itself:// that package statically imports @openpanel/db's full barrel (Resend/SMTP-// setup aside), which is exactly the eager side-effecting chain-// organization.service.ts's own lazy `load*` helpers exist to avoid — see-// this file's header. mcp.service.test.ts mocks the same relative depth for-// the same reason.+// setup aside), an eager side-effecting chain this test avoids by mocking+// at this depth. mcp.service.test.ts mocks the same relative depth for the+// same reason.const sentEmails: { templateKey: string; to: string; data: unknown }[] = [];mock.module('../../clients/email', () => ({sendEmail: async (diff --git a/packages/core/src/modules/organization/organization.service.ts b/packages/core/src/modules/organization/organization.service.tsindex d9e722491..1cf5c6954 100644--- a/packages/core/src/modules/organization/organization.service.ts+++ b/packages/core/src/modules/organization/organization.service.ts@@ -36,11 +36,8 @@ export type IServiceMember = Prisma.MemberGetPayload<{}> & { access: ProjectAccess[] };export type IServiceProjectAccess = ProjectAccess;-// Grace period between a scheduled deletion and the `delete` cron sweeping it-// up — matches V1's `addHours(new Date(), 24)`.// Session bookkeeping rows are worker-generated (the reaper can emit// session_end long after tracking stopped), so they are not billable activity.-// V1 wrote this list inline as SQL text in all four counters below.const NON_BILLABLE_EVENT_NAMES = ['session_start', 'session_end'];/** A module function's parameters with its leading `ServiceDeps` dropped. */type Tail<T extends unknown[]> = T extends [unknown, ...infer Rest]@@ -48,7 +45,6 @@ type Tail<T extends unknown[]> = T extends [unknown, ...infer Rest]: never;const DELETE_GRACE_PERIOD_MS = 24 * 60 * 60 * 1000;-// Invite link lifetime — matches V1's `addDays(new Date(), 3)`.const INVITE_EXPIRY_MS = 3 * 24 * 60 * 60 * 1000;export async function getOrganizations(@@ -363,10 +359,8 @@ export async function getOrganizationBillingEventsCountSerie(endDate: Date;}): Promise<{ count: number; day: string }[]> {- // V1 built this through a `const interval = 'day'` that was never anything- // but 'day'; the fragment writes the bucket out instead of deriving four- // spellings of it. `day` is the SELECT alias, referenced by the WHERE and- // the WITH FILL exactly as V1 referenced it.+ // `day` is the SELECT alias, referenced by both the WHERE clause and the+ // WITH FILL below.const from = formatClickhouseDate(startDate, true);const to = formatClickhouseDate(endDate, true);const statement = sql`@@ -404,7 +398,6 @@ export async function getOrganizationSubscriptionChartEndDate(if (!organization) {return null;}- // If the current period end date is after the subscription chart end date, we need to use the subscription chart end dateif (organization.subscriptionChartEndDate &&new Date(endDate) > organization.subscriptionChartEndDate@@ -475,8 +468,6 @@ export async function getSettingsForProject(};}-// -- Moved from packages/db/src/services/delete.service.ts ----export async function deleteOrganization(deps: ServiceDeps,organizationId: string@@ -559,11 +550,9 @@ export interface DeleteCronResult {}/**- * The `delete` cron fragment's body — moved from- * apps/worker/src/jobs/cron.delete.ts's `jobDelete`. Finds organizations- * scheduled for deletion or orphaned (no admin member), and projects- * individually scheduled for deletion, then sweeps both out of ClickHouse and- * Postgres in one pass.+ * Finds organizations scheduled for deletion or orphaned (no admin member),+ * and projects individually scheduled for deletion, then sweeps both out of+ * ClickHouse and Postgres in one pass.*/export async function runDeleteCron(deps: ServiceDeps@@ -571,8 +560,6 @@ export async function runDeleteCron(const db = deps.db;const now = new Date();- // Find orphaned organizations (no admin member)- // or organizations that are scheduled for deletionconst organizations = await db.organization.findMany({where: {OR: [@@ -589,7 +576,6 @@ export async function runDeleteCron(!(organization.hasSubscription && !organization.isWillBeCanceled));- // Find projects that are scheduled for deletionconst scheduledProjects = await db.project.findMany({where: { deleteAt: { lte: now } },select: { id: true },@@ -619,8 +605,6 @@ export async function runDeleteCron(};}-// -- Moved from packages/trpc/src/routers/organization.ts's inline bodies ----export async function updateOrganization(deps: ServiceDeps,input: {diff --git a/packages/core/src/modules/organization/src/win-back-highlight.ts b/packages/core/src/modules/organization/src/win-back-highlight.tsindex 96b2edacc..3fcaeb9eb 100644--- a/packages/core/src/modules/organization/src/win-back-highlight.ts+++ b/packages/core/src/modules/organization/src/win-back-highlight.ts@@ -1,8 +1,8 @@-// Behaviour is V1's, verbatim; only the wiring changed — the two stats lookups-// and the AI call arrive as injected deps (`WinBackHighlightDeps`) instead of-// static imports, the same idiom the session lifecycle uses-// (modules/session/src/runtime.ts): `organization.jobs.ts` binds them off the-// job's ctx, and tests hand in stubs, so no `mock.module` is needed anywhere.+// The two stats lookups and the AI call arrive as injected deps+// (`WinBackHighlightDeps`) instead of static imports, the same idiom the+// session lifecycle uses (modules/session/src/runtime.ts):+// `organization.jobs.ts` binds them off the job's ctx, and tests hand in+// stubs, so no `mock.module` is needed anywhere.import { format, subDays } from 'date-fns';import type { Logger } from '../../../logger';diff --git a/packages/core/src/modules/organization/src/win-back-pitch.ts b/packages/core/src/modules/organization/src/win-back-pitch.tsindex 6807b9e74..6e4512cd9 100644--- a/packages/core/src/modules/organization/src/win-back-pitch.ts+++ b/packages/core/src/modules/organization/src/win-back-pitch.ts@@ -1,5 +1,3 @@-// Ported from @openpanel/ai (dissolved into core — M4-005).-//// Wind-down win-back pitch: one short OpenAI call that turns a lapsed trial's// recent stats into a two-sentence selling argument for the wind-down emails.// Same one-shot structured-output pattern as narrative.ts — and like thediff --git a/packages/core/src/modules/organization/src/wind-down.ts b/packages/core/src/modules/organization/src/wind-down.tsindex b1b5d02c8..2021c1735 100644--- a/packages/core/src/modules/organization/src/wind-down.ts+++ b/packages/core/src/modules/organization/src/wind-down.ts@@ -1,11 +1,3 @@-// ADR-005's acceptance note gives `windDown` to the organization module.-// Behaviour is V1's, verbatim; only the wiring changed — Prisma, the two-// ClickHouse counts, the last-event lookup, the plan pricer, the highlight-// builder and `sendEmail` all arrive as injected deps (`WindDownDeps`), the-// same idiom the session lifecycle uses (modules/session/src/runtime.ts).-// `organization.jobs.ts` binds them off the job's ctx; tests hand in stubs, so-// no `mock.module` is needed.-import { getRecommendedPlan } from '@openpanel/payments';import { addDays, format, subDays } from 'date-fns';import type { CoreConfig } from '../../../config';@@ -55,7 +47,7 @@ function getMaxPerRun(config: CoreConfig): number {return config.query.windDownMaxPerRun ?? DEFAULT_MAX_PER_RUN;}-/** The organization row shape this job reads — V1's `orgQuery` include. */+/** The organization row shape this job reads. */export interface WindDownOrganization {id: string;subscriptionState: string;diff --git a/packages/core/src/modules/overview/overview.rpc.ts b/packages/core/src/modules/overview/overview.rpc.tsindex c9d4eb956..90cb34744 100644--- a/packages/core/src/modules/overview/overview.rpc.ts+++ b/packages/core/src/modules/overview/overview.rpc.ts@@ -1,14 +1,9 @@-// `overviewProcedure` is V1's own builder — `publicProcedure` plus one-// middleware that resolves share-or-membership off the raw-// `projectId`/`shareId`, BEFORE the input parser. `runFilterCommand` is a-// `protectedProcedure`, as in V1.+// `overviewProcedure` is `publicProcedure` plus one middleware that resolves+// share-or-membership off the raw `projectId`/`shareId`, BEFORE the input+// parser.//-// V1's per-range `cacheMiddleware` did NOT move with M11-001;-// `createCacheMiddleware` in rpc/base.ts is the seam that will carry it.-//-// `liveData`'s ClickHouse queries used to live inline in packages/trpc's-// router; they moved to `services.overview.getLiveData` (src/overview.sql.ts)-// so every query this module runs goes through the same `sql` tag.+// There is no per-range cache middleware yet; `createCacheMiddleware` in+// rpc/base.ts is the seam that will carry it.import { getChartPrevStartEndDate } from '@openpanel/shared';import { format } from 'date-fns';diff --git a/packages/core/src/modules/overview/overview.service.ts b/packages/core/src/modules/overview/overview.service.tsindex 3e04438c6..5ecf9411a 100644--- a/packages/core/src/modules/overview/overview.service.ts+++ b/packages/core/src/modules/overview/overview.service.ts@@ -1,13 +1,6 @@-// The ClickHouse queries moved to src/overview.sql.ts.-//-// `OverviewService` is no longer a class and there is no `overviewService`-// module singleton. Every method is a module-scope function taking-// `ServiceDeps` first and otherwise the same arguments, and-// `createOverviewService(deps)` binds them under their old method names, so-// `services.overview.getMetrics(input)` reads exactly as-// `overviewService.getMetrics(input)` did. The caller-supplied-// `constructor(client)` slot is gone with it: the client is `deps.ch`, which is-// what puts the request's id on the query's log line.+// The ClickHouse queries live in src/overview.sql.ts. Every function here+// takes `ServiceDeps` first; the client is `deps.ch`, which is what puts the+// request's id on the query's log line.import type { SqlFragment } from '@openpanel/db/src/clickhouse/sql';import { average, sum } from '@openpanel/shared';@@ -93,7 +86,6 @@ const UTM_COLUMNS = ['utm_content',];-// Typestype MetricsRow = {bounce_rate: number;unique_visitors: number;@@ -307,10 +299,10 @@ function getOverallRevenue(}/**- * V1 `withDistinctSessionsIfNeeded`: a page (`path`) filter has no column on- * `sessions`, so it's resolved against `events` first and the session ids- * that match are intersected in. Returns the mutually-exclusive pair every- * `sessions`-scoped query builder takes.+ * A page (`path`) filter has no column on `sessions`, so it's resolved+ * against `events` first and the session ids that match are intersected in.+ * Returns the mutually-exclusive pair every `sessions`-scoped query builder+ * takes.*/function sessionsFilterMode(params: {filters: IChartEventFilter[];@@ -748,9 +740,9 @@ export async function getTopGenericSeries(return { items: [] };}- // V1 always applies the sessions rawWhere here (unlike the top-items- // query above), additionally wrapping in distinct_sessions on a page- // filter — see overview.sql.ts's topGenericSeriesTimeSeriesQuery header.+ // Unlike the top-items query above, the sessions rawWhere is applied here+ // and additionally wrapped in distinct_sessions on a page filter — see+ // overview.sql.ts's topGenericSeriesTimeSeriesQuery header.const timeSeriesSessionsFilter = isPageFilter(filters)? distinctSessionsQuery({projectId,@@ -852,11 +844,9 @@ export async function getUserJourney(}>;links: Array<{ source: string; target: string; value: number }>;}> {- // Config- const TOP_ENTRIES = 3; // Only show top 3 entry pages- const TOP_DESTINATIONS_PER_NODE = 3; // Top 3 destinations from each node+ const TOP_ENTRIES = 3;+ const TOP_DESTINATIONS_PER_NODE = 3;- // Color palette - each entry page gets a consistent colorconst COLORS = chartColors.map((color) => color.main);const rawFilterWhere = getRawWhereClause('events', filters);@@ -890,9 +880,8 @@ export async function getUserJourney(return { nodes: [], links: [] };}- // Build the sankey progressively step by step. Start with entry nodes,- // then follow top destinations at each step. Node IDs combine path with- // step to prevent circular references.+ // Node ids combine path with step, so a repeated path across steps+ // doesn't collapse into one node.const nodes = new Map<string,{ path: string; value: number; step: number; color: string }@@ -971,7 +960,6 @@ export async function getUserJourney(}}- // Filter links by threshold (0.25% of total sessions)const MIN_LINK_PERCENT = 0.25;const minLinkValue = Math.ceil((totalSessions * MIN_LINK_PERCENT) / 100);const filteredLinks = links.filter((link) => link.value >= minLinkValue);@@ -988,7 +976,6 @@ export async function getUserJourney(nodeValuesFromLinks.set(link.target, current + link.value);});- // For entry nodes (step 1), only keep them if they have outgoing links after filteringnodes.forEach((nodeData, nodeId) => {if (nodeData.step === 1) {const hasOutgoing = filteredLinks.some((l) => l.source === nodeId);@@ -1155,7 +1142,7 @@ export async function getMapData(timezone);- // Placeholder lat/lng — geocoding is unresolved, same as V1.+ // Placeholder lat/lng — geocoding is not implemented yet.return results.map((row) => ({country: row.country,region: row.region ?? undefined,@@ -1166,7 +1153,7 @@ export async function getMapData(}));}-/** The dashboard's live/30-minute-window widget — moved from packages/trpc's overview router (M7-005). */+/** The dashboard's live/30-minute-window widget. */export async function getLiveData(deps: ServiceDeps,projectId: stringdiff --git a/packages/core/src/modules/overview/src/overview-raw-where.sql.test.ts b/packages/core/src/modules/overview/src/overview-raw-where.sql.test.tsindex e2efdcf99..7cb2ef095 100644--- a/packages/core/src/modules/overview/src/overview-raw-where.sql.test.ts+++ b/packages/core/src/modules/overview/src/overview-raw-where.sql.test.ts@@ -1,11 +1,11 @@/*** SQL-syntax tests for the overview module's `getRawWhereClause` (the UTM- * remapping). Same pattern as the chart cases moving to chart.sql.test.ts with- * theirs. M12-002 put `getRawWhereClause` on the `sql` tag, so these assertions- * read the rendered statement AND its bound params instead of one escaped- * string; the rest of the overview module's queries already run through- * overview.sql.ts, covered by overview.sql.test.ts. M10-005 turned it from a- * class method into a module function — it never needed a client, being pure+ * remapping). Same pattern as the chart module's SQL-syntax tests.+ * `getRawWhereClause` sits on the `sql` tag, so these assertions read the+ * rendered statement AND its bound params instead of one escaped string; the+ * rest of the overview module's queries already run through+ * overview.sql.ts, covered by overview.sql.test.ts. It is a plain module+ * function, not a class method — it never needed a client, being pure* fragment building.** Strategy: build the SQL string, then run `EXPLAIN <sql>` against the localdiff --git a/packages/core/src/modules/overview/src/overview.sql.ts b/packages/core/src/modules/overview/src/overview.sql.tsindex 0d2ead4ab..0a7c415bc 100644--- a/packages/core/src/modules/overview/src/overview.sql.ts+++ b/packages/core/src/modules/overview/src/overview.sql.ts@@ -5,12 +5,10 @@// `INTERVAL <n> <unit>` step keyword in a WITH FILL clause, which is SQL// syntax, not a value.//-// `toStartOf`/`toInterval`/`datetime` reproduce V1's `clix` static helpers-// verbatim (query-builder.ts) rather than chart.sql.ts's own `intervalBucket`:-// notably V1's overview never passed a timezone into `toStartOfWeek`/-// `toStartOfMonth` — ClickHouse resolves those from the query's-// `session_timezone` setting instead, which every statement here still sets-// (see src/run-query.ts).+// `toStartOf`/`toInterval`/`datetime` deliberately never pass a timezone+// into `toStartOfWeek`/`toStartOfMonth` — ClickHouse resolves those from the+// query's `session_timezone` setting instead, which every statement here+// still sets (see src/run-query.ts).import { type SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';import {@@ -25,7 +23,7 @@ const ROLLUP_DATE_PREFIX = '1970-01-01';export type OverviewTable = 'events' | 'sessions';-/** V1 `clix.toStartOf` — deliberately timezone-blind for week/month (see header). */+/** Deliberately timezone-blind for week/month (see header). */export function toStartOf(node: string, interval: IInterval): SqlFragment {switch (interval) {case 'minute':@@ -43,7 +41,6 @@ export function toStartOf(node: string, interval: IInterval): SqlFragment {}}-/** V1 `clix.toInterval`. */function toIntervalStep(interval: IInterval): string {switch (interval) {case 'minute':@@ -62,12 +59,11 @@ function toIntervalStep(interval: IInterval): string {}/**- * `getFillConfig`: `WITH FILL` needs FROM/TO to actually evaluate to a- * Date/DateTime constant, not a bare string — V1 got this from `clix`'s- * `toStartOf`/`datetime` helpers, which return SQL *expressions*- * (`toStartOfMonth(toDateTime(toDate('...')))`), never a plain literal.- * `sql.date`/`sql.dateTime64` bind the boundary itself; the wrapping- * functions around them reproduce that expression shape.+ * `WITH FILL` needs FROM/TO to actually evaluate to a Date/DateTime+ * constant, not a bare string. `sql.date`/`sql.dateTime64` bind the boundary+ * itself; the wrapping functions around them produce the SQL *expression*+ * shape ClickHouse needs (`toStartOfMonth(toDateTime(toDate('...')))`),+ * never a plain literal.*/function fillBoundaryParam(interval: IInterval,@@ -82,7 +78,7 @@ function fillBoundaryParam(: sql.param('DateTime', toRangeBoundaryLiteral(value, boundary));}-/** V1 always bucket-aligns FROM (via `toStartOf`) but leaves TO as-is. */+/** Always bucket-aligns FROM (via `toStartOf`) but leaves TO as-is. */function fillFrom(interval: IInterval, startDate: string): SqlFragment {const boundary = fillBoundaryParam(interval, startDate, 'start');switch (interval) {@@ -256,8 +252,8 @@ export function metricsWithPageFilterQuery(// `max(if(<rollup row>, x, NULL)) OVER ()` broadcasts the totals row's value// onto every daily row, and stays NULL when the aggregate produced no rollup- // row at all — which is the nullability the old scalar subqueries had, and- // which `getMetricsWithPageFilter` reads to tell "no data" from "zero".+ // row at all — that nullability is what `getMetricsWithPageFilter` reads+ // to tell "no data" from "zero".const overallOf = (column: string): SqlFragment =>sql`max(if(date = ${rollupDate}, ${sql.id(column)}, NULL)) OVER ()`;@@ -377,13 +373,12 @@ export function distinctSessionsQuery(}/**- * `withDistinctSessionsIfNeeded`: when the caller filtered by `path`, a- * `sessions`-scoped query is redirected through the set of session ids that- * actually match the page filter on `events`, instead of applying the- * filters directly to `sessions` (which has no `path` column of its own).- * Threaded as a WHERE clause, not appended after the finished query text —- * V1's `.merge()` is equivalent to inserting one more AND'd condition, and- * doing that after `LIMIT` is invalid SQL.+ * When the caller filtered by `path`, a `sessions`-scoped query is+ * redirected through the set of session ids that actually match the page+ * filter on `events`, instead of applying the filters directly to+ * `sessions` (which has no `path` column of its own). Threaded as a WHERE+ * clause, not appended after the finished query text — appending after+ * `LIMIT` would be invalid SQL.*/function distinctSessionsCteHeader(cte: SqlFragment | null): SqlFragment {return cte ? sql`WITH distinct_sessions AS (${cte})` : sql.empty;@@ -401,7 +396,7 @@ export interface TopEntryExitQueryInput {endDate: string;mode: 'entry' | 'exit';limit: number;- /** Mutually exclusive with `distinctSessionsCte`, exactly as V1's `withDistinctSessionsIfNeeded`. */+ /** Mutually exclusive with `distinctSessionsCte`. */rawFilterWhere: SqlFragment | null;distinctSessionsCte: SqlFragment | null;}@@ -437,7 +432,7 @@ export function topEntryExitQuery(input: TopEntryExitQueryInput): SqlFragment {// --- top generic (breakdown by a single dimension) ------------------------------/** `column`/`prefixColumn` are drawn from a closed zod enum upstream — bound- * as identifiers here rather than trusted as pre-validated text (R3). */+ * as identifiers here rather than trusted as pre-validated text. */const TOP_GENERIC_COLUMNS = ['referrer','referrer_name',@@ -467,7 +462,7 @@ export interface TopGenericQueryInput {column: string;prefixColumn: string | null;limit: number;- /** Mutually exclusive with `distinctSessionsCte`, exactly as V1's `withDistinctSessionsIfNeeded`. */+ /** Mutually exclusive with `distinctSessionsCte`. */rawFilterWhere: SqlFragment | null;distinctSessionsCte: SqlFragment | null;}@@ -534,7 +529,7 @@ export interface TopGenericSeriesTimeSeriesInput {interval: IInterval;column: string;prefixColumn: string | null;- /** Always applied — unlike the top-items query, V1 applies this unconditionally. */+ /** Always applied, unlike the top-items query which applies it conditionally. */rawFilterWhere: SqlFragment | null;/** Additionally applied on top of `rawFilterWhere` when the caller has a page filter. */distinctSessionsCte: SqlFragment | null;@@ -585,10 +580,10 @@ function orderedEventsQuery(input: OrderedEventsQueryInput): SqlFragment {}/**- * `arrayCompact` drops consecutive repeats in linear time. V1's `arrayFilter`- * spelling was Theta(n^2) in the longest session's pageview count and could not- * answer for a tenant with one very long session — the same defect, and the same- * fix, as sankey.sql.ts's DEDUPE_CONSECUTIVE.+ * `arrayCompact` drops consecutive repeats in linear time. An `arrayFilter`+ * spelling is Theta(n^2) in the longest session's pageview count and could not+ * answer for a tenant with one very long session — the same defect, and the+ * same fix, as sankey.sql.ts's DEDUPE_CONSECUTIVE.*/function pathsDedupedCte(input: OrderedEventsQueryInput,diff --git a/packages/core/src/modules/overview/src/pages.sql.ts b/packages/core/src/modules/overview/src/pages.sql.tsindex 05488da2f..e54d9c709 100644--- a/packages/core/src/modules/overview/src/pages.sql.ts+++ b/packages/core/src/modules/overview/src/pages.sql.ts@@ -31,10 +31,10 @@ function searchClause(search: string | undefined): SqlFragment {}export function topPagesQuery(input: TopPagesQueryInput): SqlFragment {- // Titles come from the requested range, not V1's `now - 30 DAY`, which read a- // month of the widest Map column for any window and made the answer depend on- // the wall clock. A page titled only outside the range now resolves to ''- // (approved, Group C fix 8).+ // Titles come from the requested range so the answer does not depend on the+ // wall clock — reading a fixed lookback window off the widest Map column+ // made the result vary by when the query ran. A page titled only outside+ // the range resolves to ''.const titlesCte = sql`SELECT concat(origin, path) as page_key, anyLast(properties['__title']) as titleFROM eventsdiff --git a/packages/core/src/modules/profile/profile.routes.test.ts b/packages/core/src/modules/profile/profile.routes.test.tsindex 0dd8e279e..ba83f0966 100644--- a/packages/core/src/modules/profile/profile.routes.test.ts+++ b/packages/core/src/modules/profile/profile.routes.test.ts@@ -1,10 +1,8 @@-// The three /profile routes end to end through `app.handle()`: status codes-// and text bodies match V1's controller byte for byte, and each handler hands-// the service exactly what the controller did. `../../http/client-auth`'s-// `authenticateClient` is mocked so the client principal is deterministic,-// same as http/auth.test.ts does; the service and the geo lookup are mocked-// so nothing reaches a database. Every mock is registered before the-// subject's first (dynamic) import — AGENTS.md.+// The three /profile routes run end to end through `app.handle()`.+// `../../http/client-auth`'s `authenticateClient` is mocked so the client+// principal is deterministic, same as http/auth.test.ts does; the service+// and the geo lookup are mocked so nothing reaches a database. Every mock is+// registered before the subject's first (dynamic) import — AGENTS.md.import { beforeAll, beforeEach, expect, mock, test } from 'bun:test';import { stubAppDeps } from '../../../test/http-fixtures';diff --git a/packages/core/src/modules/profile/profile.routes.ts b/packages/core/src/modules/profile/profile.routes.tsindex 674d9ea60..fcdcb2af7 100644--- a/packages/core/src/modules/profile/profile.routes.ts+++ b/packages/core/src/modules/profile/profile.routes.ts@@ -1,18 +1,10 @@-// Ported from apps/api/src/routes/profile.router.ts +-// apps/api/src/controllers/profile.controller.ts. V1's Fastify controller stays-// the LIVE route (DELEGATE PATTERN) and delegates its bodies to-// profile.service.ts's `identifyProfile` / `adjustProfileProperty` — the same-// functions these routes call. Status codes and text bodies (`202` + profile-// id, `400 'No projectId'`, `404 'Not found'`, `400 'Not number'`) match V1's-// `reply.status(..).send(..)` byte for byte.+// `clientAuth: { ingest: ... }` enforces the SDK credential rules. Bot+// filtering and subscription-limit checks for this router live in the+// ingest module, not this one.//-// `ingest` is V1's `clientHook` (the SDK credential rules); V1's `isBotHook`-// and `subscriptionHook` on this router live in the ingest module, not this-// one.-//-// V1 has no request-body schema for these routes (ADR-003: "/profile, /import,-// /event and /tools have no request schemas today, and adding them would be a-// behaviour change"), so the bodies are typed but not shape-validated.+// /profile has no request-body schema, so `payload` below is typed but not+// shape-validated at the boundary — unlike /profile/increment and+// /profile/decrement, which validate via `zAdjustProperty`.import { parseUserAgent } from '@openpanel/shared/server';import { z } from 'zod';diff --git a/packages/core/src/modules/profile/profile.rpc.ts b/packages/core/src/modules/profile/profile.rpc.tsindex 14554ab55..d13f898b6 100644--- a/packages/core/src/modules/profile/profile.rpc.ts+++ b/packages/core/src/modules/profile/profile.rpc.ts@@ -25,11 +25,10 @@ const DEFAULT_LIST_TAKE = 50;/*** `list` and `powerUsers` had no date filter at all, so their cost grew with- * the tenant's lifetime rather than with anything the caller chose- * (44.2 M rows read for one page of 50, measured).- * Both now take the report vocabulary's window; this is the default when the- * caller names none, and it is the range §6.8 itself uses to describe the- * change ("a power user over 90 days is not the same set as over all time").+ * the tenant's lifetime rather than with anything the caller chose (44.2 M+ * rows read for one page of 50, measured). Both now take the report+ * vocabulary's window; this is the default when the caller names none — "a+ * power user over 90 days is not the same set as over all time".*/const PROFILE_WINDOW_DEFAULT_RANGE = '3m';diff --git a/packages/core/src/modules/profile/profile.service.ts b/packages/core/src/modules/profile/profile.service.tsindex a34642ed6..a5b8409c2 100644--- a/packages/core/src/modules/profile/profile.service.ts+++ b/packages/core/src/modules/profile/profile.service.ts@@ -41,8 +41,7 @@ export { profileSearchCondition } from './src/sql';const PROFILES_CACHE_SECONDS = 60 * 5;const PROPERTY_KEYS_CACHE_SECONDS = 60;-// V1's `cacheable(fn, ...)` derived these from the functions' own names;-// naming them keeps the Redis keys `cachable:getProfiles:<args>` and+// These names fix the Redis cache keys as `cachable:getProfiles:<args>` and// `cachable:getProfilePropertyKeys:<projectId>`.const PROFILES_CACHE_NAME = 'getProfiles';const PROPERTY_KEYS_CACHE_NAME = 'getProfilePropertyKeys';diff --git a/packages/core/src/modules/profile/src/sql.ts b/packages/core/src/modules/profile/src/sql.tsindex eaa200970..fadb92095 100644--- a/packages/core/src/modules/profile/src/sql.ts+++ b/packages/core/src/modules/profile/src/sql.ts@@ -171,11 +171,11 @@ export interface ProfileListQuery extends ProfileWindow {}/**- * V1's `WHERE project_id =.. [AND search] [AND is_external =..] [AND filters]`,- * plus the M31-003 window: V1 read every profile the project ever had, so the- * cost grew with the tenant's lifetime rather than with anything the caller- * asked for. `created_at` is the column the list already orders by, so the- * bound and the order agree.+ * `WHERE project_id =.. [AND search] [AND is_external =..] [AND filters]`,+ * bounded to a window rather than reading every profile the project ever+ * had — otherwise the cost grows with the tenant's lifetime rather than with+ * anything the caller asked for. `created_at` is the column the list already+ * orders by, so the bound and the order agree.*/function profileListCondition(query: ProfileListQuery): SqlFragment {const search = profileSearchCondition(query.search);@@ -205,8 +205,7 @@ export function profileListQuery(// `uniqExact`, not `count`: the page reads `profiles FINAL` so it sees one row// per id, while the count deliberately skips FINAL (it is the expensive half// on a large tenant). Counting rows therefore counted every unmerged-// ReplacingMergeTree version and the total ran ahead of the list-// (main 1f21214a).+// ReplacingMergeTree version and the total ran ahead of the list.export function profileListCountQuery(query: ProfileListQuery): SqlFragment {return sql`SELECT uniqExact(id) as count@@ -403,8 +402,8 @@ export const PROFILE_VALUE_COLUMNS = [const PROPERTIES_PREFIX = /^properties\./;/**- * V1 interpolated `property` raw into the SELECT; a bare column now has to be- * one of `PROFILE_VALUE_COLUMNS` (`sql.id` throws otherwise).+ * A bare column has to be one of `PROFILE_VALUE_COLUMNS` (`sql.id` throws+ * otherwise).*/export function profileValuesQuery(query: {projectId: string;diff --git a/packages/core/src/modules/project/project.service.test.ts b/packages/core/src/modules/project/project.service.test.tsindex 2d539ea66..c24c12597 100644--- a/packages/core/src/modules/project/project.service.test.ts+++ b/packages/core/src/modules/project/project.service.test.ts@@ -1,9 +1,8 @@// The subject is built by its factory over a fake `ServiceDeps`, so Postgres// needs no module mock at all — `deps.db` IS the fake below, same idiom as// reference.service.test.ts. `getProjectEventsCount` / `getLastEventPerProject`-// (ClickHouse) stay a verbatim, still-lazy-loaded port with unchanged SQL-// (ADR-013 converts them in P7) — executed against local ClickHouse for this-// task's verification, not re-tested here.+// (ClickHouse) stay a lazy-loaded, unmocked call — exercised against local+// ClickHouse manually, not re-tested here.//// `createProjectForOrganization`/`updateProjectForOrganization` invalidate a// project's clients through `client.service.ts`'s module-scope@@ -165,8 +164,8 @@ function cacheableStub(}// Each factory spreads a plain-object SNAPSHOT of the real module and is// restored in afterAll. `mock.module` has no per-file scope under bare `bun-// test` (AGENTS.md), and a partial factory for `@openpanel/redis` deletes every-// export it does not name for whichever file runs next.+// test`, and a partial factory for `@openpanel/redis` deletes every export it+// does not name for whichever file runs next.const realRedis = { ...(await import('@openpanel/redis')) };mock.module('@openpanel/redis', () => ({...realRedis,diff --git a/packages/core/src/modules/project/project.service.ts b/packages/core/src/modules/project/project.service.tsindex bbb086ca3..4d8cd4d13 100644--- a/packages/core/src/modules/project/project.service.ts+++ b/packages/core/src/modules/project/project.service.ts@@ -25,15 +25,13 @@ import { getClientByIdCached } from '../client/client.service';// `TABLE_NAMES` and the date helper are core's own copies// (shared/ch-tables.ts, shared/ch-dates.ts).//-// clix sent `clickhouse_settings.session_timezone = 'UTC'` on every-// `execute()` — `clix(client)` with no timezone argument defaults to it-// (query-builder.ts:696-697, :562). `getLastEventPerProject` came off clix and-// keeps sending it so its result set stays identical; `getProjectEventsCount`-// was already a raw `chQuery` call, sent none, and still sends none.+// `getLastEventPerProject` explicitly sends session_timezone=UTC so its+// result set stays consistent; `getProjectEventsCount` is a raw `chQuery`+// call and sends none.const CLIX_SESSION_TIMEZONE = { session_timezone: 'UTC' } as const;// Session bookkeeping rows are worker-generated (the reaper can emit// session_end after tracking already stopped) — only real tracking activity-// counts. V1 wrote this list inline in both statements.+// counts.const NON_TRACKING_EVENT_NAMES = ['session_start', 'session_end'];export type IServiceProject = Project;export type IServiceProjectWithClients = Prisma.ProjectGetPayload<{@@ -60,9 +58,8 @@ export async function getProjectById(deps: DbScope, id: string) {/*** L1 LRU (60s) + L2 Redis, one instance per Postgres client — the ingest- * consumer, `/track` and mcp all read and invalidate the same one. The name is- * EMPTY for the same reason `getClientByIdCached`'s is: the in-factory- * `cacheable(...)` this replaces took an anonymous arrow, so the Redis key is+ * consumer, `/track` and mcp all read and invalidate the same one. The name+ * is EMPTY, same as `getClientByIdCached`'s, so the Redis key is* `cachable::<id>`.*/export const getProjectByIdCached = cacheablePerDb(@@ -287,7 +284,7 @@ export async function getProjectActivationStatus(};}-// --- /manage REST CRUD (apps/api/src/controllers/manage.controller.ts) ---+// --- /manage REST CRUD (project.routes.ts) ---export interface CreatedProjectClient {id: string;@@ -322,9 +319,7 @@ export async function getProjectForOrganization(});}-// Grace period between a scheduled deletion and the `delete` cron sweeping it-// up — matches V1's `addHours(new Date(), 24)` (trpc) and the manage-// controller's `Date.now() + 24 * 60 * 60 * 1000` (REST), same duration.+// Grace period between a scheduled deletion and the `delete` cron sweeping it up.const DELETE_GRACE_PERIOD_MS = 24 * 60 * 60 * 1000;export function createProjectService(diff --git a/packages/core/src/modules/realtime/realtime.routes.test.ts b/packages/core/src/modules/realtime/realtime.routes.test.tsindex 0ecca1a36..dc623220f 100644--- a/packages/core/src/modules/realtime/realtime.routes.test.ts+++ b/packages/core/src/modules/realtime/realtime.routes.test.ts@@ -1,9 +1,8 @@-// The runnable ws proof this task's notes require: `app.handle` cannot exercise-// a websocket upgrade (no real HTTP connection to upgrade), so this boots the-// actual Elysia app with `.listen` (== `Bun.serve` under the hood, same as-// main.ts) on an ephemeral port and drives it with a real `WebSocket` client —-// the same shape `apps/api/e2e/boot-proof.sh` uses for the plain-HTTP ops-// surface, extended to a ws handshake.+// `app.handle` cannot exercise a websocket upgrade (no real HTTP connection to+// upgrade), so this boots the actual Elysia app with `.listen` (== `Bun.serve`+// under the hood, same as main.ts) on an ephemeral port and drives it with a+// real `WebSocket` client — the same shape `apps/api/e2e/boot-proof.sh` uses+// for the plain-HTTP ops surface, extended to a ws handshake.//// The harness buffers messages/close events from the moment the socket is// constructed: the server can send its "No active session" / "No access" frame@@ -12,16 +11,15 @@//// `./realtime.service` and `../../shared/access-lookups` (the real lookups// auth.service.ts's `createAuthService` binds `ctx.services.auth` to) 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.+// mocked (not a real Postgres/ClickHouse/Redis), and `../../http/session` is+// mocked for the same reason http/auth.test.ts mocks it: `resolveSession` is+// still a stub.//// 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.+// holding.import { afterAll, afterEach, beforeEach, expect, mock, test } from 'bun:test';import { getSuperJson } from '@openpanel/shared';@@ -79,8 +77,8 @@ afterAll(() => {mock.module('./realtime.service', () => realService);});-// The real module, not `./src/access` (deleted) — `ctx.services.auth` binds-// these same lookups in auth.service.ts, so mocking them here is what makes+// `ctx.services.auth` 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.let projectAccess: { level: string } | null = null;@@ -309,10 +307,10 @@ test('wsOrganizationEvents: session but no org access -> "No access" then close'});});-// / F2: `organization:subscription_updated` is an instance-wide channel. Before-// the fix the open handler subscribed to it unscoped, so a member of org_1 was-// sent the `organizationId` of every OTHER organization whose subscription-// changed. The scope handed to the subscription must be the id+// `organization:subscription_updated` is an instance-wide channel. Before+// this fix the open handler subscribed to it unscoped, so a member of org_1+// was sent the `organizationId` of every OTHER organization whose+// subscription changed. The scope handed to the subscription must be the id// `getOrganizationAccess` just proved this caller is a member of — the filter// itself is asserted in realtime.service.test.ts.test('wsOrganizationEvents: subscribes scoped to the organization the caller is a member of', async () => {diff --git a/packages/core/src/modules/realtime/realtime.routes.ts b/packages/core/src/modules/realtime/realtime.routes.tsindex 315f63b58..278291cfd 100644--- a/packages/core/src/modules/realtime/realtime.routes.ts+++ b/packages/core/src/modules/realtime/realtime.routes.ts@@ -1,28 +1,10 @@-// The `/live` websocket surface, Elysia/Bun-native. Ported FRESH from-// apps/api/src/controllers/live.controller.ts's business logic, NOT delegated:-// V1's Fastify controller uses `@fastify/websocket`'s `WebSocket` (the `ws`-// package, Node EventEmitter semantics), which shares nothing with Elysia's-// `ElysiaWS`/Bun's native `ServerWebSocket` — there is no shim to delegate-// through, and touching the golden-harness-critical V1 ws stack for a few lines-// of framework glue is the risk this port avoids (task notes). V1's controller-// and router are LEFT UNTOUCHED. The shared logic — `getActiveVisitorCount`,-// the four `subscribeToPublishedEvent` calls — moved to realtime.service.ts's-// "/live websocket glue" section; both stacks call the exact same Redis-// subscription underneath.-//-// Http/auth.ts's invariant 10 (binding): `/live/visitors/:projectId` stays-// unauthenticated; the other three keep session + access; all four keep-// REJECT-AFTER-UPGRADE — the socket accepts the upgrade, then the open handler-// sends a text frame and closes it, exactly like V1. This is why none of these-// routes requests the `session` macro: that macro would 401 the HTTP upgrade-// request itself, which is a different (V1-divergent) behaviour.-//-// NAMED GAP, same as every other H module this wave: not yet reachable. main.ts-// does not mount `dashboardRoutes` until a real `AppDeps` exists (P3/P4/P8),-// and `http/session.ts`'s `resolveSession` is still a P6 stub that always-// resolves `null` — so today, the three session-gated routes close every-// connection immediately after upgrade. That is the same gap http/auth.test.ts-// already documents for every other session-macro route.+// The `/live` websocket surface. `/live/visitors/:projectId` stays+// unauthenticated by intent; the other three require a session plus+// project/org access. All four use REJECT-AFTER-UPGRADE: the socket accepts+// the upgrade, then the open handler sends a text frame and closes it. None+// of these routes uses the `session` macro, because that macro would 401 the+// HTTP upgrade request itself instead of letting the socket reject after+// connecting.import { setSuperJson } from '@openpanel/shared';import { z } from 'zod';@@ -73,7 +55,6 @@ function rejectNoAccess(ws: ClosableSocket) {export const realtimeRoutes = defineRoutes((app) =>app- // V1: wsVisitors. Unauthenticated by intent (ADR-011 invariant 10)..ws('/live/visitors/:projectId', {params: projectParams,async open(ws) {@@ -93,7 +74,6 @@ export const realtimeRoutes = defineRoutes((app) =>forgetUnsubscribe(ws);},})- // V1: wsProjectEvents..ws('/live/events/:projectId', {params: projectParams,async open(ws) {@@ -124,7 +104,6 @@ export const realtimeRoutes = defineRoutes((app) =>forgetUnsubscribe(ws);},})- // V1: wsProjectNotifications..ws('/live/notifications/:projectId', {params: projectParams,async open(ws) {@@ -155,7 +134,6 @@ export const realtimeRoutes = defineRoutes((app) =>forgetUnsubscribe(ws);},})- // V1: wsOrganizationEvents..ws('/live/organization/:organizationId', {params: organizationParams,async open(ws) {diff --git a/packages/core/src/modules/realtime/realtime.service.test.ts b/packages/core/src/modules/realtime/realtime.service.test.tsindex 36dbec459..793803a34 100644--- a/packages/core/src/modules/realtime/realtime.service.test.ts+++ b/packages/core/src/modules/realtime/realtime.service.test.ts@@ -1,26 +1,16 @@-// Realtime.service.ts takes `ServiceDeps` now, so the event buffer and the-// ClickHouse client are HANDED IN (`deps.buffers.event`, `deps.ch`) rather than-// mocked onto a module specifier.+// The event buffer and the ClickHouse client are HANDED IN+// (`deps.buffers.event`, `deps.ch`) rather than mocked onto a module+// specifier.//-// The subject and the real-module snapshot are STATIC imports.-// `@openpanel/redis` is a static import in the subject too (the R6 fix removed-// the `loadRedis` lazy hop) — Bun's `mock.module` still applies because it-// swaps an already-loaded module's exports in place, so a consumer that-// imported before the mock call still sees it — 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.+// The subject and the real-module snapshot are STATIC imports. Bun's+// `mock.module` still applies because it swaps an already-loaded module's+// exports in place, so a consumer that imported before the mock call still+// sees it — the subscribe assertions go red if it ever stops.//-// 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.-//-// Scope: the "/live websocket glue" (new logic this wave adds) plus one-// representative ClickHouse query (`getRealtimeActiveSessions`) proving the-// deps + filter/limit wiring. The other five queries are a verbatim port of-// packages/trpc/src/routers/realtime.ts's SQL — mechanical, not new behaviour —-// and are exercised end-to-end by realtime.rpc.test.ts's-// unauthenticated-boundary tests plus this repo's local ClickHouse run (see the-// task summary for the executed query + row count).+// Scope: the /live websocket glue plus one representative ClickHouse query+// (`getRealtimeActiveSessions`) proving the deps + filter/limit wiring. The+// other five queries are exercised end-to-end by realtime.rpc.test.ts's+// unauthenticated-boundary tests and this repo's local ClickHouse run.import { afterAll, beforeEach, expect, mock, test } from 'bun:test';import * as actualRedis from '@openpanel/redis';@@ -155,7 +145,7 @@ test('subscribeToProjectNotifications subscribes on notification:created and filexpect(onNotification).toHaveBeenCalledTimes(1);});-// / F2: the `organization:subscription_updated` channel is instance-wide.+// The `organization:subscription_updated` channel is instance-wide.// Unfiltered, a subscriber saw the `organizationId` of every organization whose// subscription changed — including ones it is not a member of. This test is red// without the filter.diff --git a/packages/core/src/modules/realtime/realtime.service.ts b/packages/core/src/modules/realtime/realtime.service.tsindex 3d6c5a65b..eba46f476 100644--- a/packages/core/src/modules/realtime/realtime.service.ts+++ b/packages/core/src/modules/realtime/realtime.service.ts@@ -42,11 +42,10 @@ const EXCLUDED_BADGE_EVENT_NAMES = ['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.+// defaults to `'UTC'`, 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 {@@ -134,10 +133,8 @@ function adaptiveCluster(// --- 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()`.+// These are `SqlFragment`s, 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@@ -177,8 +174,8 @@ function buildRealtimeCountryFilter(return sql`coalesce(country, '') IN ${sql.array('String', countries)}`;}-/** V1 de-duplicated the rendered `('<country>', '<city>')` text; the pair it- * rendered from is the same key, so this de-duplicates on the pair. */+/** De-duplicates on the (country, city) pair rather than on the rendered+ * `('<country>', '<city>')` text, since the pair is the real key. */function cityTuples(locations: RealtimeLocation[]): SqlFragment[] {const seen = new Set<string>();const tuples: SqlFragment[] = [];@@ -452,7 +449,7 @@ export function getActiveVisitorCount(return deps.buffers.event.getActiveVisitorCount(projectId);}-/** V1: `wsVisitors` — re-count on every batch touching this project. */+/** Re-counts on every batch touching this project. */export async function subscribeToVisitorActivity(projectId: string,onActivity: () => void@@ -464,7 +461,7 @@ export async function subscribeToVisitorActivity(});}-/** V1: `wsProjectEvents` — the batch's own count, not a re-query. */+/** The batch's own count, not a re-query. */export async function subscribeToProjectEventBatches(projectId: string,onBatch: (event: IPublishChannels['events']['batch']) => void@@ -476,7 +473,6 @@ export async function subscribeToProjectEventBatches(});}-/** V1: `wsProjectNotifications`. */export async function subscribeToProjectNotifications(projectId: string,onNotification: (@@ -495,14 +491,13 @@ export async function subscribeToProjectNotifications(}/**- * V1: `wsOrganizationEvents`. Scoped to the single organization the caller's- * membership was verified against, exactly as the three siblings above scope to- * a verified `projectId`.+ * Scoped to the single organization the caller's membership was verified+ * against, exactly as the three siblings above scope to a verified+ * `projectId`.** The channel is instance-wide: without this filter every subscriber saw the- * `organizationId` of every organization whose subscription changed, which is a- * cross-tenant identifier leak (F2). V1 had no filter either — this is a- * deliberate divergence, approved 2026-09-15.+ * `organizationId` of every organization whose subscription changed, which is+ * a cross-tenant identifier leak.*/export async function subscribeToOrganizationSubscriptionUpdates(organizationId: string,diff --git a/packages/core/src/modules/report/report.constants.ts b/packages/core/src/modules/report/report.constants.tsindex 4ad9b154f..6e8a95b79 100644--- a/packages/core/src/modules/report/report.constants.ts+++ b/packages/core/src/modules/report/report.constants.ts@@ -1,12 +1,10 @@-// `getDefaultIntervalByDates` is REWRITTEN from date-fns-// (differenceInDays/isSameDay) to plain Date math per the module map. Every-// process that constructs these Dates runs under TZ=UTC (ADR-012: "this ADR-// makes that line load-bearing rather than incidental"), so Date's local+// `getDefaultIntervalByDates` uses plain Date math instead of date-fns. Every+// process that constructs these Dates runs under TZ=UTC, so Date's local// getters (getFullYear/getMonth/getDate) already read UTC — the helpers below-// reproduce date-fns's local-calendar semantics exactly under that invariant,-// and the only inputs this function ever receives are date-only strings-// (midnight boundaries), where date-fns's exact-duration-vs-calendar-day nuance-// cannot diverge from a plain ms division anyway.+// reproduce date-fns's local-calendar semantics under that invariant. The+// only inputs this function ever receives are date-only strings (midnight+// boundaries), where date-fns's exact-duration-vs-calendar-day nuance cannot+// diverge from a plain ms division anyway.import { z } from 'zod';@@ -133,9 +131,9 @@ export const operatorsShort: Record<keyof typeof operators, string> = {// Cast type a filter value/column should be coerced to before comparing.// `string` (the default) keeps raw text comparison; the others wrap both sides-// of the comparison in the matching ClickHouse cast (see packages/db-// filter-cast.ts) so e.g. a date property compares as a date instead of-// crashing `toFloat64('2019-01-01')`.+// of the comparison in the matching ClickHouse cast (see chart/src/filter-cast.ts)+// so e.g. a date property compares as a date instead of crashing+// `toFloat64('2019-01-01')`.export const filterValueTypes = {string: 'Text',number: 'Number',@@ -638,11 +636,10 @@ export const chartColors = [*/const CHART_FORMULA_PATTERN = /^[A-Za-z0-9_ .,+\-*/()%^]*$/;-// Helper, not vocabulary — ADR-008 rules this the one genuine exception to the-// module-export rule: every consumer copies these 4 lines locally instead of-// importing them (apps/start/src/utils/object-to-zod-enums.ts is the frontend's-// copy). Kept private here for report.constants.ts's own use building the enums-// below.+// Helper, not vocabulary: every consumer copies these 4 lines locally instead+// of importing them (apps/start/src/utils/object-to-zod-enums.ts is the+// frontend's copy). Kept private here, for this file's own use building the+// enums below.function objectToZodEnums<K extends string>(obj: Record<K, unknown>): [K, ...K[]] {@@ -757,7 +754,6 @@ export const zChartFormula = z.object({),});-// Event with type field for discriminated unionexport const zChartEventWithType = zChartEvent.extend({type: z.literal('event'),});@@ -792,7 +788,6 @@ export const zRange = z.enum(objectToZodEnums(timeWindows));export const zCriteria = z.enum(['on_or_after', 'on']);-// Report Options - Discriminated union based on chart typeexport const zFunnelOptions = z.object({type: z.literal('funnel'),funnelGroup: z.string().optional(),@@ -945,28 +940,18 @@ export const zReport = zReportInput.extend({export const zChartInput = zReportInput;// ---------------------------------------------------------------------------// Inferred report/chart types, moved from-// packages/validation/src/types.validation.ts (ADR-008's module map: report-// owns "C" for the chart/report/widget vocabulary). They land beside the-// schemas they infer from, which is what removes that file's `import type { … }-// from './index'` back-edge. `IChartEvents` and `ISetCookie` do NOT come along:-// the first is a dead alias with no importers, the second is-// already../../shared/cookie.ts. `UnionOmit` has no owning module — it is kept-// here, with the report types it is only ever applied to (apps/start's-// reportSlice), until M11-007 gives apps/start its own copy.+// `UnionOmit` has no owning module; it is kept here, with the report types it+// is only ever applied to (apps/start's reportSlice).// ---------------------------------------------------------------------------export type UnionOmit<T, K extends keyof any> = T extends any? Omit<T, K>: never;-// For saved reports - complete report with required display fieldsexport type IReport = z.infer<typeof zReport>;-// For API/engine use - flexible inputexport type IReportInput = z.infer<typeof zReportInput>;-// With resolved dates (engine internal)export interface IReportInputWithDates extends IReportInput {startDate: string;endDate: string;diff --git a/packages/core/src/modules/report/report.service.ts b/packages/core/src/modules/report/report.service.tsindex 07967dfe1..d736a2d40 100644--- a/packages/core/src/modules/report/report.service.ts+++ b/packages/core/src/modules/report/report.service.ts@@ -1,7 +1,6 @@-// Every function takes `ServiceDeps` and reaches Postgres as `deps.db`;-// `loadDb` and the `@openpanel/core` self-barrel import are gone — the Prisma-// row types below are `import type`, erased at runtime.-// `onlyReportEvents`/`mergeGlobalFilters` moved to./src/series.ts — see that+// Every function takes `ServiceDeps` and reaches Postgres as `deps.db`; the+// Prisma row types below are `import type`, erased at runtime.+// `onlyReportEvents`/`mergeGlobalFilters` live in ./src/series.ts — see that// file for why.import type {@@ -142,8 +141,7 @@ export async function getReportById(deps: ServiceDeps, id: string) {}/** Unscoped lookup for mutation handlers that only receive a report id and- * need its `projectId`/`dashboardId` to run the access check — same shape as- * V1's inline `db.report.findUniqueOrThrow`. */+ * need its `projectId`/`dashboardId` to run the access check. */export async function getReportByIdOrThrow(deps: ServiceDeps, id: string) {return deps.db.report.findUniqueOrThrow({ where: { id } });}@@ -234,10 +232,9 @@ export async function getReportDataCore(}// ------------------------------------------------------------------------// Mutations — moved from packages/trpc/src/routers/report.ts's handler-// bodies. Each takes the resource already fetched by report.rpc.ts for the-// access check, so the ported router does exactly one extra Prisma round-// trip fewer than re-fetching, matching V1's query count.+// Mutations. Each takes the resource already fetched by report.rpc.ts for the+// access check, so this does exactly one fewer Prisma round trip than+// re-fetching.type IReportInputForWrite = Omit<IReport, 'projectId'>;@@ -403,7 +400,6 @@ export async function updateReportLayout(const db = deps.db;const { reportId, layout } = input;- // Upsert the layout (create if doesn't exist, update if it does)return db.reportLayout.upsert({where: {reportId,diff --git a/packages/core/src/modules/salt/salt.service.test.ts b/packages/core/src/modules/salt/salt.service.test.tsindex d3e6977e5..13ec299a4 100644--- a/packages/core/src/modules/salt/salt.service.test.ts+++ b/packages/core/src/modules/salt/salt.service.test.ts@@ -2,8 +2,7 @@// mock at all — `deps.db` IS the fake below, same idiom as// reference.service.test.ts. `@openpanel/redis`'s `cacheable` is still stubbed// (module-level `getSalts` binds it at this file's first import), so-// `rotateSalt`'s `getSalts.clear` never reaches a real Redis connection — same-// reasoning as before this wave, just without the `@openpanel/db` mock.+// `rotateSalt`'s `getSalts.clear` never reaches a real Redis connection.//// `getSalts` itself stays untested here: it is bare (no `deps` argument)// because ingest.service.ts's hot path calls it with none — see the modulediff --git a/packages/core/src/modules/salt/salt.service.ts b/packages/core/src/modules/salt/salt.service.tsindex 026600297..60704387c 100644--- a/packages/core/src/modules/salt/salt.service.ts+++ b/packages/core/src/modules/salt/salt.service.ts@@ -1,13 +1,12 @@-// Reaches Postgres as `deps.db`, no `@openpanel/db` import left. `main.ts`-// passes its own `deps` to `createInitialSalts` at boot; `salt.jobs.ts`'s-// handler passes its `JobCtx` (a `ServiceDeps` by construction) to-// `rotateSalt`.+// `main.ts` passes its own `deps` to `createInitialSalts` at boot;+// `salt.jobs.ts`'s handler passes its `JobCtx` (a `ServiceDeps` by+// construction) to `rotateSalt`.//// `getSalts` is a module-scope `cacheablePerDb`, keyed on the Postgres client-// rather than on the scope — its L1 LRU has to survive across calls to be worth-// anything, and `ingest.service.ts`'s `/track` hot path now passes the scope it-// holds instead of reading a boot-scoped singleton through the deleted compat-// seam. `generateNewSalt` clears the same instance.+// rather than on the scope — its L1 LRU has to survive across calls to be+// worth anything, so `ingest.service.ts`'s `/track` hot path passes the+// scope it holds rather than a boot-scoped singleton. `generateNewSalt`+// clears the same instance.import { generateSalt } from '@openpanel/shared/server';import { cacheablePerDb } from '../../cacheable-per-deps';diff --git a/packages/core/src/modules/session/session.jobs.ts b/packages/core/src/modules/session/session.jobs.tsindex d4c75d4a6..7c0d2f00f 100644--- a/packages/core/src/modules/session/session.jobs.ts+++ b/packages/core/src/modules/session/session.jobs.ts@@ -1,12 +1,10 @@-// Schedules moved onto the jobs at ADR-021.-//// `sessions` is this module's own queue — registry key and Redis name-// `sessions`, job name `session`, `removeOnComplete: true`, concurrency 1, all-// V1's (jobs.registry.ts). Its wire payload is `{ event, snapshot }`, which is-// what `legacyCompat.sessions` maps V1's `{type:'createSessionEnd', payload,-// snapshot}` onto. `flushSessions` / `flushReplay` / `sessionReaper` /-// `sessionVacuum` are cron fragments, spread into the ONE `cron` queue by-// jobs.registry.ts, ids and cadences unchanged (apps/worker/src/boot-cron.ts).+// `sessions`, job name `session`, `removeOnComplete: true`, concurrency 1+// (jobs.registry.ts). Its wire payload is `{ event, snapshot }`, which is+// what `legacyCompat.sessions` maps the legacy `{type:'createSessionEnd',+// payload, snapshot}` shape onto. `flushSessions` / `flushReplay` /+// `sessionReaper` / `sessionVacuum` are cron fragments, spread into the ONE+// `cron` queue by jobs.registry.ts, ids and cadences unchanged.//// Every handler reads its clients off `ctx` — the buffers and the Redis// connection main.ts built once, and the ClickHouse client the job's own@@ -41,9 +39,8 @@ const SESSION_VACUUM_CRON = '0 4 * * *';const FLUSH_SESSIONS_INTERVAL_MS = 10_000;const FLUSH_REPLAY_INTERVAL_MS = 10_000;-// Wire-shape check only — V1 never validated it either (see-// jobs/compat.test.ts), and tightening it now would reject payloads the running-// system accepts.+// Wire-shape check only — tightening it now would reject payloads the+// running system currently accepts (see jobs/compat.test.ts).//// The schema's INPUT is what the producer holds (`SessionEndJobData`, a real// `Date` on `event.createdAt`) and its OUTPUT is what a handler is actually@@ -70,10 +67,9 @@ const sessionEndPayload = z/*** The session-end job's dependencies, bound to the run's own ctx.*- * Two lookups stay dynamic, both for the same reason now that- * notification-dispatch.ts has moved into core: keeping notification.service.ts- * — and the dispatch module built on it — out of jobs.registry.ts's eager- * import graph, which every core test file walks.+ * Two lookups stay dynamic to keep `notification.service.ts` — and the+ * dispatch module built on it — out of jobs.registry.ts's eager import+ * graph, which every core test file walks.*/async function sessionEndDeps(ctx: Ctx,diff --git a/packages/core/src/modules/session/session.service.ts b/packages/core/src/modules/session/session.service.tsindex 38034748a..27647ce11 100644--- a/packages/core/src/modules/session/session.service.ts+++ b/packages/core/src/modules/session/session.service.ts@@ -362,9 +362,9 @@ export async function getSessionReplayChunksFrom();// `chunkIndex` is the row's position, not `row.chunk_index`, and `hasMore`- // counts rows the JSON filter may drop — so an unparseable chunk rewinds the- // client (docs/review/session.md, "not covered by any rule" #5). Correcting- // either changes what the endpoint returns, so it is reported, not fixed.+ // counts rows the JSON filter may drop — so an unparseable chunk rewinds+ // the client. Correcting either changes what the endpoint returns, so it+ // is reported, not fixed.return {data: rows.slice(0, REPLAY_CHUNKS_PAGE_SIZE)@@ -480,10 +480,8 @@ export function createSessionService(_services: () => Services) {/**- * Enqueue one `session_end` job, idempotent on the closed session's id.- * The ctx.queues-based producer; V1's now-deleted apps/worker kept its own- * @openpanel/queue producer (utils/session-handler.ts) because core could- * not import @openpanel/queue back (see cohort.service.ts's header).+ * Enqueue one `session_end` job, idempotent on the closed session's id,+ * through the ctx.queues-based producer.*/async function enqueueSessionEnd(input: EnqueueSessionEndInputdiff --git a/packages/core/src/modules/session/src/session-end.ts b/packages/core/src/modules/session/src/session-end.tsindex 8498cdf33..88e92776f 100644--- a/packages/core/src/modules/session/src/session-end.ts+++ b/packages/core/src/modules/session/src/session-end.ts@@ -1,7 +1,7 @@// Everything that touches Redis, ClickHouse, a buffer or a queue is INJECTED-// (`SessionEndDeps`): M10-006 moved the binding into `session.jobs.ts`, where-// the job's `ctx` supplies every client, so the requestId that opened the-// session still labels the rows this close writes.+// (`SessionEndDeps`), bound in `session.jobs.ts` from the job's own `ctx`, so+// the requestId that opened the session still labels the rows this close+// writes.import type { CoreConfig } from '../../../config';import type { EnqueueOptions } from '../../../jobs/define';diff --git a/packages/core/src/modules/session/src/session.metrics.ts b/packages/core/src/modules/session/src/session.metrics.tsindex eb11efa04..2253a2b40 100644--- a/packages/core/src/modules/session/src/session.metrics.ts+++ b/packages/core/src/modules/session/src/session.metrics.ts@@ -1,20 +1,17 @@-// The session lifecycle collectors, moved from apps/worker/src/metrics.ts onto-// core's one registry. Names, labels and buckets are V1's; the worker-side-// copies die with apps/worker (P9). The ingest-side `sessions_started_total`-// lives with the ingest path (modules/ingest/src/ingest.metrics.ts); the three-// at-scrape gauges joined this file at M9-002 — see-// `registerSessionScrapeMetrics` at the bottom.+// The session lifecycle collectors, on core's one registry. The ingest-side+// `sessions_started_total` lives with the ingest path+// (modules/ingest/src/ingest.metrics.ts); the three at-scrape gauges are+// registered by `registerSessionScrapeMetrics` at the bottom of this file.import client from 'prom-client';import { registry } from '../../../metrics';-// V1's key names, unchanged (apps/worker/src/metrics.ts).+// Must match PROJECTS_SET_KEY in buffers/session-buffer.ts — same Redis key.const SESSION_PROJECTS_KEY = 'session:projects';/**- * The slice of the cache client the gauges use. `multi` is V1's, and it is- * batching rather than a transaction — the ADR-006 swap replaces it with- * `Promise.all` over Bun's auto-pipelining when packages/redis moves.+ * The slice of the cache client the gauges use. `multi` here is batching+ * rather than a transaction.*/export interface SessionMetricsRedis {smembers(key: string): Promise<string[]>;@@ -96,12 +93,11 @@ export const sessionsVacuumed = new client.Counter({});/**- * The three scrape-time session gauges, moved from apps/worker/src/metrics.ts.+ * The three scrape-time session gauges.** Registered by main.ts and ONLY where the role consumes queues: each scrape* costs one `ZCARD` and one `GET` per project, and ten api replicas exposing- * them would multiply that Redis load for no new information- * (TARGET_ARCHITECTURE §18).+ * them would multiply that Redis load for no new information.** The client is injected rather than imported so core does not open a Redis* connection at import time — `main.ts` hands in `getRedisCache`.diff --git a/packages/core/src/modules/session/src/sql.ts b/packages/core/src/modules/session/src/sql.tsindex abc835f40..d5fb95cd8 100644--- a/packages/core/src/modules/session/src/sql.ts+++ b/packages/core/src/modules/session/src/sql.ts@@ -1,17 +1,15 @@-// Every ClickHouse query the session module runs, as pure `sql` fragments. The-// SQL text is V1's, with every value bound as a `{pN:Type}` parameter instead-// of an escaped literal, and each conversion was proven byte-equivalent against-// the local prod-copy (see the task report).+// Every ClickHouse query the session module runs, as pure `sql` fragments,+// with every value bound as a `{pN:Type}` parameter instead of an escaped+// literal.//-// Dates bind as V1's own `YYYY-MM-DD HH:mm:ss` strings on purpose: a String-// param in a DateTime64 position is parsed exactly like the literal it-// replaces, so the result sets cannot drift by a millisecond truncation.+// Dates bind as `YYYY-MM-DD HH:mm:ss` strings on purpose: a String param in+// a DateTime64 position is parsed exactly like the literal it replaces, so+// the result sets cannot drift by a millisecond truncation.//// Cluster note: `sessions` and `session_replay_chunks` are Distributed on// Cloud. The has_replay LEFT JOIN subquery and any `IN (SELECT...)` a filter-// compiles to keep V1's exact shape and run under the client's-// `distributed_product_mode: 'allow'` as before — converting a query is not the-// place to change its cluster semantics.+// compiles to run under the client's `distributed_product_mode: 'allow'` —+// changing that shape changes the query's cluster semantics.import { type SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';import { toRangeBoundaryLiteral } from '../../../shared/ch-dates';@@ -94,7 +92,7 @@ export interface SessionListQuery {filterClauses?: CompiledFilterClauses;}-/** V1 only skips the lookback window when a page is bounded by explicit dates. */+/** Skips the lookback window only when a page is bounded by explicit dates. */export function hasSessionListLookback(query: {cursor?: Date;startDate?: Date;@@ -269,7 +267,7 @@ export function sessionHasReplayQuery(query: {`;}-/** The equality filters `querySessionsCore` accepts, in V1's clause order. */+/** The equality filters `querySessionsCore` accepts. */const QUERY_SESSIONS_EQUALITY_COLUMNS = [['profileId', 'profile_id'],['referrer', 'referrer'],@@ -298,7 +296,7 @@ export interface QuerySessionsQuery/*** Without an explicit order ClickHouse returns whatever it reads first, so a* bare LIMIT hands back the oldest sessions in the window while the MCP tool- * labels them `created_at desc`. The events twin took the same fix in #476.+ * labels them `created_at desc`.*/export function querySessionsQuery(query: QuerySessionsQuery): SqlFragment {const equalities = QUERY_SESSIONS_EQUALITY_COLUMNS.filter(diff --git a/packages/core/src/modules/share/share.service.ts b/packages/core/src/modules/share/share.service.tsindex dc5af56a3..d2c3cc93d 100644--- a/packages/core/src/modules/share/share.service.ts+++ b/packages/core/src/modules/share/share.service.ts@@ -1,8 +1,3 @@-// Every function takes `ServiceDeps` and reaches Postgres as `deps.db`; the-// `loadDb` / `loadAccessService` / `loadDashboardService` /-// `loadReportsService` lazy loaders are gone, so this module value-imports-// neither `@openpanel/db` nor its own package barrel.-import ShortUniqueId from 'short-unique-id';import { TRPCForbiddenError, TRPCNotFoundError } from '../../rpc/errors';import type { ServiceDeps, Services } from '../../services';@@ -25,9 +20,6 @@ interface CookieReader {get(name: string): string | undefined;}-// ------------------------------------------------------------------------// Raw lookups (ported verbatim from packages/db/src/services/share.service.ts).-export async function getShareOverviewById(deps: ServiceDeps, id: string) {const db = deps.db;return db.shareOverview.findFirst({@@ -263,8 +255,6 @@ export async function validateOverviewShareAccess(}// ------------------------------------------------------------------------// Router bodies (ported from packages/trpc/src/routers/share.ts).-//// The `overview`/`dashboard`/`report` functions below are unauthenticated and// serve the public viewer, addressed only by `shareId`. They project an// explicit allow-list of columns and refuse to hand back any shared contentdiff --git a/packages/core/src/modules/subscription/subscription.service.ts b/packages/core/src/modules/subscription/subscription.service.tsindex a21f03506..35ad283d3 100644--- a/packages/core/src/modules/subscription/subscription.service.ts+++ b/packages/core/src/modules/subscription/subscription.service.ts@@ -1,15 +1,10 @@// `requireOrganizationAdmin` travels with the business logic here rather than// living in subscription.rpc.ts the way project.rpc.ts's simple ladder checks// do: every mutating procedure in this module gates on it first, before-// touching Polar. `requireOrganizationAdmin` comes from auth.service.ts's-// single, lazily-memoized `getAccessChecks` — independent of `ServiceDeps`, so-// it needs no change here.+// touching Polar.//-// Every function takes `ServiceDeps` and reaches Postgres as `deps.db`; the-// `loadDb`/`loadPrisma` lazy loaders are gone. M15-202: `Prisma.DbNull` (the-// JSON-column null sentinel) arrives as `deps.prisma` — the app shell puts the-// two sentinels on `AppDeps` — rather than through a lazy import back into-// `context.ts`.+// `Prisma.DbNull` (the JSON-column null sentinel) arrives as `deps.prisma`+// rather than an import, keeping this module's only dependency `ServiceDeps`.import {applySubscriptionDiscount,@@ -349,12 +344,10 @@ export async function portal(}// - Polar webhook ---------------------------------------------------------// Ported from V1's apps/api/src/controllers/webhook.controller.ts's-// `polarWebhook` + its private helpers; that controller doesn't exist in this-// tree — this module's own `/webhook/polar` route (subscription.routes.ts) is-// the only caller. `validatePolarEvent` verifies the signature over the RAW-// body bytes; any body parsing before this call breaks that verification, which-// is why the route reads `await request.text` rather than a parsed JSON body.+// This module's own `/webhook/polar` route (subscription.routes.ts) is the+// only caller. `validatePolarEvent` verifies the signature over the RAW body+// bytes; any body parsing before this call breaks that verification, which is+// why the route reads `await request.text()` rather than a parsed JSON body.type PolarEvent = ReturnType<typeof validatePolarEvent>;type PolarSubscriptionData = Extract<@@ -459,11 +452,10 @@ async function clearOrganizationCache(}/**- * Syncs the full Polar subscription state onto the organization. Used for every- * `subscription.*` event (created, active, updated, canceled, revoked,- * past_due, uncanceled) since they all carry the same Subscription object and- * `status` drives the rest. This covers new subscriptions, cancellations,- * reactivations, plan changes and payment-state changes in one place.+ * Syncs the full Polar subscription state onto the organization. Every+ * `subscription.*` event carries the same Subscription object and `status`+ * drives the rest, so one function handles new subscriptions, cancellations,+ * reactivations, plan changes and payment-state changes.*/async function syncSubscriptionToOrg(deps: ServiceDeps,@@ -632,8 +624,7 @@ async function syncSubscriptionToOrg(* Handles one verified Polar webhook event. `rawBody`/`headers` MUST be the* unparsed request bytes — `validatePolarEvent` verifies the signature over* them, and any body parsing upstream (JSON, form, anything) breaks that- * verification. `apps/api`'s Fastify controller (via `fastify-raw-body`) and- * this module's own Elysia route (via `request.text()`) both preserve this.+ * verification.*/export async function handlePolarWebhookEvent(deps: ServiceDeps,@@ -756,9 +747,6 @@ async function dispatchPolarWebhookEvent();return;}- // All subscription lifecycle events carry the same Subscription object;- // sync them through a single path (new subs, cancellations, revokes,- // reactivations, plan changes, payment-state changes).// Pause/resume transitions arrive via `subscription.updated` (the SDK's// webhook union has no dedicated paused/reactivated payloads yet) and are// reflected in `status` / `pauseAtPeriodEnd` / `resumesAt` below.diff --git a/packages/core/src/modules/widget/widget.rpc.ts b/packages/core/src/modules/widget/widget.rpc.tsindex 31125ec73..996fc22d5 100644--- a/packages/core/src/modules/widget/widget.rpc.ts+++ b/packages/core/src/modules/widget/widget.rpc.ts@@ -37,10 +37,8 @@ const BADGE_CACHE_TTL_SECONDS = 5 * 60; // queries 30 days of dataconst REALTIME_TOP_LIST_LIMIT = 10;const EVENTS_TABLE = sql.id(TABLE_NAMES.events);-/** `clix.exp('now() - INTERVAL 30 MINUTE')`, parenthesised as clix rendered it. */const REALTIME_WINDOW = sql`created_at >= (now() - INTERVAL 30 MINUTE)`;-// Helper to find widget by projectId and typeasync function findWidgetByType(db: Ctx['db'],projectId: string,@@ -103,7 +101,6 @@ async function findPublicCounterWidgetOrThrow(db: Ctx['db'], shareId: string) {}export const widgetRouter = createTRPCRouter({- // Get widget by projectId and type (returns null if not found or not public)get: protectedProcedure.input(z.object({ projectId: z.string(), type: zWidgetType })).query(async ({ input, ctx }) => {@@ -120,7 +117,6 @@ export const widgetRouter = createTRPCRouter({return widget;}),- // Toggle widget public status (creates if doesn't exist)toggle: protectedProcedure.input(z.object({@@ -145,7 +141,6 @@ export const widgetRouter = createTRPCRouter({});}),- // Update widget options (for realtime widget)updateOptions: protectedProcedure.input(z.object({@@ -189,7 +184,6 @@ export const widgetRouter = createTRPCRouter({const { projectId } = widget;const { timezone } = await getSettingsForProject(ctx, projectId);- // Cache for 5 minutes since this queries 30 days of dataconst cacheKey = `widget:badge:${projectId}`;const visitors = await getCache(cacheKey,@@ -214,7 +208,6 @@ export const widgetRouter = createTRPCRouter({.input(z.object({ shareId: z.string() })).query(async ({ input, ctx }) => {const db = ctx.db;- // Validate ShareWidget exists and is publicconst widget = await db.shareWidget.findUnique({where: {id: input.shareId,@@ -241,13 +234,11 @@ export const widgetRouter = createTRPCRouter({const { timezone } = await getSettingsForProject(ctx, projectId);- // Always fetch live count and histogramconst settings = { session_timezone: timezone };const totalSessionsStatement = sql`SELECT uniq(session_id) as total_sessions FROM ${EVENTS_TABLE} WHERE project_id = ${sql.string(projectId)} AND ${REALTIME_WINDOW}`;const minuteCountsStatement = sql`SELECT toStartOfMinute(created_at) as minute, uniq(session_id) as session_count, uniq(profile_id) as visitor_count FROM ${EVENTS_TABLE} WHERE project_id = ${sql.string(projectId)} AND ${REALTIME_WINDOW} GROUP BY minute ORDER BY minute ASC WITH FILL FROM toStartOfMinute(now() - INTERVAL 30 MINUTE) TO toStartOfMinute(now()) STEP INTERVAL 1 MINUTE`;- // Conditionally fetch countriesconst countriesQueryPromise = options.countries? chQuery<{ country: string; count: number }>(ctx,@@ -256,7 +247,6 @@ export const widgetRouter = createTRPCRouter({): Promise.resolve<Array<{ country: string; count: number }>>([]);- // Conditionally fetch referrersconst referrersQueryPromise = options.referrers? chQuery<{ referrer: string; count: number }>(ctx,@@ -265,7 +255,6 @@ export const widgetRouter = createTRPCRouter({): Promise.resolve<Array<{ referrer: string; count: number }>>([]);- // Conditionally fetch pathsconst pathsQueryPromise = options.paths? chQuery<{ path: string; count: number }>(ctx,diff --git a/packages/core/src/pino-logger.ts b/packages/core/src/pino-logger.tsindex 2c7a3653c..1bb914622 100644--- a/packages/core/src/pino-logger.ts+++ b/packages/core/src/pino-logger.ts@@ -1,10 +1,8 @@// Concrete pino implementation. `../logger.ts` is the structural interface// every module and service codes against; this file is what actually-// instantiates pino, and it is deliberately the only place in core that imports-// it (ADR-007 layout: "pino instantiated in apps/api" — apps/api builds its-// named logger by calling `createLogger` from here rather than owning a copy).-//-// Ported from @openpanel/logger, unchanged (dissolved into core — M4-003).+// instantiates pino, and it is deliberately the only place in core that+// imports it — apps/api builds its named logger by calling `createLogger`+// from here rather than owning a copy.import * as HyperDX from '@hyperdx/node-opentelemetry';import pino, { type Logger as PinoLogger } from 'pino';@@ -78,8 +76,7 @@ export function getServiceName(config: CoreConfig, name: string): string {// @openpanel/core, e.g. apps/api/src/main.ts's own `createLogger` call)// and crashes the process instead of the log line — deterministic on this// box, not a flake. Node has no such issue, so this only turns pretty-// printing off for the Bun-booted V2 API; every Node-booted process-// (V1 api/worker) is unaffected.+// printing off when booted under Bun.const isBun = !!process.versions.bun;export function createLogger({diff --git a/packages/core/src/rest.routes.ts b/packages/core/src/rest.routes.tsindex 3df5c178a..4b951fdc1 100644--- a/packages/core/src/rest.routes.ts+++ b/packages/core/src/rest.routes.ts@@ -1,7 +1,7 @@-// The three URL surfaces `app.ts` hangs CORS, OpenAPI and guards on (ADR-007-// decision 19). Each is a factory over `AppDeps`, statically composed from-// `.use`d modules — no filesystem discovery. Adding a module's HTTP half is one-// `.use` on the surface it belongs to; most modules touch exactly one.+// The three URL surfaces `app.ts` hangs CORS, OpenAPI and guards on. Each is+// a factory over `AppDeps`, statically composed from `.use`d modules — no+// filesystem discovery. Adding a module's HTTP half is one `.use` on the+// surface it belongs to; most modules touch exactly one.import { openapi } from '@elysiajs/openapi';import { Elysia } from 'elysia';@@ -28,13 +28,12 @@ import { realtimeRoutes } from './modules/realtime/realtime.routes';import { subscriptionRoutes } from './modules/subscription/subscription.routes';import { toolsRoutes } from './modules/tools/tools.routes';-// ADR-002/ADR-003 pin: @elysiajs/openapi at the 1.4.15 fallback (2.0 is NO-GO-// per spike 6). `specPath` is set explicitly rather than taking the plugin's-// `${path}/json` default, because the ops surface's contract is exactly-// `/openapi.json`.+// Pinned to the @elysiajs/openapi 1.4.15 fallback; 2.0 is not viable here.+// `specPath` is set explicitly rather than taking the plugin's `${path}/json`+// default, because the ops surface's contract is exactly `/openapi.json`.const OPENAPI_SPEC_PATH = '/openapi.json';// `/metrics` is prometheus text exposition, not an OpenAPI-describable JSON-// endpoint (ADR-003: "the transform that hides /metrics from the spec").+// endpoint, so it is excluded from the generated spec.const OPENAPI_EXCLUDED_PATHS = ['/metrics'];// How long one collected exposition is served for before it is collected again.@@ -54,18 +53,10 @@ const METRICS_EXPOSITION_TTL_MS = 5000;// `defineRoutes`'s `RouteApp` is: `.use`'d plugins widen Elysia's type// parameters in a way the bare `Elysia` type cannot express.//-// Import's /import/events is the first module to land here; project's and-// client's /manage/* and profile's /profile* joined it — client-authed API-// surface, same as /import, not session-authed like dashboardRoutes. export's-// `/export` + `/insights` joined it too — `allow: ['read', 'root']` matches-// V1's shared `validateExportRequest`. None of it is yet reachable: the-// clientAuth macro's authenticator is a P8 stub that always returns null-// (import.routes.ts's header), and main.ts does not mount `publicApiRoutes`-// until a real `AppDeps` exists (P3/P4/P8). tools' `/site-checker` +-// `/ip-lookup` joined it too — unauthenticated like V1's, per the module map.-// ingest's `/track` + `/track/device-id` lead the list: the hot path, the-// ingest `clientAuth` tier, and the one route surface whose hook ORDER is part-// of the contract.+// Client-authed API surface (`/import`, `/manage/*`, `/profile*`, `/export`,+// `/insights`, `/tools`), not session-authed like dashboardRoutes. `/track` and+// `/track/device-id` are the hot path, on the ingest `clientAuth` tier, and the+// one route surface whose hook ORDER is part of the contract.export const publicApiRoutes = (deps: AppDeps) =>new Elysia({ name: 'core/public-api-routes' })// Mounted on the SURFACE, not per module, so a new /manage or /export@@ -81,20 +72,11 @@ export const publicApiRoutes = (deps: AppDeps) =>.use(insightsRoutes(deps)).use(toolsRoutes(deps));-// Gsc's callback was the first module to land here; assistant's `/ai/agents/*`,-// mcp's `/mcp` and auth's `/oauth/*` callbacks joined it. None is reachable in-// production yet: main.ts only mounts `dashboardRoutes` once a real `AppDeps`-// exists (P3/P4/P8) — see each module's own routes.ts header for its named gap.-// `/gsc` and `/mcp` are dashboard-scope routes absent from the CORS delegator's-// `corsPaths` allowlist (ADR-002 rule 4) and get `origin: '*'`; `/oauth` IS in-// `corsPaths` — a quirk to port verbatim when app.ts wires CORS, not something-// to fix here. integration's `/webhook/slack` and subscription's-// `/webhook/polar` joined it too — like `/oauth`, `/webhook` IS in the CORS-// delegator's `corsPaths` allowlist (ADR-002 rule 4), unlike `/gsc`/`/mcp`, and-// both are the same shape of unauthenticated third-party-redirected callback as-// `/oauth`'s. realtime's `/live/*` websockets joined it too — `/live` IS in-// `corsPaths`, same as `/trpc`/`/webhook`/`/oauth`/`/misc`/`/ai`. misc's-// `/misc/*` joined it too — `/misc` IS in `corsPaths`.+// `/gsc` and `/mcp` are dashboard-scope routes absent from the CORS+// delegator's private-path allowlist (`http/cors.ts`'s `CORS_PRIVATE_PATHS`)+// and so get `origin: '*'` — a quirk to keep, not fix. `/oauth`, `/webhook`+// (integration's Slack callback, subscription's Polar callback), `/live` and+// `/misc` ARE in that allowlist.export const dashboardRoutes = (deps: AppDeps) =>new Elysia({ name: 'core/dashboard-routes' })// For `/mcp`; every other path on this surface is unmatched by the table.@@ -109,12 +91,11 @@ export const dashboardRoutes = (deps: AppDeps) =>.use(miscRoutes(deps));// The `/metrics` body, collected at most once per METRICS_EXPOSITION_TTL_MS.-// Every series and every series NAME is unchanged - the endpoint still serves-// the one core registry's full exposition, including the heap metrics; what-// changes is how often that exposition is recomputed. Consequence to know:-// the scrape-time gauges (buffer, queue, session) are now as old as the-// snapshot, i.e. up to the TTL, which is the price of not walking the heap on-// every request.+// The endpoint still serves the one core registry's full exposition,+// including the heap metrics; what changes is how often that exposition is+// recomputed. Consequence to know: the scrape-time gauges (buffer, queue,+// session) are as old as the snapshot, i.e. up to the TTL, which is the price+// of not walking the heap on every request.let metricsExposition: { body: string; expiresAt: number } | null = null;// Concurrent scrapes share one collection instead of queueing N heap walks// behind each other on the single thread.@@ -136,8 +117,7 @@ function readMetricsExposition(): Promise<string> {}if (!metricsExpositionInFlight) {// A failed collection must not be cached, and must reject exactly as- // `registry.metrics()` did before - the route's error handling is- // unchanged.+ // `registry.metrics()` throws, so the route needs no separate error path.metricsExpositionInFlight = collectMetricsExposition().finally(() => {metricsExpositionInFlight = null;});@@ -146,15 +126,14 @@ function readMetricsExposition(): Promise<string> {}// `httpMetrics` is on the ops surface because that is where `/metrics` is-// served and every role mounts it (TARGET_ARCHITECTURE §18: "HTTP and default-// metrics register everywhere"). Its hook is `{ as: 'global' }`, so it covers-// the dashboard and public-API surfaces too once they mount.+// served and every role mounts it. Its hook is `{ as: 'global' }`, so it+// covers the dashboard and public-API surfaces too once they mount.//-// healthz/metrics/misc share V1's ops surface (http/context.ts's+// healthz/metrics/misc share this ops surface (http/context.ts's// UNLOGGED_PATH_PREFIXES) — unauthenticated, uncorsed, unlogged. /metrics and-// /openapi.json are the M3 gate's ops surface: the one core registry's-// prometheus exposition, and the OpenAPI reference built from the same zod-// schemas the routes validate against.+// /openapi.json serve the one core registry's prometheus exposition, and the+// OpenAPI reference built from the same zod schemas the routes validate+// against.export const opsRoutes = (deps: AppDeps) =>new Elysia({ name: 'core/ops-routes' }).use(httpMetrics())diff --git a/packages/core/src/rpc/base.test.ts b/packages/core/src/rpc/base.test.tsindex ef8dcf67c..8da7936c2 100644--- a/packages/core/src/rpc/base.test.ts+++ b/packages/core/src/rpc/base.test.ts@@ -13,7 +13,7 @@ import {} from './base';import { createTrpcFetchHandler } from './handler';-// V1's COOKIE_OPTIONS (packages/auth/constants.ts) with a domain filled in.+// Base cookie options for these tests, with a domain filled in.const COOKIE_OPTIONS: CookieOptions = {domain: '.openpanel.dev',secure: true,@@ -116,9 +116,8 @@ test('a signed cookie with no signer throws instead of going out unsigned', asynexpect(resHeaders.getSetCookie()).toHaveLength(0);});-// V1 resolved the session in a Fastify onRequest hook, before any procedure-// ran, and 134 call sites read `ctx.session` as a value. The context builder-// resolves it once for the same reason - and it is what lets `onError` log the+// The context builder resolves the session once, since every procedure reads+// `ctx.session` as a plain value - and it is what lets `onError` log the// session without awaiting.test('the session is resolved once, before any procedure runs', async () => {const stub = stubHttpCtx();@@ -132,12 +131,10 @@ test('the session is resolved once, before any procedure runs', async () => {expect(ctx.session).toEqual(TEST_SESSION);});-// Flipped this from "inherited" to "flattened", because tRPC merges middleware-// context with `{...ctx,...next.ctx}` — a spread, which copies own enumerable-// properties ONLY. Under the prototype-chained shape every inherited field-// vanished the first time a middleware called `next({ ctx })`, and the next-// read was a TypeError inside a mutation (caught by the auth contract suite,-// group c/d).+// tRPC merges middleware context with `{...ctx, ...next.ctx}` — a spread,+// which copies own enumerable properties ONLY. A prototype-chained context+// would lose every inherited field the first time a middleware called+// `next({ ctx })`, and the next read would be a TypeError inside a mutation.test('the HttpCtx is flattened onto own properties, and services stay lazy', async () => {const { ctx } = stubHttpCtx();const trpcCtx = await makeTrpcContext(ctx, new Headers(), {diff --git a/packages/core/src/rpc/base.ts b/packages/core/src/rpc/base.tsindex b8354e3ee..b33907ee0 100644--- a/packages/core/src/rpc/base.ts+++ b/packages/core/src/rpc/base.ts@@ -4,9 +4,6 @@// The tRPC context IS the Elysia-derived `HttpCtx`: `makeTrpcContext` adds the// tRPC-specific bits and overrides exactly one field. There is no `req`/`res`// here — a procedure reads `ctx.headers`, `ctx.ip`, `ctx.logger`.-//-// `transformer`, `errorFormatter` and `Meta` are verbatim from-// packages/trpc/src/trpc.ts:44-67; error semantics are unchanged by decision.import { initTRPC, TRPCError } from '@trpc/server';import { has } from 'ramda';@@ -38,10 +35,10 @@ export interface Meta {* two RPC-only fields.** `session` is the one field this OVERRIDES. On an HTTP route it is the lazy,- * memoized resolver, so a public route pays nothing; on an RPC call it is the- * resolved value, because V1 resolved it in a Fastify `onRequest` hook for- * every /trpc request and 134 procedure call sites read it as one. Resolving- * in the context builder is also what lets `onError` log it without awaiting.+ * memoized resolver, so a public route pays nothing; on an RPC call it is+ * resolved eagerly, since every procedure reads `ctx.session.userId` directly.+ * Resolving in the context builder is also what lets `onError` log it without+ * awaiting.** It is not merely convenience: a middleware that *changed* `session`'s type* would make every standalone middleware (`cacheMiddleware`,@@ -54,8 +51,7 @@ export interface TrpcContext extends Omit<HttpCtx, 'session'> {* The connection's peer address — the one address a client cannot forge, and* therefore the rate limiter's last-resort fallback when no trusted header is* present. It is NOT `ctx.ip`: that is the *attribution* ip, which prefers- * client-forwarded headers and would give every request its own bucket- * (ADR-002 "behaviour that must be preserved explicitly" 2).+ * client-forwarded headers and would give every request its own bucket.** `undefined` where the transport does not expose it. Elysia's* `server.requestIP` is not plumbed through `HttpCtx` yet, so the fetch mount@@ -111,9 +107,9 @@ const stopWhenCancelled = t.middleware(async ({ ctx, next }) => {/*** The bare procedure. It authenticates NOTHING. Use one of the three builders- * below unless a procedure's V1 twin was written on `procedure` itself — the- * only ones are the share-aware `chartProcedure`/`overviewProcedure` bases,- * and those are `publicProcedure` plus their own middleware.+ * below unless a procedure needs to be built directly on `procedure` itself —+ * the only ones are the share-aware `chartProcedure`/`overviewProcedure`+ * bases, and those are `publicProcedure` plus their own middleware.*//*** Turns a driver failure caused by the CALLER into the status it deserves.@@ -124,8 +120,8 @@ const stopWhenCancelled = t.middleware(async ({ ctx, next }) => {* SQL. Anything `classifyDriverError` does not recognise is rethrown* untouched and stays a 500, because a query bug is not the caller's mistake.*- * This sits on `procedure` itself, which every builder derives from, so all- * 177 procedures are covered by one `.use()`.+ * This sits on `procedure` itself, which every builder derives from, so it+ * covers every procedure with one `.use()`.*/const mapDriverErrors = t.middleware(async ({ next }) => {const result = await next();@@ -147,28 +143,24 @@ export const procedure = t.procedure.use(mapDriverErrors);// ---------------------------------------------------------------------------// The procedure stack, ported from packages/trpc/src/trpc.ts:35-155.+// The procedure stack. It is a middleware stack rather than per-handler code+// because:+//+// Authentication runs before input parsing: tRPC runs `.use` middleware ahead+// of the `.input` parser, so an anonymous caller gets UNAUTHORIZED whatever it+// sends. Doing the same check inside a handler would let the caller learn the+// input shape first.//-// Is this code's law; invariants 1-13 are binding. Three properties of the port-// are load-bearing and are the reason it is a middleware stack rather than-// per-handler code:+// The check is a property of the builder, not a line a handler might forget+// to call.//-// 1. AUTHENTICATION RUNS BEFORE INPUT PARSING. tRPC runs `.use` middleware-// ahead of the `.input` parser, so an anonymous caller gets UNAUTHORIZED-// whatever it sends. Doing the same check inside a handler inverts that: the-// caller learns the input shape first, and 176 procedures changed answer from-// 401 to 400 when core mounted the bare `procedure`. 2. THE CHECK CANNOT BE-// FORGOTTEN. It is a property of the builder, not of a line a port might drop.-// Three procedures (`client.list`, `subscription.getCurrent`,-// `subscription.usage`) had no check at all while this stack was missing. 3.-// `enforceAccess` READS THE RAW, PRE-ZOD INPUT (ADR-011 invariant 2) and only-// its TOP-LEVEL `projectId` / `organizationId`. A procedure that resolves the-// project from a reportId/dashboardId is invisible to it and keeps its-// in-handler check — ADR-011 counts 58 of those, and a redundant check is-// harmless where a missing one is not.+// `enforceAccess` reads the raw, pre-Zod input and only its top-level+// `projectId` / `organizationId`. A procedure that resolves the project from+// a reportId/dashboardId instead is invisible to it and keeps its own+// in-handler check — redundant there is harmless, missing is not.//-// The lookups arrive through `ctx.services.auth` (M10-002 bound the ladder-// there, once, in auth.service.ts); core reaches no database directly.+// The lookups arrive through `ctx.services.auth`; core reaches no database+// directly.// ---------------------------------------------------------------------------const enforceUserIsAuthed = t.middleware(async ({ ctx, next }) => {@@ -179,18 +171,15 @@ const enforceUserIsAuthed = t.middleware(async ({ ctx, next }) => {try {// Narrowed, not merely copied: the spread of the checked union member is- // what gives every handler below a `session.userId` of type `string`, so a- // procedure reads it instead of re-deriving it through a per-file- // `requireLogin` (ADR-022 R10 — 38 of those, deleted at M15-007).+ // what gives every handler below a `session.userId` of type `string`.return next({ctx: {session: { ...session },},});} catch (error) {- // V1 wrote this to `console.error`; core has a request-scoped logger on- // the context and CLAUDE.md bans `console` in shipped code. Same branch,- // same outcome, same (misspelled, kept) message.+ // Logged via the request-scoped logger, not console (CLAUDE.md bans+ // console in shipped code). The misspelled message is kept as-is.ctx.logger.error({ err: error }, 'Failes to get user');throw new TRPCError({code: 'UNAUTHORIZED',@@ -246,7 +235,6 @@ const enforceAccess = t.middleware(const loggerMiddleware = t.middleware(async ({ ctx, next, getRawInput, path, input, type }) => {const rawInput = await getRawInput();- // Only log mutationsif (type === 'mutation') {ctx.logger.info({@@ -293,17 +281,13 @@ export const protectedProcedureWithoutAccess = procedure.use(loggerMiddleware).use(sessionScopeMiddleware);-// V1 delayed every non-production request by up to 200ms so a developer felt-// the latency a user does. Preserved, with the flag injected: core reads no-// process.env.+// Delays every non-production request by up to 200ms so a developer feels+// the latency a user does.const ARTIFICIAL_LATENCY_SPREAD_MS = 500;const ARTIFICIAL_LATENCY_MAX_MS = 200;export interface TrpcContextOptions {- /**- * V1's `COOKIE_OPTIONS`. Deployment-derived (it reads `DASHBOARD_URL`), so- * it is injected rather than imported: core reads no environment.- */+ /** Deployment-derived (reads `DASHBOARD_URL`), so it is injected rather than imported. */cookieOptions: CookieOptions;/** `NODE_ENV !== 'production'` at the call site. */simulateLatency?: boolean;@@ -322,7 +306,7 @@ export interface TrpcContextOptions {** Cookies go out through the fetch adapter's `resHeaders`, not through Elysia:* the handler returns a `Response` the framework did not build, so the cookie- * proxy is not a guaranteed path out (ADR-009 constraint 1).+ * proxy is not a guaranteed path out.*/export async function makeTrpcContext(ctx: HttpCtx,@@ -346,8 +330,8 @@ export async function makeTrpcContext(value: string,cookie: CookieOptions = {}): void => {- // V1's precedence, exactly: only `maxAge` and `signed` are caller-- // controlled, everything else comes from COOKIE_OPTIONS spread last.+ // Only `maxAge` and `signed` are caller-controlled; everything else+ // comes from COOKIE_OPTIONS, spread last.const merged: CookieOptions = {maxAge: cookie.maxAge,signed: cookie.signed,@@ -382,8 +366,8 @@ export async function makeTrpcContext(// Resolved once here, shadowing HttpCtx's resolver. One HTTP request is// one `createContext` call, so a batched request still costs one lookup.// `HttpCtx.session()` answers `null` for "nobody is signed in" (see- // http/session.ts); V1's routers read `ctx.session.userId`, so the empty- // shape — not `null` — is what a procedure must see.+ // http/session.ts); procedures read `ctx.session.userId` directly, so the+ // empty shape — not `null` — is what a procedure must see.session: {value: (await ctx.session()) ?? EMPTY_SESSION,enumerable: true,@@ -428,10 +412,9 @@ export interface RpcCache {export interface CacheMiddlewareDeps {cache: RpcCache;/**- * V1 wrote the cache everywhere but only *served* from it in production- * (`NODE_ENV === 'production'`), so a developer never debugged a stale- * answer. Preserved as a flag — a thunk because V1 read the env on every- * request, not once when the router module loaded.+ * Only *served* from cache in production (`NODE_ENV === 'production'`), so+ * a developer never debugs a stale answer. A thunk, not a boolean, because+ * it must be read per request rather than once when the router loads.*/serveFromCache: boolean | (() => boolean);}@@ -503,10 +486,10 @@ export interface RateLimitOptions {* both are boot-scope concerns, and injecting it is what lets a procedure be* tested without one.*- * The fingerprint is derived from `headers` and `remoteAddress`. `ip` is in the- * signature because ADR-009 names it, but a limiter must never key on it: it is- * the attribution address, which prefers client-forwarded headers and would- * give every request its own bucket (ADR-002 preserved-behaviour 2).+ * The fingerprint is derived from `headers` and `remoteAddress`, not `ip`: a+ * limiter must never key on `ip`, since it is the attribution address, which+ * prefers client-forwarded headers and would give every request its own+ * bucket.*/export type EnforceRateLimit = (args: RateLimitOptions & {diff --git a/packages/core/src/rpc/handler.ts b/packages/core/src/rpc/handler.tsindex cd92d007a..01079bc04 100644--- a/packages/core/src/rpc/handler.ts+++ b/packages/core/src/rpc/handler.ts@@ -1,11 +1,6 @@// The tRPC mount: the official fetch adapter, one handler, one `onError`.-//-// Three of the four `onError` branches are V1's (apps/api/src/app.ts:175-206)-// with one change and no others: the fields come from `ctx` and the `Request`,-// because under a fetch adapter `req` is a `Request` and has neither `socket`-// nor a logger. The messages, the levels, the payload keys and the-// `organization.list` drop are unchanged. The fourth, `CLIENT_CLOSED_REQUEST`,-// is M36-001's cancellation, which V1 did not have.+// The `onError` fields come from `ctx` and the `Request`, because under a+// fetch adapter `req` is a `Request` and has neither `socket` nor a logger.import type { AnyRouter, TRPCError } from '@trpc/server';import { fetchRequestHandler } from '@trpc/server/adapters/fetch';@@ -113,9 +108,8 @@ export interface TrpcFetchHandlerOptions extends TrpcContextOptions {}/**- * The handler `app.ts` hangs on `.all('/trpc/*')`. It returns a raw `Response`,- * so `/trpc` sits outside Elysia's response lifecycle — as it sat outside- * Fastify's in V1.+ * The handler `app.ts` hangs on `.all('/trpc/*')`. It returns a raw+ * `Response`, so `/trpc` sits outside Elysia's response lifecycle.*/export function createTrpcFetchHandler(options: TrpcFetchHandlerOptions) {const {diff --git a/packages/core/src/rpc/rate-limit.ts b/packages/core/src/rpc/rate-limit.tsindex 9dc267f4f..aa17672ae 100644--- a/packages/core/src/rpc/rate-limit.ts+++ b/packages/core/src/rpc/rate-limit.ts@@ -1,12 +1,9 @@-// IP rate limiting with an exponentially growing lockout, ported from-// packages/trpc/src/rate-limit.ts (V1). The rewrite already carried the seam-// — `EnforceRateLimit` and `createRateLimitMiddleware` in rpc/base.ts — but-// nothing implemented it, so the ten wrappers V1 had on its auth router were-// not mounted and no limit existed anywhere (ISSUES.md H4).+// IP rate limiting with an exponentially growing lockout. Implements the seam+// declared in `rpc/base.ts` (`EnforceRateLimit`, `createRateLimitMiddleware`).//-// The one structural change from V1: the enforcer takes headers, the socket-// address and a logger rather than a FastifyRequest, which is what lets a-// procedure be tested without a server.+// The enforcer takes headers, the socket address and a logger rather than a+// framework request object, which is what lets a procedure be tested without+// a server.import { getRedisCache, LRUCache } from '@openpanel/redis';import { TRPCError } from '@trpc/server';@@ -61,7 +58,7 @@ const fallbackCounters = new LRUCache<string, number>({/*** The trusted-header defaults. A limiter must never key on the ATTRIBUTION* address: that one prefers client-forwarded headers, so every request would- * get its own bucket (ADR-002 preserved-behaviour 2).+ * get its own bucket.*/const TRUSTED_ONLY = { attributionOrder: undefined, trustedOrder: undefined };diff --git a/packages/core/src/services.ts b/packages/core/src/services.tsindex 0aad3b2c6..6b8e654e8 100644--- a/packages/core/src/services.ts+++ b/packages/core/src/services.ts@@ -1,7 +1,3 @@-// The composition root (ADR-007 build step 4). `auth` is the first module to-// land here; the Ctx <-> Services circularity was proven compiling before it-// with an empty interface.-import type { Ctx } from './context';import { createAssistantService } from './modules/assistant/assistant.service';import { createAuthService } from './modules/auth/auth.service';@@ -107,10 +103,9 @@ export interface Services {mcp: ReturnType<typeof createMcpService>;}-// Stays a hoisted `function` declaration, not a `const` arrow: the one static-// ESM cycle that ran through it died with the compat seam at M15-005, but a-// `const` here would still put any future cycle in a temporal dead zone that no-// typecheck reports and that fails at process boot.+// Stays a hoisted `function` declaration, not a `const` arrow: a `const`+// here would put any future ESM cycle through this file in a temporal dead+// zone that no typecheck reports and that fails at process boot.export function createServices(deps: ServiceDeps): Services {// The thunk is captured, not copied, so two services may call each other// without a cycle: `container` is assigned before any thunk body can run,diff --git a/packages/core/src/shared/access-lookups.ts b/packages/core/src/shared/access-lookups.tsindex 7fd53fdcb..8a3a313af 100644--- a/packages/core/src/shared/access-lookups.ts+++ b/packages/core/src/shared/access-lookups.ts@@ -1,19 +1,14 @@-// The concrete, Prisma-backed access lookups (moved from-// packages/db/src/services/access.service.ts). Deliberately a sibling of-// modules/auth/src/access.ts rather than living inside it: the ladder must stay-// importable with no database (see its own header), while this file is the real-// `@openpanel/db` binding ~28 modules' `src/access.ts` files supply to it. Same-// shape as packages/trpc/src/access.ts's binding.+// The concrete, Prisma-backed access lookups. Deliberately a sibling of+// modules/auth/src/access.ts rather than living inside it: the ladder must+// stay importable with no database (see its own header), while this file is+// the real `@openpanel/db` binding ~28 modules' `src/access.ts` files supply+// to it.//// Postgres comes from `context.ts`'s `unscopedDb`. Two of the three lookups// here are `cacheable`, whose key is derived from the call's ARGUMENTS// (packages/redis/cachable.ts), so they cannot take a `ServiceDeps` leading// parameter at all; the third (`getClientAccess`) delegates to them and stays-// symmetric. Their bare signature is also a protected wire contract —-// `verification/contracts/auth/group-b-project-access.mts` imports them through-// `packages/db/src/services/access.service.ts` with no app boot at all, so the-// handle has to be one this file can resolve on its own. It is the same client-// `ctx.db` is, not a second one.+// symmetric. It is the same client `ctx.db` is, not a second one.//// `getProjectById` is spelled here rather than imported from// `project.service.ts`: `shared/` sits below `modules/` and the ladder reads@@ -22,9 +17,9 @@import type { AccessLevel } from '@openpanel/db/src/prisma-client';import { cacheable } from '@openpanel/redis';-// Lazy, as the seam this replaces was: `context.ts` value-imports-// `services.ts`, so a static import here would drag the whole 36-service graph-// into the import graph of everything that reaches this file.+// Lazy: `context.ts` value-imports `services.ts`, so a static import here+// would drag the whole 36-service graph into the import graph of everything+// that reaches this file.function unscopedDb() {return import('../context').then((m) => m.unscopedDb());}@@ -78,7 +73,6 @@ export const getProjectAccess = cacheable(projectId: string;}): Promise<IProjectAccess | null> => {try {- // Check if user has access to the projectconst project = await getProjectById(projectId);if (!project?.organizationId) {return null;diff --git a/packages/core/src/shared/ch-dates.ts b/packages/core/src/shared/ch-dates.tsindex 74cae7758..588bc60dd 100644--- a/packages/core/src/shared/ch-dates.ts+++ b/packages/core/src/shared/ch-dates.ts@@ -4,17 +4,15 @@// constructs a real ClickHouse client and a real pino logger at module load and// is a value import of `@openpanel/db` from core — see ch-tables.ts's header// for the full reasoning. Five modules already carry a byte-identical private-// copy in their own `src/dates.ts` (chart, event, group, profile, session);-// folding those into this file is its own task, not this one's.+// copy in their own `src/dates.ts` (chart, event, group, profile, session).// `ch-dates.parity.test.ts` asserts this file and @openpanel/db's agree on// every input, so the copy cannot drift silently.const CLICKHOUSE_DATE_SUFFIX = /(\.\d{3})?Z+$/;/**- * `YYYY-MM-DD HH:mm:ss` in UTC — what V1 sent as a date literal.- * `skipTime` narrows it to `YYYY-MM-DD`, for the date-only column comparisons- * the billing counters build.+ * `YYYY-MM-DD HH:mm:ss` in UTC. `skipTime` narrows it to `YYYY-MM-DD`, for+ * the date-only column comparisons the billing counters build.*/export function formatClickhouseDate(date: Date | string,diff --git a/packages/core/src/shared/ch-tables.ts b/packages/core/src/shared/ch-tables.tsindex 454c3e3d2..5df4c1639 100644--- a/packages/core/src/shared/ch-tables.ts+++ b/packages/core/src/shared/ch-tables.ts@@ -46,19 +46,16 @@ export const TABLE_NAMES = {};/**- * The table a mutation must target: `<name>_replicated ON CLUSTER '{cluster}'`- * when clustered, the plain name otherwise.+ * The mutation target as a SQL fragment: `<name>_replicated ON CLUSTER+ * '{cluster}'` when clustered, the plain name otherwise. Clustered mode =+ * production (not self-hosted); non-clustered = self-hosted. The verdict is+ * `config.clickhouseClustered`, resolved once by the config loader from+ * CLICKHOUSE_CLUSTER and SELF_HOSTED.*- * Clustered mode = production (not self-hosted); non-clustered = self-hosted.- * The verdict is `config.clickhouseClustered`, resolved once by the config- * loader from CLICKHOUSE_CLUSTER and SELF_HOSTED.- */-/**- * The mutation target as a SQL fragment. Built here rather than fed through- * `sql.id` because the clustered form is not an identifier: the `ON CLUSTER`- * clause is literal template text, and `'{cluster}'` is a ClickHouse *macro*,- * not a `{name:Type}` placeholder — it carries no type suffix, so parameter- * substitution leaves it alone.+ * Built here rather than fed through `sql.id` because the clustered form is+ * not an identifier: the `ON CLUSTER` clause is literal template text, and+ * `'{cluster}'` is a ClickHouse *macro*, not a `{name:Type}` placeholder — it+ * carries no type suffix, so parameter substitution leaves it alone.*/export function replicatedTarget(clustered: boolean,diff --git a/packages/core/src/shared/cookie.ts b/packages/core/src/shared/cookie.tsindex ada7efc6e..c52dbbd04 100644--- a/packages/core/src/shared/cookie.ts+++ b/packages/core/src/shared/cookie.ts@@ -26,10 +26,10 @@ const SAME_SITE_ATTRIBUTE = {/*** Serializes one `Set-Cookie` header value.*- * Attribute order follows the `cookie` package V1 served these through- * (@fastify/cookie), so a header produced here is byte-comparable with V1's.- * `signed` is deliberately not emitted: it is not a cookie attribute, it is an- * instruction to the caller's signer.+ * Attribute order is fixed and deliberate, so a header produced here stays+ * byte-comparable across implementations. `signed` is deliberately not+ * emitted: it is not a cookie attribute, it is an instruction to the+ * caller's signer.*/export function serializeCookie(name: string,diff --git a/packages/core/src/shared/get-client-ip.ts b/packages/core/src/shared/get-client-ip.tsindex 85b171e24..1c8919288 100644--- a/packages/core/src/shared/get-client-ip.ts+++ b/packages/core/src/shared/get-client-ip.ts@@ -30,8 +30,8 @@ export const DEFAULT_IP_HEADER_ORDER = [function isPublicIp(ip: string): boolean {// Handle IPv4-mapped IPv6 addresses (e.g., ::ffff:127.0.0.1)if (ip.startsWith('::ffff:')) {- const ipv4Part = ip.substring(7); // Extract IPv4 part after "::ffff:"- return isPublicIp(ipv4Part); // Recursively check the IPv4 address+ const ipv4Part = ip.substring(7);+ return isPublicIp(ipv4Part);}// IPv6 loopback@@ -53,7 +53,6 @@ function isPublicIp(ip: string): boolean {return false;}- // IPv4 private ranges// 10.0.0.0/8if (ip.startsWith('10.')) {return false;@@ -81,7 +80,6 @@ function isPublicIp(ip: string): boolean {}function isValidIp(ip: string): boolean {- // Basic IP validationconst ipv4 = /^(\d{1,3}\.){3}\d{1,3}$/;const ipv6 = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;return isPublicIp(ip) && (ipv4.test(ip) || ipv6.test(ip));@@ -104,7 +102,6 @@ export function getClientIpFromHeaders(for (const headerName of headerOrder) {let value: string | null = null;- // Get header valueif (headers instanceof Headers) {value = headers.get(headerName);} else {@@ -120,7 +117,7 @@ export function getClientIpFromHeaders(continue;}- // Handle x-forwarded-for (comma separated)+ // x-forwarded-for is comma separated; take the first entry.if (headerName === 'x-forwarded-for') {const firstIp = value.split(',')[0]?.trim();if (firstIp && isValidIp(firstIp)) {@@ -134,9 +131,7 @@ export function getClientIpFromHeaders(if (ip && isValidIp(ip)) {return { ip, header: headerName };}- }- // Regular headers- else if (isValidIp(value)) {+ } else if (isValidIp(value)) {return { ip: value, header: headerName };}}diff --git a/packages/core/src/shared/js-runtime/ast-walker.ts b/packages/core/src/shared/js-runtime/ast-walker.tsindex 552f96506..e4f14dfe3 100644--- a/packages/core/src/shared/js-runtime/ast-walker.ts+++ b/packages/core/src/shared/js-runtime/ast-walker.ts@@ -13,7 +13,6 @@ export function walkNode(return;}- // Handle arraysif (Array.isArray(node)) {for (const child of node) {walkNode(child, visitor, parent);@@ -28,7 +27,6 @@ export function walkNode(visitor(nodeObj, parent);}- // Recursively walk all propertiesfor (const key of Object.keys(nodeObj)) {const value = nodeObj[key];if (value && typeof value === 'object') {@@ -50,7 +48,6 @@ export function collectDeclaredIdentifiers(ast: unknown): Set<string> {if (id.type === 'Identifier') {declared.add(id.name as string);}- // Handle destructuring patternsif (id.type === 'ObjectPattern') {collectPatternIdentifiers(id, declared);}@@ -75,9 +72,6 @@ export function collectDeclaredIdentifiers(ast: unknown): Set<string> {return declared;}-/**- * Collect identifiers from destructuring patterns- */function collectPatternIdentifiers(pattern: Record<string, unknown>,declared: Set<string>diff --git a/packages/core/src/shared/js-runtime/validate.test.ts b/packages/core/src/shared/js-runtime/validate.test.tsindex c08aa2e76..d26863b1e 100644--- a/packages/core/src/shared/js-runtime/validate.test.ts+++ b/packages/core/src/shared/js-runtime/validate.test.ts@@ -1,4 +1,3 @@-// Ported from packages/js-runtime/src/validate.test.ts (main #510, #511).import { describe, expect, it } from 'bun:test';import { execute, validate } from './index';@@ -10,7 +9,6 @@ describe('validate', () => {});it('should reject function expression', () => {- // Function expressions are not allowed - only arrow functionsconst result = validate('(function(payload) { return { event: payload.name }; })');diff --git a/packages/core/src/shared/js-runtime/validate.ts b/packages/core/src/shared/js-runtime/validate.tsindex ce7f16d20..6727f2bbb 100644--- a/packages/core/src/shared/js-runtime/validate.ts+++ b/packages/core/src/shared/js-runtime/validate.ts@@ -345,10 +345,6 @@ function validateCall(return undefined;}-/**- * Validates that a JavaScript function is safe to execute- * by checking the AST for allowed operations only (allowlist approach)- */export function validate(code: string): {valid: boolean;error?: string;@@ -368,7 +364,6 @@ export function validate(code: string): {return { valid: false, error: rootError };}- // Collect all declared identifiers (variables, parameters)const declaredIdentifiers = collectDeclaredIdentifiers(ast);const rootArrow = (((ast.program as unknown as Node).body as Node[])[0]! as Node@@ -377,7 +372,6 @@ export function validate(code: string): {let validationError: string | undefined;walkNode(ast, (node, parent) => {- // Skip if we already found an errorif (validationError) {return;}@@ -418,7 +412,6 @@ export function validate(code: string): {return;}- // Check identifiers that reference globalsif (type === 'Identifier') {const name = node.name as string;@@ -428,12 +421,10 @@ export function validate(code: string): {return;}- // Skip if it's a property key (not a value reference)if (isPropertyKey(node, parent)) {return;}- // Skip if it's a declared local variable/parameterif (declaredIdentifiers.has(name)) {return;}@@ -500,7 +491,6 @@ export function validate(code: string): {return;}- // Check 'new' expressions - only allow new Date()if (type === 'NewExpression') {const callee = node.callee as Node;diff --git a/packages/core/src/shared/parser-user-agent.test.ts b/packages/core/src/shared/parser-user-agent.test.tsindex 6f4736e63..22b2771fe 100644--- a/packages/core/src/shared/parser-user-agent.test.ts+++ b/packages/core/src/shared/parser-user-agent.test.ts@@ -1,8 +1,7 @@-// Subject moved to @openpanel/shared; the suite did not follow it. Nothing runs-// a `test` script in packages/shared yet — the root `test` script names its-// four workspaces explicitly and root package.json was outside M15-010's scope-// — so moving this file would take it out of every gate. Move it when that line-// can gain the filter.+// Subject moved to @openpanel/shared; the suite did not follow it. Nothing+// runs a `test` script in packages/shared yet — the root `test` script names+// its four workspaces explicitly — so moving this file would take it out of+// every gate. Move it when that line can gain the filter.import { describe, expect, it } from 'bun:test';import { getDevice, parseUserAgent } from '@openpanel/shared/server';diff --git a/packages/core/test/request-id-end-to-end.test.ts b/packages/core/test/request-id-end-to-end.test.tsindex 8b41905c2..021c0ed66 100644--- a/packages/core/test/request-id-end-to-end.test.ts+++ b/packages/core/test/request-id-end-to-end.test.ts@@ -1,20 +1,16 @@-// Benchmark 3 / ADR-018 R1 — the requestId chain, end to end, on all three-// paths core actually has. One file, three sections:+// The requestId chain, end to end, on all three paths core actually has. One+// file, three sections://-// 1. HTTP (P2-010's original): route log -> enqueued envelope meta -> job-// handler's logger -> the enqueue that job makes. Four hops, one id. 2. CHART:-// a REAL `ctx.services.chart` query, observed on the ClickHouse call's own-// `query info` line. This is the hop the `loadChClient` loaders failed silently-// — a module that reached @openpanel/db's client itself got a connection with-// no request scope, so the id stopped at the service boundary. 3. KAFKA/INGEST:-// the other edge. `createIncomingEventHandler` is the exact function apps/api's-// main.ts hands the consumer, and the seam under test — createCtx ->-// incomingEvent -> ctx.buffers / ctx.db / ctx.services — is the real one.-// Nothing in this section is mocked.-//-// Merged sections 2 and 3 in from their own files, so the property these three-// prove together — that no path loses the id — is one file's result rather than-// three that could drift apart.+// 1. HTTP: route log -> enqueued envelope meta -> job handler's logger -> the+// enqueue that job makes. Four hops, one id. 2. CHART: a real+// `ctx.services.chart` query, observed on the ClickHouse call's own `query+// info` line — the hop where a module that reached @openpanel/db's client+// directly would get a connection with no request scope, so the id stops at+// the service boundary. 3. KAFKA/INGEST: the other edge.+// `createIncomingEventHandler` is the exact function apps/api's main.ts hands+// the consumer, and the seam under test — createCtx -> incomingEvent ->+// ctx.buffers / ctx.db / ctx.services — is the real one. Nothing in this+// section is mocked.//// Each half is already covered next to its own code — `createCtx` scoping the// producers, `wrap` carrying `meta.requestId`, `runJob` reading it back. What@@ -63,15 +59,13 @@ interface ProofServices {const realServicesModule = { ...(await import('../src/services')) };// `Services` grows with every module that lands, so this proof mocks the whole-// container with a shape of its own rather than the real one — but the mock is-// a real service: built from the SCOPED ctx, logging to that request's logger-// and enqueueing through that request's producers. A hand-rolled function-// called from the route would skip exactly the seam under test. M10-009: the-// proof's `ingest.record` is layered ON TOP of the REAL container rather than-// replacing it — sections 2 and 3 below need `ctx.services.chart` and-// `ctx.services.session` to be the real ones. The mock is still a real service-// in the sense that matters: built from the SCOPED ctx, logging to that-// request's logger and enqueueing through that request's producers.+// container with a shape of its own rather than the real one. The mock is+// still a real service — built from the SCOPED ctx, logging to that request's+// logger and enqueueing through that request's producers — because a+// hand-rolled function called from the route would skip exactly the seam under+// test. It layers `ingest.record` ON TOP of the real container rather than+// replacing it, since sections 2 and 3 below need `ctx.services.chart` and+// `ctx.services.session` to stay the real ones.const createServices = mock((deps: ServiceDeps) => ({...realServicesModule.createServices(deps),ingest: {@@ -91,7 +85,7 @@ afterAll(() => {mock.module('../src/services', () => realServicesModule);});-// mock.module is not hoisted (AGENTS.md), so everything that reaches+// mock.module applies at call time, not hoisted, so everything that reaches// `services` through `context.ts` is imported here rather than at the top.let requestLogging: typeof import('../src/http/context').requestLogging;let defineRoutes: typeof import('../src/http/define').defineRoutes;@@ -109,9 +103,9 @@ beforeEach(() => {createServices.mockClear();});-// The seven registry queues declare no jobs yet — each module brings its own-// in P5-P8 — so the proof declares a queue of its own. Everything else on the-// path is the real machinery: real producers, real envelope, real runJob.+// The proof declares its own queue rather than borrowing a registry one.+// Everything else on the path is the real machinery: real producers, real+// envelope, real runJob.const proofQueue = defineQueue('proof', {jobs: {primary: defineJob({@@ -193,8 +187,8 @@ function stubDeps() {return { deps, lines, recorded: producers.recorded };}-// The health-mounted app of P2-009, plus the one route the proof needs: an-// enqueue has to start somewhere and no module owns a job yet.+// The health-mounted app, plus the one route the proof needs: an enqueue has+// to start somewhere and no module owns a job yet.function buildApp(deps: AppDeps) {const proofRoutes = defineRoutes((app) =>app.post('/proof/track', async ({ ctx }) => ({@@ -267,7 +261,7 @@ test('one requestId spans the route log, the enqueue, the job and its follow-upexpect(response.status).toBe(200);// The mock is the service hop; a silent miss would leave the chain intact- // and prove nothing (AGENTS.md).+ // and prove nothing.expect(createServices).toHaveBeenCalledTimes(1);expect(trail(lines, recorded)).toEqual({@@ -406,7 +400,7 @@ test("a chart query made through a request-scoped ctx logs the request's own reqexpect(response.status).toBe(200);// The query really ran through `deps.ch` — a silent miss would leave the- // logger assertion below trivially true (AGENTS.md).+ // logger assertion below trivially true.expect(chartQueries).toHaveLength(1);expect(chartQueries[0]?.query).toContain('FROM events');@@ -653,7 +647,6 @@ test("the envelope's requestId reaches the handler's logger, its buffer write anexpect(ingestHarness.eventsBuffered).toHaveLength(2);// Hop 3: the boundary's session_end job, enqueued through `ctx.services`.- // Before M10-006 this carried the boot scope's compat id.expect(ingestHarness.recorded.map(({ queue, job, meta }) => ({queue,@@ -669,12 +662,9 @@ test("the envelope's requestId reaches the handler's logger, its buffer write an]);});-// The notification dispatch used to reach Postgres and the `notification`-// producer through the deleted compat seam's BOOT scope, so every job it-// enqueued was stamped with that scope's id no matter which message triggered-// it. It takes the caller's scope now, and this is the hop that proves it: the-// binding enqueues exactly what `triggerNotification` enqueues, off the deps it-// was handed, and the envelope must carry the message's own id.+// The binding enqueues exactly what `triggerNotification` enqueues, off the+// deps it was handed, so the envelope must carry the message's own requestId,+// not a boot-scope one.test("a converted read path's own enqueue carries the message's requestId", async () => {const handleEvent = createIncomingEventHandler(ingestHarness.deps, {...ingestBindings,@@ -734,34 +724,27 @@ test('a second message is scoped to its own id, and an envelope without one stil});// ===========================================================================-// Section 4 — one request, one id, all six hops (ADR-022 A3).+// Section 4 — one request, one id, all six hops.// ===========================================================================//-// Sections 1-3 each prove a segment: 1 the HTTP -> job chain through a MOCKED-// service, 2 a real converted read path with no job behind it, 3 the Kafka-// edge. A3 names the property Carl actually asked for — "follow what has-// happened for a certain request, and see the entire flow" — as one chain, and-// the hops it lists are:-//-// RequestId minted at the edge -> ctx -> a service's bound logger ->-// producers.scope({ requestId }) -> the { payload, meta } envelope -> the job's-// child logger+// One chain end to end: requestId minted at the edge -> ctx -> a service's+// bound logger -> producers.scope({ requestId }) -> the { payload, meta }+// envelope -> the job's child logger.//// Nothing below is a stand-in for a hop. The read path is-// `ctx.services.chart.getRetentionSeries`, a REAL converted service reaching-// ClickHouse through `deps.ch`; the enqueue is-// `ctx.services.cohort.enqueueCompute`, a REAL service writing onto-// `ctx.queues`; the envelope is what `wrap` produces from what the recording-// producer captured; and the job is the REAL `cohortCompute` definition and the-// REAL handler off `jobs.registry.ts`, which reaches ClickHouse again — so the-// last hop is a converted read path INSIDE a job, observed on its own `query-// info` line.+// `ctx.services.chart.getRetentionSeries`, a real service reaching ClickHouse+// through `deps.ch`; the enqueue is `ctx.services.cohort.enqueueCompute`,+// writing onto `ctx.queues`; the envelope is what `wrap` produces from what+// the recording producer captured; and the job is the real `cohortCompute`+// definition and handler off `jobs.registry.ts`, which reaches ClickHouse+// again — so the last hop is a read path inside a job, observed on its own+// `query info` line.//-// Only the two connections are stubs, and both are the seam under test: the+// Only two things are stubs, and both are the seam under test: the// ClickHouse client records what it was asked and the Postgres client answers-// one row. A `load*` loader anywhere on this path, a client that built its own-// logger, or a handler that reached past `ctx` breaks exactly one of the-// assertions below and names itself.+// one row. A loader anywhere on this path, a client that built its own+// logger, or a handler that reached past `ctx` breaks exactly one assertion+// below and names itself.const CHAIN_REQUEST_ID = 'adr022-a3-one-request';const CHAIN_PROJECT_ID = 'chain-project';@@ -871,9 +854,9 @@ test('one requestId reaches a converted read path, a real enqueue, the envelopeexpect(response.status).toBe(200);- // Hop 3: a REAL service's ClickHouse call really ran, and its own log line+ // Hop 3: a real service's ClickHouse call really ran, and its own log line// carries the request's id. A silent miss here would leave every assertion- // below trivially true (AGENTS.md).+ // below trivially true.expect(queried).toHaveLength(1);expect(queried[0]).toContain('FROM events');expect(queryLineIds(lines)).toEqual([CHAIN_REQUEST_ID]);@@ -910,7 +893,7 @@ test('one requestId reaches a converted read path, a real enqueue, the envelopeexpect(inserted).toContain('cohort_metadata');// Every `query info` line in the process — the route's and the job's — is- // the same request. This is the assertion A3 exists for.+ // the same request.const allQueryIds = queryLineIds(lines);expect(allQueryIds.length).toBeGreaterThan(1);expect(new Set(allQueryIds)).toEqual(new Set([CHAIN_REQUEST_ID]));diff --git a/packages/db/src/clickhouse/client.ts b/packages/db/src/clickhouse/client.tsindex d3e92aab4..4686527e8 100644--- a/packages/db/src/clickhouse/client.ts+++ b/packages/db/src/clickhouse/client.ts@@ -92,11 +92,6 @@ export function isClickhouseClustered(): boolean {);}-/**- * Get the replicated table name for mutations- * In clustered mode, returns table_name_replicated- * In non-clustered mode, returns the original table name- */export function getReplicatedTableName(tableName: string): string {if (isClickhouseClustered()) {return `${tableName}_replicated ON CLUSTER '{cluster}'`;@@ -141,10 +136,10 @@ const maxOpenConnections = process.env.CLICKHOUSE_MAX_OPEN_CONNECTIONS): 50;-// Per-request timeout. Was 300_000 (5 min) — way too long for fast failover-// against a dead node, and after the Hetzner LB story we want stuck inserts-// to fail and retry on a different node well before 5 min. 30s is enough for-// any legitimate batch insert in this codebase. Bumpable via env if needed.+// Per-request timeout, lowered from 300_000 (5 min) — too long for fast+// failover against a dead node. Stuck inserts should fail and retry on a+// different node well before 5 min. 30s is enough for any legitimate batch+// insert in this codebase. Bumpable via env if needed.const requestTimeoutMs = process.env.CLICKHOUSE_REQUEST_TIMEOUT_MS? Math.max(1000,@@ -192,8 +187,8 @@ export const CLICKHOUSE_OPTIONS: NodeClickHouseClientConfigOptions = {// avoids putting an L4 LB on the hot path.//// Tests sometimes import this module without CLICKHOUSE_URL set; in that-// case we fall back to a single client created the same way the old code-// did (URL = undefined, delegated to the client library's own handling).+// case we fall back to a single client (URL = undefined, delegated to the+// client library's own handling).const rawClickhouseUrls = (process.env.CLICKHOUSE_URL ?? '').split(',').map((s) => s.trim())@@ -241,9 +236,10 @@ logger.info('ClickHouse clients initialized');-// Backwards-compat export. Some callers (notably gsc.ts) use `originalCh`-// directly to bypass the retry/round-robin layer for one-off DDL or for-// places where retry semantics aren't wanted. Points at the first node.+// Backwards-compat export. Some callers (notably gsc.service.ts) use+// `originalCh` directly to bypass the retry/round-robin layer for one-off+// DDL or for places where retry semantics aren't wanted. Points at the+// first node.export const originalCh = clients[0]!;const cleanQuery = (query?: string) =>diff --git a/packages/db/src/clickhouse/migration.ts b/packages/db/src/clickhouse/migration.tsindex 3460701bd..0a2a2f01f 100644--- a/packages/db/src/clickhouse/migration.ts+++ b/packages/db/src/clickhouse/migration.ts@@ -252,7 +252,6 @@ export function moveDataBetweenTables({}): string[] {const sqls: string[] = [];- // Build the SELECT clauseconst selectClause = columns && columns.length > 0 ? columns.join(', ') : '*';if (!batch) {@@ -272,7 +271,7 @@ export function moveDataBetweenTables({let currentDate = endDate;const interval = batch.interval || 'day';- // Helper function to get the start of the week (Monday) for a given date+ // Start of the week (Monday) for a given dateconst getWeekStart = (date: Date): Date => {const d = new Date(date);const day = d.getDay();@@ -282,15 +281,12 @@ export function moveDataBetweenTables({return d;};- // Helper function to compare dates based on intervalconst shouldContinue = (current: Date,start: Date,intervalType: string): boolean => {if (intervalType === 'month') {- // For months, compare by year and month- // Continue if current month is >= start monthconst currentYear = current.getFullYear();const currentMonth = current.getMonth();const startYear = start.getFullYear();@@ -301,7 +297,6 @@ export function moveDataBetweenTables({);}if (intervalType === 'week') {- // For weeks, compare by week start datesconst currentWeekStart = getWeekStart(current);const startWeekStart = getWeekStart(start);return currentWeekStart >= startWeekStart;@@ -451,11 +446,9 @@ export async function runClickhouseMigrationCommands(sqls: string[]) {}};- // Create bound handler functionsconst handleSigterm = () => handleTermination('SIGTERM');const handleSigint = () => handleTermination('SIGINT');- // Register handlersprocess.on('SIGTERM', handleSigterm);process.on('SIGINT', handleSigint);@@ -485,7 +478,7 @@ export async function runClickhouseMigrationCommands(sqls: string[]) {async function check() {if (checking) {- return; // Skip if already checking+ return;}checking = true;@@ -530,10 +523,9 @@ export async function runClickhouseMigrationCommands(sqls: string[]) {checking = false;}- timer = setTimeout(check, 5000); // Schedule next check after current one completes+ timer = setTimeout(check, 5000);}- // Start the first check after 5 secondstimer = setTimeout(check, 5000);}),]);@@ -567,14 +559,10 @@ export async function runClickhouseMigrationCommands(sqls: string[]) {throw e;} finally {- // Clean up event listeners. bun-types 1.4.0's `Process.off` override- // declares only its own "memoryPressure" overload and it wins over the- // @types/node Signals overload, so the cast is what keeps this compiling.- // M8-005 first hit this via `code-migrations/`, which pulled the file into- // core's bun-types-only compilation; M15-204 moved that directory into this- // package and the edge is gone, but `bun-types` leads packages/db's own- // `types` array too — verified 2026-09-11 by dropping the cast and running- // `tsc --noEmit` here (TS2345 on both lines).+ // Clean up event listeners. bun-types' `Process.off` override declares+ // only its own "memoryPressure" overload and wins over the @types/node+ // Signals overload, so the cast is what keeps this compiling (dropping it+ // produces TS2345 on both lines below).const emitter = process as unknown as EventEmitter;emitter.off('SIGTERM', handleSigterm);emitter.off('SIGINT', handleSigint);diff --git a/packages/db/src/clickhouse/sql.clickhouse.test.ts b/packages/db/src/clickhouse/sql.clickhouse.test.tsindex bfcd52f9c..703760b71 100644--- a/packages/db/src/clickhouse/sql.clickhouse.test.ts+++ b/packages/db/src/clickhouse/sql.clickhouse.test.ts@@ -2,9 +2,9 @@ import { describe, expect, it } from 'bun:test';import { sql } from './sql';/**- * The ADR-013 P2 round-trip: every param type the codebase uses, bound through- * `chQuery` (so the `query_params` path is exercised through `withRetry` /- * round-robin, R1) and read back off a real local ClickHouse.+ * Every param type the codebase uses, bound through `chQuery` (so the+ * `query_params` path is exercised through `withRetry` / round-robin) and+ * read back off a real local ClickHouse.** Payloads are hostile on purpose — single quote, double quote, backslash,* newline, tab, and a literal `{p1:String}` — because the escaping lives in the@@ -249,10 +249,8 @@ describeAgainstClickhouse('param round-trip against local ClickHouse', () => {});/**- * Identifier positional matrix — measured against ClickHouse 26.1.3.52 on- * 2026-09-02. This is the split ADR-013 risk 3 says is unknown until P2 runs:- * where `{x:Identifier}` works, and where a call site must use `sql.id()`- * (validated inline text) instead.+ * Identifier positional matrix: where `{x:Identifier}` works, and where a+ * call site must use `sql.id()` (validated inline text) instead.** | Position | `{x:Identifier}` |* |--------------------------------------------|------------------|@@ -270,10 +268,9 @@ describeAgainstClickhouse('param round-trip against local ClickHouse', () => {* | `'alias.column'` in ONE param | FAILS — quoted whole |* | SETTINGS value (`session_timezone = {…}`) | FAILS — syntax error, any type |*- * Consequences for the P5-P8 conversions:- * - qualified names are two params, or one `sql.id('profiles.name')`;- * - a per-query `session_timezone` goes through `chQuery`'s- * `clickhouse_settings` argument, not through the SQL text.+ * Consequences: a qualified name is two params, or one+ * `sql.id('profiles.name')`; a per-query `session_timezone` goes through+ * `chQuery`'s `clickhouse_settings` argument, not through the SQL text.*/describeAgainstClickhouse('Identifier positional matrix', () => {const table = sql.identifier('events');@@ -379,8 +376,8 @@ describeAgainstClickhouse('local builder fallback executes (R5)', () => {const PROFILE_COLUMNS = ['first_name', 'last_name'] as const;it('binds every value the imperative assembly produced', async () => {- // R5 permits local assembly; it does not permit unbound text. Hostile- // values go in as data and the server matches nothing.+ // Local assembly is permitted; unbound text is not. Hostile values go in+ // as data and the server matches nothing.const filters = [{ column: 'first_name', value: HOSTILE },{ column: 'last_name', value: "' OR 1=1 --" },diff --git a/packages/db/src/clickhouse/sql.round-robin.clickhouse.test.ts b/packages/db/src/clickhouse/sql.round-robin.clickhouse.test.tsindex bca1517b4..350a9c815 100644--- a/packages/db/src/clickhouse/sql.round-robin.clickhouse.test.ts+++ b/packages/db/src/clickhouse/sql.round-robin.clickhouse.test.ts@@ -2,7 +2,7 @@ import { describe, expect, it } from 'bun:test';import { sql } from './sql';/**- * R1, the half the round-trip suite cannot reach: bound params must travel+ * The half the round-trip suite cannot reach: bound params must travel* through `withRetry` / round-robin, so a parameterised read keeps the failover* behaviour `chQueryWithMeta` already had for raw text.*diff --git a/packages/db/src/clickhouse/sql.test.ts b/packages/db/src/clickhouse/sql.test.tsindex c57c07e91..529e5c928 100644--- a/packages/db/src/clickhouse/sql.test.ts+++ b/packages/db/src/clickhouse/sql.test.ts@@ -3,9 +3,10 @@ import { type SqlFragment, SqlIdentifierError, sql, toStatement } from './sql';describe('sql tag — slot typing (R1)', () => {it('is a compile-time error to interpolate a bare value', () => {- // The whole safety property of ADR-013: a raw string or number can never- // reach the SQL text. If either of these ever stops erroring, injection has- // become writable again and `pnpm run typecheck` is the alarm.+ // The whole point of this type constraint: a raw string or number can+ // never reach the SQL text. If either of these ever stops erroring,+ // injection has become writable again and `pnpm run typecheck` is the+ // alarm.const path = "/blog' OR '1'='1";// @ts-expect-error — a bare string is not a SqlFragment | SqlParamconst withString = sql`SELECT * FROM events WHERE path = ${path}`;@@ -237,7 +238,7 @@ describe('injection (ported from query-builder.test.ts)', () => {const payload = '/blog/2024-03-17-supabase-activity-scheduler';const { query_params } = bind(payload);- // clix re-quoted any date-shaped substring in place; binding cannot.+ // A date-shaped substring must not be re-quoted or altered; it binds as-is.expect(query_params.p1).toBe(payload);});@@ -248,12 +249,6 @@ describe('injection (ported from query-builder.test.ts)', () => {expect(query_params.p1).toBe('{p1:String}');});- // Completed the port: the four cases below were still only asserted against- // clix when query-builder.test.ts was deleted. Each keeps that test's- // payload; what changes is the mechanism the payload proves — clix asserted- // on the escaped literal it produced, the tag asserts the value never reaches- // the text at all.-it('binds a plain ISO date string instead of quoting it', () => {const { query, query_params } =sql`SELECT * FROM events WHERE e.created_at = ${sql.string('2026-04-29 00:00:00')}`.toStatement();@@ -273,9 +268,8 @@ describe('injection (ported from query-builder.test.ts)', () => {});it('keeps a toDateTime() wrapper as SQL text with the value bound', () => {- // clix.datetime(date, 'toDateTime') produced the call AND the quoted- // literal in one string. The wrapper is structure and stays raw; the- // value is a value and binds.+ // The `toDateTime(...)` wrapper is SQL structure and stays raw; the+ // value inside it is a value and binds.const { query, query_params } =sql`SELECT * FROM events WHERE e.created_at = toDateTime(${sql.string('2026-04-29 00:00:00')})`.toStatement();diff --git a/packages/db/src/clickhouse/sql.ts b/packages/db/src/clickhouse/sql.tsindex eed7b04ab..d456e2756 100644--- a/packages/db/src/clickhouse/sql.ts+++ b/packages/db/src/clickhouse/sql.ts@@ -15,11 +15,7 @@* string to SQL text is {@link SqlBuilder.id}, which validates and throws.** Placeholder names are assigned at render time from a single counter, so- * fragments nest and repeat without colliding (R2).- *- * Exported from the package barrel. It could not be during the clix coexistence- * window — `query-builder.ts` exported its own `SqlParam` type and `export *`- * from both was ambiguous — and that file is now deleted.+ * fragments nest and repeat without colliding.** `packages/core` still imports this module by its deep path rather than* through the barrel: the barrel also re-exports `clickhouse/client.ts` and@@ -251,7 +247,7 @@ interface SqlBuilder {* Inline a validated identifier as SQL text, for the positions where* `{name:Identifier}` does not work. Throws on anything that is not a bare* (optionally once-qualified) identifier — it never falls back to- * interpolating the input (R3). Pass `allowed` wherever the call site has a+ * interpolating the input. Pass `allowed` wherever the call site has a* closed column set.*/id(name: string, allowed?: readonly string[]): SqlFragment;diff --git a/packages/db/src/code-migrations/16-restructure-profiles.ts b/packages/db/src/code-migrations/16-restructure-profiles.tsindex 8a67382fc..456109887 100644--- a/packages/db/src/code-migrations/16-restructure-profiles.ts+++ b/packages/db/src/code-migrations/16-restructure-profiles.ts@@ -161,7 +161,6 @@ export async function up(env: CodeMigrationEnv) {SETTINGS insert_distributed_sync = 1`);- // Stop once we've processed the month containing the oldest profile.if (lower.getFullYear() === startDate.getFullYear() &&lower.getMonth() === startDate.getMonth()diff --git a/packages/db/src/code-migrations/19-event-property-values-projections.ts b/packages/db/src/code-migrations/19-event-property-values-projections.tsindex 9aa48589b..b0841ced6 100644--- a/packages/db/src/code-migrations/19-event-property-values-projections.ts+++ b/packages/db/src/code-migrations/19-event-property-values-projections.ts@@ -103,7 +103,7 @@ const PROJECTIONS = [//// `CREATE ... ON CLUSTER` propagates the initiator's uuid, so the inner// table has the same name on every node and a single ON CLUSTER ALTER-// reaches all of them (verified on our deployment: 4 hosts, one uuid).+// reaches all of them.async function resolveStorageTable(isClustered: boolean): Promise<string> {const view = isClustered ? `${MV}_replicated` : MV;const res = await chMigrationClient.query({diff --git a/packages/db/src/code-migrations/20-cohort-summary-mv-sort-key.ts b/packages/db/src/code-migrations/20-cohort-summary-mv-sort-key.tsindex 03fcc14f2..c38a7711b 100644--- a/packages/db/src/code-migrations/20-cohort-summary-mv-sort-key.ts+++ b/packages/db/src/code-migrations/20-cohort-summary-mv-sort-key.ts@@ -15,11 +15,9 @@ import { type CodeMigrationEnv, getIsCluster, writeSqlDump } from './helpers';* property, then GROUP BY profile_id — they never filter profile_id. With* profile_id second, the usable key prefix ends at project_id, so every* criterion reads the project's entire slice of the MV however narrow the- * criterion is. Cohorts run one such query per criterion, on a schedule.- *- * Measured on a ~100M-row summary MV: a criterion that can only prune on- * project_id reads 103,985,861 rows (10.9s); the same criterion with name- * and event_date in the key prefix reads 115,141 rows (0.11s).+ * criterion is (measured on a ~100M-row MV: ~900x fewer rows read, 10.9s ->+ * 0.11s, with name and event_date in the key prefix). Cohorts run one such+ * query per criterion, on a schedule.** A sort key cannot be altered in place, so this creates replacement MVs* keyed for the consumer:diff --git a/packages/db/src/code-migrations/23-sessions-id-index.ts b/packages/db/src/code-migrations/23-sessions-id-index.tsindex c8d461e95..bc9858df5 100644--- a/packages/db/src/code-migrations/23-sessions-id-index.ts+++ b/packages/db/src/code-migrations/23-sessions-id-index.ts@@ -22,31 +22,17 @@ import { type CodeMigrationEnv, getIsCluster } from './helpers';* here: `id` is not in the sort key, so one session's rows can legitimately* sit in different granules.*- * That expansion is also what caps the win. Measured on the restored- * production copy, busiest anchor project (`chatpaper`, 6,224,393 session- * rows, 736 candidate granules across 9 parts), five sessions x three runs:- *- * without the index 3,124-3,431 ms 6,224,393 rows 1.44 GB read- * with the index 170-342 ms 294,885-524,267 rows 70-124 MB read- *- * 13x, not the ~90x the granule counts suggest: the bloom filter selects- * 5-10 of 736 granules, PrimaryKeyExpand widens that back to 26-45 because- * each selected granule drags its whole primary-key range through all 9- * parts. `event.details` is the same query plus a 11-22 ms events lookup, so- * it moves with it (3,140 ms -> ~250 ms).+ * That expansion also caps the win: each selected granule drags its whole+ * primary-key range through every part, so the observed speedup (~13x on a+ * 6.2M-row project) is well short of the ~90x the raw granule count suggests.** ADD INDEX is metadata-only and covers newly written parts; MATERIALIZE* INDEX backfills the existing ones. The mutation is asynchronous (this- * migration does not block on it) and idempotent, reads only the `id` column- * and writes small .idx files — it does not rewrite table data. Progress:+ * migration does not block on it), idempotent, reads only the `id` column and+ * writes small .idx files — it does not rewrite table data. Progress:** SELECT * FROM system.mutations WHERE command LIKE '%idx_id%';*- * Cost of the backfill, measured over 29,401,478 rows in 14 parts: the ALTER- * returns in under 50 ms and the mutation completed 1.1-1.2 s later on four- * consecutive runs (1122 / 1161 / 1172 / 1176 ms from submit to is_done). It- * only reads `id`, so it is bounded by one column, not by the table.- ** ROLLBACK. The index is droppable and nothing reads it explicitly, so* reverting is a single statement — `down()` below, or by hand:*@@ -55,12 +41,10 @@ import { type CodeMigrationEnv, getIsCluster } from './helpers';* Clustered:* ALTER TABLE sessions_replicated ON CLUSTER '{cluster}' DROP INDEX IF EXISTS idx_id;*- * DROP INDEX removes the .idx files from every part (0.5-0.9 s here, also- * measured), so nothing has to be re-materialised to undo it. Re-applying- * afterwards means running this migration again, i.e. ADD INDEX followed by- * MATERIALIZE INDEX — the two statements below, in that order. Queries keep- * answering correctly with or without the index; only the row count they- * scan changes.+ * Re-applying afterwards means running this migration again, i.e. ADD INDEX+ * followed by MATERIALIZE INDEX — the two statements below, in that order.+ * Queries keep answering correctly with or without the index; only the row+ * count they scan changes.*/const INDEX_NAME = 'idx_id';@@ -69,17 +53,15 @@ const INDEX_NAME = 'idx_id';* 0.01 to match `events.idx_profile_id`, the existing index over the same* shape of column (a high-cardinality opaque id).*- * Size: 35.20 MiB over 29,401,478 rows, measured on the restored production- * copy after this migration ran — ~9.8 KiB per 8192-row granule, against a- * ~4 MiB estimate that scaled `events.idx_profile_id` (40.95 MiB / 321 M- * rows) by row count. `id` is unique per row, so every granule's filter is- * saturated; `profile_id` repeats heavily inside a granule. A bloom filter's- * size follows granule count, not the rows behind it.+ * `id` is unique per row, so every granule's bloom filter is saturated,+ * unlike `profile_id` which repeats heavily inside a granule — a bloom+ * filter's size follows granule count, not the rows behind it, so this index+ * (35 MiB over 29.4M rows) comes out larger than a row-count-scaled estimate+ * from `events.idx_profile_id` would suggest.*- * Tightening the rate does not pay for itself: 0.001 costs 52.79 MiB for- * 73-179 ms, 0.0001 costs 66.87 MiB for 75-128 ms, and even a- * false-positive-free index still reads 90,106 rows per lookup because- * PrimaryKeyExpand walks one true granule through all 9 parts.+ * Tightening the rate does not pay for itself: it costs tens of MiB more for+ * a marginal drop in read time, and even a false-positive-free index still+ * pays PrimaryKeyExpand's cost of walking one true granule through every part.*/const FALSE_POSITIVE_RATE = 0.01;const GRANULARITY = 1;diff --git a/packages/db/src/code-migrations/constants.ts b/packages/db/src/code-migrations/constants.tsindex 671db4386..9a4ca2b06 100644--- a/packages/db/src/code-migrations/constants.ts+++ b/packages/db/src/code-migrations/constants.ts@@ -1,12 +1,9 @@// The vocabulary these one-shot migrations need, COPIED from packages/core-// rather than imported from it.-//-// ADR-022, Carl's rulings: "I'd rather have code-migrations isolated from core,-// so I'd rather duplicate code for this to be isolated." A migration reads rows-// written by a past version of the app, so it must keep describing the shape-// that existed when it was written — an import of the live-// `report.constants.ts` would silently redefine what migration 7 and 9 mean the-// next time someone edits a chart segment.+// rather than imported from it. Code-migrations are deliberately isolated+// from core: a migration reads rows written by a past version of the app, so+// it must keep describing the shape that existed when it was written — an+// import of the live `report.constants.ts` would silently redefine what+// migration 7 and 9 mean the next time someone edits a chart segment.//// Sources at the time of the move (2026-09-11), for anyone diffing:// packages/core/src/modules/report/report.constants.ts (the chart types)diff --git a/packages/db/src/code-migrations/helpers.ts b/packages/db/src/code-migrations/helpers.tsindex 3ddbaf2f5..79d1a70aa 100644--- a/packages/db/src/code-migrations/helpers.ts+++ b/packages/db/src/code-migrations/helpers.ts@@ -38,7 +38,7 @@ export function printBoxMessage(title: string, lines: (string | unknown)[]) {/*** The environment this script needs, read by its shell* (`packages/db/scripts/migrate-code.ts`) rather than here, so no migration- * file reads `process.env` (which travelled with the move).+ * file reads `process.env`.*/export interface CodeMigrationEnv {clickhouseCluster: boolean;diff --git a/packages/db/src/logger.ts b/packages/db/src/logger.tsindex 6f73fc6af..1a8f735aa 100644--- a/packages/db/src/logger.ts+++ b/packages/db/src/logger.ts@@ -1,11 +1,11 @@-// Self-contained pino instantiation. packages/db is a leaf "stays" package-// (TARGET_ARCHITECTURE §7) and must not reach into @openpanel/core just to-// build a logger — that direction is backwards, since core itself depends on-// db. This is the same implementation @openpanel/core/clients/logger.ts carries-// (both descend from the pre-dissolve @openpanel/logger package) — duplicated-// here deliberately rather than shared, because there is no home narrower than-// "the package itself" that both can reach without reintroducing the db <->-// core cycle this file exists to remove.+// Self-contained pino instantiation. packages/db is a leaf package and must+// not reach into @openpanel/core just to build a logger — that direction is+// backwards, since core itself depends on db.+//+// This is the same implementation @openpanel/core's `src/pino-logger.ts`+// carries, duplicated here deliberately rather than shared: there is no home+// narrower than "the package itself" that both can reach without+// reintroducing the db <-> core cycle this file exists to avoid.import * as HyperDX from '@hyperdx/node-opentelemetry';import pino, { type Logger as PinoLogger } from 'pino';@@ -15,7 +15,7 @@ export type ILogger = PinoLogger;const logLevel = process.env.LOG_LEVEL ?? 'info';const silent = process.env.LOG_SILENT === 'true';-// Exactly one shipping path at a time (see logging-capture-plan.md):+// Exactly one shipping path at a time:// - 'otlp': pino ships via the HyperDX transport (requires HYPERDX_API_KEY).// - 'stdout': pino writes JSON to stdout; an external collector ships it.const logExporter =@@ -91,9 +91,9 @@ function getServiceName(name: string): string {.join('-');}-// Same Bun/pino-pretty incompatibility as @openpanel/core/clients/logger.ts's-// `isBun` guard — see its comment. Kept in sync by hand, like the rest of-// this file.+// Same Bun/pino-pretty incompatibility as @openpanel/core's+// `src/pino-logger.ts`'s `isBun` guard — see its comment. Kept in sync by+// hand, like the rest of this file.const isBun = !!process.versions.bun;export function createLogger({ name }: { name: string }): ILogger {diff --git a/packages/db/src/types.ts b/packages/db/src/types.tsindex 465e70a66..77bbf8828 100644--- a/packages/db/src/types.ts+++ b/packages/db/src/types.ts@@ -1,14 +1,7 @@-// `IClickhouseEvent`/`IClickhouseBotEvent`/`IClickhouseProfile`/-// `INotificationPayload` all moved to @openpanel/core (M9-CLEANUP-001,-// packages/db's final-surface shrink) — the three local re-export shims that-// used to bridge them are gone. This is the type-only `db -> core` back-edge-// ADR-007 named and explicitly declined to resolve ("belongs to P8's db-// slim-down"; three options, none picked). Taken here: option 3, "accept a-// declared type-only devDependency edge" — `@openpanel/db` already depends on-// `@openpanel/core` (these shims were the reason), the edge is `import type`-// only so it creates no runtime cycle, and it is the same shape as this repo's-// existing type-only `db -> queue` cycle. Revisit if a future task picks a-// different one of the three named resolutions.+// `@openpanel/db` takes a type-only `db -> core` dependency edge here,+// accepted deliberately: `@openpanel/db` already depends on `@openpanel/core`,+// the edge is `import type` only so it creates no runtime cycle, and it is+// the same shape as this repo's existing type-only `db -> queue` cycle.import type {IClickhouseBotEvent,IClickhouseEvent,@@ -69,7 +62,7 @@ declare global {};// Steps of the wind-down sequence, in order. The column stores the last// step whose email was sent; `blocked` and `final_warning` also mean- // ingestion is rejected. See apps/worker/src/jobs/cron.wind-down.ts.+ // ingestion is rejected.type IPrismaWindDownStep =| 'expired_notice'| 'stopping_soon'diff --git a/packages/payments/src/polar.ts b/packages/payments/src/polar.tsindex 38376fcc1..c96114b41 100644--- a/packages/payments/src/polar.ts+++ b/packages/payments/src/polar.ts@@ -1,4 +1,3 @@-// src/polar.tsimport { Polar } from '@polar-sh/sdk';export {diff --git a/packages/redis/cachable.test.ts b/packages/redis/cachable.test.tsindex a9489679a..edaf15157 100644--- a/packages/redis/cachable.test.ts+++ b/packages/redis/cachable.test.ts@@ -8,7 +8,6 @@ describe('cachable', () => {beforeEach(async () => {redis = getRedisCache();- // Clear any existing cache data for clean testsconst keys = [...(await redis.keys('cachable:*')),...(await redis.keys('test-key*')),@@ -19,7 +18,6 @@ describe('cachable', () => {});afterEach(async () => {- // Clean up after each testconst keys = [...(await redis.keys('cachable:*')),...(await redis.keys('test-key*')),@@ -35,7 +33,6 @@ describe('cachable', () => {const mockDate = new Date('2023-01-01T00:00:00Z');const cachedData = { ...mockData, createdAt: mockDate };- // First, cache some dataawait redis.setex('test-key', 3600, JSON.stringify(cachedData));let fnCalled = false;@@ -64,7 +61,6 @@ describe('cachable', () => {expect(result).toEqual(mockData);expect(fnCalled).toBe(true);- // Verify it was cachedconst cached = await redis.get('test-key-2');expect(cached).toBe(JSON.stringify(mockData));});@@ -73,7 +69,6 @@ describe('cachable', () => {const mockDate = new Date('2023-01-01T00:00:00Z');const cachedData = { id: 1, createdAt: mockDate };- // Cache the data firstawait redis.setex('test-key', 3600, JSON.stringify(cachedData));let fnCalled = false;@@ -106,7 +101,6 @@ describe('cachable', () => {expect(result).toEqual(mockData);expect(fnCalled).toBe(true);- // Verify it was cachedconst key = cachedFn.getKey('arg1', 'arg2');const cached = await redis.get(key);expect(cached).toBe(JSON.stringify(mockData));@@ -127,7 +121,6 @@ describe('cachable', () => {expect(result).toEqual(mockData);expect(fnCalled).toBe(true);- // Verify it was cachedconst key = cachedFn.getKey('arg1', 'arg2');const cached = await redis.get(key);expect(cached).toBe(JSON.stringify(mockData));@@ -136,7 +129,6 @@ describe('cachable', () => {it('should return cached result when available', async () => {const mockData = { id: 1, name: 'test' };- // First cache some dataconst cachedFn = cacheable('testFunction',async (arg1: string, arg2: string) => mockData,@@ -144,7 +136,6 @@ describe('cachable', () => {);await cachedFn('arg1', 'arg2');- // Now test that it returns cached datalet fnCalled = false;const fn = async (arg1: string, arg2: string) => {fnCalled = true;@@ -171,7 +162,6 @@ describe('cachable', () => {expect(result).toBeUndefined();expect(fnCalled).toBe(true);- // Verify nothing was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBeNull();@@ -190,7 +180,6 @@ describe('cachable', () => {expect(result).toBeNull();expect(fnCalled).toBe(true);- // Verify nothing was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBeNull();@@ -209,7 +198,6 @@ describe('cachable', () => {expect(result).toBe('');expect(fnCalled).toBe(true);- // Verify nothing was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBeNull();@@ -228,7 +216,6 @@ describe('cachable', () => {expect(result).toEqual([]);expect(fnCalled).toBe(true);- // Verify nothing was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBeNull();@@ -247,7 +234,6 @@ describe('cachable', () => {expect(first).toEqual([]);expect(callCount).toBe(1);- // Verify it was written to Redisconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBe('[]');@@ -265,7 +251,6 @@ describe('cachable', () => {return [] as number[];};- // First instance writes the empty array into Redisconst firstCachedFn = cacheable('sharedEmptyArrayFn', firstFn, 3600, {cacheEmptyArray: true,});@@ -347,7 +332,6 @@ describe('cachable', () => {expect(result).toEqual({});expect(fnCalled).toBe(true);- // Verify nothing was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBeNull();@@ -366,7 +350,6 @@ describe('cachable', () => {expect(result).toBe('hello');expect(fnCalled).toBe(true);- // Verify it was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBe('"hello"');@@ -385,7 +368,6 @@ describe('cachable', () => {expect(result).toEqual([1, 2, 3]);expect(fnCalled).toBe(true);- // Verify it was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBe('[1,2,3]');@@ -404,7 +386,6 @@ describe('cachable', () => {expect(result).toEqual({ id: 1 });expect(fnCalled).toBe(true);- // Verify it was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBe('{"id":1}');@@ -423,7 +404,6 @@ describe('cachable', () => {expect(result).toBe(true);expect(fnCalled).toBe(true);- // Verify it was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBe('true');@@ -442,7 +422,6 @@ describe('cachable', () => {expect(result).toBe(42);expect(fnCalled).toBe(true);- // Verify it was cachedconst key = cachedFn.getKey('arg1');const cached = await redis.get(key);expect(cached).toBe('42');@@ -451,7 +430,6 @@ describe('cachable', () => {it('should handle cache parsing errors gracefully', async () => {const mockData = { id: 1, name: 'test' };- // First, manually set invalid JSON in cacheconst cachedFn = cacheable('testFunction',async (arg1: string) => mockData,@@ -460,9 +438,9 @@ describe('cachable', () => {const key = cachedFn.getKey('arg1');await redis.set(key, 'invalid json');- const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {- // noop- });+ const consoleSpy = vi+ .spyOn(console, 'error')+ .mockImplementation(() => {});let fnCalled = false;const fn = async (arg1: string) => {@@ -487,7 +465,6 @@ describe('cachable', () => {const mockDate = new Date('2023-01-01T00:00:00Z');const cachedData = { id: 1, createdAt: mockDate };- // First cache some data with Dateconst cachedFn = cacheable('testFunction',async (arg1: string) => cachedData,@@ -495,7 +472,6 @@ describe('cachable', () => {);await cachedFn('arg1');- // Now test that it returns cached data with proper Date parsinglet fnCalled = false;const fn = async (arg1: string) => {fnCalled = true;@@ -523,19 +499,15 @@ describe('cachable', () => {const fn = async (arg1: string, arg2: string) => ({ id: 1 });const cachedFn = cacheable(fn, 3600);- // First cache some dataawait cachedFn('arg1', 'arg2');- // Verify it's cachedconst key = cachedFn.getKey('arg1', 'arg2');let cached = await redis.get(key);expect(cached).not.toBeNull();- // Clear itconst result = await cachedFn.clear('arg1', 'arg2');expect(result).toBe(1);- // Verify it's clearedcached = await redis.get(key);expect(cached).toBeNull();});@@ -547,7 +519,6 @@ describe('cachable', () => {const payload = { id: 1, name: 'test' };await cachedFn.set('arg1', 'arg2')(payload);- // Verify it was setconst key = cachedFn.getKey('arg1', 'arg2');const cached = await redis.get(key);expect(cached).toBe(JSON.stringify(payload));diff --git a/packages/redis/cachable.ts b/packages/redis/cachable.tsindex ae46a69cc..c446d995e 100644--- a/packages/redis/cachable.ts+++ b/packages/redis/cachable.ts@@ -7,10 +7,9 @@ export const deleteCache = (key: string) => {return getRedisCache().del(key);};-// Global LRU cache for getCache functionconst globalLruCache = new LRUCache<string, any>({- max: 5000, // Store up to 5000 entries- ttl: 1000 * 60, // 1 minutes default TTL+ max: 5000,+ ttl: 1000 * 60,});export async function getCache<T>(@@ -19,7 +18,6 @@ export async function getCache<T>(fn: () => Promise<T>,useLruCache?: boolean): Promise<T> {- // L1 Cache: Check global LRU cache first (in-memory, instant)if (useLruCache) {const lruHit = globalLruCache.get(key);if (lruHit !== undefined) {@@ -27,37 +25,32 @@ export async function getCache<T>(}}- // L2 Cache: Check Redis cache (shared across instances)const hit = await getRedisCache().get(key);if (hit) {const parsed = parseCache(hit);- // Store in LRU cache for next timeif (useLruCache) {globalLruCache.set(key, parsed, {- ttl: expireInSec * 1000, // Use the same TTL as Redis+ ttl: expireInSec * 1000,});}return parsed;}- // Cache miss: Execute functionconst data = await fn();- // Store in both cachesif (useLruCache) {globalLruCache.set(key, data, {ttl: expireInSec * 1000,});}- // Fire and forget Redis write for better performance+ // Fire-and-forget: the caller does not wait on the Redis write.getRedisCache().setex(key, expireInSec, JSON.stringify(data));return data;}-// Helper functions for managing global LRU cacheexport function clearGlobalLruCache(key?: string) {if (key) {return globalLruCache.delete(key);@@ -105,7 +98,6 @@ function stringify(obj: unknown): string {return pairs.join(':');}- // Fallback for any other typesreturn String(obj);}@@ -114,12 +106,10 @@ export interface CacheableOptions {}function shouldCache(result: unknown, options: CacheableOptions = {}): boolean {- // Don't cache undefined or nullif (result === undefined || result === null) {return false;}- // Don't cache empty stringsif (typeof result === 'string') {return result.length > 0;}@@ -128,12 +118,10 @@ function shouldCache(result: unknown, options: CacheableOptions = {}): boolean {return options.cacheEmptyArray ? true : result.length > 0;}- // Don't cache empty objectsif (typeof result === 'object' && result !== null) {return Object.keys(result).length > 0;}- // Cache everything else (booleans, numbers, etc.)return true;}@@ -153,7 +141,7 @@ const parseCache = (cached: string) => {};// L1 cache: short TTL to offload Redis; clear() invalidates Redis, other nodes may serve stale from LRU for up to this long-const CACHEABLE_LRU_TTL_MS = 60 * 1000; // 60 seconds+const CACHEABLE_LRU_TTL_MS = 60 * 1000;const CACHEABLE_LRU_MAX = 1000;// Overload 1: cacheable(fn, expireInSec, options?)@@ -201,7 +189,6 @@ export function cacheable<T extends (...args: any) => any>(let expireInSec: number | null = null;let options: CacheableOptions = {};- // Parse parameters based on function signatureif (typeof fnOrName === 'function') {// Overload 1: cacheable(fn, expireInSec, options?)expireInSec = typeof fnOrExpireInSec === 'number' ? fnOrExpireInSec : null;@@ -256,7 +243,6 @@ export function cacheable<T extends (...args: any) => any>(}}- // Cache miss: execute functionconst result = await fn(...(args as any));if (shouldCache(result, options)) {diff --git a/packages/redis/dead-letter.ts b/packages/redis/dead-letter.tsindex 8871b0406..6cf95d6e5 100644--- a/packages/redis/dead-letter.ts+++ b/packages/redis/dead-letter.ts@@ -1,17 +1,12 @@/*** The ingest consumer's dead-letter destination: a capped Redis list.*- * Carl, 2026-09-14: *"For now, we can just store errors in redis and drop the- * event, push it to a redis list and only keep the last N events."*- *- * It replaces `produceDeadLetterEvent`, which produced to- * `${KAFKA_EVENTS_TOPIC}-dlq` — a topic nothing in the tree ever creates. Drill- * 08 measured that produce failing 1,592 times with 0 successes (`Number of- * partitions is invalid`), and the failure left the offset unresolved, which is- * the unbounded handler-error redelivery loop drill 02's re-run 2 measured at- * 78-79 laps per message. The Kafka producer is still exported from- * `@openpanel/core`, and the consumer's `sendToDeadLetter` seam is unchanged,- * so swapping back is one line in `apps/api`'s wiring.+ * It replaces `produceDeadLetterEvent`, which produced to a Kafka DLQ topic+ * that was never created — that failure left the offset unresolved, which+ * caused an unbounded handler-error redelivery loop (dozens of laps per+ * message). The Kafka producer is still exported from `@openpanel/core`, and+ * the consumer's `sendToDeadLetter` seam is unchanged, so swapping back is+ * one line in `apps/api`'s wiring.** THE RECORD IS A DEBUGGING SAMPLE, NOT A RECOVERY MECHANISM. The list keeps* the last N and nothing more; the event itself is gone from the pipeline. The@@ -19,11 +14,11 @@* `_dead_letter_failed_total`, because a capped list makes 50,000 drops look* exactly like 12.*- * Why here and not in `packages/core`'s ingest module: the whole of it is Redis- * mechanics — one MULTI, one LPUSH, one LTRIM — and core's only export door is- * its barrel, which M20-001's scope does not cover. The input type is- * structural, so `DeadLetterMessage` (kafkajs `Buffer`s and `IHeaders`)- * satisfies it without this package depending on kafkajs or on core.+ * Why here and not in `packages/core`'s ingest module: the whole of it is+ * Redis mechanics — one MULTI, one LPUSH, one LTRIM — and core's only export+ * door is its barrel. The input type is structural, so `DeadLetterMessage`+ * (kafkajs `Buffer`s and `IHeaders`) satisfies it without this package+ * depending on kafkajs or on core.*//** The one list. Not configurable: an operator has to be able to find it. */diff --git a/packages/redis/duplicate-marker.ts b/packages/redis/duplicate-marker.tsindex 2ff72ae35..15af3a48a 100644--- a/packages/redis/duplicate-marker.ts+++ b/packages/redis/duplicate-marker.ts@@ -1,39 +1,30 @@/*** The ingest consumer's duplicate MARKER.*- * Carl, 2026-09-14, on the offset watermark this replaces: *"are they purely- * for logging reprocessed? Then we should remove them, i dont care. we can use- * the redis check we talked about earlier to mark if it was a duplicate- * event?"*- ** It is keyed on the EVENT, not on a Kafka offset. The event `id` is- * producer-minted, so a redelivered message re-presents the same id — drill 08- * confirmed all 161 of its duplicates were byte-identical replays sharing one- * `id`, one `created_at` and one `session_id`. A key therefore survives- * restarts, rebalances, evictions and process boundaries, none of which the- * in-process watermark survived: drill 08 measured 161 real duplicates and 0- * `REPROCESSED` lines.+ * producer-minted, so a redelivered message re-presents the same id. A key+ * therefore survives restarts, rebalances, evictions and process boundaries,+ * none of which an in-process watermark would.*- * MARK MEANS COUNT AND LOG. IT DOES NOT MEAN DROP. This tells the caller the id- * has been seen before; the caller inserts the event either way. A false- * positive on a suppressing check is silent data loss, and whether the events- * table ever gets dedupe is Carl's decision, not this file's.+ * MARK MEANS COUNT AND LOG. IT DOES NOT MEAN DROP. This tells the caller the+ * id has been seen before; the caller inserts the event either way. A false+ * positive on a suppressing check is silent data loss, so whether the events+ * table ever gets real dedupe is a separate decision from this marker.** ONE round trip, `SET key NX PX`: the set and the "did it already exist"- * answer are the same command, and there is no clean seam to fold it into — the- * session buffer's own GET and Lua EVAL live in `packages/core`'s `buffers/`,- * which this change does not own.+ * answer are the same command, and there is no clean seam to fold it into —+ * the session buffer's own GET and Lua EVAL live in `packages/core`'s+ * `buffers/`, which this module does not own.** IT MUST BE GIVEN THE CACHE CLIENT. That one fails fast: offline queue off* once connected, `commandTimeout` 500 ms. `getRedisQueue` keeps- * `maxRetriesPerRequest: null` for BullMQ and would block a handler for tens of- * seconds — which is how drill 02's consumer was evicted past its 30 s session- * timeout, and an eviction is the only reassignment M19 measured costing- * duplicate rows.+ * `maxRetriesPerRequest: null` for BullMQ and would block a handler for tens+ * of seconds, risking exactly the kind of consumer eviction — past its Kafka+ * session timeout — that produces duplicate rows.*- * Why here and not in `packages/core`'s ingest module: the whole of it is Redis- * mechanics, and core's only export door is its barrel, which this task's scope- * does not cover — the same reason `dead-letter.ts` lives here.+ * Why here and not in `packages/core`'s ingest module: the whole of it is+ * Redis mechanics, and core's only export door is its barrel — the same+ * reason `dead-letter.ts` lives here.*//** Live key prefix. An operator has to be able to find these. */diff --git a/packages/redis/publisher.test.ts b/packages/redis/publisher.test.tsindex 15287c112..cde682aa7 100644--- a/packages/redis/publisher.test.ts+++ b/packages/redis/publisher.test.ts@@ -1,13 +1,13 @@/**- * F1: one subscriber leaving must not silence the others.+ * One subscriber leaving must not silence the others.** `subscribeToPublishedEvent` hands every caller the SAME ioredis connection- * (`getRedisSub`, a process-wide singleton), so before this the unsubscribe it- * returned took the channel away from the whole process. M23-003 measured it on- * the `/live` sockets: close one, every other open socket received nothing for- * 30 s. What is pinned here is the reference count — and, just as important,- * that the LAST listener leaving still sends a real UNSUBSCRIBE, so the fix- * cannot degrade into "never unsubscribe".+ * (`getRedisSub`, a process-wide singleton), so the unsubscribe it returns+ * must not take the channel away from the whole process — on the `/live`+ * sockets, closing one used to leave every other open socket receiving+ * nothing for 30s. What is pinned here is the reference count — and, just as+ * important, that the LAST listener leaving still sends a real UNSUBSCRIBE,+ * so the fix cannot degrade into "never unsubscribe".** No real Redis: a stand-in for the shared connection that records the wire* commands and can push a `message` event, which is the entire surface thediff --git a/packages/redis/publisher.ts b/packages/redis/publisher.tsindex ca53562a1..ed7ec58ea 100644--- a/packages/redis/publisher.ts+++ b/packages/redis/publisher.ts@@ -47,10 +47,9 @@ type ChannelMessageListener = (message: string) => void;* Every subscriber in the process shares ONE ioredis connection (`getRedisSub`,* a module-level singleton). SUBSCRIBE and UNSUBSCRIBE on it are process-wide,* so a per-subscriber UNSUBSCRIBE silences every other subscriber on that- * channel — measured by M23-003 as F1: closing one `/live` socket left every- * other open socket receiving nothing for 30 s, across routes and across- * projects, because `/live/events` and `/live/visitors` both ride- * `events:batch`.+ * channel: closing one `/live` socket left every other open socket receiving+ * nothing for 30 s, across routes and across projects, because+ * `/live/events` and `/live/visitors` both ride `events:batch`.** So the channel is reference-counted here rather than at each call site: the* wire SUBSCRIBE happens only on 0 -> 1 and the wire UNSUBSCRIBE only on 1 ->@@ -64,9 +63,7 @@ type ChannelMessageListener = (message: string) => void;* which defaults to `true` in `redis/RedisOptions.js:45` and is not overridden* for this client). Since the wire commands stay one-to-one with the 0 -> 1 and* 1 -> 0 edges, ioredis's own set stays exactly the set of channels with a- * non-zero count. Confirmed live against the local server on 2026-09-15:- * destroying the socket under a subscribed client and publishing after the- * reconnect still delivered, with no re-subscribe from here.+ * non-zero count.*/const listenersByChannel = new Map<string, Set<ChannelMessageListener>>();diff --git a/packages/redis/redis.test.ts b/packages/redis/redis.test.tsindex 0f45e8e99..27c58d36a 100644--- a/packages/redis/redis.test.ts+++ b/packages/redis/redis.test.ts@@ -1,14 +1,14 @@/*** The CACHE client must reject promptly when Redis is unreachable.*- * Drill 02 (rev e004e199) measured `/track` blocking 9,427 / 12,039 / 41,978 ms- * on a stopped Redis, with 10 of 20 requests never answered inside 30 s,- * because the command was queued and waited out ioredis's 20-attempt reconnect- * cycle. These tests pin the three properties that fixed it, and the one that- * must NOT change (the queue client).+ * Without this, `/track` could block for tens of seconds on a stopped Redis+ * (some requests never answering at all) because the command was queued and+ * waited out ioredis's 20-attempt reconnect cycle. These tests pin the three+ * properties that fixed it, and the one that must NOT change (the queue+ * client).*- * No real Redis: an unreachable port covers "never connected", and a fake RESP- * server covers "connected, then gone".+ * No real Redis: an unreachable port covers "never connected", and a fake+ * RESP server covers "connected, then gone".*/import net from 'node:net';diff --git a/packages/redis/redis.ts b/packages/redis/redis.tsindex c0bb9ae77..e583f0dc2 100644--- a/packages/redis/redis.ts+++ b/packages/redis/redis.ts@@ -12,14 +12,13 @@ const options: RedisOptions = {* node). Nothing else in the request path sets a deadline there — `/track`* never answered inside 30 s in that fault before this.*- * It has to clear the heaviest LEGITIMATE command by a wide margin, or a busy- * event-buffer flush would start failing as if Redis were down — and under- * M18-001 a failed flush refuses to commit Kafka offsets. Measured on this box- * (`apps/api/e2e/redis-command-cost.ts`): the event buffer's worst case, a- * MULTI of 4,000 rpush (~4 MB), p99 33.95 ms; `LRANGE 0..3999` p99 21.26 ms;- * `GET` p99 0.18 ms. 500 ms is ~15x the worst of those.+ * It has to clear the heaviest legitimate command by a wide margin, or a busy+ * event-buffer flush would start failing as if Redis were down, and a failed+ * flush refuses to commit Kafka offsets. 500 ms is roughly 15x the measured+ * p99 of that flush's worst case (`apps/api/e2e/redis-command-cost.ts`), so it+ * will not fire under normal load.*- * Every number behind this file: `apps/api/e2e/redis-fail-fast.md`.+ * Full numbers: `apps/api/e2e/redis-fail-fast.md`.*/export const CACHE_COMMAND_TIMEOUT_MS = 500;@@ -29,10 +28,9 @@ export const CACHE_COMMAND_TIMEOUT_MS = 500;* backoff is a window of hard failures that lasts past the moment Redis comes* back, and it grows with the length of the outage — ioredis's default is* `min(attempt * 50, 2000)` ms and the attempt counter never resets while the- * server is away. Time from "Redis is back" to "`/track` answers 200 again"- * (`apps/api/e2e/redis-fail-fast.ts`, phase C): after a 20 s outage 390/395/396- * ms on the default cap vs 349/340/342 ms on this one, after a 60 s outage- * 1,137/1,135 ms vs 416/413 ms.+ * server is away. This tighter cap keeps that recovery window well under a+ * second even after a long outage (measured in `apps/api/e2e/redis-fail-fast.ts`,+ * phase C).*/const CACHE_RECONNECT_DELAY_STEP_MS = 50;const CACHE_RECONNECT_MAX_DELAY_MS = 500;@@ -40,9 +38,8 @@ const CACHE_RECONNECT_MAX_DELAY_MS = 500;/*** BullMQ mandates `maxRetriesPerRequest: null` and an offline queue: a blocking* BRPOPLPUSH must not be given up on, and a queued job must not be dropped- * because the socket blinked. M18-003 made the CACHE client fail fast and- * deliberately left this alone (Carl, 2026-09-13: "for cache we should have- * fail fast, for queue I think we should have the settings we have already").+ * because the socket blinked. The cache client fails fast; this one+ * deliberately does not.*/export const QUEUE_CLIENT_OPTIONS: RedisOptions = {...options,@@ -109,39 +106,28 @@ const createRedisClient = (};/**- * The CACHE client fails fast. Drill 02 measured `/track` blocking 9,427 /- * 12,039 / 41,978 ms on a stopped Redis, and 10 of 20 requests getting no- * answer inside 30 s, because on ioredis's defaults the command is QUEUED and- * waits out 20 reconnect attempts (backoff `min(times * 50, 2000)` ms) before- * `MaxRetriesPerRequestError`. Everything on the ingest path already treats+ * The CACHE client fails fast. On ioredis's defaults, a command issued while+ * Redis is down is queued and waits out the reconnect backoff before+ * `MaxRetriesPerRequestError`, which measured as multi-second `/track`+ * blocking on a stopped Redis. Everything on the ingest path already treats* these reads as optional — `device-id.ts` catches the session-buffer failure- * and mints the deterministic session id — so the wait bought nothing but a+ * and mints the deterministic session id — so that wait bought nothing but a* slower failure.*- * Two mechanisms, because there are two faults:+ * Two mechanisms, because there are two faults: the offline queue is turned+ * off once connected, so a command issued while the socket is known-down is+ * rejected in microseconds rather than queued; `commandTimeout` bounds the+ * case the offline queue cannot see, where the socket is up and the server+ * answers nothing. `commandTimeout` alone is not enough — ioredis arms the+ * deadline before the writable check, so a queued command still pays it in+ * full. Numbers and the case for 500 ms specifically:+ * `apps/api/e2e/redis-fail-fast.md`.*- * **The offline queue goes off**, so a command issued while the socket is- * known-down is rejected in microseconds rather than queued. This is what keeps- * a warm-cache `/track` at its normal latency during an outage. -- * **`commandTimeout`** bounds the case the offline queue cannot see, where the- * socket is up and the server answers nothing.- *- * Reproduced and measured before/after on this box, with the API pointed at a- * TCP proxy that can stop or freeze: with Redis stopped, a warm-auth `/track`- * goes from 2-of-3 requests never answered inside 30 s to 200 × 10 at p50 10.0- * ms, and a cold-auth one from the same 30 s hang to 500 at p50 1.3 ms.- * `commandTimeout` on its own, with the queue left on, was measured as well and- * is not enough: it bounds the tail but leaves that warm `/track` at 1,011 ms,- * because ioredis arms the deadline before the writable check, so the queued- * command pays it in full. The cost of going further, and why the deadline is- * 500 ms: `apps/api/e2e/redis-fail-fast.md`.- *- * THE OFFLINE QUEUE STAYS ON UNTIL THE CLIENT HAS CONNECTED ONCE. ioredis+ * The offline queue stays on until the client has connected once: ioredis* rejects every command issued before the first connect completes when the- * queue is off — including the ones a process issues while it is still booting- * — which would make boot order decide whether a command works. A process that- * has never reached Redis therefore still falls back to `commandTimeout`, which- * is bounded; one that has connected fails instantly.+ * queue is off, which would make boot order decide whether a command works. A+ * process that has never reached Redis falls back to `commandTimeout`+ * instead; one that has connected fails instantly.*/export function createFailFastCacheClient(name: string,diff --git a/packages/sdks/express/get-client-ip.ts b/packages/sdks/express/get-client-ip.tsindex 732769297..b882ca040 100644--- a/packages/sdks/express/get-client-ip.ts+++ b/packages/sdks/express/get-client-ip.ts@@ -34,8 +34,8 @@ export const DEFAULT_IP_HEADER_ORDER = [function isPublicIp(ip: string): boolean {// Handle IPv4-mapped IPv6 addresses (e.g., ::ffff:127.0.0.1)if (ip.startsWith('::ffff:')) {- const ipv4Part = ip.substring(7); // Extract IPv4 part after "::ffff:"- return isPublicIp(ipv4Part); // Recursively check the IPv4 address+ const ipv4Part = ip.substring(7);+ return isPublicIp(ipv4Part);}// IPv6 loopback@@ -92,7 +92,6 @@ function getHeaderOrder(): string[] {}function isValidIp(ip: string): boolean {- // Basic IP validationconst ipv4 = /^(\d{1,3}\.){3}\d{1,3}$/;const ipv6 = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;return isPublicIp(ip) && (ipv4.test(ip) || ipv6.test(ip));@@ -114,7 +113,6 @@ export function getClientIpFromHeaders(for (const headerName of headerOrder) {let value: string | null = null;- // Get header valueif (headers instanceof Headers) {value = headers.get(headerName);} else {@@ -130,7 +128,6 @@ export function getClientIpFromHeaders(continue;}- // Handle x-forwarded-for (comma separated)if (headerName === 'x-forwarded-for') {const firstIp = value.split(',')[0]?.trim();if (firstIp && isValidIp(firstIp)) {@@ -144,9 +141,7 @@ export function getClientIpFromHeaders(if (ip && isValidIp(ip)) {return { ip, header: headerName };}- }- // Regular headers- else if (isValidIp(value)) {+ } else if (isValidIp(value)) {return { ip: value, header: headerName };}}diff --git a/packages/sdks/sdk/src/index.ts b/packages/sdks/sdk/src/index.tsindex 7cc6d4f5f..0d651d202 100644--- a/packages/sdks/sdk/src/index.ts+++ b/packages/sdks/sdk/src/index.ts@@ -1,15 +1,13 @@-// Hand-duplicated on purpose, not imported: the wire contract's source of truth-// is @openpanel/core/modules/ingest/ingest.constants.ts ("ingest owns C"), but-// core's package.json exports map is deliberately narrow (no `./*` wildcard —-// see packages/core/AGENTS.md) and rollup-plugin-dts (tsup's dts bundler)-// cannot inline a type that resolves through that map's `*` pattern: it leaves-// an unresolvable `@openpanel/core/...` reference in dist/index.d.ts, which-// breaks for every consumer since core isn't published. A plain deep import-// into any workspace-internal shim package hits the same wall one hop later,-// since those packages now just re-export core's. Keeping a literal copy here-// is what keeps this package's shipped.d.ts self-contained. The SDK wire-// contract tests (verification/contracts/sdk) exercise both sides at runtime,-// so a drift shows up as a behavioral failure even without a type-level check.+// Hand-duplicated on purpose, not imported: the wire contract's source of+// truth is @openpanel/core/modules/ingest/ingest.constants.ts, but core's+// package.json exports map is deliberately narrow (no `./*` wildcard) and+// rollup-plugin-dts (tsup's dts bundler) cannot inline a type that resolves+// through that map's `*` pattern: it leaves an unresolvable+// `@openpanel/core/...` reference in dist/index.d.ts, which breaks for every+// consumer since core isn't published. A plain deep import into any+// workspace-internal shim package hits the same wall one hop later, since+// those packages now just re-export core's. Keeping a literal copy here is+// what keeps this package's shipped .d.ts self-contained.import { Api } from './api';export type ProfileId = string | number;@@ -137,10 +135,7 @@ export class OpenPanel {});}- // placeholder for future use- init() {- // empty- }+ init() {}ready() {this.options.disabled = false;@@ -284,9 +279,7 @@ export class OpenPanel {/*** @deprecated This method is deprecated and will be removed in a future version.*/- alias(_payload: AliasPayload) {- // noop- }+ alias(_payload: AliasPayload) {}increment(payload: IncrementPayload) {return this.send({diff --git a/packages/seed/src/traffic.ts b/packages/seed/src/traffic.tsindex 81e0eea3b..773738c37 100644--- a/packages/seed/src/traffic.ts+++ b/packages/seed/src/traffic.ts@@ -1,11 +1,12 @@-// Turns an archetype's shape (hourly curve, weekday curve) into visitor counts-// per day and per hour. Ported from openpanel-mock's opmock/internal/traffic.+// Turns an archetype's shape (hourly curve, weekday curve) into visitor+// counts per day and per hour.//-// The daily multiplier is a product of: trend slow growth/decline, anchored so-// "today" == 1.0 walk a mean-reverting random walk across days (weeks drift)-// weekday the archetype's day-of-week curve noise small independent per-day-// jitter anomaly rare spike or dip days Everything is a pure function of (seed,-// key, day), so seeding twice gives the same curve.+// The daily multiplier is a product of: trend (slow growth/decline,+// anchored so "today" == 1.0), walk (a mean-reverting random walk across+// days — weeks drift), weekday (the archetype's day-of-week curve), noise+// (small independent per-day jitter), and anomaly (rare spike or dip days).+// Everything is a pure function of (seed, key, day), so seeding twice gives+// the same curve.import { Rng } from './rng';diff --git a/packages/shared/src/server/crypto.ts b/packages/shared/src/server/crypto.tsindex 07b6aa295..fb1ef3093 100644--- a/packages/shared/src/server/crypto.ts+++ b/packages/shared/src/server/crypto.ts@@ -19,13 +19,11 @@ export async function hashPassword(keyLength = 32): Promise<string> {return new Promise((resolve, reject) => {- // generate random 16 bytes long salt - recommended by NodeJS Docsconst salt = generateSalt();scrypt(password, salt, keyLength, (err, derivedKey) => {if (err) {reject(err);}- // derivedKey is of type Bufferresolve(`${salt}.${derivedKey.toString('hex')}`);});});@@ -50,7 +48,6 @@ export async function verifyPassword(if (err) {reject(err);}- // compare the new supplied password with the hashed password using timeSafeEqualresolve(timingSafeEqual(new Uint8Array(hashKeyBuff), new Uint8Array(derivedKey)));diff --git a/packages/shared/src/server/parser-user-agent.ts b/packages/shared/src/server/parser-user-agent.tsindex c2b4aee0f..427ee6a4b 100644--- a/packages/shared/src/server/parser-user-agent.ts+++ b/packages/shared/src/server/parser-user-agent.ts@@ -157,7 +157,6 @@ function isKnownPhoneModel(model?: string): boolean {}const parse = (ua: string): UAParser.IResult => {- // Check cache firstconst cached = parseCache.get(ua);if (cached) {return cached;@@ -166,8 +165,8 @@ const parse = (ua: string): UAParser.IResult => {const parser = new UAParser(ua);let res = parser.getResult();- // Some user agents are not detected correctly by ua-parser-js- // Doing some extra checks for ios+ // Some user agents are not detected correctly by ua-parser-js; extra+ // checks handle iOS.if (!(res.device.model || res.os.name)) {const iphone = isIphone(ua);if (iphone) {@@ -203,8 +202,8 @@ const parse = (ua: string): UAParser.IResult => {}}- // Extract app-style UA info (e.g., "Model=Redmi Note 8 Pro; Manufacturer=Xiaomi")- // This handles UAs from mobile apps that include device info in a custom format+ // Handles UAs from mobile apps that embed device info in a custom format+ // (e.g. "Model=Redmi Note 8 Pro; Manufacturer=Xiaomi").const appInfo = extractAppStyleInfo(ua);if (appInfo.model || appInfo.manufacturer) {const model = res.device.model || appInfo.model;@@ -221,7 +220,6 @@ const parse = (ua: string): UAParser.IResult => {};}- // If we still don't have a vendor, try to detect brand from UA or modelif (!res.device.vendor && (res.device.model || res.os.name)) {const detectedBrand = detectBrand(ua, res.device.model);if (detectedBrand) {@@ -235,7 +233,6 @@ const parse = (ua: string): UAParser.IResult => {}}- // Cache the resultparseCache.set(ua, res);return res;};@@ -317,7 +314,6 @@ function isServer(res: UAParser.IResult) {return true;}- // If all of these are undefined, we can consider it a serverreturn (res.os.name === undefined &&res.browser.name === undefined &&@@ -350,7 +346,6 @@ export function getDevice(ua: string, model?: string) {return 'mobile';}- // Check for mobile patternsconst mobile1 = MOBILE_REGEX_1.test(ua);const mobile2 = MOBILE_REGEX_2.test(ua.slice(0, 4));@@ -374,12 +369,10 @@ export function getDevice(ua: string, model?: string) {// For Android without explicit mobile/tablet indicators and no known model,// check if there's any brand/model info suggesting it's a phoneif (isAndroid && !hasMobileKeyword && !isSamsungMobile && !isLGMobile) {- // Extract model from app-style UA if presentconst appInfo = extractAppStyleInfo(ua);if (appInfo.model && isKnownPhoneModel(appInfo.model)) {return 'mobile';}- // If we have a brand but no clear device type, assume mobile for Androidconst brand = detectBrand(ua, appInfo.model);if (brand) {return 'mobile';diff --git a/self-hosting/quiz.ts b/self-hosting/quiz.tsindex 1e4f93b7e..ea06b8b48 100644--- a/self-hosting/quiz.ts+++ b/self-hosting/quiz.ts@@ -105,10 +105,8 @@ function removeServiceFromDockerCompose(serviceName: string) {const dockerComposePath = path.resolve(__dirname, 'docker-compose.yml');const dockerComposeContent = fs.readFileSync(dockerComposePath, 'utf-8');- // Parse the YAML fileconst dockerCompose = yaml.load(dockerComposeContent) as DockerComposeFile;- // Remove the serviceif (dockerCompose.services[serviceName]) {delete dockerCompose.services[serviceName];console.log(`Service '${serviceName}' has been removed.`);@@ -117,7 +115,6 @@ function removeServiceFromDockerCompose(serviceName: string) {// return;}- // filter depends_onObject.keys(dockerCompose.services).forEach((service) => {const serviceConfig = dockerCompose.services[service];if (serviceConfig?.depends_on) {@@ -135,7 +132,6 @@ function removeServiceFromDockerCompose(serviceName: string) {}});- // filter volumesObject.keys(dockerCompose.volumes ?? {}).forEach((volume) => {if (dockerCompose.volumes && volume.startsWith(serviceName)) {delete dockerCompose.volumes[volume];@@ -146,7 +142,6 @@ function removeServiceFromDockerCompose(serviceName: string) {delete dockerCompose.volumes;}- // Convert the object back to YAMLconst newYaml = yaml.dump(dockerCompose, {lineWidth: -1,});diff --git a/test/bun-preload.ts b/test/bun-preload.tsindex 534c796f1..55cd3e926 100644--- a/test/bun-preload.ts+++ b/test/bun-preload.ts@@ -1,27 +1,25 @@/**- * `bun test` preload for `packages/db` and `apps/api` — the successor to- * `test/global-setup.ts`, which vitest ran once per run and bun has no- * equivalent for.+ * `bun test` preload for `packages/db` and `apps/api`.** Two jobs, in this order:*- * 1. **Pin the infrastructure URLs at the ISOLATED test databases**- * (TESTFIX-001). This is a safety property, not a convenience: no test may- * reach the application's own `openpanel` databases, which on this box hold- * a copy of production — fixture teardown there mutates the dataset the+ * 1. **Pin the infrastructure URLs at the ISOLATED test databases.** This is+ * a safety property, not a convenience: no test may reach the+ * application's own `openpanel` databases, which on this box hold a copy+ * of production — fixture teardown there mutates the dataset the* migration goldens are diffed against, and a delete against a 318M-row* table does not finish inside a test timeout. `test/databases.ts` is the* single source of truth for the strings.* 2. **Bootstrap those databases and load the shared fixture**, tearing it* down again when the file's tests finish.*- * `preload` runs once per test FILE under `--isolate` (measured on Bun 1.4.0:- * 4 files, 4 preloads, one pid, strictly sequential — and neither `globalThis`- * nor `process.env` survives between them, so there is no in-process channel- * to dedupe through). Everything here is therefore written to be idempotent- * and is serialised by that sequencing: `bootstrapTestDatabases` is idempotent- * by construction, and setup/teardown are paired around a single file's tests- * so no file can observe another's teardown.+ * `preload` runs once per test FILE under `--isolate`, strictly sequential+ * within one process — neither `globalThis` nor `process.env` survives+ * between files, so there is no in-process channel to dedupe through.+ * Everything here is therefore written to be idempotent and is serialised by+ * that sequencing: `bootstrapTestDatabases` is idempotent by construction,+ * and setup/teardown are paired around a single file's tests so no file can+ * observe another's teardown.** The imports below are deliberately dynamic and deliberately below the env* pins: `packages/db`'s ClickHouse module constructs its clients at import@@ -39,11 +37,11 @@ export const TEST_PROJECT_ID = 'integration-test';export const TEST_ORG_ID = 'integration-org';/**- * Called twice, exactly as `test/global-setup.ts` called it in both `setup`- * and `teardown`. The second call is not redundant: a test file may rewrite- * `CLICKHOUSE_URL` for its own purposes — `sql.round-robin.clickhouse.test.ts`- * points it at a dead node first, on purpose — and the fixture helpers read- * the variable at call time, so teardown must re-pin before it deletes rows.+ * Called twice: once for setup, once for teardown. The second call is not+ * redundant: a test file may rewrite `CLICKHOUSE_URL` for its own purposes —+ * `sql.round-robin.clickhouse.test.ts` points it at a dead node first, on+ * purpose — and the fixture helpers read the variable at call time, so+ * teardown must re-pin before it deletes rows.*/function pinTestDatabases() {process.env.DATABASE_URL = TEST_DATABASE_URL;diff --git a/test/databases.ts b/test/databases.tsindex f0af5515b..7397cfee0 100644--- a/test/databases.ts+++ b/test/databases.ts@@ -8,9 +8,9 @@* migration goldens are diffed against, and a lightweight delete against a* 318M-row table does not finish inside a test timeout.*- * Every test connection string is derived from here — vitest.shared.ts pins- * the worker env at these values and test/bootstrap-databases.ts creates and- * migrates them. Nothing in test/ may hard-code a database name.+ * Every test connection string is derived from here — test/bun-preload.ts+ * pins the worker env at these values and test/bootstrap-databases.ts+ * creates and migrates them. Nothing in test/ may hard-code a database name.*/const POSTGRES_ORIGIN = 'postgresql://postgres:postgres@localhost:23432';diff --git a/test/fixtures.ts b/test/fixtures.tsindex 9684a13c0..5f7529c03 100644--- a/test/fixtures.ts+++ b/test/fixtures.ts@@ -229,8 +229,6 @@ async function insertFixtures(client: ChClient, projectId: string) {format: 'JSONEachRow',});- // Alice: session_start → page_view → session_end (2 days ago, spaced 2 min apart)- // Charlie: session_start → screen_view → page_view → purchase → session_end (5 days ago, spaced 5 min apart)// Events are spaced so windowFunnel strict_increase mode works correctly.await client.insert({table: 'events',diff --git a/tooling/codemods/p11-codemod.ts b/tooling/codemods/p11-codemod.tsindex 831e89d66..f91bb6869 100644--- a/tooling/codemods/p11-codemod.ts+++ b/tooling/codemods/p11-codemod.ts@@ -1,10 +1,8 @@/*** P11: repoint importers of the four dissolving packages —* @openpanel/validation, @openpanel/constants, @openpanel/common,- * @openpanel/json — at the targets recorded in./p11-map.json.- *- * The map is the single source of truth and is the JSON block of- * docs/P11_DISSOLUTION_MAP.md verbatim. A row's `to` is the default target;+ * @openpanel/json — at the targets recorded in ./p11-map.json, the single+ * source of truth. A row's `to` is the default target;* `toByConsumer[<workspace>]` overrides it for one workspace.** Three things it does that a sed cannot: - one import statement fans out to@@ -12,7 +10,7 @@* are regrouped by target; - per-symbol `type` keywords are preserved exactly* as written. A `type` keyword can sit on a runtime binding used only in* `z.infer<typeof x>`; dropping it promotes an erased import into a real one- * and changes the bundle (ADR-008 risk 4); - a named re-export (`export { X }+ * and changes the bundle; - a named re-export (`export { X }* from '@openpanel/validation'`) is rewritten the same way an import is — same* clause grammar, same per-symbol targets.*diff --git a/tooling/gates/conformance/cli.ts b/tooling/gates/conformance/cli.tsindex e788d2480..5bedbd39a 100644--- a/tooling/gates/conformance/cli.ts+++ b/tooling/gates/conformance/cli.ts@@ -1,10 +1,9 @@/*** Assembles every ADR-022 check into one report and decides --assert.*- * Output contract (docs/CONFORMANCE_GATE_SPEC.md, "Output shape"): one block- * per rule, offenders as `file:line`, a TOTAL line per rule and one overall,- * stable ordering and no timestamps in the body — so the fix wave proves a rule- * reached zero by diffing two reports.+ * Output contract: one block per rule, offenders as `file:line`, a TOTAL+ * line per rule and one overall, stable ordering and no timestamps in the+ * body — so a change can be verified by diffing two reports.*/import { readFileSync } from 'node:fs';@@ -63,8 +62,8 @@ const START_SOURCE_ROOT = 'apps/start/src';const MODULES_ROOT = `${CORE_SOURCE_ROOT}/modules`;const CONFIG_ENV_FILE = `${API_SOURCE_ROOT}/config/env.ts`;// Static `from '../v1-compat'` and dynamic `await import('../v1-compat')` alike:-// 34 of today's importers reach it through a lazy import, which is the R6 defect-// itself and would be missed by a `from` pattern.+// a lazy import is still an R6 defect and would be missed by a `from`-only+// pattern.const V1_COMPAT_IMPORT = /['"][^'"]*\/v1-compat['"]/;const RULE_ID_WIDTH = 4;const SEPARATOR_WIDTH = 80;@@ -335,8 +334,8 @@ function buildRules(tree: Tree): RuleBlock[] {const v1Compat = tree.core.find((source) => source.path === CORE_V1_COMPAT_FILE);- // Tests count: ADR-022's "69 importers" is what fix-wave step 2 has to move,- // and a test importing v1-compat is as much a caller as a service is.+ // Tests count too: a test importing v1-compat is as much a caller as a+ // service is.const v1CompatImporters = tree.allCoreText.filter(({ path, text }) =>path !== CORE_V1_COMPAT_FILE && V1_COMPAT_IMPORT.test(text)@@ -519,9 +518,9 @@ function buildRules(tree: Tree): RuleBlock[] {tree)),- // The two slices ADR-022's baseline table states (7 and 8). They are- // VIEWS of the rules above, not extra violations, so they carry no- // target: asserting on them would count the same edges twice.+ // These two slices are VIEWS of the rules above, not extra+ // violations, so they carry no target: asserting on them would count+ // the same edges twice.asView(cruiserMetric('ADR-022 baseline slice: shared/ -> above it',@@ -602,10 +601,10 @@ function metricIsAboveTarget(metric: Metric): boolean {}/**- * The headline numbers, up top, so the ADR-022 baseline table can be checked- * against this run without scrolling 700 lines. Each entry names the rule and- * the metric it comes from; the numbers themselves come from the same Metric- * objects the blocks below print, never from a second measurement.+ * The headline numbers, up top, so results can be checked at a glance without+ * scrolling 700 lines. Each entry names the rule and the metric it comes+ * from; the numbers themselves come from the same Metric objects the blocks+ * below print, never from a second measurement.*/const BASELINE_METRICS: readonly {rule: string;diff --git a/tooling/gates/conformance/conformance.constants.ts b/tooling/gates/conformance/conformance.constants.tsindex 12e320804..b36d1a307 100644--- a/tooling/gates/conformance/conformance.constants.ts+++ b/tooling/gates/conformance/conformance.constants.ts@@ -3,10 +3,10 @@** They live here rather than inline because two of them are load-bearing* carve-outs a reader has to be able to audit without reading the checks:- * ASSET_LOADER_ALLOWLIST and SANCTIONED_CREATE_SERVICES_SITES, both R6.+ * ASSET_LOADER_ALLOWLIST and SANCTIONED_CREATE_SERVICES_SITES.*/-/** The tree ADR-022 governs. Paths everywhere are repo-relative POSIX. */+/** Paths everywhere are repo-relative POSIX. */export const CORE_SOURCE_ROOT = 'packages/core/src';export const CORE_SERVICES_FILE = 'packages/core/src/services.ts';export const CORE_V1_COMPAT_FILE = 'packages/core/src/v1-compat.ts';@@ -23,10 +23,10 @@ export const IGNORED_DIRECTORY_NAMES = new Set([]);/**- * R6 — the only files that may call `createServices(`. ADR-022 R15 names them- * exhaustively: the composition root itself, the context builder every- * transport goes through, the routes' lazy builder, the jobs runtime, and the- * app's boot. A file outside this list is an offender.+ * The only files that may call `createServices(`: the composition root+ * itself, the context builder every transport goes through, the routes'+ * lazy builder, the jobs runtime, and the app's boot. A file outside this+ * list is an offender.*/export const SANCTIONED_CREATE_SERVICES_SITES: readonly string[] = ['packages/core/src/services.ts',@@ -37,12 +37,7 @@ export const SANCTIONED_CREATE_SERVICES_SITES: readonly string[] = [];/**- * R6 — the asset-loader carve-out, and the reason for each entry.- *- * "Lazy-load assets, never dependencies." Reading a file or a row on first use- * is data loading and is legal; lazily importing a sibling service or a- * db/ch/redis handle the caller was already handed is the defect the rule- * exists to remove.+ * The asset-loader carve-out, and the reason for each entry.** This is an ALLOWLIST of exact `file::function` pairs, deliberately NOT a* pattern. A pattern ("loaders that touch the filesystem", "loaders under@@ -57,7 +52,7 @@ export const ASSET_LOADER_ALLOWLIST: readonly {}[] = [// Geo.ts reads a MaxMind.mmdb file from disk on first use. That is an ASSET// load: no sibling service, no db/ch/redis handle, nothing the caller already- // holds. ADR-022 names it as one of the two legitimate cases.+ // holds.{file: 'packages/core/src/clients/geo.ts',functionName: 'loadDatabase',@@ -66,7 +61,7 @@ export const ASSET_LOADER_ALLOWLIST: readonly {},// Flush-exports.ts reads an export cursor ROW on first use. Also data, and it// reads it through the db handle it was already handed rather than importing- // one. ADR-022 names it as the second legitimate case.+ // one.{file: 'packages/core/src/modules/integration/src/flush-exports.ts',functionName: 'loadCursor',@@ -75,16 +70,12 @@ export const ASSET_LOADER_ALLOWLIST: readonly {},];-/**- * R10 — where the access checks are allowed to live. ADR-022: "Access checks- * live in the auth service and the builders, never per rpc file."- */+/** Where the access checks are allowed to live. */export const AUTH_STACK_PATHS: readonly string[] = ['packages/core/src/rpc/base.ts','packages/core/src/modules/auth/',];-/** R10 — the four names ADR-022's check line enumerates. */export const ACCESS_CHECK_FUNCTION_NAMES = new Set(['requireLogin','requireReadAccess',@@ -92,11 +83,11 @@ export const ACCESS_CHECK_FUNCTION_NAMES = new Set(['requireAccess',]);-/** R14 — the prefix, and the one app allowed to keep it. */+/** The prefix, and the one app allowed to keep it. */export const NEXT_PUBLIC_PREFIX = 'NEXT_PUBLIC_';export const NEXT_PUBLIC_ALLOWED_ROOT = 'apps/public/';-/** R14 — residue markers that must not survive the rewrite. */+/** Residue markers that must not appear in the source tree. */export const RESIDUE_PATTERNS: readonly { label: string; pattern: RegExp }[] = [{ label: 'NEXT_PUBLIC_ prefix', pattern: /NEXT_PUBLIC_/ },// \b so `fika` matches the template's name and not, say, `fikan` in prose.@@ -105,20 +96,20 @@ export const RESIDUE_PATTERNS: readonly { label: string; pattern: RegExp }[] = [];/**- * R15 — constructors that open a connection or build a client. A `new` of one- * of these, or a call to one of the factory names, at MODULE scope is the+ * Constructors that open a connection or build a client. A `new` of one of+ * these, or a call to one of the factory names, at MODULE scope is the* violation; inside a factory body it is exactly what core is supposed to do.** The name matched is the CONSTRUCTED one, however it is spelled: `new* GitHub(...)` and `new Arctic.Google(...)` are the same construction, and a- * checker that only looked at bare identifiers could not see the second one at- * all (CONFORMANCE_PLAN.md §1l). `checkModuleScopeConstruction` resolves a- * qualified `new A.B.C()` down to `C` before looking it up here.+ * checker that only looked at bare identifiers could not see the second one+ * at all. `checkModuleScopeConstruction` resolves a qualified `new A.B.C()`+ * down to `C` before looking it up here.** The OAuth clients (`arctic`) are credential holders rather than sockets, so- * nothing about them has to be closed — but they are built from config and- * they are exactly what R15 means by "the app constructs": one at module scope- * would freeze a deployment's client id and secret into the import graph.+ * nothing about them has to be closed — but they are built from config, and+ * one at module scope would freeze a deployment's client id and secret into+ * the import graph.*/export const CONNECTION_CONSTRUCTOR_NAMES = new Set(['Redis',@@ -141,14 +132,14 @@ export const CONNECTION_FACTORY_NAME_PATTERN =/^create(?:[A-Z][A-Za-z]*)?(?:Client|Connection|Redis|Db|Pool)$/;/**- * R21 — util basenames that are the same helper under two names. `super-json`+ * Util basenames that are the same helper under two names. `super-json`* in apps/start is core's `shared/json`; without the alias a basename check* reads them as two unrelated files and undercounts the duplication by one.*/export const UTIL_BASENAME_ALIASES = new Map([['super-json', 'json']]);/**- * R21 — where a "dumb utility" lives today: an app's `src/utils/`, core's+ * Where a "dumb utility" lives today: an app's `src/utils/`, core's* `shared/` drawer, or a package's own top level (`packages/redis/json.ts`).*/export const UTIL_DIRECTORY_PATTERNS: readonly RegExp[] = [@@ -158,9 +149,9 @@ export const UTIL_DIRECTORY_PATTERNS: readonly RegExp[] = [];/**- * R21 — a package's entrypoint is not a utility. Every package has one, so- * without this the basename check reports six `index.ts` "duplicates" and buries- * the five real copies.+ * A package's entrypoint is not a utility. Every package has one, so+ * without this the basename check reports six `index.ts` "duplicates" and+ * buries the five real copies.*/export const UTIL_BASENAME_EXCLUSIONS = new Set(['index',@@ -168,14 +159,12 @@ export const UTIL_BASENAME_EXCLUSIONS = new Set(['constants',]);-/** R21 — the package ADR-022's C7 chore will create. Absent today. */export const SHARED_PACKAGE_NAME = '@openpanel/shared';export const SHARED_PACKAGE_ROOT = 'packages/shared';/**- * R22 — delegated to dependency-cruiser: M14-002 landed the layer rules and the- * peer-resolution verification passed, so ADR-022's grep fallback is not in- * play. These are the rule names whose violation counts this gate reports.+ * Delegated to dependency-cruiser. These are the rule names whose violation+ * counts this gate reports.*/export const CRUISER_LAYER_RULE_NAMES: readonly string[] = ['core-layers-shared-is-the-bottom',@@ -186,14 +175,14 @@ export const CRUISER_LAYER_RULE_NAMES: readonly string[] = ['core-layers-registries-below-index',];-/** R12 — delegated to the cruiser rule ADR-008 already ships. */+/** Delegated to the cruiser rule that already ships. */export const CRUISER_FRONTEND_RULE_NAME = 'frontend-values-only-constants';/**- * R22 — the two slices ADR-022's baseline table states (7 and 8). They are- * narrower than the cruiser rules that produce them, so the gate prints both:- * the cruiser's own per-rule count (the delegated number) and the baseline- * slice, computed from the cruiser's own edges rather than re-derived.+ * These two slices are narrower than the cruiser rules that produce them,+ * so the gate prints both: the cruiser's own per-rule count (the delegated+ * number) and the baseline slice, computed from the cruiser's own edges+ * rather than re-derived.*/export const R22_SHARED_UPWARD_RULE = 'core-layers-shared-is-the-bottom';export const R22_TRANSPORT_UPWARD_RULE = 'core-layers-transport-below-modules';diff --git a/tooling/gates/conformance/cruiser.ts b/tooling/gates/conformance/cruiser.tsindex c234c60f5..06c5504e9 100644--- a/tooling/gates/conformance/cruiser.ts+++ b/tooling/gates/conformance/cruiser.ts@@ -1,13 +1,9 @@/*** R12 and R22 are delegated to dependency-cruiser, not reimplemented here.*- * Made `dependency-cruiser` a declared root devDependency, verified that it- * resolves its optional `typescript` peer (the 82-false-violation failure- * ADR-022 made R22 conditional on), and landed the layer rules- * in.dependency-cruiser.cjs. So this module runs the cruise and reports its- * per-rule violation counts. ADR-022's layer-aware fallback in this gate is not- * in play; a bare `../` depth grep is forbidden either way, because a module- * importing `defineJob` at `../../jobs/define` is importing DOWNWARD.+ * This module runs the cruise and reports its per-rule violation counts. A+ * bare `../` depth grep is forbidden either way, because a module importing+ * `defineJob` at `../../jobs/define` is importing DOWNWARD.** If the cruise cannot run, that is a hard failure: a delegated check that* silently reports zero is worse than no check.diff --git a/tooling/gates/conformance/rules.test.ts b/tooling/gates/conformance/rules.test.tsindex cd83bb065..7cf61bc58 100644--- a/tooling/gates/conformance/rules.test.ts+++ b/tooling/gates/conformance/rules.test.ts@@ -2,8 +2,7 @@* The gate's own tests.** Two of them are mandatory, and they are the reason this gate parses TypeScript- * instead of grepping. Both traps were measured against `packages/core/src` on- * 2026-09-08 and both make a naive gate report the wrong number:+ * instead of grepping. Both traps make a naive gate report the wrong number:** trap 1 `rg 'export function create[A-Za-z]+Service\(deps'` finds 28 of the* 36 factories, because eight signatures span lines.@@ -238,9 +237,9 @@ const c = process.env['BRACKETED'];describe('R15 — the two constructor spellings modules/auth/src/oauth.ts uses', () => {// Both arctic clients, both correct: built per call, from config. The bug- // M15-202 fixed was the checker, not this file — `GitHub` was not in the- // constructor set and `Arctic.Google` is a property access an- // `ts.isIdentifier` guard cannot see at all (CONFORMANCE_PLAN.md §1l).+ // this guards against was in the checker, not this file — `GitHub` was not+ // in the constructor set and `Arctic.Google` is a property access an+ // `ts.isIdentifier` guard cannot see at all.const oauthShape = `import * as Arctic from 'arctic';import { GitHub } from 'arctic';diff --git a/tooling/gates/conformance/rules.ts b/tooling/gates/conformance/rules.tsindex db0bcaeff..734628cb4 100644--- a/tooling/gates/conformance/rules.ts+++ b/tooling/gates/conformance/rules.ts@@ -1,24 +1,14 @@/**- * The ADR-022 conformance checks.+ * Conformance checks, run against already-parsed sources.*- * Every check is a pure function over already-parsed sources, so the gate's own- * tests can run it against a fixture string. That is not decoration: the two- * miscount traps in docs/CONFORMANCE_GATE_SPEC.md can only be proven covered by- * feeding a check a source that contains them.- *- * Where a grep would lie, the check walks the TypeScript AST:- *- * R3 a factory signature can span lines, so the argument list is not on the- * `export function` line. `rg 'create[A-Za-z]+Service\(deps'` saw 28 of 36 on- * 2026-09-08. R5 `ReturnType<typeof create` appears once in services.ts and the- * match is a COMMENT (services.ts:154) explaining the circularity rule. The- * pattern is applied in code zero times. R6 `createServices(` in a comment or a- * string is not a call site. R7 `rg 'process\.env\.'` both over- and- * under-counts: rpc/base.ts:246 is a comment saying core reads no process.env,- * and get-client-ip.ts:83 is a real read written `process.env?.` that the- * pattern misses. R15 `new Redis(` inside a factory body is exactly what core- * is supposed to do; at module scope it is the violation. Only scope tells them- * apart.+ * Every check is a pure function, so it can run against a fixture string in+ * this gate's own tests. Where a grep would lie, the check walks the+ * TypeScript AST instead: a factory signature can span lines (R3);+ * `ReturnType<typeof create` can appear inside a comment, not just in code+ * (R5); `createServices(` can appear in a comment or a string, not just as a+ * call (R6); `process.env` has a bracketed form a dotted-form grep misses+ * (R7); `new Redis(` is correct inside a factory body and a violation at+ * module scope, and only scope tells them apart (R15).*/import { existsSync, readFileSync } from 'node:fs';@@ -208,12 +198,8 @@ const isReturnTypeOfFactory = (type: ts.TypeNode | undefined): boolean => {/*** R5b — every member of the `Services` interface is typed- * `ReturnType<typeof createXService>`, IN CODE.- *- * The trap: `rg -o 'ReturnType<typeof create' packages/core/src/services.ts`- * returns 1, and that match is the comment at services.ts:154 explaining why- * `ReturnType<typeof createServices>` is circular. The AST never sees a comment,- * so this counts 0 today, which is the true number.+ * `ReturnType<typeof createXService>`, IN CODE — a comment using the same+ * text does not count.*/export function checkServicesMembers(sources: ParsedSource[]): Metric {const offenders: Offender[] = [];@@ -250,7 +236,7 @@ export function checkServicesMembers(sources: ParsedSource[]): Metric {return {label: `Services members typed ReturnType<typeof createXService> in code (not comments) — ${conforming} of ${members}`,- // The metric ADR-022's baseline states is the number of CONFORMING members;+ // This metric reports the number of CONFORMING members, not offenders;// the assert target is that every member conforms.count: offenders.length,target: 0,@@ -305,13 +291,12 @@ const allowedAssetLoader = (/*** R6b — no `load*` dependency loaders.*- * The carve-out is the explicit ASSET_LOADER_ALLOWLIST, not a pattern: a loader- * that reads a MaxMind database or a cursor row is loading DATA, and ADR-022- * allows it. A loader that lazily imports a sibling service or a db/ch/redis- * handle the caller already holds is the defect. Since nothing in the source- * text reliably separates the two, the gate refuses to guess — a new loader has- * to be added to the allowlist by hand, with a reason, in a diff a reviewer- * reads.+ * The carve-out is the explicit ASSET_LOADER_ALLOWLIST, not a pattern: a+ * loader that reads a MaxMind database or a cursor row loads DATA, which is+ * allowed. A loader that lazily imports a sibling service or a db/ch/redis+ * handle the caller already holds is the defect. Nothing in the source text+ * reliably separates the two, so a new loader must be added to the allowlist+ * by hand, with a reason, in a diff a reviewer reads.*/export function checkDependencyLoaders(sources: ParsedSource[]): Metric {const offenders: Offender[] = [];@@ -504,10 +489,8 @@ export function checkResidue(files: ResidueScanInput[]): Metric[] {}}- // ADR-022's baseline states NEXT_PUBLIC_ for packages/core/src on its own- // (10 across 10 files); the rest of the tree is a second, wider metric.- // Both are asserted, so splitting them costs nothing and keeps the baseline- // number reproducible line-for-line.+ // Core and the rest of the tree are asserted as two separate metrics,+ // not one, so each stays independently reproducible.if (pattern.source.includes(NEXT_PUBLIC_PREFIX)) {const inCore = offenders.filter((offender) =>offender.file.startsWith(`${CORE_SOURCE_ROOT}/`)@@ -548,10 +531,9 @@ export function checkResidue(files: ResidueScanInput[]): Metric[] {* The name a `new` expression actually constructs, however it is qualified.** `new GitHub(...)` is an identifier; `new Arctic.Google(...)` is a property- * access, and an `ts.isIdentifier` guard cannot see it at all — the checker- * would walk straight past a namespace-imported client- * (CONFORMANCE_PLAN.md §1l). Both spellings construct the same thing, so both- * resolve to the rightmost name here.+ * access that a plain `ts.isIdentifier` guard would miss entirely, walking+ * straight past a namespace-imported client. Both resolve to the rightmost+ * name here.*/function constructedName(expression: ts.Expression): string | undefined {if (ts.isIdentifier(expression)) {@@ -631,9 +613,8 @@ const utilKey = (path: string): string | undefined => {/*** R21 — nothing is copied between packages to dodge a dependency edge.*- * The count is duplicate COPIES, not colliding names: one file per group is the- * canonical one and the rest are the copies to delete. ADR-022's expected end- * state says "5 duplicate util copies deleted", which is this number.+ * The count is duplicate COPIES, not colliding names: one file per group is+ * the canonical one and the rest are copies to delete.*/export function checkDuplicateUtilities(paths: string[]): Metric {const groups = new Map<string, string[]>();diff --git a/tooling/gates/conformance/sources.ts b/tooling/gates/conformance/sources.tsindex 1afc870a5..b48507d53 100644--- a/tooling/gates/conformance/sources.ts+++ b/tooling/gates/conformance/sources.ts@@ -2,9 +2,8 @@* Source collection and parsing for the conformance checks.** Every check takes an array of `ParsedSource` rather than reading the disk- * itself. That is what makes the checks testable against a fixture string —- * which is the only way to prove the two miscount traps in- * docs/CONFORMANCE_GATE_SPEC.md are actually covered.+ * itself. That is what makes the checks testable against a fixture string,+ * which is the only way to prove known miscount traps are actually covered.*/import { readdirSync, readFileSync, statSync } from 'node:fs';diff --git a/tooling/publish/generate-readme.ts b/tooling/publish/generate-readme.tsindex 349d7574b..3a137fc66 100644--- a/tooling/publish/generate-readme.ts+++ b/tooling/publish/generate-readme.ts@@ -16,12 +16,9 @@ const dedentContent = (text: string): string => {return text;}- // Find the minimum indentation (excluding empty lines)- // We'll dedent code blocks too, so include them in the calculationlet minIndent = Number.POSITIVE_INFINITY;for (const line of lines) {const trimmed = line.trim();- // Skip empty linesif (trimmed.length === 0) {continue;}@@ -31,21 +28,16 @@ const dedentContent = (text: string): string => {}}- // If no indentation found, return as-isif (minIndent === Number.POSITIVE_INFINITY || minIndent === 0) {return text;}- // Remove the common indentation from all linesreturn lines.map((line) => {- // For lines shorter than minIndent, just return them as-is (preserves empty lines)if (line.length < minIndent) {return line;}- // Remove the common indentationconst dedented = line.slice(minIndent);- // If the line was all whitespace, return empty string to preserve the linereturn line.trim().length === 0 ? '' : dedented;}).join('\n');@@ -57,7 +49,6 @@ const transformMdxToReadme = (): string => {let content = mdxContent;- // Load MDX component content filesconst commonSdkConfigPath = workspacePath('apps/public/src/components/common-sdk-config.mdx');@@ -84,7 +75,6 @@ const transformMdxToReadme = (// Ignore if file doesn't exist}- // Extract title from frontmatterconst frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n/);let title = packageName;let description = '';@@ -100,12 +90,11 @@ const transformMdxToReadme = (description = descMatch[1].trim();}- // Remove frontmattercontent = content.replace(/^---\n[\s\S]*?\n---\n/, '');}- // Replace MDX component references with their actual content- // This must happen before code block protection so component content is also protected+ // Must run before code-block protection below, so injected component+ // content is protected too.if (commonSdkConfigContent) {content = content.replace(/<CommonSdkConfig\s*\/>/g,@@ -119,25 +108,17 @@ const transformMdxToReadme = ();}- // Protect code blocks from transformation- // Extract code blocks before any transformations to preserve their contentconst codeBlockPlaceholders: string[] = [];- // Match code blocks: ```language (optional) followed by content until closing ```- // Using [\s\S] to match across newlines, non-greedy to stop at first closing ```const codeBlockRegex = /```[\s\S]*?```/g;- // Extract and replace code blocks with placeholderscontent = content.replace(codeBlockRegex, (match) => {const placeholder = `__CODE_BLOCK_${codeBlockPlaceholders.length}__`;codeBlockPlaceholders.push(match);return placeholder;});- // Remove import statements (outside code blocks)content = content.replace(/^import\s+.*$/gm, '');- // Handle Tabs component specially - convert to markdown sections- // Extract tabs items from items propconst tabsItemsMatch = content.match(/<Tabs\s+items=\{([^}]+)\}>/);const tabsItems = tabsItemsMatch?.[1]? tabsItemsMatch[1]@@ -146,9 +127,7 @@ const transformMdxToReadme = (.map((item) => item.trim()): [];- // Replace Tabs/Tab structure with markdown sectionsif (tabsItems.length > 0) {- // Match each Tab and convert to a markdown sectioncontent = content.replace(/<Tab\s+value="([^"]+)">([\s\S]*?)<\/Tab>/g,(match, value, tabContent) => {@@ -156,10 +135,8 @@ const transformMdxToReadme = (return `\n#### ${value}\n\n${dedented}\n\n`;});- // Remove the Tabs wrappercontent = content.replace(/<Tabs[^>]*>([\s\S]*?)<\/Tabs>/g, '$1');} else {- // Fallback: if no items prop, just convert tabs to sectionscontent = content.replace(/<Tab\s+value="([^"]+)">([\s\S]*?)<\/Tab>/g,(match, value, tabContent) => {@@ -170,16 +147,11 @@ const transformMdxToReadme = (content = content.replace(/<Tabs[^>]*>([\s\S]*?)<\/Tabs>/g, '$1');}- // Remove self-closing JSX components (like <CommonSdkConfig />, <WebSdkConfig />)content = content.replace(/<[A-Z][a-zA-Z]*[^>]*\/>/g, '');- // Remove JSX component tags but preserve content between opening/closing tags- // Handle nested components by recursively removing outer tags- // This regex matches opening tag, captures content (including nested tags), and closing taglet previousContent = '';while (content !== previousContent) {previousContent = content;- // Match JSX components with their content - handles one level of nestingcontent = content.replace(/<([A-Z][a-zA-Z]*)[^>]*>([\s\S]*?)<\/\1>/g,(match, tagName, innerContent) => {@@ -188,24 +160,19 @@ const transformMdxToReadme = ();}- // Remove any remaining JSX tags (self-closing or unmatched)content = content.replace(/<\/?[A-Z][a-zA-Z]*[^>]*>/g, '');- // Restore code blockscodeBlockPlaceholders.forEach((codeBlock, index) => {content = content.replace(`__CODE_BLOCK_${index}__`, codeBlock);});- // Convert internal links (starting with /) to absolute URLscontent = content.replace(/\[([^\]]+)\]\((\/[^)]+)\)/g,'[$1](https://openpanel.dev$2)');- // Clean up extra blank linescontent = content.replace(/\n{3,}/g, '\n\n').trim();- // Build the README headerconst docUrl = `https://openpanel.dev/docs/sdks/${packageName.replace('@openpanel/', '')}`;let readme = `# ${title}\n\n`;diff --git a/tooling/scripts/pin-from-pnpm-lock.ts b/tooling/scripts/pin-from-pnpm-lock.tsindex e70593dee..634f97a15 100644--- a/tooling/scripts/pin-from-pnpm-lock.ts+++ b/tooling/scripts/pin-from-pnpm-lock.ts@@ -1,12 +1,11 @@#!/usr/bin/env bun/**- * P13 groundwork: pin every declared range to the version `pnpm-lock.yaml`+ * Pins every declared dependency range to the version `pnpm-lock.yaml`* already resolved for it.*- * ADR-014's stop rule ends P13 the moment a pin cannot be reproduced under bun,- * and bun 1.4.0 cannot read `pnpm-lock.yaml` — it re-resolves the whole graph- * from the declared ranges. A caret in a manifest is therefore an instruction- * to a resolver we are about to replace. Writing the resolved version into the+ * Bun cannot read `pnpm-lock.yaml` — it re-resolves the whole graph from the+ * declared ranges. A caret in a manifest is therefore an instruction to a+ * resolver this repo no longer uses. Writing the resolved version into the* manifest turns each range into a fact the next installer has to reproduce* rather than a question it gets to answer.*@@ -21,27 +20,25 @@* which name a resolution strategy rather than a range; - `peerDependencies`,* which are compatibility contracts (pnpm's `autoInstallPeers: true` lists them* under an importer's `dependencies` in the lock even though the manifest- * declares them as peers); - the two stale `prisma: ^5.1.1` devDeps ADR-017- * rule 2 carves out by path (see ADR_017_RULE_2_FROZEN below); - every- * `version:` field in the lock. NOT ONE RESOLUTION MOVES.+ * declares them as peers); - the two stale `prisma: ^5.1.1` devDeps carved out+ * by path (see ADR_017_RULE_2_FROZEN below); - every `version:` field in the+ * lock. NOT ONE RESOLUTION MOVES.** Why the lock's specifiers are rewritten here instead of by `pnpm install`: a- * non-frozen `pnpm install` re-resolves the whole graph and dedupes it. On this- * tree, on 2026-09-07, that pruned 142 package versions across 135 package- * names and added none — `@babel/core` collapsing from four copies to two,- * `magicast` from three to two — which is real resolution movement in the same- * commit that is supposed to prove nothing moved. Rewriting the specifier- * fields is the mechanical, resolution-preserving half of what that install- * would do; `pnpm install --frozen-lockfile` then verifies the result is- * consistent.+ * non-frozen `pnpm install` re-resolves the whole graph and dedupes it — on+ * this tree that pruned well over a hundred duplicate package versions in one+ * pass, which is real resolution movement in a commit meant to prove nothing+ * moved. Rewriting the specifier fields is the mechanical, resolution-+ * preserving half of what that install would do; `pnpm install+ * --frozen-lockfile` then verifies the result is consistent.** Edits are surgical — only the value on a matched line is replaced — so key* order, indentation and every comment survive byte-for-byte, and nothing is* written when a file would be unchanged. That is what makes a second run a* no-op.*- * Bun run tooling/scripts/pin-from-pnpm-lock.ts bun run- * tooling/scripts/pin-from-pnpm-lock.ts --check # exit 1 if stale+ * bun run tooling/scripts/pin-from-pnpm-lock.ts+ * bun run tooling/scripts/pin-from-pnpm-lock.ts --check # exit 1 if stale*/import { write, YAML } from 'bun';@@ -66,13 +63,11 @@ const PROTOCOL_SPECIFIER = /^(workspace|catalog|npm|link|file|git|github):/;const PLAIN_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z-.]+)?$/;/**- * Rule 2 (ACCEPTED) names these two lines by path and rules that the stale- * `prisma: ^5.1.1` devDeps "are to be **deleted, not aligned to 6.14**" — i.e.- * touching their version is itself the wrong move, and the deletion belongs to- * a CLEAN task. Pinning them to the 5.9.1 the lock resolved would be exactly- * the aligning edit the ADR forbids, so the pinner leaves the manifest entry- * AND its `specifier:` in the lock alone. Rule 3 is the general P13 pinning- * permission; rule 2 is a specific, named exception to it.+ * These two `prisma: ^5.1.1` devDeps are stale and slated for deletion, not+ * for alignment to the version currently resolved. Pinning them to what the+ * lock resolved would look like an intentional upgrade rather than the+ * temporary state they're in, so the pinner leaves both the manifest entry+ * and its `specifier:` in the lock alone.*/const ADR_017_RULE_2_FROZEN: ReadonlySet<string> = new Set(['packages/redis\tdevDependencies\tprisma',diff --git a/tooling/scripts/write-p13-lock-snapshot.ts b/tooling/scripts/write-p13-lock-snapshot.tsindex 247c7db6e..0459d6d58 100644--- a/tooling/scripts/write-p13-lock-snapshot.ts+++ b/tooling/scripts/write-p13-lock-snapshot.ts@@ -4,9 +4,9 @@** The snapshot is the reference `tooling/gates/p13-drift.sh` compares an* installed tree against. It exists as a separate committed file because- * M13-002 DELETES `pnpm-lock.yaml`: once the lock is gone there is nothing left- * to say what pnpm had resolved, and "did the installer swap move anything?"- * becomes unanswerable. This file outlives the lock.+ * once the lock is gone there is nothing left to say what pnpm had+ * resolved, and "did the installer swap move anything?" becomes+ * unanswerable. This file outlives the lock.** Shape: { "<importer path>": { "<dependency>": "<exact version>" } }*