@obsunified/collector 2.2.3 → 2.4.3

package/dist/{ingest-auth-C5-8Mly5.d.ts → ingest-auth-BTowieER.d.ts}

@@ -1,4 +1,62 @@
 import { Hono, Context, MiddlewareHandler } from 'hono';
+import { AlertState } from '@obsunified/types';
+
+/**
+ * Email alert channel: the runtime-neutral half.
+ *
+ * The collector package runs on Cloudflare Workers as well as Node, and a
+ * Worker cannot open an SMTP connection. So the package only defines what an
+ * email transport must do (`AlertEmailTransport`) and how an alert reads as
+ * mail (`formatAlertEmail`); a host that can speak SMTP binds a transport as
+ * `env.ALERT_EMAIL` (the Node collector does, from `ALERT_SMTP_*`, see
+ * apps/collector-node/src/alert-email.ts). Without that binding, rules with
+ * an email channel are refused at create/update time and an email channel on
+ * an existing rule counts as a failed delivery at fire time.
+ */
+
+interface AlertEmailMessage {
+    to: string[];
+    subject: string;
+    text: string;
+}
+interface AlertEmailTransport {
+    /**
+     * Sends one message. Resolves only when the SMTP server accepted it for
+     * every recipient; rejects otherwise.
+     */
+    send(message: AlertEmailMessage): Promise<void>;
+}
+/** What every channel is told about a transition (the webhook JSON body). */
+interface AlertNotificationPayload {
+    rule: {
+        id: string;
+        name: string;
+        signal: string;
+    };
+    value: number;
+    threshold: number;
+    comparison: string;
+    state: AlertState;
+    evaluatedAt: string;
+    projectId: string;
+    /**
+     * RFC 0002 Stage 6 — populated when the rule is bound to an Analysis
+     * (`rule.analysisId` set). The narrative is the gated, LLM-generated
+     * sentence the dashboard panel was last showing — what's actually
+     * happening, in plain English. Webhooks consuming this can put the
+     * narrative in the Slack/PagerDuty body directly.
+     */
+    analysis?: {
+        id: string;
+        narrative: string | null;
+        status: string | null;
+    };
+}
+declare const isValidEmailAddress: (addr: string) => boolean;
+declare function formatAlertEmail(payload: AlertNotificationPayload): {
+    subject: string;
+    text: string;
+};
 
 /**
  * Pluggable logger interface for the collector framework.
@@ -69,6 +127,12 @@ interface CollectorEnv {
     /** Durable Object namespace for live-tail SSE pub/sub. Optional — when
      *  unbound the /internal/telemetry/tail endpoint returns 503. */
     TAIL_HUB?: DurableObjectNamespace;
+    /**
+     * SMTP transport for email alert channels. Bound by hosts that can send
+     * mail (the Node collector, from `ALERT_SMTP_*`); never set on Cloudflare
+     * Workers. Without it, rules with an email channel are refused.
+     */
+    ALERT_EMAIL?: AlertEmailTransport;
     /** Write-only API key for SDK ingest endpoints (/v1/*) */
     INGEST_KEY?: string;
     /** Password for dashboard login */
@@ -135,6 +199,37 @@ interface CollectorEnv {
     /** @deprecated Use DASHBOARD_PASSWORD instead */
     TELEMETRY_QUERY_TOKEN?: string;
 }
