@secondlayer/shared 13.3.0 → 13.5.0

package/dist/src/schemas/insights.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+/**
+* The insight contract. The tenant (`/api/insights`) and platform
+* (`/api/accounts/insights`) routes serve `Insight` verbatim. The web app keeps
+* a field-for-field copy in `apps/web/src/lib/insights.ts`; change both
+* together.
+*
+* The types are written out and the schemas annotated with them, rather than
+* inferred: the bundled `.d.ts` loses inferred zod types (they come out as
+* `unknown`), the same reason `schemas/webhooks.ts` annotates its schemas.
+*/
+declare const INSIGHT_SEVERITIES: readonly ["losing", "will_fail", "costs", "recovered"];
+type InsightSeverity = (typeof INSIGHT_SEVERITIES)[number];
+type InsightResourceKind = "webhook" | "subgraph" | "account";
+type InsightEvidence = {
+	kind: "series"
+	title: string
+	series: {
+		name: string
+		role: "a" | "context" | "mark"
+		points: number[]
+	}[]
+	labels: [number, string][]
+	unit?: string
+} | {
+	kind: "table"
+	title: string
+	columns: string[]
+	rows: (string | number)[][]
+	markRow?: number
+} | {
+	kind: "shapes"
+	title: string
+	shapes: {
+		code: string
+		body: string
+		count: number
+		isNew: boolean
+	}[]
+} | {
+	kind: "timeline"
+	title: string
+	steps: {
+		what: string
+		at: string
+		note?: string
+		failed: boolean
+	}[]
+};
+interface Insight {
+	id: string;
+	rule: string;
+	severity: InsightSeverity;
+	impact: number;
+	resource: {
+		kind: InsightResourceKind
+		id: string
+		name: string
+	};
+	line: string;
+	meta?: string;
+	lead: string;
+	body: string;
+	evidence: InsightEvidence[];
+	handoff: {
+		prompt: string
+		commands: string[]
+	};
+	how: {
+		detector: string
+		facts: [string, string][]
+		label?: {
+			cause: string
+			confidence: number
+		}
+	};
+	createdAt: string;
+	resolvedAt?: string | null;
+}
+interface InsightListResponse {
+	data: Insight[];
+}
+declare const InsightSeveritySchema: z.ZodType<InsightSeverity>;
+declare const InsightResourceKindSchema: z.ZodType<InsightResourceKind>;
+declare const InsightEvidenceSchema: z.ZodType<InsightEvidence>;
+declare const InsightSchema: z.ZodType<Insight>;
+declare const InsightListResponseSchema: z.ZodType<InsightListResponse>;
+declare const SEVERITY_ORDER: Record<InsightSeverity, number>;
+export { INSIGHT_SEVERITIES, Insight, InsightEvidence, InsightEvidenceSchema, InsightListResponse, InsightListResponseSchema, InsightResourceKind, InsightResourceKindSchema, InsightSchema, InsightSeverity, InsightSeveritySchema, SEVERITY_ORDER };

package/dist/src/schemas/insights.js

@@ -0,0 +1,98 @@
+// src/schemas/insights.ts
+import { z } from "zod";
+var INSIGHT_SEVERITIES = [
+  "losing",
+  "will_fail",
+  "costs",
+  "recovered"
+];
+var InsightSeveritySchema = z.enum(INSIGHT_SEVERITIES);
+var InsightResourceKindSchema = z.enum(["webhook", "subgraph", "account"]);
+var InsightEvidenceSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("series"),
+    title: z.string(),
+    series: z.array(z.object({
+      name: z.string(),
+      role: z.enum(["a", "context", "mark"]),
+      points: z.array(z.number())
+    })),
+    labels: z.array(z.tuple([z.number(), z.string()])),
+    unit: z.string().optional()
+  }),
+  z.object({
+    kind: z.literal("table"),
+    title: z.string(),
+    columns: z.array(z.string()),
+    rows: z.array(z.array(z.union([z.string(), z.number()]))),
+    markRow: z.number().optional()
+  }),
+  z.object({
+    kind: z.literal("shapes"),
+    title: z.string(),
+    shapes: z.array(z.object({
+      code: z.string(),
+      body: z.string(),
+      count: z.number(),
+      isNew: z.boolean()
+    }))
+  }),
+  z.object({
+    kind: z.literal("timeline"),
+    title: z.string(),
+    steps: z.array(z.object({
+      what: z.string(),
+      at: z.string(),
+      note: z.string().optional(),
+      failed: z.boolean()
+    }))
+  })
+]);
+var InsightSchema = z.object({
+  id: z.string(),
+  rule: z.string(),
+  severity: InsightSeveritySchema,
+  impact: z.number(),
+  resource: z.object({
+    kind: InsightResourceKindSchema,
+    id: z.string(),
+    name: z.string()
+  }),
+  line: z.string(),
+  meta: z.string().optional(),
+  lead: z.string(),
+  body: z.string(),
+  evidence: z.array(InsightEvidenceSchema),
+  handoff: z.object({
+    prompt: z.string(),
+    commands: z.array(z.string())
+  }),
+  how: z.object({
+    detector: z.string(),
+    facts: z.array(z.tuple([z.string(), z.string()])),
+    label: z.object({ cause: z.string(), confidence: z.number() }).optional()
+  }),
+  createdAt: z.string(),
+  resolvedAt: z.string().nullable().optional()
+});
+var InsightListResponseSchema = z.object({
+  data: z.array(InsightSchema)
+});
+var SEVERITY_ORDER = {
+  losing: 0,
+  will_fail: 1,
+  costs: 2,
+  recovered: 3
+};
+export {
+  INSIGHT_SEVERITIES,
+  InsightEvidenceSchema,
+  InsightListResponseSchema,
+  InsightResourceKindSchema,
+  InsightSchema,
+  InsightSeveritySchema,
+  SEVERITY_ORDER
+};
+
+//# debugId=3EFEA80342CD257B64756E2164756E21
+//# sourceMappingURL=insights.js.map

