Skip to content

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 a
diff --git a/apps/api/e2e/trpc-routing-golden.ts b/apps/api/e2e/trpc-routing-golden.ts
index 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.ts
index 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 project
const createResult = await makeRequest('POST', '/manage/projects', {
name: `Test Project ${Date.now()}`,
domain: 'https://example.com',
@@ -110,7 +109,6 @@ async function testProjects() {
}
}
- // List projects
const listResult = await makeRequest('GET', '/manage/projects');
results.push(listResult);
console.log(
@@ -121,14 +119,12 @@ async function testProjects() {
}
if (projectId) {
- // Get project
const getResult = await makeRequest('GET', `/manage/projects/${projectId}`);
results.push(getResult);
console.log(
`✓ GET /manage/projects/:id: ${getResult.success ? '✅' : '❌'} ${getResult.status}`
);
- // Update project
const 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 client
const createResult = await makeRequest('POST', '/manage/clients', {
name: `Test Client ${Date.now()}`,
projectId: projectId || undefined,
@@ -183,7 +178,6 @@ async function testClients(projectId?: string) {
}
}
- // List clients
const listResult = await makeRequest(
'GET',
projectId ? `/manage/clients?projectId=${projectId}` : '/manage/clients'
@@ -197,14 +191,12 @@ async function testClients(projectId?: string) {
}
if (clientId) {
- // Get client
const getResult = await makeRequest('GET', `/manage/clients/${clientId}`);
results.push(getResult);
console.log(
`✓ GET /manage/clients/:id: ${getResult.success ? '✅' : '❌'} ${getResult.status}`
);
- // Update client
const 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 client
const deleteResult = await makeRequest(
'DELETE',
`/manage/clients/${clientId}`
@@ -237,7 +228,6 @@ async function testReferences(projectId?: string) {
return;
}
- // Create reference
const 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 references
const listResult = await makeRequest(
'GET',
`/manage/references?projectId=${projectId}`
@@ -272,7 +261,6 @@ async function testReferences(projectId?: string) {
}
if (referenceId) {
- // Get reference
const 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 reference
const 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 reference
const 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 clients
await testClients(projectId);
// Test references (requires a project)
await testReferences(projectId);
- // Summary
console.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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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 helper
function 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 segments
const { title, description } = await getOgData(og);
- // Truncate title and description
const truncatedTitle = truncateText(title, 100);
const truncatedDescription = description
? truncateText(description, 200)
: undefined;
- // Get background image URL
const 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 */}
<div
style={{
bottom: '55px',
@@ -240,7 +234,6 @@ export async function GET(
marginTop: 'auto',
}}
>
- {/* Title */}
<div
style={{
fontSize: truncatedTitle.length > 40 ? '56px' : '72px',
@@ -254,7 +247,6 @@ export async function GET(
{truncatedTitle}
</div>
- {/* Description */}
{truncatedDescription ? (
<div
style={{
diff --git a/apps/start/src/agents/client.ts b/apps/start/src/agents/client.ts
index 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.tsx
index 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 area
const 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 ? (
<g
mask={
@@ -170,7 +167,6 @@ export function Area({
</g>
) : null}
- {/* Stroke line on top of area */}
{showLine ? (
<>
<LinePath
diff --git a/apps/start/src/components/charts/bar-chart.tsx b/apps/start/src/components/charts/bar-chart.tsx
index 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 synchronously
function 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 overlay
function 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 children
const 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 scale
const 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 axis
const 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 bandwidth
const bandWidth = barWidthProp ?? categoryScale.bandwidth();
- // Compute max value considering stacking
const maxValue = useMemo(() => {
if (stacked) {
- // For stacked bars, sum all values at each data point
let 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 value
let 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 axis
const 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 bars
const stackOffsets = useMemo(() => {
if (!stacked) {
return undefined;
@@ -330,7 +319,6 @@ const ChartCore = memo(function ChartCore({
return () => clearTimeout(timer);
}, [animationDuration, revealSignature]);
- // Mouse move handler
const 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 over
const 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 bar
const 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 bars
let cumulative = 0;
let seriesIdx = 0;
for (const line of lines) {
@@ -402,7 +387,6 @@ const ChartCore = memo(function ChartCore({
}
}
} else {
- // Vertical grouped bars
const 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 band
let tooltipX: number;
if (isHorizontal) {
- // Position tooltip at the end of the longest bar
const 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-overlay
const 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.tsx
index 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 animation
const 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 series
const 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 width
return 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 lineCap
const 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 width
const 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 position
const 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 height
const 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 position
const 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.tsx
index 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 xScale
const 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.ts
index 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.tsx
index 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.tsx
index 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 */}
<g
onMouseEnter={handleMouseEnter}
@@ -249,7 +247,6 @@ export function MarkerGroup({
y={-size}
/>
- {/* Main marker */}
<MarkerCircle
borderColor={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 portal
diff --git a/apps/start/src/components/charts/op-date-pill.tsx b/apps/start/src/components/charts/op-date-pill.tsx
index 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 date
return `${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.tsx
index 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.tsx
index 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 category
const title = useMemo(() => {
if (!tooltipData) {
return undefined;
}
- // For bar charts (horizontal or vertical), use the category name
if (barXAccessor) {
return barXAccessor(tooltipData.point);
}
- // For line/area charts, use the date
return 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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 why
diff --git a/apps/start/src/components/facehash/avatar-fallback.tsx b/apps/start/src/components/facehash/avatar-fallback.tsx
index 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.tsx
index 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 state
const usesCssHover = groupHover;
- // Determine which colors to use based on scheme
const effectiveColors = React.useMemo(() => {
- // If explicit colors prop is provided, use it
if (colors) {
return colors;
}
- // If colorClasses is provided, don't use inline colors
if (colorClasses) {
return undefined;
}
- // Use scheme-specific colors or defaults
const 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 name
const { 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 preset
const preset = INTENSITY_PRESETS[intensity3d];
- // Calculate 3D transforms
const { 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 state
const 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 style
const sizeValue = typeof size === 'number' ? `${size}px` : size;
- // Initial letter
const initial = name.charAt(0).toUpperCase();
- // Background: either hex color (inline) or class
const 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' && (
<div
aria-hidden="true"
@@ -371,7 +358,6 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(
/>
)}
- {/* Face container with 3D transform */}
<div
className={
usesCssHover && interactive
@@ -393,7 +379,6 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(
} as React.CSSProperties
}
>
- {/* Face SVG */}
<FaceComponent
style={{
position: 'absolute',
@@ -402,7 +387,6 @@ export const Facehash = React.forwardRef<HTMLDivElement, FacehashProps>(
}}
/>
- {/* Initial letter */}
{showInitial && (
<span
data-facehash-avatar-initial=""
diff --git a/apps/start/src/components/facehash/faces.tsx b/apps/start/src/components/facehash/faces.tsx
index 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 }) => (
<svg
aria-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 }) => (
<svg
aria-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 }) => (
<svg
aria-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 }) => (
<svg
aria-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.tsx
index 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 closed
useOnPushModal('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.tsx
index 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 component
function 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 to
export 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 query
const 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 revenue
const { 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 setup
const 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 */}
<div
className="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 */}
<div
className="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">
<div
className="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 */}
<div
className="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.tsx
index 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.ts
index 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 density
let 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 provided
if (viewport && coordinates.length > 0) {
const viewportCoords = coordinates.filter(
(coord) =>
@@ -367,7 +362,6 @@ export function clusterCoordinates(
}
}
} else {
- // Simple zoom-based adjustment when adaptive is disabled
adjustedRadius = radius * Math.max(0.5, 1 / Math.sqrt(zoom));
}
@@ -415,7 +409,6 @@ function basicClusterCoordinates(coordinates: Coordinate[], radius: number) {
},
};
- // Mark the initial coordinate as visited
visited.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 coordinates
for (const member of [...cluster.members]) {
coordinatesWithDensity.forEach(
({
@@ -459,7 +451,6 @@ function basicClusterCoordinates(coordinates: Coordinate[], radius: number) {
}
}
- // Calculate the proper center for the cluster
cluster.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 debugging
export 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 dateline
const 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 crossing
let 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 crossing
for (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.tsx
index 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.tsx
index 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 container
const 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 + activeCoordinate
clientX = 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 components
const chartWithClickHandler = React.useMemo(() => {
const addClickHandler = (node: React.ReactNode): React.ReactNode => {
- // Handle null, undefined, strings, numbers
if (!React.isValidElement(node)) {
return node;
}
- // Check if this is a chart component
const componentName =
(node.type as any)?.displayName || (node.type as any)?.name;
const isChartComponent =
@@ -168,12 +151,10 @@ export const ChartClickMenu = forwardRef<
return children;
}
- // Handle arrays
if (Array.isArray(children)) {
return children.map(addClickHandler);
}
- // Handle React fragments
if (
React.isValidElement(children) &&
children.type === React.Fragment
@@ -186,7 +167,6 @@ export const ChartClickMenu = forwardRef<
});
}
- // Recursively process single child
return addClickHandler(children);
};
@@ -202,14 +182,12 @@ export const ChartClickMenu = forwardRef<
children: processChildren(element.props.children),
});
}
- // For chart components, add onClick directly
return React.cloneElement(element, {
onClick: handleChartClick,
children: processChildren(element.props.children),
});
}
- // Recursively process children for non-chart components
if (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 child
if (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.ts
index 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 metadata
groupKey?: 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 level
const 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 level
const newGroup: GroupedItem<T> = {
group: levelName,
items: [],
@@ -113,17 +102,13 @@ export function groupByNames<T extends { names: string[] }>(
}
}
- // Add the actual item to the deepest group
currentGroup.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 items
result.push(...flattenGroupedItems(item.items));
} else if (item) {
- // It's an actual item
result.push(item);
}
}
@@ -154,7 +137,6 @@ export function findGroup<T>(
return group;
}
- // Search in nested groups
for (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 items
const 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 values
const 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 group
const 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 row
const 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 items
const nestedGroups: GroupedItem<T>[] = [];
const actualItems: T[] = [];
@@ -328,26 +290,19 @@ export function groupsToTableRows<T extends TableRow>(
}
}
- // Process actual items first
actualItems.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 hierarchy
if (index === 0) {
- // First row shows all breakdown values
for (let i = 0; i < breakdownCount; i++) {
breakdownDisplay.push(breakdownValues[i] ?? null);
}
} else {
- // Subsequent rows: show values from parent path, then item values
for (let i = 0; i < breakdownCount; i++) {
if (i < currentPath.length) {
- // Show value from parent group path
breakdownDisplay.push(currentPath[i] ?? null);
} else if (i < breakdownValues.length) {
- // Show current breakdown value from the item
breakdownDisplay.push(breakdownValues[i] ?? null);
} else {
breakdownDisplay.push(null);
@@ -363,7 +318,6 @@ export function groupsToTableRows<T extends TableRow>(
});
});
- // Process nested groups
for (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 those
if (breakdowns.length > 0) {
return breakdowns.map((b) => getPropertyLabel(b.name));
}
- // Otherwise, infer from series names
// All series should have the same number of breakdown values
if (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 descending
flatRows.sort((a, b) => b.sum - a.sum);
- // Group rows by breakdown values hierarchically
const grouped: GroupedTableRow[] = [];
const breakdownCount = flatRows[0]?.breakdownValues.length ?? 0;
if (breakdownCount === 0) {
- // No breakdowns, just return flat rows
return 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 value
const 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 group
const 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 hierarchically
sortedGroups.forEach(([firstBreakdownValue, groupRows]) => {
- // Within each first-breakdown group, sort by sum
groupRows.sort((a, b) => b.sum - a.sum);
- // Generate group key for this first-breakdown group
const groupKey = firstBreakdownValue;
- // For each row in the group
groupRows.forEach((row, index) => {
const breakdownDisplay: (string | null)[] = [];
const firstRow = groupRows[0]!;
if (index === 0) {
- // First row shows all breakdown values
breakdownDisplay.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 row
breakdownDisplay.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 group
const 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 rows
const 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 index
const 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 mapping
const 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 rows
const 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 descending
if (!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 rows
const 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.tsx
index 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 props
leftPinnedColumns: 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) */}
<div
style={{
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 rows
const {
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 rows
const rows = expandableRows ?? flatRows ?? [];
- // Filter rows based on global search and apply sorting
const filteredRows = useMemo(() => {
let result = rows;
- // Apply search filter
if (globalFilter.trim()) {
const searchLower = globalFilter.toLowerCase();
result = rows.filter((row) => {
- // Search in serie name
if (row.serieName.toLowerCase().includes(searchLower)) {
return true;
}
- // Search in breakdown values
if (
row.breakdownValues.some((val) =>
val?.toLowerCase().includes(searchLower)
@@ -303,7 +292,6 @@ export function ReportTable({
return true;
}
- // Search in metric values
const metrics = ['count', 'sum', 'average', 'min', 'max'] as const;
if (
metrics.some((metric) =>
@@ -313,7 +301,6 @@ export function ReportTable({
return true;
}
- // Search in date values
if (
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 group
if (grouped && result.length > 0) {
const groupedRows = result as ExpandableTableRow[] | GroupedTableRow[];
- // Sort function based on current sort state
const 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 values
if (aValue == null && bValue == null) {
continue;
}
@@ -383,7 +366,6 @@ export function ReportTable({
return -1;
}
- // Compare values
if (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 recursively
function sortExpandableRows(
rows: ExpandableTableRow[],
isTopLevel = true
): ExpandableTableRow[] {
- // Sort rows: groups by count first (only at top level), then apply user sort
const sorted = [...rows].sort((a, b) => {
- // At top level, sort groups by count first
if (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 level
return 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 sorting
if (!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 values
if (aValue == null && bValue == null) {
continue;
}
@@ -486,7 +461,6 @@ export function ReportTable({
return -1;
}
- // Compare values
if (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 visualization
const { 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 rows
function 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 it
individualRows.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 ranges
const individualRows = getIndividualRows(rows);
const isSingleSeries = individualRows.length === 1;
if (isSingleSeries) {
- // For single series, calculate ranges from date values
const 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 dates
dates.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 series
metricRanges.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 parsing
const 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 opacity
let opacity: number;
if (max === min) {
opacity = 0.5;
@@ -652,7 +609,6 @@ export function ReportTable({
};
};
- // Normalize visibleSeries to string array
const 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 changes
const visibleSeriesIdsHash = useMemo(() => {
return visibleSeriesIds.sort().join(',');
}, [visibleSeriesIds]);
- // Get serie index for color
const getSerieIndex = (serieId: string): number => {
return data.series.findIndex((s) => s.id === serieId);
};
- // Toggle serie visibility
const 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 handlers
const 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 columns
const columns = useMemo<ColumnDef<TableRow | GroupedTableRow>[]>(() => {
const cols: ColumnDef<TableRow | GroupedTableRow>[] = [];
- // Serie name column (pinned left) with checkbox
cols.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 array
const 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 group
if (firstRowInGroup.id === original.id) {
isFirstRowInGroup = true;
} else {
@@ -781,7 +726,6 @@ export function ReportTable({
onClick={(e) => {
e.stopPropagation();
e.preventDefault();
- // Toggle expanded state manually
setExpanded((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 expanded
const 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 yet
if (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 expanded
const allExpanded =
rowsAtLevel.length > 0 &&
rowsAtLevel.every(
@@ -870,7 +810,6 @@ export function ReportTable({
if (!grouped) {
return;
}
- // Toggle all groups at this breakdown level
setExpanded((prev) => {
const newExpanded: ExpandedState =
typeof prev === 'object' ? { ...prev } : {};
@@ -969,7 +908,6 @@ export function ReportTable({
});
});
- // Metric columns
const 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 columns
dates.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 change
const columnsHash = useMemo(() => {
return columns.map((col) => col.id).join(',');
}, [columns]);
- // Memoize table options to ensure table updates when filteredRows changes
const 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 setup
useEffect(() => {
const updateScrollMargin = throttle(() => {
if (parentRef.current) {
@@ -1169,7 +1101,6 @@ export function ReportTable({
};
}, []);
- // Handle global mouseup to reset resize flag
useEffect(() => {
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 memoization
const rowModelToUse = grouped
? table.getExpandedRowModel()
@@ -1205,12 +1135,10 @@ export function ReportTable({
const virtualRows = virtualizer.getVirtualItems();
- // Get visible columns in order
const headerColumns = table
.getAllLeafColumns()
.filter((col) => table.getState().columnVisibility[col.id] !== false);
- // Separate columns into pinned and scrollable
const leftPinnedColumns = headerColumns.filter(
(col) => col.columnDef.meta?.pinned === 'left'
);
@@ -1221,7 +1149,6 @@ export function ReportTable({
(col) => !col.columnDef.meta?.pinned
);
- // Calculate widths for virtualization
const 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 it
const shouldVirtualizeHorizontal = scrollableColumns.length > 10;
@@ -1248,7 +1174,6 @@ export function ReportTable({
overscan: shouldVirtualizeHorizontal ? 5 : scrollableColumns.length,
});
- // Get virtual columns - if not virtualizing, return all columns
const virtualColumns = shouldVirtualizeHorizontal
? horizontalVirtualizer.getVirtualItems()
: scrollableColumns.map((col, index) => ({
@@ -1262,7 +1187,6 @@ export function ReportTable({
lane: 0,
}));
- // Pre-compute grid template columns string and headers
const { 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 columns
const 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 */}
<div
className="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) */}
<div
style={{
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 */}
<div
style={{
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.tsx
index 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 series
const 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 memoization
const 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 ranges
metricRanges.avgRate.min = Math.min(
metricRanges.avgRate.min,
row.avgRate
@@ -130,7 +126,6 @@ export function ConversionTable({
row.conversions
);
- // Date ranges
dates.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 style
const 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 name
if (
row.serieName.some((name) =>
name?.toLowerCase().includes(searchLower)
@@ -198,7 +191,6 @@ export function ConversionTable({
return true;
}
- // Search in breakdown values
if (
row.breakdownValues.some((val) =>
val?.toLowerCase().includes(searchLower)
@@ -207,7 +199,6 @@ export function ConversionTable({
return true;
}
- // Search in metric values
if (
String(row.avgRate).toLowerCase().includes(searchLower) ||
String(row.total).toLowerCase().includes(searchLower) ||
@@ -216,7 +207,6 @@ export function ConversionTable({
return true;
}
- // Search in date values
if (
Object.values(row.dateValues).some((val) =>
String(val).toLowerCase().includes(searchLower)
@@ -268,7 +258,6 @@ export function ConversionTable({
return -1;
}
- // Compare values
if (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.ts
index 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 type
const initialState: InitialState = {
ready: false,
dirty: false,
@@ -217,7 +216,6 @@ export const reportSlice = createSlice({
state.metric = 'count';
}
- // Initialize sankey options if switching to sankey
if (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 function
export const {
reset,
ready,
diff --git a/apps/start/src/components/report/sidebar/filters/FilterItem.tsx b/apps/start/src/components/report/sidebar/filters/FilterItem.tsx
index 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.tsx
index 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 queries
const 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 index
const 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 index
const columnKey =
column.key ??
(typeof column.name === 'string'
diff --git a/apps/start/src/modals/insight-details.tsx b/apps/start/src/modals/insight-details.tsx
index 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 mount
useEffect(() => {
mutation.mutate({ insightId: insight.id });
diff --git a/apps/start/src/modals/view-chart-users.tsx b/apps/start/src/modals/view-chart-users.tsx
index 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 component
function 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 ready
useEffect(() => {
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 change
useEffect(() => {
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 component
interface 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 serie
const matchingChartSeries = useMemo(() => {
if (!(selectedSerieId && chartData)) {
return [];
@@ -315,7 +310,6 @@ function ChartUsersView({ chartData, report, date }: ChartUsersViewProps) {
);
}
-// Funnel-specific props and component
interface FunnelUsersViewProps {
report: IReportInput;
stepIndex: number;
@@ -416,7 +410,6 @@ function FunnelUsersView({
);
}
-// Union type for props
type ViewChartUsersProps =
| {
type: 'chart';
@@ -431,7 +424,6 @@ type ViewChartUsersProps =
breakdownValues?: string[];
};
-// Main component that routes to the appropriate view
export 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.ts
index 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 sections
DASHBOARD: 'Dashboard',
diff --git a/packages/core/scripts/get-bots.ts b/packages/core/scripts/get-bots.ts
index 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 regex
return { regex, ...rest };
}
- // Convert to includes
return { includes: regex, ...rest };
});
}
async function main() {
- // Get document, or throw exception on error
try {
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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 MGET
const 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.ts
index 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.ts
index 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: IServiceCreateEventPayload
diff --git a/packages/core/src/cacheable-per-deps.ts b/packages/core/src/cacheable-per-deps.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 bundle
const 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.ts
index 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.ts
index 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.ts
index 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 spelling
diff --git a/packages/core/src/context.ts b/packages/core/src/context.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: the
diff --git a/packages/core/src/http/hooks.ts b/packages/core/src/http/hooks.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 of
diff --git a/packages/core/src/modules/chart/chart.constants.ts b/packages/core/src/modules/chart/chart.constants.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 users
export 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 group
const 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_count
const totalCountResult = evaluateFormula(
formula.formula,
totalCountScope
@@ -112,7 +109,6 @@ export function compute(
const formulaTotalCount =
totalCountResult === undefined ? undefined : round(totalCountResult, 2);
- // Calculate formula for each date
const 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 group
const 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.ts
index 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 series
const definition = definitions[cs.definitionIndex];
const alphaId = includeAlphaIds
? alphabetIds[cs.definitionIndex]
: undefined;
- // Build display name with optional alpha ID
let displayName: string[];
- // Replace the first name (which is the event name) with the display name if it exists
const 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 exists
if (alphaId) {
displayName = [`(${alphaId}) ${names[0]}`, ...names.slice(1)];
} else {
displayName = names;
}
- // Calculate metrics for this series
const 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 compatibility
const eventName =
definition?.type === 'formula'
? definition.displayName || definition.formula || 'Formula'
: definition?.name || cs.context.event || 'unknown';
- // Find matching previous series
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 comes
diff --git a/packages/core/src/modules/chart/src/retention.sql.ts b/packages/core/src/modules/chart/src/retention.sql.ts
index 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 a
diff --git a/packages/core/src/modules/chart/src/run-query.ts b/packages/core/src/modules/chart/src/run-query.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 whatever
diff --git a/packages/core/src/modules/chart/src/table-filter-where.ts b/packages/core/src/modules/chart/src/table-filter-where.ts
index 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.ts
index 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.ts
index 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.ts
index 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: string
diff --git a/packages/core/src/modules/cohort/cohort.rpc.ts b/packages/core/src/modules/cohort/cohort.rpc.ts
index 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.ts
index 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 own
diff --git a/packages/core/src/modules/cohort/cohort.service.ts b/packages/core/src/modules/cohort/cohort.service.ts
index 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 count
FROM ${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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 window
if (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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 limits
let 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.ts
index 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.ts
index 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.ts
index 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 minutes
export 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.ts
index 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 date
if (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 date
const 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.ts
index 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 hour
this.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 limit
if (
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 waiting
this.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 line
const 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 lines
const 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 buffer
if (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 data
const 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 properties
const properties = this.stripMixpanelProperties(props, query);
if (props.$insert_id) {
properties.__source_insert_id = String(props.$insert_id);
}
- // Add useful properties
if (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 data
const 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 desktop
return 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 properties
const 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.ts
index 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 stream
const 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 tracking
const 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 events
const 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 events
const 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 data
const country = rawEvent.country || '';
const city = rawEvent.city || '';
const region = rawEvent.region || '';
- // Extract browser/device info
const browser = rawEvent.browser || '';
const browserVersion = ''; // Not available in Umami CSV
const os = rawEvent.os || '';
@@ -315,7 +306,6 @@ export class UmamiProvider extends BaseImportProvider<UmamiRawEvent> {
properties.__query = query;
}
- // Add useful properties from Umami data
if (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.ts
index 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 patterns
if (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.ts
index 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.ts
index 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.ts
index 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 future
if (
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 minutes
const 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 user
if (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.ts
index 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.ts
index 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.ts
index 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 IPs
const ipFilter = client.project.filters.filter(
(filter): filter is IProjectFilterIp => filter.type === 'ip'
);
@@ -214,7 +208,6 @@ export async function validateIngestRequest({
);
}
- // Filter out blocked profile ids
const 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.ts
index 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.ts
index 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.ts
index 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 the
diff --git a/packages/core/src/modules/ingest/src/device-id.test.ts b/packages/core/src/modules/ingest/src/device-id.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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-supp
expect(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.ts
index 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: string
diff --git a/packages/core/src/modules/insight/src/cached-query.ts b/packages/core/src/modules/insight/src/cached-query.ts
index 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.ts
index 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.ts
index 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, no
diff --git a/packages/core/src/modules/insight/src/explain.ts b/packages/core/src/modules/insight/src/explain.ts
index 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.ts
index 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 first
const 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.ts
index 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.ts
index 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 first
const existing = prev
? await db.projectInsight.findFirst({
where: {
@@ -140,12 +139,11 @@ export function createInsightStore(deps: ServiceDeps): InsightStore {
let insight: InsightRow;
if (existing) {
- // Update existing
insight = 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 update
insight = 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 new
insight = 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.ts
index 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.ts
index 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 weekday
const 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 dimension
const 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 maps
const 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.ts
index 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 modes
const 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 auth
export const zS3ExportConfigIamRole = zS3ExportConfigBase.merge(zS3AuthIamRole);
export type IS3ExportConfigIamRole = z.infer<typeof zS3ExportConfigIamRole>;
-// S3 config with access key auth
export const zS3ExportConfigAccessKey =
zS3ExportConfigBase.merge(zS3AuthAccessKey);
export type IS3ExportConfigAccessKey = z.infer<typeof zS3ExportConfigAccessKey>;
-// Combined discriminated union
export const zS3ExportConfig = z.discriminatedUnion('authMode', [
zS3ExportConfigIamRole,
zS3ExportConfigAccessKey,
]);
export type IS3ExportConfig = z.infer<typeof zS3ExportConfig>;
-// GCS Export Integration Config
export 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.ts
index 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.ts
index 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 connection
await 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: () => Services
diff --git a/packages/core/src/modules/integration/src/export/batch-creator.ts b/packages/core/src/modules/integration/src/export/batch-creator.ts
index 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 info
partitionDate: string; // YYYY-MM-DD
partitionHour: 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.ts
index 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.ts
index 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 discovery
partition_date: string; // YYYY-MM-DD
partition_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.ts
index 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: FlushExportsDeps
diff --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.ts
index 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.ts
index 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 encrypted
this.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: CoreConfig
diff --git a/packages/core/src/modules/integration/src/object-store/s3-adapter.ts b/packages/core/src/modules/integration/src/object-store/s3-adapter.ts
index 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 expire
this.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: CoreConfig
diff --git a/packages/core/src/modules/integration/src/object-store/types.ts b/packages/core/src/modules/integration/src/object-store/types.ts
index 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.ts
index 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.ts
index 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.ts
import * 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.ts
index 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 it
diff --git a/packages/core/src/modules/mcp/mcp.service.test.ts b/packages/core/src/modules/mcp/mcp.service.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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?: string
diff --git a/packages/core/src/modules/misc/misc.service.ts b/packages/core/src/modules/misc/misc.service.ts
index 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 fallback
if (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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: () => Services
diff --git a/packages/core/src/modules/notification/src/notification-dispatch.ts b/packages/core/src/modules/notification/src/notification-dispatch.ts
index 715a24666..67b72d45e 100644
Binary files a/packages/core/src/modules/notification/src/notification-dispatch.ts and b/packages/core/src/modules/notification/src/notification-dispatch.ts differ
diff --git a/packages/core/src/modules/onboarding/onboarding.service.test.ts b/packages/core/src/modules/onboarding/onboarding.service.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 date
if (
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 deletion
const 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 deletion
const 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.ts
index 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.ts
index 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 the
diff --git a/packages/core/src/modules/organization/src/wind-down.ts b/packages/core/src/modules/organization/src/wind-down.ts
index 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.ts
index 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.ts
index 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',
];
-// Types
type 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 color
const 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 filtering
nodes.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: string
diff --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.ts
index 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 local
diff --git a/packages/core/src/modules/overview/src/overview.sql.ts b/packages/core/src/modules/overview/src/overview.sql.ts
index 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.ts
index 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 title
FROM events
diff --git a/packages/core/src/modules/profile/profile.routes.test.ts b/packages/core/src/modules/profile/profile.routes.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 fil
expect(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.ts
index 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.ts
index 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 union
export 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 type
export 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 fields
export type IReport = z.infer<typeof zReport>;
-// For API/engine use - flexible input
export 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.ts
index 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.ts
index 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 module
diff --git a/packages/core/src/modules/salt/salt.service.ts b/packages/core/src/modules/salt/salt.service.ts
index 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.ts
index 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.ts
index 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: EnqueueSessionEndInput
diff --git a/packages/core/src/modules/session/src/session-end.ts b/packages/core/src/modules/session/src/session-end.ts
index 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.ts
index 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.ts
index 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.ts
index 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 content
diff --git a/packages/core/src/modules/subscription/subscription.service.ts b/packages/core/src/modules/subscription/subscription.service.ts
index 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.ts
index 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 data
const 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 type
async 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 data
const 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 public
const 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 histogram
const 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 countries
const 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 referrers
const 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 paths
const pathsQueryPromise = options.paths
? chQuery<{ path: string; count: number }>(
ctx,
diff --git a/packages/core/src/pino-logger.ts b/packages/core/src/pino-logger.ts
index 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.ts
index 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.ts
index 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', asyn
expect(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.ts
index 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 mutations
if (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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 project
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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/8
if (ip.startsWith('10.')) {
return false;
@@ -81,7 +80,6 @@ function isPublicIp(ip: string): boolean {
}
function isValidIp(ip: string): boolean {
- // Basic IP validation
const 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 value
if (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.ts
index 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 arrays
if (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 properties
for (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 patterns
if (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.ts
index 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 functions
const 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.ts
index 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 error
if (validationError) {
return;
}
@@ -418,7 +412,6 @@ export function validate(code: string): {
return;
}
- // Check identifiers that reference globals
if (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/parameter
if (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.ts
index 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.ts
index 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-up
expect(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 req
expect(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 an
expect(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 envelope
expect(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 envelope
expect(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.ts
index 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.ts
index 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 clause
const 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 date
const 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 interval
const shouldContinue = (
current: Date,
start: Date,
intervalType: string
): boolean => {
if (intervalType === 'month') {
- // For months, compare by year and month
- // Continue if current month is >= start month
const 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 dates
const currentWeekStart = getWeekStart(current);
const startWeekStart = getWeekStart(start);
return currentWeekStart >= startWeekStart;
@@ -451,11 +446,9 @@ export async function runClickhouseMigrationCommands(sqls: string[]) {
}
};
- // Create bound handler functions
const handleSigterm = () => handleTermination('SIGTERM');
const handleSigint = () => handleTermination('SIGINT');
- // Register handlers
process.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 seconds
timer = 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.ts
index 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.ts
index 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.ts
index 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 | SqlParam
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 38376fcc1..c96114b41 100644
--- a/packages/payments/src/polar.ts
+++ b/packages/payments/src/polar.ts
@@ -1,4 +1,3 @@
-// src/polar.ts
import { Polar } from '@polar-sh/sdk';
export {
diff --git a/packages/redis/cachable.test.ts b/packages/redis/cachable.test.ts
index 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 tests
const keys = [
...(await redis.keys('cachable:*')),
...(await redis.keys('test-key*')),
@@ -19,7 +18,6 @@ describe('cachable', () => {
});
afterEach(async () => {
- // Clean up after each test
const 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 data
await 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 cached
const 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 first
await 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 cached
const 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 cached
const 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 data
const 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 data
let 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 cached
const 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 cached
const 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 cached
const 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 cached
const 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 Redis
const 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 Redis
const firstCachedFn = cacheable('sharedEmptyArrayFn', firstFn, 3600, {
cacheEmptyArray: true,
});
@@ -347,7 +332,6 @@ describe('cachable', () => {
expect(result).toEqual({});
expect(fnCalled).toBe(true);
- // Verify nothing was cached
const 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 cached
const 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 cached
const 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 cached
const 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 cached
const 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 cached
const 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 cache
const 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 Date
const 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 parsing
let 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 data
await cachedFn('arg1', 'arg2');
- // Verify it's cached
const key = cachedFn.getKey('arg1', 'arg2');
let cached = await redis.get(key);
expect(cached).not.toBeNull();
- // Clear it
const result = await cachedFn.clear('arg1', 'arg2');
expect(result).toBe(1);
- // Verify it's cleared
cached = 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 set
const 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.ts
index 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 function
const 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 time
if (useLruCache) {
globalLruCache.set(key, parsed, {
- ttl: expireInSec * 1000, // Use the same TTL as Redis
+ ttl: expireInSec * 1000,
});
}
return parsed;
}
- // Cache miss: Execute function
const data = await fn();
- // Store in both caches
if (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 cache
export 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 types
return String(obj);
}
@@ -114,12 +106,10 @@ export interface CacheableOptions {
}
function shouldCache(result: unknown, options: CacheableOptions = {}): boolean {
- // Don't cache undefined or null
if (result === undefined || result === null) {
return false;
}
- // Don't cache empty strings
if (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 objects
if (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 signature
if (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 function
const result = await fn(...(args as any));
if (shouldCache(result, options)) {
diff --git a/packages/redis/dead-letter.ts b/packages/redis/dead-letter.ts
index 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.ts
index 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.ts
index 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 the
diff --git a/packages/redis/publisher.ts b/packages/redis/publisher.ts
index 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.ts
index 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.ts
index 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.ts
index 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 validation
const 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 value
if (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.ts
index 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.ts
index 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.ts
index 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 Docs
const salt = generateSalt();
scrypt(password, salt, keyLength, (err, derivedKey) => {
if (err) {
reject(err);
}
- // derivedKey is of type Buffer
resolve(`${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 timeSafeEqual
resolve(
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.ts
index 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 first
const 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 model
if (!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 result
parseCache.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 server
return (
res.os.name === undefined &&
res.browser.name === undefined &&
@@ -350,7 +346,6 @@ export function getDevice(ua: string, model?: string) {
return 'mobile';
}
- // Check for mobile patterns
const 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 phone
if (isAndroid && !hasMobileKeyword && !isSamsungMobile && !isLGMobile) {
- // Extract model from app-style UA if present
const appInfo = extractAppStyleInfo(ua);
if (appInfo.model && isKnownPhoneModel(appInfo.model)) {
return 'mobile';
}
- // If we have a brand but no clear device type, assume mobile for Android
const brand = detectBrand(ua, appInfo.model);
if (brand) {
return 'mobile';
diff --git a/self-hosting/quiz.ts b/self-hosting/quiz.ts
index 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 file
const dockerCompose = yaml.load(dockerComposeContent) as DockerComposeFile;
- // Remove the service
if (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_on
Object.keys(dockerCompose.services).forEach((service) => {
const serviceConfig = dockerCompose.services[service];
if (serviceConfig?.depends_on) {
@@ -135,7 +132,6 @@ function removeServiceFromDockerCompose(serviceName: string) {
}
});
- // filter volumes
Object.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 YAML
const newYaml = yaml.dump(dockerCompose, {
lineWidth: -1,
});
diff --git a/test/bun-preload.ts b/test/bun-preload.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 calculation
let minIndent = Number.POSITIVE_INFINITY;
for (const line of lines) {
const trimmed = line.trim();
- // Skip empty lines
if (trimmed.length === 0) {
continue;
}
@@ -31,21 +28,16 @@ const dedentContent = (text: string): string => {
}
}
- // If no indentation found, return as-is
if (minIndent === Number.POSITIVE_INFINITY || minIndent === 0) {
return text;
}
- // Remove the common indentation from all lines
return 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 indentation
const dedented = line.slice(minIndent);
- // If the line was all whitespace, return empty string to preserve the line
return line.trim().length === 0 ? '' : dedented;
})
.join('\n');
@@ -57,7 +49,6 @@ const transformMdxToReadme = (
): string => {
let content = mdxContent;
- // Load MDX component content files
const 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 frontmatter
const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
let title = packageName;
let description = '';
@@ -100,12 +90,11 @@ const transformMdxToReadme = (
description = descMatch[1].trim();
}
- // Remove frontmatter
content = 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 content
const 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 placeholders
content = 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 prop
const 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 sections
if (tabsItems.length > 0) {
- // Match each Tab and convert to a markdown section
content = 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 wrapper
content = content.replace(/<Tabs[^>]*>([\s\S]*?)<\/Tabs>/g, '$1');
} else {
- // Fallback: if no items prop, just convert tabs to sections
content = 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 tag
let previousContent = '';
while (content !== previousContent) {
previousContent = content;
- // Match JSX components with their content - handles one level of nesting
content = 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 blocks
codeBlockPlaceholders.forEach((codeBlock, index) => {
content = content.replace(`__CODE_BLOCK_${index}__`, codeBlock);
});
- // Convert internal links (starting with /) to absolute URLs
content = content.replace(
/\[([^\]]+)\]\((\/[^)]+)\)/g,
'[$1](https://openpanel.dev$2)'
);
- // Clean up extra blank lines
content = content.replace(/\n{3,}/g, '\n\n').trim();
- // Build the README header
const 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.ts
index 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.ts
index 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>" } }
*