@obsunified/collector 2.0.1

package/dist/index.d.ts

@@ -0,0 +1,1197 @@
+import * as hono from 'hono';
+import { MiddlewareHandler, Hono } from 'hono';
+import * as hono_types from 'hono/types';
+import * as _obsunified_types from '@obsunified/types';
+import { StoredSpan, TelemetryOverviewOptions, TelemetryOverviewResponse, TelemetryTraceDetailResponse, TelemetryInstrumentationGapsResponse, TelemetryIssueOptions, TelemetryIssueOverviewResponse, TelemetryIssueDetailResponse, UsageEventRecord, UsageOverviewOptions, UsageOverviewResponse, UsageSessionDetailResponse, UsageSessionSummary, AlertRuleInput, AlertRule, AlertStateRow, AlertState, AlertEvaluationsListResponse, AlertComparison, JsonValue, EvidenceReference, EvidenceReferenceContract, Project, IngestKey, IngestKeyWithPlaintext } from '@obsunified/types';
+import { b as CollectorEnv, c as CollectorRouteContext, L as Logger, C as ChildSpanRunner } from './ingest-auth-HFVO1zIp.js';
+export { a as CollectorApp, d as consoleLogger, e as createIngestAuth } from './ingest-auth-HFVO1zIp.js';
+import { ActionConfidence } from '@obsunified/types/constants';
+import { Pool } from 'pg';
+
+/**
+ * Storage seam for the collector — RFC 0008.
+ *
+ * Stores and plugins target this interface instead of `D1Database` directly,
+ * so a future Node / better-sqlite3 / ClickHouse runtime is one new adapter
+ * away rather than a fork-and-rewrite. The shape is deliberately D1's
+ * existing `prepare → bind → first|all|run` chain so the migration of
+ * existing stores is mechanical (search-and-replace the constructor type).
+ *
+ * Today there is one implementation, `D1Adapter`. A `MemSqlDb` test double
+ * lives next door under `test-utils/`; `BetterSqliteAdapter` and
+ * `ClickHouseAdapter` are deferred until they have a real runtime to serve.
+ */
+interface SqlDb {
+    readonly dialect?: SqlDialect;
+    prepare(sql: string): SqlStatement;
+    /**
+     * Run multiple prepared statements as a batch. On D1 this maps to a
+     * single network round-trip; on a future better-sqlite3 adapter it
+     * wraps the calls in a transaction. Returns one result per statement
+     * in input order, mirroring D1's `batch`.
+     *
+     * Statements MUST have been produced by this same `SqlDb` instance —
+     * mixing adapters is an error and runtime behavior is undefined.
+     */
+    batch(statements: SqlStatement[]): Promise<Array<{
+        meta: {
+            changes: number;
+        };
+    }>>;
+}
+type SqlDialectName = "sqlite" | "postgres";
+interface SqlDialect {
+    readonly name: SqlDialectName;
+    now(): string;
+    sinceHours(param: string): string;
+    sinceMinutes(param: string): string;
+    jsonText(expr: string, path: string): string;
+}
+interface SqlStatement {
+    bind(...args: unknown[]): SqlStatement;
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+    all<T = Record<string, unknown>>(): Promise<{
+        results: T[];
+    }>;
+    run(): Promise<{
+        meta: {
+            changes: number;
+        };
+    }>;
+}
+/**
+ * D1 already conforms to this shape almost exactly; the adapter normalizes
+ * two small differences:
+ *  - `all()` on D1 returns `results?: T[]` (optional). We coerce to `[]`.
+ *  - `run()`'s `meta.changes` is optional on D1. We coerce to `0`.
+ * Both differences are runtime-undetectable for the queries this codebase
+ * issues (every successful all() returns results; every run() against an
+ * INSERT/UPDATE/DELETE reports changes), but coercing keeps the typed
+ * interface honest.
+ */
+declare class D1Adapter implements SqlDb {
+    private readonly d1;
+    readonly dialect: SqlDialect;
+    constructor(d1: D1Database);
+    prepare(sql: string): SqlStatement;
+    batch(statements: SqlStatement[]): Promise<Array<{
+        meta: {
+            changes: number;
+        };
+    }>>;
+}
+
+interface ServiceMapOptions {
+    projectId: string;
+    hours: number;
+    source?: "all" | "sdk" | "ebpf";
+}
+interface ServiceOperationsOptions {
+    projectId: string;
+    service: string;
+    hours: number;
+}
+
+interface TelemetryInstrumentationGapCalibrationOptions {
+    projectId: string;
+    hours: number;
+    limit?: number;
+}
+
+declare class TelemetryStore {
+    private readonly db;
+    constructor(db: SqlDb);
+    ingest(spans: StoredSpan[]): Promise<{
+        inserted: number;
+        traceCount: number;
+    }>;
+    getOverview(options: TelemetryOverviewOptions): Promise<TelemetryOverviewResponse>;
+    getTraceDetail(traceId: string, projectId: string): Promise<TelemetryTraceDetailResponse | null>;
+    getTraceGaps(traceId: string, projectId: string): Promise<TelemetryInstrumentationGapsResponse | null>;
+    calibrateTraceGaps(options: TelemetryInstrumentationGapCalibrationOptions): Promise<{
+        thresholds: _obsunified_types.InstrumentationGapThresholds;
+        windowHours: number;
+        sampledSpanCount: number;
+        traceCount: number;
+        flaggedTraceCount: number;
+        blindspotCount: number;
+        uninstrumentedTimeMs: number;
+        flaggedTraceRate: number;
+        status: string;
+        topTraces: {
+            traceId: string;
+            rootSpanName: string;
+            serviceName: string;
+            totalDurationMs: number;
+            blindspotCount: number;
+            uninstrumentedTimeMs: number;
+            ratio: number;
+            topBlindspot: _obsunified_types.TelemetryInstrumentationGap | null;
+        }[];
+        timestamp: string;
+    }>;
+    getIssueOverview(options: TelemetryIssueOptions): Promise<TelemetryIssueOverviewResponse>;
+    getIssueDetail(issueId: string, options: TelemetryIssueOptions): Promise<TelemetryIssueDetailResponse | null>;
+    getExportRows(options: TelemetryOverviewOptions): Promise<string>;
+    getServiceMap(options: ServiceMapOptions): Promise<{
+        nodes: {
+            service: string;
+            spanCount: number;
+            errorCount: number;
+            traceCount: number;
+            errorRate: number;
+        }[];
+        edges: {
+            source: string;
+            target: string;
+            calls: number;
+            errors: number;
+            errorRate: number;
+            p50DurationMs: number;
+            p95DurationMs: number;
+            rps: number;
+            isEbpf: boolean;
+        }[];
+    }>;
+    getServiceOperations(options: ServiceOperationsOptions): Promise<{
+        service: string;
+        spanCount: number;
+        traceCount: number;
+        errorCount: number;
+        operations: {
+            spanName: string;
+            calls: number;
+            errors: number;
+            errorRate: number;
+            p50DurationMs: number;
+            p95DurationMs: number;
+        }[];
+        recentErrors: {
+            traceId: string;
+            spanId: string;
+            spanName: string;
+            statusMessage: string | null;
+            durationMs: number;
+            startTime: string;
+        }[];
+    }>;
+    purgeExpired(): Promise<number>;
+}
+
+/**
+ * UsageStore — union of all repos.
+ * - A's in-memory aggregation approach (more flexible, handles legacy load time keys)
+ * - A's broader error detection (event_type='frontend_error' OR severity='error')
+ * - A's multi-key load time parsing (loadTimeMs, load_time_ms, durationMs)
+ * - A's purgeExpired()
+ * - A's summarizeMap helper
+ */
+
+declare class UsageStore {
+    private readonly db;
+    constructor(db: SqlDb);
+    ingest(events: UsageEventRecord[]): Promise<{
+        inserted: number;
+        sessionCount: number;
+    }>;
+    getOverview(options: UsageOverviewOptions): Promise<UsageOverviewResponse>;
+    getSessionDetail(sessionId: string, projectId: string): Promise<UsageSessionDetailResponse | null>;
+    /**
+     * List sessions with an optional qualitative filter.
+     *
+     * Aggregates per session_id in a single query; supports three filters
+     * derived from session-level rollups: sessions that errored, sessions
+     * with no interactions (engagement drop-off), and sessions with slow
+     * page loads.
+     */
+    listSessions(options: {
+        projectId: string;
+        hours: number;
+        filter: "all" | "ended_in_error" | "dropoff" | "slow";
+        slowMs?: number;
+        limit?: number;
+    }): Promise<{
+        sessions: Array<UsageSessionSummary & {
+            interactionCount: number;
+            maxLoadTimeMs: number | null;
+        }>;
+    }>;
+    purgeExpired(): Promise<number>;
+}
+
+/**
+ * Factory that materializes an `SqlDb` for the request's `env`. Per-request
+ * because Cloudflare's `D1Database` binding only exists once `env` is in
+ * scope; on Workers this is essentially free since `D1Adapter` is a thin
+ * wrapper. Hosts override this to inject a fake DB in tests, a different
+ * engine in alternate runtimes, or a tracing wrapper at the storage layer.
+ */
+type SqlDbFactory = (env: CollectorEnv) => SqlDb;
+interface SpanProcessorPlugin {
+    name: string;
+    process(spans: StoredSpan[], context: CollectorRouteContext): Promise<StoredSpan[]> | StoredSpan[];
+}
+interface UsageEventProcessorPlugin {
+    name: string;
+    process(events: UsageEventRecord[], context: CollectorRouteContext): Promise<UsageEventRecord[]> | UsageEventRecord[];
+}
+interface CollectorPluginContext {
+    addSpanProcessor(processor: SpanProcessorPlugin): void;
+    addUsageEventProcessor(processor: UsageEventProcessorPlugin): void;
+    getRegisteredPluginNames(): string[];
+}
+interface CollectorPlugin {
+    name: string;
+    register(app: Hono<{
+        Bindings: CollectorEnv;
+    }>, context: CollectorRuntime): void;
+}
+interface CollectorAuthConfig {
+    /** Single middleware applied to both /v1/* (ingest) and /internal/* (query) routes */
+    middleware?: MiddlewareHandler<{
+        Bindings: CollectorEnv;
+        Variables: any;
+    }>;
+    /** @deprecated Use middleware instead. Ingest-only auth for /v1/* routes. */
+    ingest?: MiddlewareHandler<{
+        Bindings: CollectorEnv;
+        Variables: any;
+    }>;
+    /** @deprecated Use middleware instead. Query-only auth for /internal/* routes. */
+    query?: MiddlewareHandler<{
+        Bindings: CollectorEnv;
+        Variables: any;
+    }>;
+}
+interface CollectorConfig {
+    plugins: CollectorPlugin[];
+    auth?: CollectorAuthConfig;
+    /** Comma-separated allowed origins for CORS on ingest endpoints */
+    allowedOrigins?: string;
+    /** Register dashboard auth routes and middleware */
+    dashboardAuth?: {
+        middleware: MiddlewareHandler<{
+            Bindings: CollectorEnv;
+            Variables: any;
+        }>;
+        registerRoutes: (app: Hono<{
+            Bindings: CollectorEnv;
+        }>) => void;
+    };
+    /**
+     * Pluggable structured logger. Defaults to console output. Pass a logger
+     * from `@obsunified/telemetry-sdk` to ship the collector's own log output as
+     * OTLP — see apps/collector/SELF_INSTRUMENTATION.md.
+     */
+    logger?: Logger;
+    /**
+     * Wraps async work in a child span on the active request span. Wire this
+     * to `@obsunified/telemetry-sdk`'s `withChildSpan` from the worker entrypoint to
+     * surface LLM hops + DB-heavy paths as nested spans. Defaults to
+     * pass-through.
+     */
+    withChildSpan?: ChildSpanRunner;
+    /**
+     * RFC 0008 — override the storage adapter. Per-request factory because
+     * `env.DB` only exists once a request lands. Defaults to wrapping
+     * `env.DB` in `D1Adapter`. Override in tests (use `MemSqlDb`) or to add
+     * a tracing layer at the storage seam.
+     */
+    sqlDb?: SqlDbFactory;
+}
+declare class CollectorRuntime implements CollectorPluginContext {
+    private readonly spanProcessors;
+    private readonly usageEventProcessors;
+    private readonly plugins;
+    private readonly sqlDbFactory;
+    readonly logger: Logger;
+    readonly withChildSpan: ChildSpanRunner;
+    constructor(logger?: Logger, withChildSpan?: ChildSpanRunner, sqlDbFactory?: SqlDbFactory);
+    /**
+     * Materialize an `SqlDb` for this request. Stores will accept this
+     * directly once Phase 1.5 of RFC 0008 lands; until then plugins that
+     * want to bypass `c.env.DB` can call this to opt in early.
+     */
+    getSqlDb(env: CollectorEnv): SqlDb;
+    registerPlugin(plugin: CollectorPlugin): void;
+    addSpanProcessor(processor: SpanProcessorPlugin): void;
+    addUsageEventProcessor(processor: UsageEventProcessorPlugin): void;
+    getRegisteredPluginNames(): string[];
+    createRouteContext(env: CollectorEnv, hono: CollectorRouteContext["hono"]): CollectorRouteContext;
+    createStore(env: CollectorEnv): TelemetryStore;
+    createUsageStore(env: CollectorEnv): UsageStore;
+    runSpanProcessors(spans: StoredSpan[], context: CollectorRouteContext): Promise<StoredSpan[]>;
+    runUsageEventProcessors(events: UsageEventRecord[], context: CollectorRouteContext): Promise<UsageEventRecord[]>;
+}
+declare const createTelemetryCollectorApp: (pluginsOrConfig: CollectorPlugin[] | CollectorConfig) => Hono<{
+    Bindings: CollectorEnv;
+}>;
+/**
+ * Scheduled handler that purges expired telemetry and usage rows.
+ * Wire into wrangler.toml: `[triggers] crons = ["0 * * * *"]`
+ * Source: AgentOwl + DecisionOps
+ */
+declare const createRetentionCleanupHandler: (options?: {
+    logger?: Logger;
+}) => {
+    scheduled(_event: ScheduledEvent, env: CollectorEnv, _ctx: ExecutionContext): Promise<void>;
+};
+/**
+ * RFC 0002 Stage 1 — run any due Analyses. Cheap to call frequently because
+ * `runAllDueAnalyses` filters by `last_run + refreshSeconds < now` before
+ * touching D1.
+ *
+ * Wire to a per-minute trigger in wrangler.toml: `crons = ["* * * * *"]`.
+ * Kept distinct from retention so the per-minute tick doesn't sweep every
+ * retention table every cycle.
+ */
+declare const createAnalysesRunHandler: (options?: {
+    logger?: Logger;
+    tracer?: ChildSpanRunner;
+}) => {
+    scheduled(_event: ScheduledEvent, env: CollectorEnv, _ctx: ExecutionContext): Promise<void>;
+};
+
+declare const actionRoutesPlugin: CollectorPlugin;
+
+declare const aiReceiverPlugin: CollectorPlugin;
+
+/**
+ * Span processor that routes large AI payloads to the ai_span_payloads
+ * side table.
+ *
+ * For every span that has an `openinference.span.kind` attribute, we look
+ * for `ai.payload.input` / `ai.payload.output`, write them (plus the kind)
+ * to `ai_span_payloads`, and strip them from the span's attributes_json
+ * before it hits `telemetry_spans`.
+ *
+ * This keeps the hot spans table lean while preserving full replay data
+ * for AI calls.
+ */
+
+declare const aiSpanPayloadsProcessorPlugin: CollectorPlugin;
+
+declare function evaluateAllRules(env: CollectorEnv, options?: {
+    logger?: Logger;
+    tracer?: ChildSpanRunner;
+    concurrency?: number;
+    ruleTimeoutMs?: number;
+}): Promise<{
+    evaluated: number;
+    fired: number;
+    resolved: number;
+}>;
+/**
+ * Scheduled handler suitable for wrangler cron triggers. Dispatches on the
+ * cron expression so multiple triggers can share this handler.
+ */
+declare function createAlertEvaluatorHandler(): {
+    scheduled(_event: {
+        cron: string;
+    }, env: CollectorEnv, ctx: {
+        waitUntil(promise: Promise<unknown>): void;
+    }): Promise<void>;
+};
+
+declare const alertsRoutesPlugin: CollectorPlugin;
+
+/**
+ * RFC 0002 — HTTP surface for application-aware Analyses.
+ *
+ *   GET  /internal/analyses               — list registered definitions
+ *   GET  /internal/analyses/:id/result    — definition + latest result
+ *   GET  /internal/analyses/results       — bulk: every definition + latest
+ *   POST /internal/analyses/:id/run       — Stage 4: on-demand re-run for
+ *                                            view: "page" investigations
+ *
+ * Cron writes happen via the scheduled handler (see analyses-runner.ts).
+ * The on-demand POST exists so an investigation page's [Re-run] button
+ * doesn't have to wait for the next 5-min tick.
+ */
+
+declare const analysesRoutesPlugin: CollectorPlugin;
+
+/**
+ * RFC 0002 Stage 5 — Ask box HTTP surface.
+ *
+ *   POST /internal/ask  { question }  → AskResponse
+ *
+ * The dashboard's top-bar AskBox calls this once per question. Single-turn
+ * for v1; the conversational `/ask` thread (with follow-ups + "Save as
+ * panel") lands in a follow-up commit.
+ *
+ * The route does no SQL itself — it composes runAsk() from the catalog
+ * lookups (AnalysesStore + getAllAnalysesForProject) and the LLM config.
+ * If ANTHROPIC_API_KEY is unset we return a structured error rather than
+ * 500-ing, so the dashboard can render a "set ANTHROPIC_API_KEY to
+ * enable Ask" hint instead of a generic failure.
+ */
+
+declare const askRoutesPlugin: CollectorPlugin;
+
+declare const botFilterPlugin: CollectorPlugin;
+
+type CausalConfidence = ActionConfidence;
+interface ActionRef {
+    id: string;
+    projectId: string;
+    rootActionId: string;
+    causedByActionId: string | null;
+    actorType: string;
+    actorId: string | null;
+    actionKind: string;
+    name: string | null;
+    status: string;
+    startedAt: string;
+    endedAt: string | null;
+    durationMs: number | null;
+    traceId: string | null;
+    spanId: string | null;
+    sessionId: string | null;
+    interactionId: string | null;
+    userId: string | null;
+    agentRunId: string | null;
+    stepId: string | null;
+    toolCallId: string | null;
+    promptVersion: string | null;
+    modelName: string | null;
+    provider: string | null;
+    totalCostUsd: number | null;
+    causalConfidence: CausalConfidence;
+    attrsJson: string | null;
+}
+interface AgentRunRef {
+    id: string;
+    projectId: string;
+    agentId: string;
+    agentName: string;
+    agentVersion: string;
+    goal: string | null;
+    outcome: string | null;
+    autonomyLevel: string;
+    status: string;
+    errorMessage: string | null;
+    totalCostUsd: number | null;
+    totalDurationMs: number | null;
+    metadataJson: string | null;
+}
+interface ToolCallRef {
+    id: string;
+    actionId: string;
+    projectId: string;
+    toolName: string;
+    argsHash: string;
+    resultHash: string;
+    errorType: string | null;
+    sideEffect: number;
+    approvalState: string | null;
+    argsRedacted: string | null;
+    resultRedacted: string | null;
+    mcpAuditJson: string | null;
+    mutationBeforeJson: string | null;
+    mutationAfterJson: string | null;
+    mutationDiffJson: string | null;
+    mutationArtifactId: string | null;
+}
+interface RetrievalEventRef {
+    id: string;
+    actionId: string;
+    projectId: string;
+    retrieverName: string;
+    queryHash: string;
+    documentsJson: string | null;
+    totalResults: number;
+    maxRelevanceScore: number | null;
+    durationMs: number | null;
+}
+interface EvalResultRef {
+    id: string;
+    actionId: string;
+    projectId: string;
+    evaluatorName: string;
+    evaluatorVersion: string;
+    score: number | null;
+    passed: number;
+    reasoning: string | null;
+    rubricJson: string | null;
+}
+interface ArtifactRef {
+    id: string;
+    actionId: string;
+    projectId: string;
+    artifactName: string;
+    artifactType: string;
+    storageRef: string | null;
+    sizeBytes: number | null;
+    sha256Hash: string | null;
+    contentPreview: string | null;
+}
+
+/**
+ * RFC 0006 Phase 3.1 — Connected rail manifest endpoint.
+ *
+ *   GET /internal/connected/:kind/:id
+ *
+ * Returns the entity's identity-graph neighbors (Up / Across / Down) +
+ * topic neighbors (Related), bundled into the shape the dashboard's
+ * <ConnectedRail /> renders directly. Built on `IdentityIndex` so the
+ * underlying SQL is shared with `/internal/timeline/:sessionId` and any
+ * future cross-signal consumer.
+ *
+ * The handler is the single read path the rail uses. Sections that have
+ * no neighbors render as `links: []` with an `emptyReason` explaining
+ * why — never absent. This is the "informative absence" pattern from
+ * RFC 0006 § Connected rail / Empty-state.
+ */
+
+declare const connectedRoutesPlugin: CollectorPlugin;
+
+/**
+ * Serves the dashboard SPA.
+ *
+ * For Cloudflare Workers: configure [assets] in wrangler.toml pointing to
+ * the @obsunified/dashboard build output. The Workers runtime handles static file
+ * serving automatically; this plugin provides the fallback route for SPA
+ * client-side routing.
+ *
+ * For Node.js / other runtimes: serve static files from @obsunified/dashboard/dist
+ * using your framework's static file middleware, then mount this plugin for
+ * the SPA fallback.
+ */
+declare const dashboardRoutesPlugin: CollectorPlugin;
+
+declare const defaultSpanEnrichmentPlugin: CollectorPlugin;
+
+declare const evalCasesRoutesPlugin: CollectorPlugin;
+
+declare const evidenceRetrievalRoutesPlugin: CollectorPlugin;
+
+/**
+ * Normalize OpenTelemetry `gen_ai.*` semantic-convention attributes, OTel MCP attributes,
+ * and OpenInference span kinds into the canonical obs-unified Agent Action Graph schema.
+ *
+ * References:
+ *   https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ *   https://github.com/Arize-ai/openinference/blob/main/spec/
+ *
+ * Must run BEFORE ai-span-payloads-processor — that processor assumes
+ * `openinference.span.kind` and `ai.payload.*` are already set.
+ */
+
+declare const genAiNormalizerPlugin: CollectorPlugin;
+
+declare const identityReceiverPlugin: CollectorPlugin;
+
+declare const issueEnrichmentPlugin: CollectorPlugin;
+
+declare const issueInsightsPlugin: CollectorPlugin;
+
+declare const logsReceiverPlugin: CollectorPlugin;
+
+/** OTLP/HTTP metrics receiver. Accepts JSON or protobuf, with gzip. */
+
+declare const metricsReceiverPlugin: CollectorPlugin;
+
+/**
+ * Drives the in-dashboard Onboarding tab — returns counts of signal
+ * types, used to decide which "you need to wire X" snippets to show
+ * the user.
+ *
+ * Returns zeros for tables that don't yet exist (e.g. fresh DB) rather
+ * than 500ing — onboarding has to work on day zero.
+ */
+declare const onboardingRoutesPlugin: CollectorPlugin;
+
+/** OTLP/HTTP trace receiver. Accepts JSON or protobuf, with gzip. */
+
+declare const otlpReceiverPlugin: CollectorPlugin;
+
+declare const platformRoutesPlugin: CollectorPlugin;
+
+/**
+ * RFC 0007 — pprof profiling receiver + read endpoints.
+ *
+ *   POST /v1/profiles/pprof              — accepts gzipped pprof blob
+ *   GET  /internal/profiles/:id          — proxies the blob back
+ *   GET  /internal/profiles/:id?trace_id=… — Phase 4.5 server-side filter
+ *
+ * Phase 4 minimal scope: ingest-time pprof parsing is deferred. The
+ * receiver writes the blob verbatim to R2 / filesystem and reads
+ * trace_ids from an `x-obs-trace-ids` header (comma-separated). The
+ * @obsunified/telemetry-sdk profile helper will stamp this; eBPF agents that
+ * don't emit the header just don't populate `profile_trace_index`,
+ * which means the trace waterfall's 🔥 badge won't fire for those
+ * profiles. Aggregate views still work.
+ *
+ * A follow-on commit can add server-side pprof parsing using a Buf-
+ * generated schema or pprof-format. The endpoint shape doesn't change
+ * when that lands.
+ */
+
+declare const profileRoutesPlugin: CollectorPlugin;
+
+declare const projectsRoutesPlugin: CollectorPlugin;
+
+declare const queryRoutesPlugin: CollectorPlugin;
+
+declare const redactionProcessorPlugin: CollectorPlugin;
+
+declare const replayQueryRoutesPlugin: CollectorPlugin;
+
+declare const replayReceiverPlugin: CollectorPlugin;
+
+/**
+ * Live tail SSE endpoint. The dashboard opens an EventSource here; the
+ * collector proxies to the TailHub Durable Object which holds the open
+ * stream and fans out broadcasts from ingest.
+ */
+declare const tailRoutesPlugin: CollectorPlugin;
+
+declare const timelineRoutesPlugin: CollectorPlugin;
+
+declare const uaEnrichmentPlugin: CollectorPlugin;
+
+declare const usageNormalizationPlugin: CollectorPlugin;
+
+declare const usagePrivacyPlugin: CollectorPlugin;
+
+declare const usageQueryRoutesPlugin: CollectorPlugin;
+
+/** Union: A's JSON error handling, event limit, env-based retention. P/D's dynamic CORS. */
+
+declare const usageReceiverPlugin: CollectorPlugin;
+
+declare const usersQueryRoutesPlugin: CollectorPlugin;
+
+declare const utmEnrichmentPlugin: CollectorPlugin;
+
+/**
+ * Creates auth routes and middleware for dashboard password login.
+ *
+ * Routes added:
+ *   POST /auth/login  — accepts { password }, sets session cookie
+ *   GET  /auth/check  — returns { authenticated: true/false }
+ *   POST /auth/logout — clears session cookie
+ *
+ * The returned middleware validates the session cookie on protected routes.
+ */
+declare function createDashboardAuth(config: {
+    password: string;
+}): {
+    middleware: MiddlewareHandler<{
+        Bindings: CollectorEnv;
+        Variables: {
+            projectId: string;
+        };
+    }>;
+    registerRoutes: (app: hono.Hono<{
+        Bindings: CollectorEnv;
+    }>) => void;
+};
+
+/**
+ * In-memory SSE pub/sub hub for live-tailing spans and logs.
+ *
+ * Ingest plugins call `/publish` after writing to D1; the dashboard opens an
+ * EventSource on `/internal/telemetry/tail` which proxies here via `/subscribe`.
+ *
+ * One singleton DO instance is used (idFromName("singleton")); it fans out to
+ * every connected subscriber, filtering by projectId and kind server-side so
+ * clients don't see other tenants' data.
+ *
+ * Heartbeat frames keep the connection alive through proxies with idle
+ * timeouts (Vite dev proxy, Cloudflare edge).
+ */
+type TailKind = "span" | "log";
+interface TailEvent {
+    kind: TailKind;
+    projectId: string;
+    row: Record<string, unknown>;
+    t: string;
+}
+declare class TailHub {
+    private readonly subscribers;
+    private readonly encoder;
+    fetch(req: Request): Promise<Response>;
+    private subscribe;
+    private drop;
+    private broadcast;
+}
+
+type ActionRecord = Omit<ActionRef, "projectId"> & {
+    projectId: string;
+};
+type AgentRunRecord = Omit<AgentRunRef, "projectId"> & {
+    projectId: string;
+};
+type ToolCallRecord = Omit<ToolCallRef, "projectId" | "sideEffect"> & {
+    projectId: string;
+    sideEffect: boolean | number;
+};
+type RetrievalEventRecord = Omit<RetrievalEventRef, "projectId"> & {
+    projectId: string;
+};
+type EvalResultRecord = Omit<EvalResultRef, "projectId" | "passed"> & {
+    projectId: string;
+    passed: boolean | number;
+};
+type ArtifactRecord = Omit<ArtifactRef, "projectId"> & {
+    projectId: string;
+};
+declare class ActionStore {
+    private readonly db;
+    constructor(db: SqlDb);
+    upsertAction(action: ActionRecord): Promise<void>;
+    upsertAgentRun(run: AgentRunRecord): Promise<void>;
+    upsertToolCall(toolCall: ToolCallRecord): Promise<void>;
+    upsertRetrievalEvent(event: RetrievalEventRecord): Promise<void>;
+    upsertEvalResult(result: EvalResultRecord): Promise<void>;
+    upsertArtifact(artifact: ArtifactRecord): Promise<void>;
+    getAction(projectId: string, actionId: string): Promise<ActionRef | null>;
+    listActionsByRoot(projectId: string, rootActionId: string, limit?: number): Promise<ActionRef[]>;
+    getAgentRun(projectId: string, agentRunId: string): Promise<AgentRunRef | null>;
+    listToolCallsByAction(projectId: string, actionId: string, limit?: number): Promise<ToolCallRef[]>;
+    listRetrievalEventsByAction(projectId: string, actionId: string, limit?: number): Promise<RetrievalEventRef[]>;
+    listEvalResultsByAction(projectId: string, actionId: string, limit?: number): Promise<EvalResultRef[]>;
+    listArtifactsByAction(projectId: string, actionId: string, limit?: number): Promise<ArtifactRef[]>;
+}
+
+declare function compareValue(value: number, threshold: number, comparison: AlertComparison): boolean;
+declare class AlertsStore {
+    private readonly db;
+    constructor(db: SqlDb);
+    validateInput(input: AlertRuleInput): void;
+    listRules(projectId: string): Promise<AlertRule[]>;
+    getRule(id: string, projectId: string): Promise<AlertRule | null>;
+    createRule(projectId: string, input: AlertRuleInput): Promise<AlertRule>;
+    updateRule(id: string, projectId: string, patch: Partial<AlertRuleInput>): Promise<AlertRule | null>;
+    deleteRule(id: string, projectId: string): Promise<boolean>;
+    listEnabledRules(): Promise<AlertRule[]>;
+    getState(ruleId: string): Promise<AlertStateRow | null>;
+    transitionState(ruleId: string, projectId: string, newState: AlertState, now: string): Promise<void>;
+    recordEvaluation(ruleId: string, projectId: string, value: number, state: AlertState, notified: boolean): Promise<void>;
+    listEvaluations(params: {
+        ruleId: string;
+        projectId?: string;
+        hours: number;
+        limit?: number;
+    }): Promise<AlertEvaluationsListResponse>;
+    evaluateRule(rule: AlertRule): Promise<number>;
+    /**
+     * Stage 6 — fetch the latest narrative associated with this rule's
+     * bound analysis. Used by the evaluator when firing an analysis-bound
+     * alert so the webhook payload includes the human-readable
+     * narrative, not just a threshold crossing.
+     */
+    getAnalysisNarrative(projectId: string, analysisId: string): Promise<{
+        narrative: string | null;
+        status: string | null;
+    } | null>;
+    private evaluateSpanRule;
+    private evaluateLogRule;
+    private evaluateUsageRule;
+    private evaluateAIRule;
+}
+
+/**
+ * Storage seam for opaque blob payloads — replay rrweb chunks and
+ * pprof profiles.
+ *
+ * Two implementations:
+ *  - `R2BlobStore` — Cloudflare R2 binding (default on Workers).
+ *  - `S3BlobStore` (sibling file) — AWS S3 / MinIO / any S3-compatible.
+ *
+ * Replay chunks live under `replays/<session_id>/<chunk_id>`; pprof
+ * profiles live under `profiles/<service>/<trace_id>/<span_id>`. The
+ * adapter never sees these paths — they're constructed by the callers
+ * (`replay-receiver`, `profile-routes`).
+ */
+interface BlobStore {
+    put(key: string, body: ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, options?: BlobPutOptions): Promise<void>;
+    get(key: string): Promise<BlobObject | null>;
+    delete(key: string): Promise<void>;
+    list(prefix: string, options?: BlobListOptions): Promise<BlobListResult>;
+}
+interface BlobPutOptions {
+    httpMetadata?: {
+        contentType?: string;
+        contentEncoding?: string;
+    };
+    customMetadata?: Record<string, string>;
+}
+interface BlobListOptions {
+    limit?: number;
+    cursor?: string;
+}
+interface BlobObject {
+    body: ReadableStream<Uint8Array>;
+    bytes(): Promise<Uint8Array>;
+    /**
+     * Object size in bytes when the store knows it cheaply (S3 `ContentLength`,
+     * R2 `size`). Undefined when it can't be determined without reading the body.
+     */
+    size?: number;
+    httpMetadata?: {
+        contentType?: string;
+        contentEncoding?: string;
+    };
+    customMetadata?: Record<string, string>;
+}
+interface BlobListResult {
+    objects: Array<{
+        key: string;
+        size: number;
+        uploaded: Date;
+    }>;
+    cursor?: string;
+    truncated: boolean;
+}
+/**
+ * R2 adapter. R2's binding shape is already very close to this
+ * interface; the adapter normalizes the differences (cursor type,
+ * list pagination shape).
+ */
+declare class R2BlobStore implements BlobStore {
+    private readonly bucket;
+    constructor(bucket: R2Bucket);
+    put(key: string, body: ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, options?: BlobPutOptions): Promise<void>;
+    get(key: string): Promise<BlobObject | null>;
+    delete(key: string): Promise<void>;
+    list(prefix: string, options?: BlobListOptions): Promise<BlobListResult>;
+}
+declare class BlobStoreToR2Adapter implements R2Bucket {
+    private readonly store;
+    constructor(store: BlobStore);
+    put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options?: R2PutOptions): Promise<R2Object>;
+    get(key: string, _options?: R2GetOptions): Promise<R2ObjectBody | null>;
+    delete(keys: string | string[]): Promise<void>;
+    list(options?: R2ListOptions): Promise<R2Objects>;
+    head(key: string): Promise<R2Object | null>;
+    createMultipartUpload(_key: string, _options?: R2MultipartOptions): Promise<R2MultipartUpload>;
+    resumeMultipartUpload(_key: string, _uploadId: string): R2MultipartUpload;
+}
+
+/**
+ * S3-compatible adapter for `BlobStore`. Works against AWS S3, MinIO,
+ * Cloudflare R2's S3 API, Backblaze B2, etc.
+ *
+ * Uses `@aws-sdk/client-s3` v3. The adapter is intentionally thin —
+ * just enough to satisfy `BlobStore` for replay + pprof payloads. We
+ * deliberately do NOT expose pre-signed URLs, ACLs, or storage-class
+ * tuning — those belong in a richer storage adapter for users that
+ * outgrow the default.
+ */
+
+type S3Body = Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;
+type S3CommandBody = Exclude<S3Body, ArrayBuffer>;
+interface S3ClientShape {
+    send(command: unknown): Promise<unknown>;
+}
+interface S3SdkConstructors {
+    PutObjectCommand: new (input: {
+        Bucket: string;
+        Key: string;
+        Body?: S3CommandBody;
+        ContentType?: string;
+        ContentEncoding?: string;
+        Metadata?: Record<string, string>;
+    }) => unknown;
+    GetObjectCommand: new (input: {
+        Bucket: string;
+        Key: string;
+    }) => unknown;
+    DeleteObjectCommand: new (input: {
+        Bucket: string;
+        Key: string;
+    }) => unknown;
+    ListObjectsV2Command: new (input: {
+        Bucket: string;
+        Prefix: string;
+        MaxKeys?: number;
+        ContinuationToken?: string;
+    }) => unknown;
+}
+interface S3BlobStoreOptions {
+    client: S3ClientShape;
+    commands: S3SdkConstructors;
+    bucket: string;
+}
+declare class S3BlobStore implements BlobStore {
+    private readonly opts;
+    constructor(opts: S3BlobStoreOptions);
+    put(key: string, body: S3Body, options?: BlobPutOptions): Promise<void>;
+    get(key: string): Promise<BlobObject | null>;
+    delete(key: string): Promise<void>;
+    list(prefix: string, options?: BlobListOptions): Promise<BlobListResult>;
+}
+
+type EvalCaseSourceType = "agent_run" | "action" | "ai_call" | "tool_call" | "trace";
+interface EvalCaseSourceLinks {
+    sourceAgentRunId?: string | null;
+    sourceActionId?: string | null;
+    sourceAiCallId?: string | null;
+    sourceToolCallId?: string | null;
+    sourceTraceId?: string | null;
+    sourceSpanId?: string | null;
+}
+interface EvalCaseInput {
+    sourceEntityType: EvalCaseSourceType;
+    sourceEntityId: string;
+    name: string;
+    expectedOutcome?: string | null;
+    rubric?: JsonValue | null;
+    redactedPrompt?: JsonValue | null;
+    referencePayload?: JsonValue | null;
+    metadata?: Record<string, JsonValue>;
+    source?: EvalCaseSourceLinks;
+}
+interface EvalCase extends Required<EvalCaseSourceLinks> {
+    id: string;
+    projectId: string;
+    sourceEntityType: EvalCaseSourceType;
+    sourceEntityId: string;
+    name: string;
+    expectedOutcome: string | null;
+    rubric: JsonValue | null;
+    redactedPrompt: JsonValue | null;
+    referencePayload: JsonValue | null;
+    metadata: Record<string, JsonValue>;
+    createdAt: string;
+    updatedAt: string;
+    evidenceReferences?: EvidenceReference[];
+    evidenceContract?: EvidenceReferenceContract;
+}
+interface EvalCaseListOptions {
+    projectId: string;
+    sourceEntityType?: EvalCaseSourceType;
+    sourceEntityId?: string;
+    limit?: number;
+}
+type EvalRunStatus = "pending" | "running" | "completed" | "failed" | "canceled";
+interface EvalRunCandidate {
+    agentId: string | null;
+    agentVersion: string | null;
+    promptId: string | null;
+    promptVersion: string | null;
+    modelProvider: string | null;
+    model: string | null;
+    modelVersion: string | null;
+}
+interface EvalRunSourceCase {
+    id: string;
+    name: string;
+    sourceEntityType: string;
+    sourceEntityId: string;
+    sourceAgentRunId: string | null;
+    sourceActionId: string | null;
+    sourceAiCallId: string | null;
+    sourceToolCallId: string | null;
+    sourceTraceId: string | null;
+    sourceSpanId: string | null;
+    evidenceReferences?: EvidenceReference[];
+    evidenceContract?: EvidenceReferenceContract;
+}
+interface EvalRun {
+    id: string;
+    projectId: string;
+    evalCaseId: string | null;
+    status: EvalRunStatus;
+    candidate: EvalRunCandidate;
+    startedAt: string | null;
+    endedAt: string | null;
+    totalCount: number;
+    passCount: number;
+    failCount: number;
+    averageScore: number | null;
+    metadata: Record<string, JsonValue>;
+    createdAt: string;
+    sourceEvalCase?: EvalRunSourceCase | null;
+    evidenceReferences?: EvidenceReference[];
+    evidenceContract?: EvidenceReferenceContract;
+}
+interface EvalRunInput {
+    id?: string;
+    evalCaseId?: string | null;
+    status?: EvalRunStatus;
+    candidate?: Partial<EvalRunCandidate>;
+    startedAt?: string | null;
+    endedAt?: string | null;
+    totalCount?: number;
+    passCount?: number;
+    failCount?: number;
+    averageScore?: number | null;
+    metadata?: Record<string, JsonValue>;
+}
+interface EvalRunsListOptions {
+    projectId: string;
+    evalCaseId?: string;
+    status?: EvalRunStatus;
+    limit?: number;
+}
+declare class EvalCaseSourceNotFoundError extends Error {
+    readonly projectId: string;
+    readonly sourceEntityType: EvalCaseSourceType;
+    readonly sourceEntityId: string;
+    constructor(projectId: string, sourceEntityType: EvalCaseSourceType, sourceEntityId: string);
+}
+declare const isEvalCaseSourceType: (value: unknown) => value is EvalCaseSourceType;
+declare const isEvalRunStatus: (value: unknown) => value is EvalRunStatus;
+declare class EvalCasesStore {
+    private readonly db;
+    constructor(db: SqlDb);
+    createCase(projectId: string, input: EvalCaseInput): Promise<EvalCase>;
+    getCase(projectId: string, id: string): Promise<EvalCase | null>;
+    listCases(options: EvalCaseListOptions): Promise<EvalCase[]>;
+    createRun(projectId: string, input: EvalRunInput): Promise<EvalRun>;
+    getRun(projectId: string, id: string): Promise<EvalRun | null>;
+    listRuns(options: EvalRunsListOptions): Promise<EvalRun[]>;
+    refreshRunSummary(projectId: string, id: string): Promise<void>;
+    private evalRunSelectSql;
+    private hydrateSource;
+    private getActionSource;
+    private getToolCallSource;
+    private findPayload;
+    private buildMetadata;
+}
+
+type MetricType = "gauge" | "sum" | "histogram" | "exp_histogram" | "summary";
+/**
+ * A metric data point normalized for storage. Series-identifying fields
+ * (name, resource/scope context, attributes) are repeated on each point so
+ * the store can do series upsert in a single pass.
+ */
+interface DecodedMetricPoint {
+    name: string;
+    description: string | null;
+    unit: string | null;
+    type: MetricType;
+    isMonotonic: boolean | null;
+    temporality: number | null;
+    scopeName: string | null;
+    scopeVersion: string | null;
+    serviceName: string | null;
+    resourceAttrsJson: string | null;
+    attributesJson: string | null;
+    identity: string;
+    tsNs: string;
+    startTsNs: string | null;
+    value: number | null;
+    count: number | null;
+    sum: number | null;
+    min: number | null;
+    max: number | null;
+    boundsJson: string | null;
+    bucketCountsJson: string | null;
+    /**
+     * Type-specific fields that don't fit the column schema:
+     *   - exp_histogram: { scale, zeroCount, zeroThreshold, positive: {offset, bucketCounts}, negative: {offset, bucketCounts} }
+     *   - summary: { quantileValues: [{quantile, value}, ...] }
+     */
+    extraJson: string | null;
+    exemplarsJson: string | null;
+}
+
+/**
+ * Metrics storage.
+ *
+ * Each ingest collapses points to their series identity, upserts the series
+ * row, then batch-inserts points. Series upsert is per-unique-identity per
+ * request — at small batch sizes this is cheap; a followup can switch to a
+ * single SELECT-many + batched INSERT-missing when volume demands it.
+ */
+
+interface MetricExemplarPoint {
+    id: string;
+    pointId: string;
+    seriesId: string;
+    metricName: string;
+    serviceName: string | null;
+    traceId: string | null;
+    spanId: string | null;
+    tsNs: string;
+    value: number;
+    receivedAt: string;
+}
+declare class MetricsStore {
+    private readonly db;
+    constructor(db: SqlDb);
+    purgeExpired(): Promise<number>;
+    ingestBatch(opts: {
+        projectId: string;
+        points: DecodedMetricPoint[];
+        receivedAt: string;
+        expiresAt: string;
+    }): Promise<void>;
+    exemplarsForTrace(projectId: string, traceId: string, limit?: number): Promise<MetricExemplarPoint[]>;
+    recentExemplars(opts: {
+        projectId: string;
+        serviceName?: string | null;
+        metricPrefix?: string | null;
+        limit?: number;
+    }): Promise<MetricExemplarPoint[]>;
+    /**
+     * Ensures a `metric_series` row exists for every unique identity in the
+     * batch. Returns a map of identity → series row for point linking.
+     */
+    private resolveSeries;
+}
+
+declare class ProjectsStore {
+    private readonly db;
+    constructor(db: SqlDb);
+    listProjects(): Promise<Project[]>;
+    getProject(id: string): Promise<Project | null>;
+    createProject(input: {
+        name: string;
+        slug: string;
+    }): Promise<Project>;
+    updateProject(id: string, patch: {
+        name?: string;
+        payloadCaptureEnabled?: boolean;
+    }): Promise<Project | null>;
+    ensureDefaultProject(): Promise<void>;
+    listKeys(projectId: string): Promise<IngestKey[]>;
+    createKey(projectId: string, name: string): Promise<IngestKeyWithPlaintext>;
+    revokeKey(keyId: string): Promise<boolean>;
+    findByKeyHash(keyHash: string): Promise<{
+        projectId: string;
+        keyId: string;
+    } | null>;
+    /**
+     * Idempotently register the legacy env INGEST_KEY as a bootstrap key on the
+     * default project, so existing deployments keep working without manual migration.
+     */
+    bootstrapEnvKey(plaintext: string): Promise<void>;
+}
+
+interface PostgresAdapterOptions {
+    /**
+     * Statement-level timeout in milliseconds. Defaults to 30s. Issued
+     * via `SET statement_timeout` at the start of each query (session-level;
+     * `SET LOCAL` outside a transaction would be a no-op).
+     */
+    statementTimeoutMs?: number;
+}
+declare class PostgresAdapter implements SqlDb {
+    private readonly pool;
+    readonly dialect: SqlDialect;
+    private readonly statementTimeoutMs;
+    constructor(pool: Pool, options?: PostgresAdapterOptions);
+    prepare(sql: string): SqlStatement;
+    batch(statements: SqlStatement[]): Promise<Array<{
+        meta: {
+            changes: number;
+        };
+    }>>;
+}
+
+/** All built-in plugins in recommended registration order */
+declare const allPlugins: CollectorPlugin[];
+declare const createDefaultCollectorApp: (config?: Partial<CollectorConfig>) => hono.Hono<{
+    Bindings: CollectorEnv;
+}, hono_types.BlankSchema, "/">;
+declare const _default: hono.Hono<{
+    Bindings: CollectorEnv;
+}, hono_types.BlankSchema, "/">;
+
+export { type ActionRecord, ActionStore, type AgentRunRecord, AlertsStore, type ArtifactRecord, type BlobListOptions, type BlobListResult, type BlobObject, type BlobPutOptions, type BlobStore, BlobStoreToR2Adapter, type CollectorAuthConfig, type CollectorConfig, CollectorEnv, type CollectorPlugin, CollectorRouteContext, CollectorRuntime, D1Adapter, type EvalCase, type EvalCaseInput, type EvalCaseListOptions, type EvalCaseSourceLinks, EvalCaseSourceNotFoundError, type EvalCaseSourceType, EvalCasesStore, type EvalResultRecord, type EvalRun, type EvalRunCandidate, type EvalRunInput, type EvalRunSourceCase, type EvalRunStatus, type EvalRunsListOptions, Logger, MetricsStore, PostgresAdapter, type PostgresAdapterOptions, ProjectsStore, R2BlobStore, type RetrievalEventRecord, S3BlobStore, type S3BlobStoreOptions, type SpanProcessorPlugin, type SqlDb, type SqlDbFactory, type SqlStatement, type TailEvent, TailHub, type TailKind, type ToolCallRecord, type UsageEventProcessorPlugin, actionRoutesPlugin, aiReceiverPlugin, aiSpanPayloadsProcessorPlugin, alertsRoutesPlugin, allPlugins, analysesRoutesPlugin, askRoutesPlugin, botFilterPlugin, compareValue, connectedRoutesPlugin, createAlertEvaluatorHandler, createAnalysesRunHandler, createDashboardAuth, createDefaultCollectorApp, createRetentionCleanupHandler, createTelemetryCollectorApp, dashboardRoutesPlugin, _default as default, defaultSpanEnrichmentPlugin, evalCasesRoutesPlugin, evaluateAllRules, evidenceRetrievalRoutesPlugin, genAiNormalizerPlugin, identityReceiverPlugin, isEvalCaseSourceType, isEvalRunStatus, issueEnrichmentPlugin, issueInsightsPlugin, logsReceiverPlugin, metricsReceiverPlugin, onboardingRoutesPlugin, otlpReceiverPlugin, platformRoutesPlugin, profileRoutesPlugin, projectsRoutesPlugin, queryRoutesPlugin, redactionProcessorPlugin, replayQueryRoutesPlugin, replayReceiverPlugin, tailRoutesPlugin, timelineRoutesPlugin, uaEnrichmentPlugin, usageNormalizationPlugin, usagePrivacyPlugin, usageQueryRoutesPlugin, usageReceiverPlugin, usersQueryRoutesPlugin, utmEnrichmentPlugin };