+/**
+ * Optional string settings on `CollectorEnv` that host adapters (such as
+ * `apps/collector-node`) forward directly from the process environment after
+ * trimming whitespace and coercing blank strings to `undefined`.
+ */
+declare const COLLECTOR_OPTIONAL_STRING_ENV_KEYS: readonly ["RETENTION_HOURS", "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENAI_BASE_URL", "NARRATIVE_MODEL", "NARRATIVE_BUDGET_PER_HOUR", "ALERT_WEBHOOK_ALLOW_PRIVATE", "MAX_BODY_BYTES", "TELEMETRY_REDACT_FIELDS", "OBS_PAYLOAD_CAPTURE_DEFAULT"];
+/**
+ * String settings on `CollectorEnv` that require explicit host handling (e.g.
+ * required auth secrets, CORS origin parsing, Worker-only self-instrumentation
+ * vars, or deprecated Worker tokens) and must not be blindly forwarded by the
+ * generic optional-env loop.
+ */
+declare const COLLECTOR_HOST_MANAGED_ENV_KEYS: readonly ["INGEST_KEY", "DASHBOARD_PASSWORD", "DASHBOARD_TOKEN", "ALLOWED_ORIGINS", "ALLOW_UNAUTHENTICATED", "OBS_DASHBOARD_INGEST_KEY", "OBS_COLLECTOR_SELF_URL", "OBS_SELF_AWAIT_EXPORTS", "TELEMETRY_INGEST_TOKEN", "USAGE_INGEST_TOKEN", "TELEMETRY_QUERY_TOKEN"];
+declare const COLLECTOR_STRING_ENV_MANIFEST: {
+    readonly forwarded: readonly ["RETENTION_HOURS", "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENAI_BASE_URL", "NARRATIVE_MODEL", "NARRATIVE_BUDGET_PER_HOUR", "ALERT_WEBHOOK_ALLOW_PRIVATE", "MAX_BODY_BYTES", "TELEMETRY_REDACT_FIELDS", "OBS_PAYLOAD_CAPTURE_DEFAULT"];
+    readonly hostManaged: readonly ["INGEST_KEY", "DASHBOARD_PASSWORD", "DASHBOARD_TOKEN", "ALLOWED_ORIGINS", "ALLOW_UNAUTHENTICATED", "OBS_DASHBOARD_INGEST_KEY", "OBS_COLLECTOR_SELF_URL", "OBS_SELF_AWAIT_EXPORTS", "TELEMETRY_INGEST_TOKEN", "USAGE_INGEST_TOKEN", "TELEMETRY_QUERY_TOKEN"];
+};
+type CollectorOptionalStringEnvKey = (typeof COLLECTOR_OPTIONAL_STRING_ENV_KEYS)[number];
+type CollectorHostManagedEnvKey = (typeof COLLECTOR_HOST_MANAGED_ENV_KEYS)[number];
+type CollectorManifestStringEnvKey = CollectorOptionalStringEnvKey | CollectorHostManagedEnvKey;
+type CollectorObjectBindingKey = "DB" | "REPLAYS_BUCKET" | "PROFILES_BUCKET" | "TAIL_HUB" | "ALERT_EMAIL";
+type CollectorStringEnvKey = Exclude<keyof CollectorEnv, CollectorObjectBindingKey>;
+/**
+ * Verifies that every string key in `declaredKeys` is categorized in either
+ * `COLLECTOR_OPTIONAL_STRING_ENV_KEYS` or `COLLECTOR_HOST_MANAGED_ENV_KEYS`
+ * without overlap. Throws if any key is uncategorized or duplicated.
+ */
+declare function assertCollectorEnvManifestCompleteness(declaredKeys: readonly string[], manifest?: {
+    readonly forwarded: readonly string[];
+    readonly hostManaged: readonly string[];
+}): void;
 interface CollectorRouteContext {
     hono: Context<{
         Bindings: CollectorEnv;
@@ -171,4 +266,4 @@ declare function createIngestAuth(config?: {
     };
 }>;
 
-export { type ChildSpanRunner as C, type Logger as L, type CollectorApp as a, type CollectorEnv as b, type CollectorRouteContext as c, consoleLogger as d, createIngestAuth as e, resetIngestAuthCache as r };
+export { type AlertEmailMessage as A, COLLECTOR_HOST_MANAGED_ENV_KEYS as C, type Logger as L, type AlertEmailTransport as a, type AlertNotificationPayload as b, COLLECTOR_OPTIONAL_STRING_ENV_KEYS as c, COLLECTOR_STRING_ENV_MANIFEST as d, type ChildSpanRunner as e, type CollectorApp as f, type CollectorEnv as g, type CollectorHostManagedEnvKey as h, type CollectorManifestStringEnvKey as i, type CollectorObjectBindingKey as j, type CollectorOptionalStringEnvKey as k, type CollectorRouteContext as l, type CollectorStringEnvKey as m, assertCollectorEnvManifestCompleteness as n, consoleLogger as o, createIngestAuth as p, formatAlertEmail as q, isValidEmailAddress as r, resetIngestAuthCache as s };

package/dist/{openai-GSJZGFGL.js → openai-VDKVVZAV.js}

@@ -1,7 +1,7 @@
 import {
   LlmCallError,
   askEvidenceReferences
-} from "./chunk-ZSF5XP3B.js";
+} from "./chunk-RASSTGNB.js";
 
 // src/lib/openai.ts
 import { EVIDENCE_REFERENCE_CONTRACT } from "@obsunified/types";
@@ -381,4 +381,4 @@ export {
   generateNarrativeOpenAI,
   runAskOpenAI
 };
-//# sourceMappingURL=openai-GSJZGFGL.js.map
+//# sourceMappingURL=openai-VDKVVZAV.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsunified/collector",
-  "version": "2.2.3",
+  "version": "2.4.3",
   "description": "Plugin-based observability collector runtime with pluggable SQL/blob storage.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
     "@obsunified/pprof-decoder": "2.0.2",
-    "@obsunified/types": "2.2.1"
+    "@obsunified/types": "2.4.1"
   },
   "peerDependencies": {
     "hono": "^4.7.0",
@@ -66,6 +66,8 @@
     "build": "tsup",
     "type-check": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
+    "check:migrations": "vitest run src/migrations/parity.test.ts",
+    "check:db-parity": "node scripts/check-db-parity.mjs",
     "bench": "vitest bench --run",
     "codegen": "PATH=\"$PWD/node_modules/.bin:$PATH\" buf generate"
   }

