@obsunified/collector 2.0.1

package/src/migrations-postgres/038_tool_call_evidence.sql

@@ -0,0 +1,11 @@
+-- AI debugging evidence for side-effecting tool calls.
+--
+-- These fields are opt-in evidence channels. They intentionally store only
+-- explicit audit/diff envelopes emitted by instrumentation, not raw tool
+-- arguments, results, or transport metadata.
+
+ALTER TABLE tool_calls ADD COLUMN IF NOT EXISTS mcp_audit_json JSONB;
+ALTER TABLE tool_calls ADD COLUMN IF NOT EXISTS mutation_before_json JSONB;
+ALTER TABLE tool_calls ADD COLUMN IF NOT EXISTS mutation_after_json JSONB;
+ALTER TABLE tool_calls ADD COLUMN IF NOT EXISTS mutation_diff_json JSONB;
+ALTER TABLE tool_calls ADD COLUMN IF NOT EXISTS mutation_artifact_id TEXT;

package/src/migrations-postgres/039_drop_trace_instrumentation_gaps.sql

@@ -0,0 +1,11 @@
+-- Drop the materialized trace instrumentation gaps table.
+--
+-- Trace instrumentation gaps are now computed lazily at read time from the
+-- trace's spans (see `getTelemetryTraceGaps` in lib/store/trace-detail.ts),
+-- rather than being materialized on the ingest hot path. The table and its
+-- index are therefore unused: nothing writes to them, and reads compute gaps
+-- on demand. `DROP TABLE` removes the dependent index; the explicit
+-- `DROP INDEX` mirrors the D1 sibling migration.
+
+DROP INDEX IF EXISTS idx_trace_gaps_duration;
+DROP TABLE IF EXISTS trace_instrumentation_gaps;

package/src/migrations-postgres/040_evidence_retrieval_refs.sql