package/dist/src/schemas/insights.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/schemas/insights.ts"],
+  "sourcesContent": [
+    "import { z } from \"zod\";\n\n/**\n * The insight contract. The tenant (`/api/insights`) and platform\n * (`/api/accounts/insights`) routes serve `Insight` verbatim. The web app keeps\n * a field-for-field copy in `apps/web/src/lib/insights.ts`; change both\n * together.\n *\n * The types are written out and the schemas annotated with them, rather than\n * inferred: the bundled `.d.ts` loses inferred zod types (they come out as\n * `unknown`), the same reason `schemas/webhooks.ts` annotates its schemas.\n */\n\nexport const INSIGHT_SEVERITIES = [\n\t\"losing\",\n\t\"will_fail\",\n\t\"costs\",\n\t\"recovered\",\n] as const;\n\nexport type InsightSeverity = (typeof INSIGHT_SEVERITIES)[number];\n\nexport type InsightResourceKind = \"webhook\" | \"subgraph\" | \"account\";\n\nexport type InsightEvidence =\n\t| {\n\t\t\tkind: \"series\";\n\t\t\ttitle: string;\n\t\t\tseries: {\n\t\t\t\tname: string;\n\t\t\t\trole: \"a\" | \"context\" | \"mark\";\n\t\t\t\tpoints: number[];\n\t\t\t}[];\n\t\t\tlabels: [number, string][];\n\t\t\tunit?: string;\n\t  }\n\t| {\n\t\t\tkind: \"table\";\n\t\t\ttitle: string;\n\t\t\tcolumns: string[];\n\t\t\trows: (string | number)[][];\n\t\t\tmarkRow?: number;\n\t  }\n\t| {\n\t\t\tkind: \"shapes\";\n\t\t\ttitle: string;\n\t\t\tshapes: { code: string; body: string; count: number; isNew: boolean }[];\n\t  }\n\t| {\n\t\t\tkind: \"timeline\";\n\t\t\ttitle: string;\n\t\t\tsteps: { what: string; at: string; note?: string; failed: boolean }[];\n\t  };\n\nexport interface Insight {\n\tid: string;\n\trule: string;\n\tseverity: InsightSeverity;\n\timpact: number;\n\tresource: {\n\t\tkind: InsightResourceKind;\n\t\tid: string;\n\t\tname: string;\n\t};\n\tline: string;\n\tmeta?: string;\n\tlead: string;\n\tbody: string;\n\tevidence: InsightEvidence[];\n\thandoff: { prompt: string; commands: string[] };\n\thow: {\n\t\tdetector: string;\n\t\tfacts: [string, string][];\n\t\tlabel?: { cause: string; confidence: number };\n\t};\n\tcreatedAt: string;\n\tresolvedAt?: string | null;\n}\n\nexport interface InsightListResponse {\n\tdata: Insight[];\n}\n\nexport const InsightSeveritySchema: z.ZodType<InsightSeverity> =\n\tz.enum(INSIGHT_SEVERITIES);\n\nexport const InsightResourceKindSchema: z.ZodType<InsightResourceKind> = z.enum(\n\t[\"webhook\", \"subgraph\", \"account\"],\n);\n\nexport const InsightEvidenceSchema: z.ZodType<InsightEvidence> =\n\tz.discriminatedUnion(\"kind\", [\n\t\tz.object({\n\t\t\tkind: z.literal(\"series\"),\n\t\t\ttitle: z.string(),\n\t\t\tseries: z.array(\n\t\t\t\tz.object({\n\t\t\t\t\tname: z.string(),\n\t\t\t\t\trole: z.enum([\"a\", \"context\", \"mark\"]),\n\t\t\t\t\tpoints: z.array(z.number()),\n\t\t\t\t}),\n\t\t\t),\n\t\t\tlabels: z.array(z.tuple([z.number(), z.string()])),\n\t\t\tunit: z.string().optional(),\n\t\t}),\n\t\tz.object({\n\t\t\tkind: z.literal(\"table\"),\n\t\t\ttitle: z.string(),\n\t\t\tcolumns: z.array(z.string()),\n\t\t\trows: z.array(z.array(z.union([z.string(), z.number()]))),\n\t\t\tmarkRow: z.number().optional(),\n\t\t}),\n\t\tz.object({\n\t\t\tkind: z.literal(\"shapes\"),\n\t\t\ttitle: z.string(),\n\t\t\tshapes: z.array(\n\t\t\t\tz.object({\n\t\t\t\t\tcode: z.string(),\n\t\t\t\t\tbody: z.string(),\n\t\t\t\t\tcount: z.number(),\n\t\t\t\t\tisNew: z.boolean(),\n\t\t\t\t}),\n\t\t\t),\n\t\t}),\n\t\tz.object({\n\t\t\tkind: z.literal(\"timeline\"),\n\t\t\ttitle: z.string(),\n\t\t\tsteps: z.array(\n\t\t\t\tz.object({\n\t\t\t\t\twhat: z.string(),\n\t\t\t\t\tat: z.string(),\n\t\t\t\t\tnote: z.string().optional(),\n\t\t\t\t\tfailed: z.boolean(),\n\t\t\t\t}),\n\t\t\t),\n\t\t}),\n\t]);\n\nexport const InsightSchema: z.ZodType<Insight> = z.object({\n\tid: z.string(),\n\trule: z.string(),\n\tseverity: InsightSeveritySchema,\n\timpact: z.number(),\n\tresource: z.object({\n\t\tkind: InsightResourceKindSchema,\n\t\tid: z.string(),\n\t\tname: z.string(),\n\t}),\n\tline: z.string(),\n\tmeta: z.string().optional(),\n\tlead: z.string(),\n\tbody: z.string(),\n\tevidence: z.array(InsightEvidenceSchema),\n\thandoff: z.object({\n\t\tprompt: z.string(),\n\t\tcommands: z.array(z.string()),\n\t}),\n\thow: z.object({\n\t\tdetector: z.string(),\n\t\tfacts: z.array(z.tuple([z.string(), z.string()])),\n\t\tlabel: z.object({ cause: z.string(), confidence: z.number() }).optional(),\n\t}),\n\tcreatedAt: z.string(),\n\tresolvedAt: z.string().nullable().optional(),\n});\n\nexport const InsightListResponseSchema: z.ZodType<InsightListResponse> =\n\tz.object({\n\t\tdata: z.array(InsightSchema),\n\t});\n\nexport const SEVERITY_ORDER: Record<InsightSeverity, number> = {\n\tlosing: 0,\n\twill_fail: 1,\n\tcosts: 2,\n\trecovered: 3,\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "3EFEA80342CD257B64756E2164756E21",
+  "names": []
+}