package/src/__tests__/autosre-closed-loop.test.ts

@@ -2423,6 +2423,116 @@ describe("AutoSRE governance hardening", () => {
 		db.close();
 	});
 
+	it("POST /internal/findings: schema-backed validation, trimming and defaults", async () => {
+		const db = createMigratedSqliteDb();
+		const { app, env } = createTestApp(db);
+		const post = (body: unknown) =>
+			app.request(
+				"/internal/findings",
+				{
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify(body),
+				},
+				env,
+			);
+		const base = {
+			title: "t",
+			summary: "s",
+			symptomEntityKind: "trace",
+			symptomEntityId: "t1",
+			faultLocusEntityKind: "service",
+			faultLocusEntityId: SERVICE_NODE,
+		};
+		const required =
+			"title, summary, symptomEntityKind, symptomEntityId, faultLocusEntityKind, and faultLocusEntityId are required";
+
+		// Combined required message: missing and empty-after-trim.
+		for (const bad of [
+			{ ...base, title: undefined },
+			{ ...base, summary: "   " },
+			{ ...base, faultLocusEntityId: 5 },
+		]) {
+			const res = await post(bad);
+			expect(res.status).toBe(400);
+			expect(((await res.json()) as { error: string }).error).toBe(required);
+		}
+
+		// causalChain explicit messages.
+		const notArray = await post({ ...base, causalChain: "nope" });
+		expect(notArray.status).toBe(400);
+		expect(((await notArray.json()) as { error: string }).error).toBe(
+			"causalChain must be an array",
+		);
+		const badPred = await post({
+			...base,
+			causalChain: [
+				{
+					subjectKind: "trace",
+					subjectId: "t1",
+					predicate: "made_up",
+					objectKind: "span",
+					objectId: "s1",
+				},
+			],
+		});
+		expect(badPred.status).toBe(400);
+		expect(((await badPred.json()) as { error: string }).error).toBe(
+			"causalChain[0].predicate is not a known evidence predicate: made_up",
+		);
+
+		// Tightened: wrong-typed optional fields now 400 with path: message.
+		const badConf = await post({ ...base, confidence: "high" });
+		expect(badConf.status).toBe(400);
+		expect(((await badConf.json()) as { error: string }).error).toContain(
+			"confidence:",
+		);
+		const badTier = await post({ ...base, causalProofTier: "bogus" });
+		expect(badTier.status).toBe(400);
+		expect(((await badTier.json()) as { error: string }).error).toContain(
+			"causalProofTier:",
+		);
+		const badKind = await post({ ...base, symptomEntityKind: "not_a_kind" });
+		expect(badKind.status).toBe(400);
+
+		// Trimming + defaults.
+		const ok = await post({
+			title: "  Padded title  ",
+			summary: " Padded summary ",
+			symptomEntityKind: " trace ",
+			symptomEntityId: " t1 ",
+			faultLocusEntityKind: " service ",
+			faultLocusEntityId: ` ${SERVICE_NODE} `,
+			idempotencyKey: "   ",
+			incidentId: null,
+			rootCauseEntityKind: null,
+			cohortVerdict: null,
+		});
+		expect(ok.status).toBe(201);
+		const created = (await ok.json()) as {
+			finding: Record<string, unknown>;
+		};
+		expect(created.finding.title).toBe("Padded title");
+		expect(created.finding.summary).toBe("Padded summary");
+		expect(
+			created.finding.symptom_entity_kind ?? created.finding.symptomEntityKind,
+		).toBe("trace");
+		// Blank idempotencyKey is ignored: two identical posts create two findings.
+		const again = await post({
+			title: "  Padded title  ",
+			summary: " Padded summary ",
+			symptomEntityKind: "trace",
+			symptomEntityId: "t1",
+			faultLocusEntityKind: "service",
+			faultLocusEntityId: SERVICE_NODE,
+			idempotencyKey: "   ",
+		});
+		expect(((await again.json()) as { id: string }).id).not.toBe(
+			(created.finding as { id: string }).id,
+		);
+		db.close();
+	});
+
 	it("J9: GET /internal/evals/runs/:id reports existence so counterfactual prerequisites can be checked first", async () => {
 		const db = createMigratedSqliteDb();
 		const { app, env } = createTestApp(db);