@@ -0,0 +1,47 @@
+-- RFC 0011 — materialized evidence retrieval refs and expansion telemetry.
+
+CREATE TABLE IF NOT EXISTS evidence_retrieval_refs (
+  ref_id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  anchor_kind TEXT NOT NULL,
+  anchor_id TEXT NOT NULL,
+  source TEXT NOT NULL,
+  query_json JSONB,
+  compacted_from_json JSONB,
+  returned_json JSONB,
+  issued_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_seen_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  expires_at TIMESTAMPTZ
+);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_refs_project_seen
+  ON evidence_retrieval_refs (project_id, last_seen_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_refs_project_kind
+  ON evidence_retrieval_refs (project_id, kind, last_seen_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_refs_project_anchor
+  ON evidence_retrieval_refs (project_id, anchor_kind, anchor_id);
+
+CREATE TABLE IF NOT EXISTS evidence_ref_expansions (
+  id TEXT PRIMARY KEY,
+  ref_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  source TEXT,
+  operation TEXT NOT NULL,
+  result_status TEXT NOT NULL,
+  limit_value INTEGER,
+  query_text TEXT,
+  expanded_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_expansions_project_time
+  ON evidence_ref_expansions (project_id, expanded_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_expansions_project_ref
+  ON evidence_ref_expansions (project_id, ref_id, expanded_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_expansions_project_kind
+  ON evidence_ref_expansions (project_id, kind, expanded_at DESC);

package/src/migrations-postgres/README.md

@@ -0,0 +1,40 @@
+# Postgres migrations
+
+Companion migrations for the Postgres adapter (`PostgresAdapter`). The canonical
+schema lives in `../migrations/` as SQLite/D1; this directory mirrors each
+numbered migration translated for Postgres semantics.
+
+## Translation rules
+
+Mechanical rewrites from SQLite → Postgres:
+
+| SQLite                  | Postgres                                                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `TEXT`                  | `TEXT` (unchanged)                                                                                                                   |
+| `INTEGER`               | `BIGINT`                                                                                                                             |
+| `REAL`                  | `DOUBLE PRECISION`                                                                                                                   |
+| `?` placeholders        | `$1`, `$2`, … (rewritten by `PostgresAdapter` at runtime — DDL files use `?` only if they're parameterized, which they shouldn't be) |
+| `AUTOINCREMENT`         | `GENERATED BY DEFAULT AS IDENTITY`                                                                                                   |
+| `INSERT OR REPLACE`     | `INSERT … ON CONFLICT (…) DO UPDATE SET …`                                                                                           |
+| Stored `TEXT` with JSON | `JSONB` (always; the dashboard read paths can leverage indexed JSON queries on Postgres)                                             |
+
+## Numbering
+
+Files MUST share the numeric prefix of their D1 sibling so the migration runner
+can ensure parity. If `004_logs.sql` exists in `../migrations/`, this directory
+MUST contain `004_logs.sql` as well. A CI check will refuse to merge PRs that
+break parity.
+
+## What's translated
+
+The first three migrations are translated as a proof of the pattern. The
+remaining migrations are tracked in
+[`docs/postgres-migration.md`](../../../../docs/postgres-migration.md); they'll
+land alongside the first hosted-Postgres deployment.
+
+## What's NOT translated
+
+`009_projects_and_keys.sql` uses SQLite's `BLOB` type for the hashed API key.
+Postgres uses `BYTEA` and the column-name rewrite is in
+`009_projects_and_keys.sql` here (a non-mechanical translation; review carefully
+when porting forward).

package/src/otlp/acceptance.test.ts

@@ -0,0 +1,373 @@
+/**
+ * OTLP acceptance suite — exercises the live `/v1/*` endpoints over HTTP
+ * against a running collector. Skipped unless `OTLP_ACCEPTANCE_URL` is set.
+ *
+ * Run via `pnpm run e2e:otlp` from the repo root, which spins up `wrangler
+ * dev` on :8790 with `ALLOW_UNAUTHENTICATED=true` and sets the env var for
+ * this suite.
+ *
+ * Covers the three bars the RFC defines for parity with the Go receiver:
+ *  1. Stock SDK path — protobuf + gzip + OTLP-JSON all accepted
+ *  2. Response envelope — empty on full success, partial_success on over-cap
+ *  3. Error contract — 400 on malformed, 415 on bad content-type
+ */
+
+import {
+	create,
+	fromBinary,
+	fromJson,
+	toBinary,
+	toJson,
+} from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+declare const process: { env: Record<string, string | undefined> };
+
+const gzip = async (bytes: Uint8Array): Promise<ArrayBuffer> => {
+	const stream = new Response(bytes as BodyInit).body?.pipeThrough(
+		new CompressionStream("gzip"),
+	);
+	return new Response(stream).arrayBuffer();
+};
+
+import { ExportLogsServiceRequestSchema } from "./gen/opentelemetry/proto/collector/logs/v1/logs_service_pb.js";
+import { ExportMetricsServiceRequestSchema } from "./gen/opentelemetry/proto/collector/metrics/v1/metrics_service_pb.js";
+import {
+	ExportTraceServiceRequestSchema,
+	ExportTraceServiceResponseSchema,
+} from "./gen/opentelemetry/proto/collector/trace/v1/trace_service_pb.js";
+import {
+	AnyValueSchema,
+	KeyValueSchema,
+} from "./gen/opentelemetry/proto/common/v1/common_pb.js";
+import {
+	LogRecordSchema,
+	ResourceLogsSchema,
+	ScopeLogsSchema,
+	SeverityNumber,
+} from "./gen/opentelemetry/proto/logs/v1/logs_pb.js";
+import {
+	AggregationTemporality,
+	GaugeSchema,
+	HistogramDataPointSchema,
+	HistogramSchema,
+	MetricSchema,
+	NumberDataPointSchema,
+	ResourceMetricsSchema,
+	ScopeMetricsSchema,
+	SumSchema,
+} from "./gen/opentelemetry/proto/metrics/v1/metrics_pb.js";
+import { ResourceSchema } from "./gen/opentelemetry/proto/resource/v1/resource_pb.js";
+import {
+	ResourceSpansSchema,
+	ScopeSpansSchema,
+	SpanSchema,
+} from "./gen/opentelemetry/proto/trace/v1/trace_pb.js";
+
+const base = process.env.OTLP_ACCEPTANCE_URL;
+const suite = base ? describe : describe.skip;
+
+const serviceAttr = () =>
+	create(KeyValueSchema, {
+		key: "service.name",
+		value: create(AnyValueSchema, {
+			value: { case: "stringValue", value: "e2e-otlp" },
+		}),
+	});
+
+const buildTraces = (count: number) =>
+	create(ExportTraceServiceRequestSchema, {
+		resourceSpans: [
+			create(ResourceSpansSchema, {
+				resource: create(ResourceSchema, { attributes: [serviceAttr()] }),
+				scopeSpans: [
+					create(ScopeSpansSchema, {
+						scope: { name: "acceptance" },
+						spans: Array.from({ length: count }, (_, i) =>
+							create(SpanSchema, {
+								traceId: new Uint8Array(16).fill((i % 255) + 1),
+								spanId: new Uint8Array(8).fill((i % 255) + 1),
+								name: `op-${i}`,
+								startTimeUnixNano: 1_700_000_000_000_000_000n + BigInt(i),
+								endTimeUnixNano: 1_700_000_000_100_000_000n + BigInt(i),
+							}),
+						),
+					}),
+				],
+			}),
+		],
+	});
+
+const buildLogs = (message: string) =>
+	create(ExportLogsServiceRequestSchema, {
+		resourceLogs: [
+			create(ResourceLogsSchema, {
+				resource: create(ResourceSchema, { attributes: [serviceAttr()] }),
+				scopeLogs: [
+					create(ScopeLogsSchema, {
+						scope: { name: "acceptance" },
+						logRecords: [
+							create(LogRecordSchema, {
+								timeUnixNano: BigInt(Date.now()) * 1_000_000n,
+								observedTimeUnixNano: BigInt(Date.now()) * 1_000_000n,
+								severityNumber: SeverityNumber.ERROR,
+								severityText: "ERROR",
+								body: create(AnyValueSchema, {
+									value: { case: "stringValue", value: message },
+								}),
+							}),
+						],
+					}),
+				],
+			}),
+		],
+	});
+
+const buildMetrics = () =>
+	create(ExportMetricsServiceRequestSchema, {
+		resourceMetrics: [
+			create(ResourceMetricsSchema, {
+				resource: create(ResourceSchema, { attributes: [serviceAttr()] }),
+				scopeMetrics: [
+					create(ScopeMetricsSchema, {
+						scope: { name: "acceptance" },
+						metrics: [
+							create(MetricSchema, {
+								name: "e2e.gauge",
+								data: {
+									case: "gauge",
+									value: create(GaugeSchema, {
+										dataPoints: [
+											create(NumberDataPointSchema, {
+												timeUnixNano: 1_700_000_000_000_000_000n,
+												value: { case: "asDouble", value: 42 },
+											}),
+										],
+									}),
+								},
+							}),
+							create(MetricSchema, {
+								name: "e2e.sum",
+								data: {
+									case: "sum",
+									value: create(SumSchema, {
+										isMonotonic: true,
+										aggregationTemporality: AggregationTemporality.CUMULATIVE,
+										dataPoints: [
+											create(NumberDataPointSchema, {
+												timeUnixNano: 1_700_000_000_000_000_000n,
+												value: { case: "asInt", value: 100n },
+											}),
+										],
+									}),
+								},
+							}),
+							create(MetricSchema, {
+								name: "e2e.hist",
+								data: {
+									case: "histogram",
+									value: create(HistogramSchema, {
+										aggregationTemporality: AggregationTemporality.DELTA,
+										dataPoints: [
+											create(HistogramDataPointSchema, {
+												timeUnixNano: 1_700_000_000_000_000_000n,
+												count: 5n,
+												sum: 50,
+												explicitBounds: [10, 50],
+												bucketCounts: [2n, 2n, 1n],
+											}),
+										],
+									}),
+								},
+							}),
+						],
+					}),
+				],
+			}),
+		],
+	});
+
+const post = (
+	path: string,
+	body: BodyInit | Uint8Array,
+	headers: Record<string, string> = {},
+) =>
+	fetch(`${base}${path}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json", ...headers },
+		body: body as BodyInit,
+	});
+
+suite("OTLP acceptance (live)", () => {
+	it("health check is reachable", async () => {
+		const res = await fetch(`${base}/health`);
+		expect(res.ok).toBe(true);
+	});
+
+	describe("/v1/traces", () => {
+		it("accepts JSON and returns empty envelope (200)", async () => {
+			const msg = buildTraces(3);
+			const body = JSON.stringify(toJson(ExportTraceServiceRequestSchema, msg));
+			const res = await post("/v1/traces", body);
+			expect(res.status).toBe(200);
+			expect(res.headers.get("content-type")).toContain("application/json");
+			expect(await res.json()).toEqual({});
+		});
+
+		it("accepts protobuf and returns empty envelope (200)", async () => {
+			const bytes = toBinary(ExportTraceServiceRequestSchema, buildTraces(3));
+			const res = await post("/v1/traces", bytes, {
+				"Content-Type": "application/x-protobuf",
+			});
+			expect(res.status).toBe(200);
+			expect(res.headers.get("content-type")).toContain(
+				"application/x-protobuf",
+			);
+			const msg = fromBinary(
+				ExportTraceServiceResponseSchema,
+				new Uint8Array(await res.arrayBuffer()),
+			);
+			expect(msg.partialSuccess).toBeUndefined();
+		});
+
+		it("decompresses gzip request bodies", async () => {
+			const raw = new TextEncoder().encode(
+				JSON.stringify(toJson(ExportTraceServiceRequestSchema, buildTraces(2))),
+			);
+			const res = await post("/v1/traces", await gzip(raw), {
+				"Content-Encoding": "gzip",
+			});
+			expect(res.status).toBe(200);
+		});
+
+		it("returns partial_success when batch exceeds the cap", async () => {
+			const bytes = toBinary(ExportTraceServiceRequestSchema, buildTraces(501));
+			const res = await post("/v1/traces", bytes, {
+				"Content-Type": "application/x-protobuf",
+			});
+			expect(res.status).toBe(200);
+			const msg = fromBinary(
+				ExportTraceServiceResponseSchema,
+				new Uint8Array(await res.arrayBuffer()),
+			);
+			expect(msg.partialSuccess?.rejectedSpans).toBe(1n);
+			expect(msg.partialSuccess?.errorMessage).toMatch(/cap/);
+		});
+
+		it("accepts valid spans and rejects malformed ones in the same batch (RFC bar #3)", async () => {
+			// 99 valid spans + 1 with an invalid (too-short) trace id.
+			// The Go reference receiver accepts the 99 and reports 1 rejected
+			// via partial_success.
+			const msg = buildTraces(99);
+			const bad = msg.resourceSpans[0]?.scopeSpans[0]?.spans[0];
+			expect(bad).toBeDefined();
+			if (!bad) return;
+			const badClone = { ...bad, traceId: new Uint8Array([1, 2, 3]) };
+			msg.resourceSpans[0]?.scopeSpans[0]?.spans.push(badClone);
+
+			// protobuf refuses to encode invalid trace_id bytes, so send JSON.
+			const json = toJson(ExportTraceServiceRequestSchema, msg) as {
+				resourceSpans: Array<{
+					scopeSpans: Array<{ spans: Array<{ traceId: string }> }>;
+				}>;
+			};
+			// Corrupt the last span's traceId after JSON encoding so it reaches
+			// the receiver but fails `normalizeHex` length validation.
+			const spans = json.resourceSpans[0]?.scopeSpans[0]?.spans;
+			const lastSpan = spans?.[spans.length - 1];
+			expect(lastSpan).toBeDefined();
+			if (!lastSpan) return;
+			lastSpan.traceId = "010203"; // too short for hex or base64
+
+			const res = await post("/v1/traces", JSON.stringify(json));
+			expect(res.status).toBe(200);
+			const body = (await res.json()) as {
+				partialSuccess?: {
+					rejectedSpans?: string;
+					errorMessage?: string;
+				};
+			};
+			expect(body.partialSuccess?.rejectedSpans).toBe("1");
+			expect(body.partialSuccess?.errorMessage).toMatch(/invalid|malformed/i);
+		});
+
+		it("rejects malformed JSON with 400", async () => {
+			const res = await post("/v1/traces", "{not json");
+			expect(res.status).toBe(400);
+		});
+
+		it("rejects unknown content-type with 415", async () => {
+			const res = await post("/v1/traces", "whatever", {
+				"Content-Type": "text/plain",
+			});
+			expect(res.status).toBe(415);
+		});
+
+		it("rejects unknown content-encoding with 415", async () => {
+			const res = await post(
+				"/v1/traces",
+				JSON.stringify(toJson(ExportTraceServiceRequestSchema, buildTraces(1))),
+				{ "Content-Encoding": "brotli" },
+			);
+			expect(res.status).toBe(415);
+		});
+	});
+
+	describe("/v1/logs", () => {
+		it("accepts OTLP JSON logs (empty envelope on full success)", async () => {
+			const body = JSON.stringify(
+				toJson(ExportLogsServiceRequestSchema, buildLogs("json-log")),
+			);
+			const res = await post("/v1/logs", body);
+			expect(res.status).toBe(200);
+			expect(await res.json()).toEqual({});
+		});
+
+		it("accepts OTLP protobuf logs", async () => {
+			const bytes = toBinary(
+				ExportLogsServiceRequestSchema,
+				buildLogs("protobuf-log"),
+			);
+			const res = await post("/v1/logs", bytes, {
+				"Content-Type": "application/x-protobuf",
+			});
+			expect(res.status).toBe(200);
+		});
+	});
+
+	describe("/v1/metrics", () => {
+		it("accepts OTLP JSON gauge + sum + histogram", async () => {
+			const body = JSON.stringify(
+				toJson(ExportMetricsServiceRequestSchema, buildMetrics()),
+			);
+			const res = await post("/v1/metrics", body);
+			expect(res.status).toBe(200);
+			expect(await res.json()).toEqual({});
+		});
+
+		it("accepts OTLP protobuf metrics", async () => {
+			const bytes = toBinary(ExportMetricsServiceRequestSchema, buildMetrics());
+			const res = await post("/v1/metrics", bytes, {
+				"Content-Type": "application/x-protobuf",
+			});
+			expect(res.status).toBe(200);
+		});
+
+		it("round-trips proto-JSON → collector → decode without loss", async () => {
+			const json = toJson(ExportMetricsServiceRequestSchema, buildMetrics());
+			// Round-trip sanity: re-parse the JSON we're about to POST and confirm
+			// it's still schema-valid. Catches proto-JSON encoding regressions.
+			expect(() =>
+				fromJson(ExportMetricsServiceRequestSchema, json),
+			).not.toThrow();
+		});
+	});
+});
+
+if (!base) {
+	// Emit a visible note even if the suite is skipped, so CI doesn't silently
+	// pass without having run the acceptance tests.
+	console.warn(
+		"[otlp-acceptance] OTLP_ACCEPTANCE_URL not set — skipping live suite",
+	);
+}

package/src/otlp/decode/body.ts

@@ -0,0 +1,127 @@
+import type { JsonValue } from "@bufbuild/protobuf";
+import type { Context } from "hono";
+
+export type OtlpWireFormat = "json" | "protobuf";
+
+export interface ReadBodyResult {
+	bytes: Uint8Array;
+	wireFormat: OtlpWireFormat;
+}
+
+export class OtlpDecodeError extends Error {
+	constructor(
+		message: string,
+		public readonly status: 400 | 415,
+	) {
+		super(message);
+	}
+}
+
+/**
+ * Reads and decompresses an OTLP request body, returning the raw bytes plus
+ * the inferred wire format. Throws `OtlpDecodeError` for unsupported content-
+ * types or malformed gzip.
+ */
+export const readOtlpBody = async (c: Context): Promise<ReadBodyResult> => {
+	const contentType = (c.req.header("content-type") ?? "").toLowerCase();
+	const wireFormat = detectWireFormat(contentType);
+
+	let body = await c.req.arrayBuffer();
+	const encoding = (c.req.header("content-encoding") ?? "").toLowerCase();
+	if (encoding === "gzip") {
+		body = await gunzip(body);
+	} else if (encoding && encoding !== "identity") {
+		throw new OtlpDecodeError(`Unsupported content-encoding: ${encoding}`, 415);
+	}
+
+	return { bytes: new Uint8Array(body), wireFormat };
+};
+
+const detectWireFormat = (contentType: string): OtlpWireFormat => {
+	if (contentType.includes("application/x-protobuf")) return "protobuf";
+	if (contentType.includes("application/json")) return "json";
+	throw new OtlpDecodeError(
+		`Unsupported content-type: ${contentType || "(missing)"}`,
+		415,
+	);
+};
+
+const gunzip = async (input: ArrayBuffer): Promise<ArrayBuffer> => {
+	const stream = new Response(input).body?.pipeThrough(
+		new DecompressionStream("gzip"),
+	);
+	if (!stream) throw new OtlpDecodeError("Empty gzip body", 400);
+	return new Response(stream).arrayBuffer();
+};
+
+export const decodeJsonBody = (bytes: Uint8Array): JsonValue => {
+	const text = new TextDecoder().decode(bytes);
+	if (!text.length) return {};
+	const parsed = JSON.parse(text) as JsonValue;
+	rewriteHexIdsToBase64(parsed);
+	return parsed;
+};
+
+/**
+ * The OTLP JSON encoding spec requires `trace_id` (16 bytes) and `span_id`
+ * (8 bytes) to be lowercase hex strings — but proto-JSON's default encoding
+ * for `bytes` fields is base64, which is what protobuf-es's `fromJson`
+ * expects. The Go reference receiver accepts both; we do too, by walking
+ * the parsed JSON and converting any hex-shaped ID field to base64 before
+ * handing it to the schema decoder.
+ *
+ * Mutates the input in-place. Recognized field names cover every place a
+ * trace/span ID appears in OTLP: span, link, log record, exemplar.
+ */
+const rewriteHexIdsToBase64 = (node: JsonValue): void => {
+	if (Array.isArray(node)) {
+		for (const item of node) rewriteHexIdsToBase64(item);
+		return;
+	}
+	if (!node || typeof node !== "object") return;
+	const obj = node as Record<string, JsonValue>;
+	for (const key of Object.keys(obj)) {
+		const value = obj[key];
+		if (typeof value === "string") {
+			if ((key === "traceId" || key === "trace_id") && isHex(value, 32)) {
+				obj[key] = hexToBase64(value);
+			} else if (
+				(key === "spanId" ||
+					key === "span_id" ||
+					key === "parentSpanId" ||
+					key === "parent_span_id") &&
+				isHex(value, 16)
+			) {
+				obj[key] = hexToBase64(value);
+			} else if (isTimestampKey(key) && !isUint64String(value)) {
+				delete obj[key];
+			}
+		} else if (isTimestampKey(key) && typeof value !== "number") {
+			delete obj[key];
+		} else {
+			rewriteHexIdsToBase64(value);
+		}
+	}
+};
+
+const isHex = (s: string, length: number): boolean =>
+	s.length === length && /^[0-9a-f]+$/i.test(s);
+
+const isTimestampKey = (key: string): boolean =>
+	key === "timeUnixNano" ||
+	key === "observedTimeUnixNano" ||
+	key === "startTimeUnixNano" ||
+	key === "endTimeUnixNano";
+
+const isUint64String = (s: string): boolean => /^\d+$/.test(s);
+
+const hexToBase64 = (hex: string): string => {
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < bytes.length; i++) {
+		bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+	}
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++)
+		binary += String.fromCharCode(bytes[i] ?? 0);
+	return btoa(binary);
+};