package/migrations/0169_subgraph_health_history.ts

@@ -0,0 +1,54 @@
+import { type Kysely, sql } from "kysely";
+import { onControlPlane } from "../src/db/migration-role.ts";
+
+/**
+ * Health history: lag/rows/storage columns on the (previously unwritten)
+ * snapshot table, plus fingerprint-grouped handler errors (cap 50/subgraph,
+ * enforced at write time).
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+	await sql`SET lock_timeout = '30s'`.execute(db);
+	await onControlPlane(async () => {
+		await sql`
+			ALTER TABLE subgraph_health_snapshots
+				ADD COLUMN IF NOT EXISTS chain_tip bigint,
+				ADD COLUMN IF NOT EXISTS rows_written_total bigint,
+				ADD COLUMN IF NOT EXISTS storage_bytes bigint
+		`.execute(db);
+
+		await sql`
+			CREATE TABLE IF NOT EXISTS subgraph_error_groups (
+				id                  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+				subgraph_name       text NOT NULL,
+				fingerprint         text NOT NULL,
+				source_name         text NOT NULL,
+				event_type          text,
+				message             text NOT NULL,
+				frame               text,
+				count               bigint NOT NULL DEFAULT 1,
+				sample_tx_id        text,
+				sample_block_height bigint,
+				first_seen          timestamptz NOT NULL DEFAULT now(),
+				last_seen           timestamptz NOT NULL DEFAULT now(),
+				UNIQUE (subgraph_name, fingerprint)
+			)
+		`.execute(db);
+
+		await sql`
+			CREATE INDEX IF NOT EXISTS subgraph_error_groups_name_seen_idx
+			ON subgraph_error_groups (subgraph_name, last_seen DESC)
+		`.execute(db);
+	});
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	await onControlPlane(async () => {
+		await sql`DROP TABLE IF EXISTS subgraph_error_groups`.execute(db);
+		await sql`
+			ALTER TABLE subgraph_health_snapshots
+				DROP COLUMN IF EXISTS chain_tip,
+				DROP COLUMN IF EXISTS rows_written_total,
+				DROP COLUMN IF EXISTS storage_bytes
+		`.execute(db);
+	});
+}

package/migrations/0170_insights.ts

@@ -0,0 +1,63 @@
+import { type Kysely, sql } from "kysely";
+import { onControlPlane } from "../src/db/migration-role.ts";
+
+/**
+ * Ranked dashboard insights (one open row per resource + rule) and the
+ * per-resource "expected" mutes. Created on every control-plane database:
+ * the platform DB (account rules) and each tenant / self-host DB (webhook and
+ * subgraph rules). `account_id` is NULL on tenant and self-host rows (there is
+ * no meaningful account id there) so it carries no foreign key.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+	await onControlPlane(async () => {
+		await sql`
+			CREATE TABLE insights (
+				id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+				account_id    uuid,
+				resource_kind text NOT NULL,
+				resource_id   text NOT NULL,
+				rule          text NOT NULL,
+				severity      text NOT NULL,
+				impact        double precision NOT NULL DEFAULT 0,
+				payload       jsonb NOT NULL,
+				first_seen_at timestamptz NOT NULL DEFAULT now(),
+				last_seen_at  timestamptz NOT NULL DEFAULT now(),
+				clear_streak  integer NOT NULL DEFAULT 0,
+				resolved_at   timestamptz,
+				dismissed_at  timestamptz
+			)
+		`.execute(db);
+
+		await sql`
+			CREATE UNIQUE INDEX insights_open_key ON insights
+				(coalesce(account_id, '00000000-0000-0000-0000-000000000000'::uuid), resource_kind, resource_id, rule)
+				WHERE resolved_at IS NULL
+		`.execute(db);
+
+		await sql`
+			CREATE INDEX insights_account_recent ON insights (account_id, resolved_at)
+		`.execute(db);
+
+		await sql`
+			CREATE TABLE insight_mutes (
+				account_id    uuid,
+				resource_kind text NOT NULL,
+				resource_id   text NOT NULL,
+				rule          text NOT NULL,
+				created_at    timestamptz NOT NULL DEFAULT now()
+			)
+		`.execute(db);
+
+		await sql`
+			CREATE UNIQUE INDEX insight_mutes_key ON insight_mutes
+				(coalesce(account_id, '00000000-0000-0000-0000-000000000000'::uuid), resource_kind, resource_id, rule)
+		`.execute(db);
+	});
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	await onControlPlane(async () => {
+		await sql`DROP TABLE IF EXISTS insight_mutes`.execute(db);
+		await sql`DROP TABLE IF EXISTS insights`.execute(db);
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@secondlayer/shared",
-	"version": "13.3.0",
+	"version": "13.5.0",
 	"description": "Internal building blocks shared across Secondlayer packages.",
 	"license": "MIT",
 	"repository": {
@@ -240,6 +240,18 @@
 		"./classify": {
 			"types": "./dist/src/classify/index.d.ts",
 			"import": "./dist/src/classify/index.js"
+		},
+		"./insights": {
+			"types": "./dist/src/insights/index.d.ts",
+			"import": "./dist/src/insights/index.js"
+		},
+		"./insights/thresholds": {
+			"types": "./dist/src/insights/thresholds.d.ts",
+			"import": "./dist/src/insights/thresholds.js"
+		},
+		"./schemas/insights": {
+			"types": "./dist/src/schemas/insights.d.ts",
+			"import": "./dist/src/schemas/insights.js"
 		}
 	},
 	"files": ["dist", "migrations"],