Skip to content

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

ralph(M15-114): Per-module fixes: packages/core/src/modules/insight - R1, R11, R13, R16 and the findings no rule covers

ralphc6a281cbda7f
diff --git a/apps/start/src/routes/_app.$organizationId.$projectId.insights.tsx b/apps/start/src/routes/_app.$organizationId.$projectId.insights.tsx
index 8ea5fda3a..33c947fd5 100644
--- a/apps/start/src/routes/_app.$organizationId.$projectId.insights.tsx
+++ b/apps/start/src/routes/_app.$organizationId.$projectId.insights.tsx
@@ -1,3 +1,4 @@
+import { INSIGHT_LIST_ALL_MAX_LIMIT } from '@openpanel/core/modules/insight/insight.constants';
import { FullPageEmptyState } from '@/components/full-page-empty-state';
import { useRangePageContext } from '@/hooks/use-page-context-helpers';
import { InsightCard } from '@/components/insights/insight-card';
@@ -71,7 +72,7 @@ function Component() {
const { data: insights, isLoading } = useQuery(
trpc.insight.listAll.queryOptions({
projectId,
- limit: 500,
+ limit: INSIGHT_LIST_ALL_MAX_LIMIT,
}),
);
const navigate = useNavigate();
diff --git a/packages/core/src/modules/insight/insight.constants.ts b/packages/core/src/modules/insight/insight.constants.ts
index 785eadc77..f71f17c65 100644
--- a/packages/core/src/modules/insight/insight.constants.ts
+++ b/packages/core/src/modules/insight/insight.constants.ts
@@ -3,6 +3,14 @@
// AGENTS.md rule, which constrains a constants file's imports, and this file
// has none.
+// The two list procedures' page bounds. Vocabulary, not implementation: the
+// dashboard pages that call `insight.list` / `insight.listAll` size their own
+// requests against the same numbers the procedure enforces.
+export const INSIGHT_LIST_DEFAULT_LIMIT = 50;
+export const INSIGHT_LIST_MAX_LIMIT = 100;
+export const INSIGHT_LIST_ALL_DEFAULT_LIMIT = 200;
+export const INSIGHT_LIST_ALL_MAX_LIMIT = 500;
+
export type InsightMetricKey = 'sessions' | 'pageviews' | 'share';
export type InsightMetricUnit = 'count' | 'ratio';
diff --git a/packages/core/src/modules/insight/insight.rpc.ts b/packages/core/src/modules/insight/insight.rpc.ts
index 01c649410..4feddc122 100644
--- a/packages/core/src/modules/insight/insight.rpc.ts
+++ b/packages/core/src/modules/insight/insight.rpc.ts
@@ -12,7 +12,13 @@
import { z } from 'zod';
import { createTRPCRouter, protectedProcedure } from '../../rpc/base';
-import type { InsightPayload } from './insight.constants';
+import {
+ INSIGHT_LIST_ALL_DEFAULT_LIMIT,
+ INSIGHT_LIST_ALL_MAX_LIMIT,
+ INSIGHT_LIST_DEFAULT_LIMIT,
+ INSIGHT_LIST_MAX_LIMIT,
+ type InsightPayload,
+} from './insight.constants';
const DAY_MS = 24 * 60 * 60 * 1000;
const EXPLAIN_COLUMNS = [
@@ -22,12 +28,21 @@ const EXPLAIN_COLUMNS = [
'utm_source',
] as const;
+// `list` deduplicates by window AFTER the query, so it has to over-fetch or a
+// page of duplicates comes back short.
+const LIST_DEDUPE_OVERFETCH = 3;
+
export const insightRouter = createTRPCRouter({
list: protectedProcedure
.input(
z.object({
projectId: z.string(),
- limit: z.number().min(1).max(100).optional().default(50),
+ limit: z
+ .number()
+ .min(1)
+ .max(INSIGHT_LIST_MAX_LIMIT)
+ .optional()
+ .default(INSIGHT_LIST_DEFAULT_LIMIT),
})
)
.query(async ({ input: { projectId, limit }, ctx }) => {
@@ -43,7 +58,7 @@ export const insightRouter = createTRPCRouter({
// nulls:last), with the statistical impactScore as the tiebreaker.
const allInsights = await ctx.services.insight.listInsights({
projectId,
- limit: limit * 3,
+ limit: limit * LIST_DEDUPE_OVERFETCH,
});
// WindowKind priority: yesterday (1) > rolling_7d (2) > rolling_30d (3)
@@ -83,7 +98,12 @@ export const insightRouter = createTRPCRouter({
.input(
z.object({
projectId: z.string(),
- limit: z.number().min(1).max(500).optional().default(200),
+ limit: z
+ .number()
+ .min(1)
+ .max(INSIGHT_LIST_ALL_MAX_LIMIT)
+ .optional()
+ .default(INSIGHT_LIST_ALL_DEFAULT_LIMIT),
})
)
.query(async ({ input: { projectId, limit }, ctx }) => {
diff --git a/packages/core/src/modules/insight/insight.service.test.ts b/packages/core/src/modules/insight/insight.service.test.ts
index af40b85fb..86635187c 100644
--- a/packages/core/src/modules/insight/insight.service.test.ts
+++ b/packages/core/src/modules/insight/insight.service.test.ts
@@ -24,10 +24,22 @@ const $executeRaw = mock((..._args: unknown[]) => {
executeRawCalls.push(_args);
return Promise.resolve(executeRawReturns.shift() ?? 0);
});
+// M15-114: the explain cache is `deps.redis` (ADR-022 R16), so the fake is a
+// map on the scope — no `@openpanel/redis` module mock, which would replace
+// that barrel process-wide for every other file in the run.
+const redisStore = new Map<string, string>();
+const redis = {
+ get: mock((key: string) => Promise.resolve(redisStore.get(key) ?? null)),
+ setex: mock((key: string, _ttl: number, value: string) => {
+ redisStore.set(key, value);
+ return Promise.resolve();
+ }),
+};
// insight.service.ts never touches ClickHouse directly (it's PG-only, via
// $executeRaw above), so `deps.ch` stays unbuilt.
const deps = {
db: { $executeRaw },
+ redis,
config: testCoreConfig(),
} as unknown as import('../../services').ServiceDeps;
@@ -38,9 +50,19 @@ mock.module('./src/referrer-spikes', () => ({
getReferrerSpikes: spikesQuery,
}));
-const legacyGenerateInsights = mock(async () => [
- { type: 'traffic_spike', message: 'test', data: {} },
-]);
+const LEGACY_SPIKE = {
+ type: 'traffic_spike',
+ message: 'test',
+ // A `TrafficSpikeResult` — `Insight.data` is the union of the ten detector
+ // result shapes, not `any`.
+ data: {
+ referrer_name: 'instagram.com',
+ date: '2026-09-01',
+ visitor_count: 120,
+ avg_previous_7_days: 30,
+ },
+};
+const legacyGenerateInsights = mock(async () => [LEGACY_SPIKE]);
mock.module('./src/legacy-scan', () => ({
createLegacyInsightsScanner: () => ({
generateInsights: legacyGenerateInsights,
@@ -57,26 +79,6 @@ mock.module('./src/explain', () => ({
generateInsightExplanation,
}));
-const redisStore = new Map<string, string>();
-const getRedisCache = mock(() => ({
- get: mock((key: string) => Promise.resolve(redisStore.get(key) ?? null)),
- setex: mock((key: string, _ttl: number, value: string) => {
- redisStore.set(key, value);
- return Promise.resolve();
- }),
-}));
-// Spread the real module rather than hand-listing every export: `mock.module`
-// replaces this specifier process-wide (bun runs every test file in one
-// shared module registry without `--isolate` — see AGENTS.md), so a partial
-// factory here (this barrel also carries `getCache`, the pub/sub publisher
-// and the run-every helpers) would silently break any other consumer sharing
-// this process — e.g. the mcp module's auth.ts, which calls `getCache`.
-const actualRedis = await import('@openpanel/redis');
-mock.module('@openpanel/redis', () => ({
- ...actualRedis,
- getRedisCache,
-}));
-
let subject: typeof import('./insight.service');
beforeAll(async () => {
subject = await import('./insight.service');
@@ -134,9 +136,7 @@ test('scanLegacyInsights delegates to the pre-engine detector, kept for parity',
const result = await subject.scanLegacyInsights(deps, 'p1');
expect(legacyGenerateInsights).toHaveBeenCalledWith('p1');
- expect(result).toEqual([
- { type: 'traffic_spike', message: 'test', data: {} },
- ]);
+ expect(result).toEqual([LEGACY_SPIKE]);
});
test('explainInsight is a cache-aside over the AI call, keyed by the caller-supplied cacheKey', async () => {
@@ -162,6 +162,11 @@ test('explainInsight is a cache-aside over the AI call, keyed by the caller-supp
);
expect(generateInsightExplanation).toHaveBeenCalledTimes(1);
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).
+ expect(redis.setex).toHaveBeenCalledTimes(1);
+ expect(redis.get).toHaveBeenCalledTimes(2);
});
test('createInsightService binds every InsightService method', () => {
diff --git a/packages/core/src/modules/insight/insight.service.ts b/packages/core/src/modules/insight/insight.service.ts
index 4e37f9a78..168a9985f 100644
--- a/packages/core/src/modules/insight/insight.service.ts
+++ b/packages/core/src/modules/insight/insight.service.ts
@@ -19,8 +19,11 @@
// (ADR-013); `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 (M12-008).
+//
+// M15-114: the explain cache runs on `deps.redis` (ADR-022 R16) — the app
+// shell owns that connection's lifecycle; this module never opens one of
+// its own.
-import { getRedisCache } from '@openpanel/redis';
import { sendEmail } from '../../clients/email';
import type { Logger } from '../../logger';
import type { ServiceDeps, Services } from '../../services';
@@ -627,22 +630,19 @@ export async function listInsights(
});
}
-export async function listAllInsights(
+/**
+ * The same query as `listInsights` under the name the insights PAGE calls it
+ * by; the two differ only in the router — `insight.list` over-fetches and
+ * deduplicates by window, `insight.listAll` takes the rows as they come.
+ */
+export function listAllInsights(
deps: ServiceDeps,
args: {
projectId: string;
limit: number;
}
-) {
- const db = deps.db;
- return db.projectInsight.findMany({
- where: { projectId: args.projectId, state: 'active' },
- orderBy: [
- { relevanceScore: { sort: 'desc', nulls: 'last' } },
- { impactScore: 'desc' },
- ],
- take: args.limit,
- });
+): ReturnType<typeof listInsights> {
+ return listInsights(deps, args);
}
/**
@@ -655,7 +655,7 @@ export async function explainInsight(
input: ExplainInsightInput,
cacheKey: string
): Promise<InsightExplanation | null> {
- const cached = await getRedisCache().get(cacheKey);
+ const cached = await deps.redis.get(cacheKey);
if (cached) {
return JSON.parse(cached) as InsightExplanation;
}
@@ -665,7 +665,7 @@ export async function explainInsight(
// Only cache a successful explanation — a null is a transient LLM failure
// and should be retried on the next click.
if (explanation) {
- await getRedisCache().setex(
+ await deps.redis.setex(
cacheKey,
EXPLAIN_CACHE_TTL_SEC,
JSON.stringify(explanation)
diff --git a/packages/core/src/modules/insight/src/engine.ts b/packages/core/src/modules/insight/src/engine.ts
index f38250006..d6accb743 100644
--- a/packages/core/src/modules/insight/src/engine.ts
+++ b/packages/core/src/modules/insight/src/engine.ts
@@ -8,6 +8,7 @@ import type {
ComputeResult,
InsightModule,
InsightStore,
+ SeverityBand,
WindowKind,
} from './types';
import { resolveWindow } from './windows';
@@ -18,6 +19,24 @@ const DEFAULT_WINDOWS: WindowKind[] = [
'rolling_30d',
];
+/** Severity is an ORDER, not an alphabet — comparing the band strings with `>`
+ * only agrees with it while the names happen to sort l < m < s. */
+const SEVERITY_RANK: Record<SeverityBand, number> = {
+ low: 1,
+ moderate: 2,
+ severe: 3,
+};
+
+function isSeverityIncrease(
+ next: SeverityBand | null | undefined,
+ prev: SeverityBand | null | undefined
+): boolean {
+ if (!(next && prev)) {
+ return false;
+ }
+ return SEVERITY_RANK[next] > SEVERITY_RANK[prev];
+}
+
/**
* Sanitize a string for PostgreSQL by removing null bytes (0x00).
* PostgreSQL text columns don't accept null bytes in UTF-8 encoding.
@@ -284,7 +303,7 @@ export function createEngine(args: {
decision.reason === 'direction_flip'
? 'direction_flip'
: decision.reason === 'severity_change'
- ? sev && prev.severityBand && sev > prev.severityBand
+ ? isSeverityIncrease(sev, prev.severityBand)
? 'severity_up'
: 'severity_down'
: 'updated';
diff --git a/packages/core/src/modules/insight/src/insight-modules.ts b/packages/core/src/modules/insight/src/insight-modules.ts
deleted file mode 100644
index 8c1a7b533..000000000
--- a/packages/core/src/modules/insight/src/insight-modules.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-export * from './engine';
-export * from './material';
-export * from './modules';
-export * from './scoring';
-export * from './store';
-export * from './types';
-export * from './utils';
-export * from './windows';
diff --git a/packages/core/src/modules/insight/src/legacy-scan.ts b/packages/core/src/modules/insight/src/legacy-scan.ts
index ce5ff57e0..2a2dd5ffe 100644
--- a/packages/core/src/modules/insight/src/legacy-scan.ts
+++ b/packages/core/src/modules/insight/src/legacy-scan.ts
@@ -56,10 +56,33 @@ const REFERRAL_SOURCE_MIN_SHARE = 0.5;
const COMPLETED_EVENT_STATUS = 'completed';
+/** Whatever the detector that produced the insight selected. Three of the ten
+ * shapes carry no date-ish column at all — see `insightPeriod`. */
+export type LegacyInsightData =
+ | TrafficSpikeResult
+ | EventSurgeResult
+ | NewVisitorTrendResult
+ | ReferralSourceResult
+ | SessionDurationResult
+ | TopContentResult
+ | BounceRateResult
+ | ReturningVisitorResult
+ | GeographicShiftResult
+ | EventCompletionResult;
+
export interface Insight {
type: string;
message: string;
- data: any;
+ data: LegacyInsightData;
+}
+
+/** The one period column a result shape carries, or '' for the shapes that
+ * carry none — those sort last, as an Invalid Date always has. */
+function insightPeriod(data: LegacyInsightData): string {
+ const periods = data as Partial<
+ Record<'date' | 'month' | 'week' | 'quarter', string>
+ >;
+ return periods.date || periods.month || periods.week || periods.quarter || '';
}
interface TrafficSpikeResult {
@@ -305,12 +328,8 @@ class LegacyInsightsScanner {
...eventCompletions,
].sort((a, b) => {
// Sort by most recent data first
- const dateA = new Date(
- a.data.date || a.data.month || a.data.week || a.data.quarter
- );
- const dateB = new Date(
- b.data.date || b.data.month || b.data.week || b.data.quarter
- );
+ 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/material.ts b/packages/core/src/modules/insight/src/material.ts
index 96c66e064..4f689ee16 100644
--- a/packages/core/src/modules/insight/src/material.ts
+++ b/packages/core/src/modules/insight/src/material.ts
@@ -1,11 +1,15 @@
import { severityBand as band } from './scoring';
-import type { MaterialDecision, PersistedInsight } from './types';
+import type {
+ InsightDirection,
+ MaterialDecision,
+ PersistedInsight,
+} from './types';
export function materialDecision(
prev: PersistedInsight | null,
next: {
changePct?: number;
- direction?: 'up' | 'down' | 'flat';
+ direction?: InsightDirection;
}
): MaterialDecision {
const nextBand = band(next.changePct);
@@ -14,7 +18,7 @@ export function materialDecision(
}
// direction flip is always meaningful
- const prevDir = (prev.direction ?? 'flat') as any;
+ const prevDir = prev.direction ?? 'flat';
const nextDir = next.direction ?? 'flat';
if (prevDir !== nextDir && (nextDir === 'up' || nextDir === 'down')) {
return {
@@ -25,7 +29,7 @@ export function materialDecision(
}
// severity band change
- const prevBand = (prev.severityBand ?? null) as any;
+ const prevBand = prev.severityBand ?? null;
if (prevBand !== nextBand && nextBand !== null) {
return {
material: true,
diff --git a/packages/core/src/modules/insight/src/modules/page-trends.module.ts b/packages/core/src/modules/insight/src/modules/page-trends.module.ts
index dd7ac4e9d..929b82d50 100644
--- a/packages/core/src/modules/insight/src/modules/page-trends.module.ts
+++ b/packages/core/src/modules/insight/src/modules/page-trends.module.ts
@@ -19,6 +19,10 @@ import {
const DELIMITER = '|||';
+/** One number, two call sites: the threshold below and `enumerateDimensions`'s
+ * fallback, which had drifted back to the pre-tightening 100. */
+const MAX_PAGES_PER_RUN = 30;
+
/** clix inlined the value; the pageview event name now binds. */
const SCREEN_VIEW_EVENT = sql.string('screen_view');
@@ -144,15 +148,20 @@ export const pageTrendsModule: InsightModule = {
// minTotal: require at least 1% combined share (current + baseline)
// minAbsDelta: require at least 1.0 percentage point shift
// minPct: require at least 35% relative change in share
- // maxDims: evaluate at most 30 pages/run (was 100)
- thresholds: { minTotal: 100, minAbsDelta: 100, minPct: 0.35, maxDims: 30 },
+ // maxDims: evaluate at most MAX_PAGES_PER_RUN pages/run (was 100)
+ thresholds: {
+ minTotal: 100,
+ minAbsDelta: 100,
+ minPct: 0.35,
+ maxDims: MAX_PAGES_PER_RUN,
+ },
async enumerateDimensions(ctx) {
const { currentMap, baselineMap } = await fetchPageTrendAggregates(ctx);
const topDims = selectTopDimensions(
currentMap,
baselineMap,
- this.thresholds?.maxDims ?? 100
+ this.thresholds?.maxDims ?? MAX_PAGES_PER_RUN
);
return topDims.map((dim) => `page:${dim}`);
},
diff --git a/packages/core/src/modules/insight/src/scoring.ts b/packages/core/src/modules/insight/src/scoring.ts
index 59a72ec0a..fa411e57b 100644
--- a/packages/core/src/modules/insight/src/scoring.ts
+++ b/packages/core/src/modules/insight/src/scoring.ts
@@ -1,4 +1,4 @@
-import type { ComputeResult } from './types';
+import type { ComputeResult, SeverityBand } from './types';
export function defaultImpactScore(r: ComputeResult): number {
const vol = (r.currentValue ?? 0) + (r.compareValue ?? 0);
@@ -7,9 +7,7 @@ export function defaultImpactScore(r: ComputeResult): number {
return Math.log1p(vol) * (pct * 100);
}
-export function severityBand(
- changePct?: number | null
-): 'low' | 'moderate' | 'severe' | null {
+export function severityBand(changePct?: number | null): SeverityBand | null {
const p = Math.abs(changePct ?? 0);
if (p < 0.1) {
return null;
diff --git a/packages/core/src/modules/insight/src/store.ts b/packages/core/src/modules/insight/src/store.ts
index 32815ed4b..3552504f9 100644
--- a/packages/core/src/modules/insight/src/store.ts
+++ b/packages/core/src/modules/insight/src/store.ts
@@ -8,11 +8,38 @@ import type { Prisma } from '@openpanel/db/src/prisma-client';
import type { ServiceDeps } from '../../../services';
import type {
Cadence,
+ InsightDirection,
+ InsightState,
InsightStore,
PersistedInsight,
+ SeverityBand,
WindowKind,
} from './types';
+/** One `project_insights` row as Prisma returns it. */
+type InsightRow = Awaited<
+ ReturnType<ServiceDeps['db']['projectInsight']['update']>
+>;
+
+/** The row's `state`/`direction`/`severityBand` are text columns; the engine's
+ * vocabulary for them is narrower than `string`. */
+function toPersistedInsight(row: InsightRow): PersistedInsight {
+ return {
+ id: row.id,
+ projectId: row.projectId,
+ moduleKey: row.moduleKey,
+ dimensionKey: row.dimensionKey,
+ windowKind: row.windowKind as WindowKind,
+ state: row.state as InsightState,
+ version: row.version,
+ impactScore: row.impactScore,
+ lastSeenAt: row.lastSeenAt,
+ lastUpdatedAt: row.lastUpdatedAt,
+ direction: row.direction as InsightDirection | null,
+ severityBand: row.severityBand as SeverityBand | null,
+ };
+}
+
/** `Prisma.DbNull` is a plain sentinel value that lives in the same module as
* the constructed client — reached through `context.ts`'s seam so this file
* value-imports nothing from `@openpanel/db`. Lazy: `context.ts`
@@ -24,300 +51,277 @@ function loadPrismaSentinels() {
export function createInsightStore(deps: ServiceDeps): InsightStore {
const db = deps.db;
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).
- async listProjectIdsForCadence(_cadence: Cadence): Promise<string[]> {
- const projects = await db.project.findMany({
- where: {
- deleteAt: null,
- eventsCount: { gt: 10_000 },
- updatedAt: { gt: new Date(Date.now() - 1000 * 60 * 60 * 24) },
- organization: {
- subscriptionStatus: 'active',
+ // `cadence` isn't read — there is only one today ('daily') — but it stays
+ // on the signature because InsightStore's contract names it (V1 parity).
+ async listProjectIdsForCadence(_cadence: Cadence): Promise<string[]> {
+ const projects = await db.project.findMany({
+ where: {
+ deleteAt: null,
+ eventsCount: { gt: 10_000 },
+ updatedAt: { gt: new Date(Date.now() - 1000 * 60 * 60 * 24) },
+ organization: {
+ subscriptionStatus: 'active',
+ },
},
- },
- select: { id: true },
- });
- return projects.map((p) => p.id);
- },
-
- async getProjectCreatedAt(projectId: string): Promise<Date | null> {
- const project = await db.project.findFirst({
- where: { id: projectId, deleteAt: null },
- select: { createdAt: true },
- });
- return project?.createdAt ?? null;
- },
-
- async getActiveInsightByIdentity({
- projectId,
- moduleKey,
- dimensionKey,
- windowKind,
- }): Promise<PersistedInsight | null> {
- const insight = await db.projectInsight.findFirst({
- where: {
- projectId,
- moduleKey,
- dimensionKey,
- windowKind,
- state: 'active',
- },
- });
-
- if (!insight) {
- return null;
- }
+ select: { id: true },
+ });
+ return projects.map((p) => p.id);
+ },
- return {
- id: insight.id,
- projectId: insight.projectId,
- moduleKey: insight.moduleKey,
- dimensionKey: insight.dimensionKey,
- windowKind: insight.windowKind as WindowKind,
- state: insight.state as 'active' | 'suppressed' | 'closed',
- version: insight.version,
- impactScore: insight.impactScore,
- lastSeenAt: insight.lastSeenAt,
- lastUpdatedAt: insight.lastUpdatedAt,
- direction: insight.direction,
- severityBand: insight.severityBand,
- };
- },
+ async getProjectCreatedAt(projectId: string): Promise<Date | null> {
+ const project = await db.project.findFirst({
+ where: { id: projectId, deleteAt: null },
+ select: { createdAt: true },
+ });
+ return project?.createdAt ?? null;
+ },
- async upsertInsight({
- projectId,
- moduleKey,
- dimensionKey,
- window,
- card,
- metrics,
- now,
- decision,
- prev,
- }): Promise<PersistedInsight> {
- const baseData = {
+ async getActiveInsightByIdentity({
projectId,
moduleKey,
dimensionKey,
- windowKind: window.kind,
- state: prev?.state === 'closed' ? 'active' : (prev?.state ?? 'active'),
- title: card.title,
- summary: card.summary ?? null,
- displayName: card.displayName,
- payload: card.payload,
- direction: metrics.direction ?? null,
- impactScore: metrics.impactScore,
- severityBand: metrics.severityBand ?? null,
- version: prev ? (decision.material ? prev.version + 1 : prev.version) : 1,
- windowStart: window.start,
- windowEnd: window.end,
- lastSeenAt: now,
- lastUpdatedAt: now,
- };
-
- // Try to find existing insight first
- const existing = prev
- ? await db.projectInsight.findFirst({
- where: {
- projectId,
- moduleKey,
- dimensionKey,
- windowKind: window.kind,
- state: prev.state,
- },
- })
- : null;
-
- let insight: any;
- if (existing) {
- // Update existing
- insight = await db.projectInsight.update({
- where: { id: existing.id },
- data: {
- ...baseData,
- threadId: existing.threadId, // Preserve 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).
- ...(decision.material ? { enrichedAt: null } : {}),
- },
- });
- } else {
- // Create new - need to check if there's a closed/suppressed one to reopen
- const closed = await db.projectInsight.findFirst({
+ windowKind,
+ }): Promise<PersistedInsight | null> {
+ const insight = await db.projectInsight.findFirst({
where: {
projectId,
moduleKey,
dimensionKey,
- windowKind: window.kind,
- state: { in: ['closed', 'suppressed'] },
+ windowKind,
+ state: 'active',
},
- orderBy: { lastUpdatedAt: 'desc' },
});
- if (closed) {
- // Reopen and update
+ return insight ? toPersistedInsight(insight) : null;
+ },
+
+ async upsertInsight({
+ projectId,
+ moduleKey,
+ dimensionKey,
+ window,
+ card,
+ metrics,
+ now,
+ decision,
+ prev,
+ }): Promise<PersistedInsight> {
+ const baseData = {
+ projectId,
+ moduleKey,
+ dimensionKey,
+ windowKind: window.kind,
+ state: prev?.state === 'closed' ? 'active' : (prev?.state ?? 'active'),
+ title: card.title,
+ summary: card.summary ?? null,
+ displayName: card.displayName,
+ payload: card.payload,
+ direction: metrics.direction ?? null,
+ impactScore: metrics.impactScore,
+ severityBand: metrics.severityBand ?? null,
+ version: prev ? (decision.material ? prev.version + 1 : prev.version) : 1,
+ windowStart: window.start,
+ windowEnd: window.end,
+ lastSeenAt: now,
+ lastUpdatedAt: now,
+ };
+
+ // Try to find existing insight first
+ const existing = prev
+ ? await db.projectInsight.findFirst({
+ where: {
+ projectId,
+ moduleKey,
+ dimensionKey,
+ windowKind: window.kind,
+ state: prev.state,
+ },
+ })
+ : null;
+
+ let insight: InsightRow;
+ if (existing) {
+ // Update existing
insight = await db.projectInsight.update({
- where: { id: closed.id },
+ where: { id: existing.id },
data: {
...baseData,
- state: 'active',
- threadId: closed.threadId, // Preserve threadId
- // Reopening is a material event — re-enrich it.
- enrichedAt: null,
+ threadId: existing.threadId, // Preserve 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).
+ ...(decision.material ? { enrichedAt: null } : {}),
},
});
} else {
- // Create new
- insight = await db.projectInsight.create({
- data: {
- ...baseData,
- firstDetectedAt: now,
+ // Create new - need to check if there's a closed/suppressed one to reopen.
+ // `suppressed` is only ever a row written before `applySuppression` began
+ // deleting instead of suppressing; it stays in the filter so those rows
+ // still reopen with their threadId.
+ const closed = await db.projectInsight.findFirst({
+ where: {
+ projectId,
+ moduleKey,
+ dimensionKey,
+ windowKind: window.kind,
+ state: { in: ['closed', 'suppressed'] },
},
+ orderBy: { lastUpdatedAt: 'desc' },
});
+
+ if (closed) {
+ // Reopen and update
+ insight = await db.projectInsight.update({
+ where: { id: closed.id },
+ data: {
+ ...baseData,
+ state: 'active',
+ threadId: closed.threadId, // Preserve threadId
+ // Reopening is a material event — re-enrich it.
+ enrichedAt: null,
+ },
+ });
+ } else {
+ // Create new
+ insight = await db.projectInsight.create({
+ data: {
+ ...baseData,
+ firstDetectedAt: now,
+ },
+ });
+ }
}
- }
- return {
- id: insight.id,
- projectId: insight.projectId,
- moduleKey: insight.moduleKey,
- dimensionKey: insight.dimensionKey,
- windowKind: insight.windowKind as WindowKind,
- state: insight.state as 'active' | 'suppressed' | 'closed',
- version: insight.version,
- impactScore: insight.impactScore,
- lastSeenAt: insight.lastSeenAt,
- lastUpdatedAt: insight.lastUpdatedAt,
- direction: insight.direction,
- severityBand: insight.severityBand,
- };
- },
+ return toPersistedInsight(insight);
+ },
- // 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.
- async insertEvent({
- insightId,
- eventKind,
- changeFrom,
- changeTo,
- now,
- }): Promise<void> {
- const { DbNull } = await loadPrismaSentinels();
- await db.insightEvent.create({
- data: {
- insightId,
- eventKind,
- changeFrom: changeFrom
- ? (changeFrom as Prisma.InputJsonValue)
- : DbNull,
- changeTo: changeTo
- ? (changeTo as Prisma.InputJsonValue)
- : DbNull,
- createdAt: now,
- },
- });
- },
+ // 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.
+ async insertEvent({
+ insightId,
+ eventKind,
+ changeFrom,
+ changeTo,
+ now,
+ }): Promise<void> {
+ const { DbNull } = await loadPrismaSentinels();
+ await db.insightEvent.create({
+ data: {
+ insightId,
+ eventKind,
+ changeFrom: changeFrom
+ ? (changeFrom as Prisma.InputJsonValue)
+ : DbNull,
+ changeTo: changeTo
+ ? (changeTo as Prisma.InputJsonValue)
+ : DbNull,
+ createdAt: now,
+ },
+ });
+ },
- async closeMissingActiveInsights({
- projectId,
- moduleKey,
- windowKind,
- seenDimensionKeys,
- now,
- staleDays,
- }): Promise<number> {
- const staleDate = new Date(now);
- staleDate.setDate(staleDate.getDate() - staleDays);
+ async closeMissingActiveInsights({
+ projectId,
+ moduleKey,
+ windowKind,
+ seenDimensionKeys,
+ now,
+ staleDays,
+ }): Promise<number> {
+ const staleDate = new Date(now);
+ staleDate.setDate(staleDate.getDate() - staleDays);
- const result = await db.projectInsight.updateMany({
- where: {
- projectId,
- moduleKey,
- windowKind,
- state: 'active',
- lastSeenAt: { lt: staleDate },
- dimensionKey: { notIn: seenDimensionKeys },
- },
- data: {
- state: 'closed',
- lastUpdatedAt: now,
- },
- });
+ const result = await db.projectInsight.updateMany({
+ where: {
+ projectId,
+ moduleKey,
+ windowKind,
+ state: 'active',
+ lastSeenAt: { lt: staleDate },
+ dimensionKey: { notIn: seenDimensionKeys },
+ },
+ data: {
+ state: 'closed',
+ lastUpdatedAt: now,
+ },
+ });
- return result.count;
- },
+ return result.count;
+ },
- async applySuppression({
- projectId,
- moduleKey,
- windowKind,
- keepTopN,
- now,
- }): Promise<{ deleted: number }> {
- // Below-top-N insights are DELETED rather than persisted as `suppressed`
- // rows. Nothing reads suppressed insights (every query filters state=active),
- // yet they were ~75% of the table. A dimension that later climbs back into
- // the top-N is simply re-created on the next run — it loses thread
- // continuity, which is cosmetic and not surfaced anywhere.
- const insights = await db.projectInsight.findMany({
- where: {
- projectId,
- moduleKey,
- windowKind,
- state: 'active',
- },
- orderBy: { impactScore: 'desc' },
- });
+ async applySuppression({
+ projectId,
+ moduleKey,
+ windowKind,
+ keepTopN,
+ now,
+ }): Promise<{ deleted: number }> {
+ // Below-top-N insights are DELETED rather than persisted as `suppressed`
+ // rows. Nothing reads suppressed insights (every query filters state=active),
+ // yet they were ~75% of the table. A dimension that later climbs back into
+ // the top-N is simply re-created on the next run — it loses thread
+ // continuity, which is cosmetic and not surfaced anywhere.
+ //
+ // Nothing here writes `suppressed` any more; the two paths that still read
+ // it (the reopen lookup above, `cleanupStaleInsights`) exist for rows
+ // written before that change.
+ const insights = await db.projectInsight.findMany({
+ where: {
+ projectId,
+ moduleKey,
+ windowKind,
+ state: 'active',
+ },
+ orderBy: { impactScore: 'desc' },
+ });
- if (insights.length === 0) {
- return { deleted: 0 };
- }
+ if (insights.length === 0) {
+ return { deleted: 0 };
+ }
- const toDelete: string[] = [];
+ const toDelete: string[] = [];
- if (windowKind === 'yesterday') {
- // Drop stale "yesterday" insights whose windowEnd isn't actually
- // yesterday (prevents showing "Yesterday traffic dropped" from 2+ days
- // ago), then apply top-N to the fresh remainder.
- const yesterday = new Date(now);
- yesterday.setUTCHours(0, 0, 0, 0);
- yesterday.setUTCDate(yesterday.getUTCDate() - 1);
- const yesterdayTime = yesterday.getTime();
+ if (windowKind === 'yesterday') {
+ // Drop stale "yesterday" insights whose windowEnd isn't actually
+ // yesterday (prevents showing "Yesterday traffic dropped" from 2+ days
+ // ago), then apply top-N to the fresh remainder.
+ const yesterday = new Date(now);
+ yesterday.setUTCHours(0, 0, 0, 0);
+ yesterday.setUTCDate(yesterday.getUTCDate() - 1);
+ const yesterdayTime = yesterday.getTime();
- const fresh: typeof insights = [];
- for (const insight of insights) {
- const isStale = insight.windowEnd
- ? new Date(insight.windowEnd).setUTCHours(0, 0, 0, 0) !==
- yesterdayTime
- : true;
- if (isStale) {
+ const fresh: typeof insights = [];
+ for (const insight of insights) {
+ const isStale = insight.windowEnd
+ ? new Date(insight.windowEnd).setUTCHours(0, 0, 0, 0) !==
+ yesterdayTime
+ : true;
+ if (isStale) {
+ toDelete.push(insight.id);
+ } else {
+ fresh.push(insight);
+ }
+ }
+ // `fresh` preserves the impactScore-desc order; everything past keepTopN goes.
+ for (const insight of fresh.slice(keepTopN)) {
+ toDelete.push(insight.id);
+ }
+ } else {
+ for (const insight of insights.slice(keepTopN)) {
toDelete.push(insight.id);
- } else {
- fresh.push(insight);
}
}
- // `fresh` preserves the impactScore-desc order; everything past keepTopN goes.
- for (const insight of fresh.slice(keepTopN)) {
- toDelete.push(insight.id);
- }
- } else {
- for (const insight of insights.slice(keepTopN)) {
- toDelete.push(insight.id);
- }
- }
- if (toDelete.length === 0) {
- return { deleted: 0 };
- }
+ if (toDelete.length === 0) {
+ return { deleted: 0 };
+ }
- const result = await db.projectInsight.deleteMany({
- where: { id: { in: toDelete } },
- });
- return { deleted: result.count };
- },
+ const result = await db.projectInsight.deleteMany({
+ where: { id: { in: toDelete } },
+ });
+ return { deleted: result.count };
+ },
};
}
diff --git a/packages/core/src/modules/insight/src/types.ts b/packages/core/src/modules/insight/src/types.ts
index ae863c67e..620adca6b 100644
--- a/packages/core/src/modules/insight/src/types.ts
+++ b/packages/core/src/modules/insight/src/types.ts
@@ -3,6 +3,14 @@ import type { StatementRunner } from './cached-query';
export type Cadence = 'daily';
+/** Ordered least → most severe; `SEVERITY_RANK` is the order to compare on. */
+export type SeverityBand = 'low' | 'moderate' | 'severe';
+
+export type InsightDirection = 'up' | 'down' | 'flat';
+
+/** `suppressed` is legacy: `applySuppression` deletes rather than writes it. */
+export type InsightState = 'active' | 'suppressed' | 'closed';
+
export type WindowKind = 'yesterday' | 'rolling_7d' | 'rolling_30d';
export interface WindowRange {
@@ -33,7 +41,7 @@ export interface ComputeResult {
currentValue?: number;
compareValue?: number;
changePct?: number; // -0.15 = -15%
- direction?: 'up' | 'down' | 'flat';
+ direction?: InsightDirection;
extra?: Record<string, unknown>; // share delta pp, rank, sparkline, etc.
}
@@ -93,13 +101,13 @@ export interface PersistedInsight {
moduleKey: string;
dimensionKey: string;
windowKind: WindowKind;
- state: 'active' | 'suppressed' | 'closed';
+ state: InsightState;
version: number;
impactScore: number;
lastSeenAt: Date;
lastUpdatedAt: Date;
- direction?: string | null;
- severityBand?: string | null;
+ direction?: InsightDirection | null;
+ severityBand?: SeverityBand | null;
}
/** Material change decision used for events/notifications. */
@@ -114,7 +122,7 @@ export type MaterialReason =
export interface MaterialDecision {
material: boolean;
reason: MaterialReason;
- newSeverityBand?: 'low' | 'moderate' | 'severe' | null;
+ newSeverityBand?: SeverityBand | null;
}
/**
@@ -138,9 +146,9 @@ export interface InsightStore {
window: WindowRange;
card: RenderedCard;
metrics: {
- direction?: 'up' | 'down' | 'flat';
+ direction?: InsightDirection;
impactScore: number;
- severityBand?: string | null;
+ severityBand?: SeverityBand | null;
};
now: Date;
decision: MaterialDecision;
diff --git a/packages/core/src/modules/insight/src/utils.ts b/packages/core/src/modules/insight/src/utils.ts
index 60330a506..f061f79aa 100644
--- a/packages/core/src/modules/insight/src/utils.ts
+++ b/packages/core/src/modules/insight/src/utils.ts
@@ -22,6 +22,13 @@ export function computeMedian(sortedValues: number[]): number {
: (sortedValues[mid] ?? 0);
}
+/** ClickHouse's JSON format returns Int columns as strings, hence `cnt`'s
+ * widening — every caller declares it `number` and every value is coerced. */
+interface DailyCountRow {
+ date: string;
+ cnt: number | string | null;
+}
+
/**
* Compute weekday medians from daily breakdown data.
* Groups by dimension, filters to matching weekday, computes median per dimension.
@@ -31,7 +38,7 @@ export function computeMedian(sortedValues: number[]): number {
* @param getDimension - Function to extract normalized dimension from row
* @returns Map of dimension -> median value
*/
-export function computeWeekdayMedians<T>(
+export function computeWeekdayMedians<T extends DailyCountRow>(
data: T[],
targetWeekday: number,
getDimension: (row: T) => string
@@ -40,14 +47,14 @@ export function computeWeekdayMedians<T>(
const byDimension = new Map<string, number[]>();
for (const row of data) {
- const rowWeekday = getWeekday(new Date((row as any).date));
+ const rowWeekday = getWeekday(new Date(row.date));
if (rowWeekday !== targetWeekday) {
continue;
}
const dim = getDimension(row);
const values = byDimension.get(dim) ?? [];
- values.push(Number((row as any).cnt ?? 0));
+ values.push(Number(row.cnt ?? 0));
byDimension.set(dim, values);
}
@@ -111,7 +118,8 @@ export function getEndOfDay(date: Date): Date {
export function buildLookupMap<T>(
results: T[],
getKey: (row: T) => string,
- getCount: (row: T) => number = (row) => Number((row as any).cnt ?? 0)
+ getCount: (row: T) => number = (row) =>
+ Number((row as { cnt?: number | string | null }).cnt ?? 0)
): Map<string, number> {
const map = new Map<string, number>();
for (const row of results) {