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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsdeleted file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 existinginsight = 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.tsindex 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.tsindex 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) {