@obsunified/collector 2.0.1 → 2.2.0

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import * as hono from 'hono';
-import { MiddlewareHandler, Hono } from 'hono';
+import { MiddlewareHandler, Hono, Context } 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 { StoredSpan, TelemetryOverviewOptions, TelemetryOverviewResponse, TelemetryTraceDetailResponse, TelemetryInstrumentationGapsResponse, TelemetryIssueOptions, TelemetryIssueOverviewResponse, TelemetryIssueDetailResponse, UsageEventRecord, UsageOverviewOptions, UsageOverviewResponse, UsageSessionDetailResponse, UsageSessionSummary, AlertRuleInput, AlertRule, AlertStateRow, AlertState, AlertEvaluationsListResponse, AlertComparison, ChangeBlastRadiusResult, ContentionCandidate, ChangeEvent, ChangeEventInput, InvestigationFinding, InvestigationFindingInput, OntologyNode, OntologyEdge, CanonicalNodeIdentity, OntologyGraphResponse, RelationshipCertainty, CausalTriple, IncidentInvestigation, RemediationProposal, EvidenceEntityKind, RemediationProposalInput, JsonValue, EvidenceReference, EvidenceReferenceContract, Project, IngestKey, IngestKeyWithPlaintext } from '@obsunified/types';
+import { b as CollectorEnv, L as Logger, C as ChildSpanRunner, c as CollectorRouteContext } from './ingest-auth-C5-8Mly5.js';
+export { a as CollectorApp, d as consoleLogger, e as createIngestAuth } from './ingest-auth-C5-8Mly5.js';
 import { ActionConfidence } from '@obsunified/types/constants';
 import { Pool } from 'pg';
 
@@ -81,6 +81,83 @@ declare class D1Adapter implements SqlDb {
     }>>;
 }
 
+/**
+ * RFC 0002 Stage 1 — runner that executes SQL-only Analyses on the existing
+ * scheduled handler.
+ *
+ * runSqlAnalysis  — execute one definition's `sql` against D1 and shape the
+ *                   row(s) into an AnalysisResult.
+ * runAllDueAnalyses — orchestrator: refresh the in-process registry into
+ *                   analysis_definitions, find which ones are due, run them,
+ *                   persist the results. Per-analysis errors are isolated
+ *                   via Promise.allSettled so one bad SQL doesn't kill the
+ *                   batch.
+ *
+ * Result shape convention: an Analysis SQL is expected to return a single
+ * row with the columns:
+ *
+ *   status         TEXT  | NULL  -- 'ok' | 'warn' | 'critical' | 'unknown'
+ *   primary_value  REAL  | NULL
+ *   baseline_value REAL  | NULL
+ *   payload        TEXT  | NULL  -- JSON-serialized object, optional
+ *
+ * If `status` is NULL we derive it from the magnitude of delta_pct
+ * (>=25% → critical, >=10% → warn, else ok). delta_pct itself is computed
+ * here from primary/baseline so individual SQL queries don't have to.
+ */
+
+/**
+ * Orchestrator. Refreshes the analysis_definitions registry from the
+ * in-process registry (so newly-derived Tier 1 analyses become visible
+ * to the dashboard within one tick), then runs whatever's due.
+ *
+ * Runs once per project in the `projects` table (falling back to the
+ * `default` project when the table is empty or unreadable), so analyses and
+ * the alert rules bound to them refresh for every tenant, not just the
+ * first one.
+ */
+declare function runAllDueAnalyses(ctx: {
+    env: CollectorEnv;
+    retentionHours: number;
+    logger?: Logger;
+    tracer?: ChildSpanRunner;
+}, _runtime?: unknown): Promise<{
+    ran: number;
+    failed: number;
+    refreshed: number;
+    narrated: number;
+    skipped?: number;
+}>;
+
+/**
+ * Retention for the secondary tables the hourly sweep did not cover. Each
+ * rule is tied to an existing contract rather than a new policy:
+ *
+ *  - `alert_evaluations`: `/internal/alerts/evaluations` accepts at most a
+ *    720-hour window, so rows older than that are unreachable through the API.
+ *  - `ask_evidence_events`: feeds `getTopAskedAnalyses`, whose trailing window
+ *    is 7 days; rows older than 30 days cannot influence it.
+ *  - `metric_series`: identity rows whose points have all expired and that
+ *    were created before the retention window. They hold no data; the next
+ *    ingest of that identity recreates the row.
+ *  - `evidence_retrieval_refs`: rows carry their own `expires_at` (copied from
+ *    the signal they reference); expansions follow their ref.
+ */
+
+interface HousekeepingSummary {
+    alert_evaluations: number;
+    ask_evidence_events: number;
+    metric_series: number;
+    evidence_refs: number;
+    evidence_ref_expansions: number;
+    ontology_edges?: number;
+    ontology_nodes?: number;
+    change_events?: number;
+    incident_investigations?: number;
+    investigation_findings?: number;
+    remediation_proposals?: number;
+}
+
 interface ServiceMapOptions {
     projectId: string;
     hours: number;
@@ -298,6 +375,18 @@ interface CollectorConfig {
      * a tracing layer at the storage seam.
      */
     sqlDb?: SqlDbFactory;
+    /**
+     * Raw request body cap for `/v1/*` and `/internal/*` in bytes. Defaults
+     * to `MAX_BODY_BYTES` from the environment, then 10 MiB. Oversized
+     * requests get a 413 before any handler buffers the body.
+     */
+    maxBodyBytes?: number;
+    /**
+     * Body cap for the unauthenticated `/auth/*` routes (login/check/logout).
+     * Defaults to 16 KiB and is independent of `maxBodyBytes`, so an anonymous
+     * client can never make the host buffer an ingest-sized body.
+     */
+    maxAuthBodyBytes?: number;
 }
 declare class CollectorRuntime implements CollectorPluginContext {
     private readonly spanProcessors;
@@ -327,30 +416,56 @@ declare const createTelemetryCollectorApp: (pluginsOrConfig: CollectorPlugin[] |
     Bindings: CollectorEnv;
 }>;
 /**
- * Scheduled handler that purges expired telemetry and usage rows.
- * Wire into wrangler.toml: `[triggers] crons = ["0 * * * *"]`
- * Source: AgentOwl + DecisionOps
+ * Runtime-neutral entry point for a background maintenance task.
+ *
+ * `run(env)` does the work and needs nothing but a `CollectorEnv`, so any
+ * host (Cloudflare cron, a Node `setInterval`, a Kubernetes CronJob hitting
+ * a one-shot script) can drive it. `scheduled(event, env, ctx)` is the thin
+ * Cloudflare Workers adapter over `run` — the event and context are accepted
+ * for signature compatibility with `ExportedHandler.scheduled` but are never
+ * consulted, so non-Workers hosts should call `run` directly rather than
+ * fabricating placeholder event objects.
  */
+interface ScheduledTaskHandler<TSummary = void> {
+    run(env: CollectorEnv): Promise<TSummary>;
+    scheduled(event: ScheduledEvent, env: CollectorEnv, ctx: ExecutionContext): Promise<void>;
+}
+/** Per-table purge counts reported by the retention cleanup task. */
+interface RetentionCleanupSummary {
+    spans: number;
+    usage: number;
+    logs: number;
+    ai_calls: number;
+    metric_points: number;
+    analysis_results: number;
+    profile_blobs: number;
+    /** RFC 0010 action spine rows removed (trees older than RETENTION_HOURS). */
+    actions: number;
+    /** Leaf rows removed with their actions: agent_runs, tool_calls,
+     *  retrieval_events, eval_results and artifacts. */
+    action_leaves: number;
+    /** Secondary tables (see lib/housekeeping.ts); zeros when that step failed. */
+    housekeeping: HousekeepingSummary;
+}
 declare const createRetentionCleanupHandler: (options?: {
     logger?: Logger;
-}) => {
-    scheduled(_event: ScheduledEvent, env: CollectorEnv, _ctx: ExecutionContext): Promise<void>;
-};
+}) => ScheduledTaskHandler<RetentionCleanupSummary>;
 /**
  * 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.
+ * Wire to a per-minute trigger in wrangler.toml: `crons = ["* * * * *"]`,
+ * or call `.run(env)` from a non-Workers host scheduler. 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>;
-};
+}) => ScheduledTaskHandler<AnalysesRunSummary | undefined>;
+/** Shape returned by `runAllDueAnalyses` and surfaced via the run handler. */
+type AnalysesRunSummary = Awaited<ReturnType<typeof runAllDueAnalyses>>;
 
 declare const actionRoutesPlugin: CollectorPlugin;
 
@@ -371,15 +486,20 @@ declare const aiReceiverPlugin: CollectorPlugin;
 
 declare const aiSpanPayloadsProcessorPlugin: CollectorPlugin;
 
+/** Resolve a hostname to its addresses (e.g. `dns.lookup(host, { all: true })`). */
+type HostLookup = (hostname: string) => Promise<string[]>;
+
 declare function evaluateAllRules(env: CollectorEnv, options?: {
     logger?: Logger;
     tracer?: ChildSpanRunner;
     concurrency?: number;
     ruleTimeoutMs?: number;
+    hostLookup?: HostLookup;
 }): Promise<{
     evaluated: number;
     fired: number;
     resolved: number;
+    redelivered: number;
 }>;
 /**
  * Scheduled handler suitable for wrangler cron triggers. Dispatches on the
@@ -429,6 +549,8 @@ declare const analysesRoutesPlugin: CollectorPlugin;
 
 declare const askRoutesPlugin: CollectorPlugin;
 
+declare const autosreRoutesPlugin: CollectorPlugin;
+
 declare const botFilterPlugin: CollectorPlugin;
 
 type CausalConfidence = ActionConfidence;
@@ -666,18 +788,61 @@ declare const usersQueryRoutesPlugin: CollectorPlugin;
 declare const utmEnrichmentPlugin: CollectorPlugin;
 
 /**
- * Creates auth routes and middleware for dashboard password login.
+ * Fixed-window failure limiter for `POST /auth/login`. Only failed attempts
+ * count; a successful login clears the client's bucket. State is in-memory,
+ * so on Cloudflare Workers it is per isolate and on Node per process — it
+ * slows a single-origin brute force without any shared storage, and it can
+ * never lock an operator out for longer than one window.
+ */
+interface LoginRateLimitOptions {
+    /** Failed attempts allowed per window before 429. Default 10. */
+    maxFailures?: number;
+    /** Window length in milliseconds. Default 15 minutes. */
+    windowMs?: number;
+    /** Upper bound on tracked clients; the oldest bucket is evicted past it. */
+    maxClients?: number;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+
+interface DashboardAuthConfig {
+    password?: string;
+    token?: string;
+    /**
+     * Failed-login limiter for POST /auth/login (see login-rate-limit.ts).
+     * Pass `false` to disable; defaults to 10 failures per 15 minutes.
+     * `clientAddress` lets the host supply the connection's peer address;
+     * `trustProxyHeaders` honours forwarding headers from a trusted proxy.
+     * Without either, Workers use the edge-set client IP and every other
+     * runtime has no trustworthy identity: limiting is then skipped (never a
+     * shared bucket, which would let one client lock everyone out) and a
+     * warning is logged once via `warn` (default `console.warn`).
+     */
+    loginRateLimit?: (LoginRateLimitOptions & {
+        clientAddress?: (c: Context<{
+            Bindings: CollectorEnv;
+        }>) => string | undefined;
+        trustProxyHeaders?: boolean;
+        /** Sink for the one-time "limiter inactive" warning. */
+        warn?: (message: string) => void;
+    }) | false;
+}
+/**
+ * Creates auth routes and middleware for dashboard password login and
+ * programmatic read/admin bearer token authentication.
  *
  * Routes added:
  *   POST /auth/login  — accepts { password }, sets session cookie
- *   GET  /auth/check  — returns { authenticated: true/false }
+ *   GET  /auth/check  — returns { authenticated: true/false } (supports cookie and Bearer token)
  *   POST /auth/logout — clears session cookie
  *
- * The returned middleware validates the session cookie on protected routes.
+ * The returned middleware validates either:
+ *   1. Authorization: Bearer <token> (programmatic read/admin token for MCP/API)
+ *   2. obs_session cookie (human dashboard user session)
+ *
+ * Ingest keys are rejected on dashboard/internal routes — they are write-only.
  */
-declare function createDashboardAuth(config: {
-    password: string;
-}): {
+declare function createDashboardAuth(config?: DashboardAuthConfig): {
     middleware: MiddlewareHandler<{
         Bindings: CollectorEnv;
         Variables: {
@@ -718,6 +883,107 @@ declare class TailHub {
     private broadcast;
 }
 
+/**
+ * Retention for the RFC 0010 action graph (`actions` spine plus the
+ * `agent_runs`, `tool_calls`, `retrieval_events`, `eval_results` and
+ * `artifacts` leaves).
+ *
+ * Unlike the telemetry tables these rows carry no `expires_at`; the sweep
+ * derives expiry from `actions.started_at` and the configured
+ * `RETENTION_HOURS`. The unit of deletion is the causal tree
+ * (`project_id`, `root_action_id`): a tree is selected, rechecked and
+ * removed as a whole inside one `SqlDb.batch` (a D1 batch or a Postgres
+ * transaction), never action by action. A tree is kept whole while any of
+ * its actions:
+ *
+ *   - started inside the retention window,
+ *   - is still in progress (`ended_at IS NULL`),
+ *   - belongs to an `agent_runs` row whose `status` is `running`,
+ *   - is referenced by an `eval_cases` row in the same project via
+ *     `source_action_id`, `source_agent_run_id`, or (through a `tool_calls`
+ *     row) `source_tool_call_id`.
+ *
+ * Work is bounded per invocation: each batch packs whole trees up to
+ * `maxActionsPerBatch` actions and `maxTreesPerBatch` trees, and the sweep
+ * stops after `maxBatches`. A tree with more than `maxActionsPerBatch`
+ * actions can never be deleted atomically within those bounds, so it is
+ * retained intact and reported as `oversized_trees` (and logged by the
+ * handler) instead of being deleted in pieces. Raise `maxActionsPerBatch`
+ * to reclaim such trees.
+ *
+ * Concurrency: every DELETE repeats the eligibility predicate, so a tree
+ * that gained a fresh or unfinished action, a `running` run, or an eval
+ * case between selection and deletion is left alone. On D1 the batch is a
+ * single serialized SQLite transaction, so that recheck is airtight. On
+ * Postgres (READ COMMITTED) each statement sees writes committed before it
+ * started, so a commit landing between the leaf deletes and the final spine
+ * delete of the same tree could leave that tree's spine without its leaves.
+ * That needs an ingest for a tree whose newest action is already older than
+ * the retention window, inside a sub-second window; it is documented rather
+ * than locked against because `SqlDb` has no row-locking primitive.
+ *
+ * Intentionally **not** deleted here:
+ *
+ *   - `artifacts.storage_ref` blobs — only the metadata row goes; the blob
+ *     store is not consulted (the collector never wrote those blobs).
+ *   - `agent_runs` rows whose `id` is not an action in the tree — nothing
+ *     proves when they started.
+ *   - `ai_span_payloads.action_id` and `evidence_retrieval_refs` anchors —
+ *     those tables have their own `expires_at` retention.
+ *   - `eval_cases`, `eval_runs`, `eval_case_results` — curated fixtures,
+ *     never retention-bound.
+ */
+
+interface ActionGraphRetentionOptions {
+    /** Retention window; trees whose newest action is older than this expire. */
+    retentionHours: number;
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+    /**
+     * Upper bound on actions deleted per batch/transaction. Also the largest
+     * tree the sweep will delete; bigger trees are retained and reported.
+     * Defaults to 500.
+     */
+    maxActionsPerBatch?: number;
+    /** Upper bound on trees per batch (bounds statements per transaction). Defaults to 25. */
+    maxTreesPerBatch?: number;
+    /** Upper bound on batches per invocation. Defaults to 10. */
+    maxBatches?: number;
+}
+/** Per-table delete counts for one `purgeExpiredActionGraph` call. */
+interface ActionGraphPurgeSummary {
+    actions: number;
+    agent_runs: number;
+    tool_calls: number;
+    retrieval_events: number;
+    eval_results: number;
+    artifacts: number;
+    /** Whole trees deleted. */
+    trees: number;
+    /** Batches (transactions) executed. */
+    batches: number;
+    /** `true` when `maxBatches` was hit while deletable trees remained. */
+    truncated: boolean;
+    /**
+     * Expired, otherwise eligible trees retained because they hold more than
+     * `maxActionsPerBatch` actions. Capped at `OVERSIZED_REPORT_LIMIT`.
+     */
+    oversized_trees: number;
+    /** Identities of the reported oversized trees, for operators. */
+    oversized: Array<{
+        project_id: string;
+        root_action_id: string;
+        actions: number;
+    }>;
+}
+/** Cutoff as the same ISO text shape the collector writes to `started_at`. */
+declare const actionRetentionCutoff: (retentionHours: number, nowMs?: number) => string;
+/**
+ * Purge expired action trees. Safe to call repeatedly: a second call right
+ * after the first finds no deletable trees and changes nothing.
+ */
+declare function purgeExpiredActionGraph(db: SqlDb, options: ActionGraphRetentionOptions): Promise<ActionGraphPurgeSummary>;
+
 type ActionRecord = Omit<ActionRef, "projectId"> & {
     projectId: string;
 };
@@ -756,10 +1022,15 @@ declare class ActionStore {
     listArtifactsByAction(projectId: string, actionId: string, limit?: number): Promise<ArtifactRef[]>;
 }
 
+interface AlertsStoreOptions {
+    /** Permit webhook targets on loopback / private / link-local hosts. */
+    allowPrivateWebhookTargets?: boolean;
+}
 declare function compareValue(value: number, threshold: number, comparison: AlertComparison): boolean;
 declare class AlertsStore {
     private readonly db;
-    constructor(db: SqlDb);
+    private readonly options;
+    constructor(db: SqlDb, options?: AlertsStoreOptions);
     validateInput(input: AlertRuleInput): void;
     listRules(projectId: string): Promise<AlertRule[]>;
     getRule(id: string, projectId: string): Promise<AlertRule | null>;
@@ -767,8 +1038,24 @@ declare class AlertsStore {
     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>;
+    getState(ruleId: string, projectId: string): Promise<AlertStateRow | null>;
+    /**
+     * Record a state transition with its notification still outstanding
+     * (`notified = 0`); `markNotified` flips it once a channel accepts the
+     * alert. On a database that has not applied migration 049 the column is
+     * missing: the transition is still written (legacy statement) so alerting
+     * keeps working through a rolling deploy, and the evaluator treats a row
+     * without the column as delivered.
+     */
     transitionState(ruleId: string, projectId: string, newState: AlertState, now: string): Promise<void>;
+    /**
+     * Mark the transition `(state, lastStateChange)` as delivered. Scoped to
+     * the exact transition the caller notified for: if the rule changed state
+     * again while the webhook was in flight, the newer transition keeps its
+     * own outstanding flag. Returns false when nothing matched (stale or
+     * already marked). On a pre-049 schema there is nothing to mark.
+     */
+    markNotified(ruleId: string, projectId: string, state: AlertState, lastStateChange: string): Promise<boolean>;
     recordEvaluation(ruleId: string, projectId: string, value: number, state: AlertState, notified: boolean): Promise<void>;
     listEvaluations(params: {
         ruleId: string;
@@ -793,6 +1080,289 @@ declare class AlertsStore {
     private evaluateAIRule;
 }
 
+declare function recordChangeEvent(db: SqlDb, projectId: string, input: ChangeEventInput): Promise<ChangeEvent>;
+declare function listChangeEvents(db: SqlDb, options: {
+    projectId: string;
+    environment?: string;
+    serviceName?: string;
+    targetNodeId?: string;
+    kind?: string;
+    since?: string;
+    limit?: number;
+}): Promise<ChangeEvent[]>;
+declare function getChangeEvent(db: SqlDb, projectId: string, changeId: string, environment?: string): Promise<ChangeEvent | null>;
+/**
+ * Indexed cross-trace contention lookup (RFC 0013 § 4.B).
+ * Uses `idx_spans_contention_lookup` (`project_id, environment, target_node_id, start_time, end_time`).
+ * Enforces P1 #5: if the target node is unscoped (`is_scoped_identity = 0`), caps
+ * `relationshipCertainty` at `"inferred"`.
+ */
+declare function findCrossTraceContention(db: SqlDb, options: {
+    projectId: string;
+    environment: string;
+    targetNodeId: string;
+    excludeTraceId: string;
+    startTime: string;
+    endTime: string;
+    limit?: number;
+}): Promise<ContentionCandidate[]>;
+/**
+ * Computes traffic-normalized cohort rate lift, minimum sample gates, shared-degradation
+ * noisy-neighbor contention checks, and code-path overlap for a `change_event`
+ * (RFC 0013 § 4.A, P1 #1, P1 #2).
+ */
+declare function computeChangeBlastRadius(db: SqlDb, projectId: string, changeId: string, options?: {
+    environment?: string;
+    minComparableSample?: number;
+}): Promise<ChangeBlastRadiusResult | null>;
+
+declare function recordInvestigationFinding(db: SqlDb, projectId: string, input: InvestigationFindingInput): Promise<InvestigationFinding>;
+declare function getInvestigationFinding(db: SqlDb, projectId: string, findingId: string, environment?: string): Promise<InvestigationFinding | null>;
+declare function searchInvestigationFindings(db: SqlDb, options: {
+    projectId: string;
+    environment?: string;
+    fingerprint?: string;
+    symptomEntityId?: string;
+    rootCauseEntityId?: string;
+    causalVerificationStatus?: string;
+    incidentId?: string;
+    limit?: number;
+}): Promise<InvestigationFinding[]>;
+declare class CounterfactualVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verifies a PairedCounterfactualProof in SQL against `eval_runs` and `eval_case_results`
+ * (RFC 0013 § 5.A & P1 #3).
+ *
+ * Requires:
+ *  1. `failingRunId` and all `passingRunIds` belong to `projectId` and ran against `evalCaseId`
+ *     with the identical non-null `input_payload_hash`.
+ *  2. `failingRunId` failed (`passed = 0`) and its `failure_fingerprint` matches `finding.fingerprint`.
+ *  3. All `passingRunIds` passed (`passed = 1`) and `passingRunIds.length >= requiredTrials`.
+ *  4. Failing and passing runs have distinct recorded version/commit/prompt lineage.
+ */
+declare function verifyPairedCounterfactualProof(db: SqlDb, projectId: string, findingId: string, input: {
+    environment?: string;
+    evalCaseId: string;
+    failingRunId: string;
+    passingRunIds: string[];
+    requiredTrials?: number;
+}): Promise<InvestigationFinding>;
+
+interface ExtractedSpanLineage {
+    environment: string;
+    namespace: string;
+    serviceName: string | null;
+    serviceVersion: string | null;
+    commitSha: string | null;
+    configDigest: string | null;
+    sourceNode: CanonicalNodeIdentity | null;
+    targetNode: CanonicalNodeIdentity | null;
+    edgePredicate: string | null;
+    errorSignature: string | null;
+}
+/**
+ * Extracts runtime lineage (`environment`, `serviceVersion`, `commitSha`, `configDigest`),
+ * canonical source/target `OntologyNode` identities, and `errorSignature` from a span.
+ */
+declare function extractSpanLineageAndTopology(span: StoredSpan): ExtractedSpanLineage;
+/**
+ * Upserts environment-scoped `ontology_nodes`, `ontology_edges`, and inferred version-transition
+ * `change_events` from ingested spans.
+ */
+declare function upsertOntologyFromSpans(db: SqlDb, spans: StoredSpan[], options?: {
+    bypassCache?: boolean;
+}): Promise<void>;
+/**
+ * Tarjan's O(V + E) Strongly Connected Components (SCC) condensation algorithm
+ * (RFC 0013 § 1.B & P2 #6). Ensures cyclic service/queue topologies never cause
+ * infinite loops during dependency traversal.
+ */
+declare function computeTarjanScc(nodes: OntologyNode[], edges: OntologyEdge[]): {
+    annotatedNodes: OntologyNode[];
+    components: Array<{
+        sccId: string;
+        nodeIds: string[];
+        isCyclic: boolean;
+    }>;
+};
+interface TraceSpanLocusInput {
+    span_id: string;
+    parent_span_id: string | null;
+    service_name: string | null;
+    span_name: string;
+    span_kind: number;
+    status_code: number;
+    status_message: string | null;
+    start_time: string;
+    end_time: string;
+    duration_ms: number;
+    environment?: string | null;
+    target_node_id?: string | null;
+    error_signature?: string | null;
+}
+interface TraceFaultLocusResult {
+    faultLocusSpan: TraceSpanLocusInput | null;
+    faultLocusNodeId: string | null;
+    relationshipCertainty: RelationshipCertainty;
+    causalProofTier: "unverified_locus";
+    causalTriples: CausalTriple[];
+}
+/**
+ * Per-trace cycle-guarded DFS fault locus detector (RFC 0013 § 1.B & P1 #1).
+ * Identifies where an error surfaced (`originated_fault_in_span`) while keeping
+ * `causalProofTier: "unverified_locus"` separate from `relationshipCertainty: "exact"`.
+ */
+declare function localizeTraceFaultLocus(traceId: string, spans: TraceSpanLocusInput[]): TraceFaultLocusResult;
+/**
+ * Queries `telemetry_spans` for a trace and computes its fault locus.
+ */
+declare function loadTraceFaultLocusFromDb(db: SqlDb, projectId: string, traceId: string): Promise<TraceFaultLocusResult>;
+/**
+ * Loads the environment-scoped operational ontology graph with Tarjan SCC
+ * cycle metadata and dependency blackout indicators.
+ */
+declare function getOntologyGraph(db: SqlDb, options: {
+    projectId: string;
+    environment?: string;
+}): Promise<OntologyGraphResponse>;
+
+/**
+ * Opens or deduplicates an active `incident_investigation` (RFC 0013 § 6.A & P2 #7).
+ * Multiple firing alerts or webhook retries for the same `(project_id, environment, target_node_id, symptom_category)`
+ * coalesce into a single active incident.
+ */
+declare function openOrDeduplicateIncident(db: SqlDb, projectId: string, input: {
+    id?: string;
+    environment?: string;
+    targetNodeId: string;
+    symptomCategory?: string;
+    symptomAnchorKind: EvidenceEntityKind;
+    symptomAnchorId: string;
+    symptomFingerprint?: string | null;
+    latestBundle?: Record<string, unknown> | null;
+}): Promise<{
+    incident: IncidentInvestigation;
+    deduplicated: boolean;
+}>;
+declare function getIncidentInvestigation(db: SqlDb, projectId: string, incidentId: string, environment?: string): Promise<IncidentInvestigation | null>;
+declare function listIncidentInvestigations(db: SqlDb, options: {
+    projectId: string;
+    environment?: string;
+    status?: string;
+    limit?: number;
+}): Promise<IncidentInvestigation[]>;
+/**
+ * Exclusive runner lease acquisition / renewal (RFC 0013 § 6.B & P2 #7).
+ * Prevents competing AutoSRE runners from investigating or remediating the same
+ * incident simultaneously.
+ */
+declare function acquireIncidentLease(db: SqlDb, projectId: string, incidentId: string, input: {
+    environment?: string;
+    runnerId: string;
+    leaseDurationSeconds?: number;
+    nowIso?: string;
+}): Promise<{
+    acquired: true;
+    incident: IncidentInvestigation;
+} | {
+    acquired: false;
+    reason: string;
+    conflictOwnerId: string | null;
+    leaseExpiresAt: string | null;
+}>;
+/**
+ * SSRF-safe, HMAC-SHA256 signed AutoSRE incident webhook outbox delivery
+ * (RFC 0013 § 6.A).
+ */
+declare function dispatchIncidentWebhook(db: SqlDb, projectId: string, incidentId: string, webhook: {
+    url: string;
+    secret?: string;
+    allowPrivateNetworks?: boolean;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    delivered: boolean;
+    status?: number;
+    error?: string;
+}>;
+declare class RemediationGateError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Pre-execution remediation proposal gate (RFC 0013 § 6.B & P1 #4).
+ */
+declare function proposeRemediationAction(db: SqlDb, projectId: string, input: RemediationProposalInput): Promise<RemediationProposal>;
+declare function getRemediationProposal(db: SqlDb, projectId: string, proposalId: string, environment?: string): Promise<RemediationProposal | null>;
+declare function listRemediationProposals(db: SqlDb, options: {
+    projectId: string;
+    environment?: string;
+    status?: string;
+    incidentId?: string;
+    findingId?: string;
+    limit?: number;
+}): Promise<RemediationProposal[]>;
+/**
+ * Human dashboard session approval for `pending_human_approval` proposals
+ * (RFC 0013 § 6.B & P1 #4). Mints a single-use `grantToken`.
+ */
+declare function approveRemediationProposal(db: SqlDb, projectId: string, proposalId: string, options: {
+    environment?: string;
+    approvedByUserId: string;
+}): Promise<RemediationProposal>;
+declare function rejectRemediationProposal(db: SqlDb, projectId: string, proposalId: string, options: {
+    environment?: string;
+    rejectedByUserId: string;
+    reason?: string;
+}): Promise<RemediationProposal>;
+/**
+ * Single-use grant redemption with optimistic `expectedCurrentState` verification
+ * against `ontology_nodes` (RFC 0013 § 6.B & P1 #4).
+ */
+declare function claimRemediationGrant(db: SqlDb, projectId: string, proposalId: string, options: {
+    environment?: string;
+    grantToken: string;
+    runnerId?: string;
+    nowIso?: string;
+}): Promise<RemediationProposal>;
+/**
+ * Records remediation completion, updates `ontology_nodes` to desired state,
+ * and arms the +2m/+5m/+15m post-remediation watchdog on the finding.
+ */
+declare function completeRemediationProposal(db: SqlDb, projectId: string, proposalId: string, options: {
+    environment?: string;
+    resultingChangeId?: string | null;
+    remediationAgentRunId?: string | null;
+    baselineRequestRatePerMin?: number | null;
+    nowIso?: string;
+}): Promise<RemediationProposal>;
+declare function failRemediationProposal(db: SqlDb, projectId: string, proposalId: string, options: {
+    environment?: string;
+    failureReason: string;
+    nowIso?: string;
+}): Promise<RemediationProposal>;
+interface WatchdogEvaluationSummary {
+    evaluated: number;
+    recovered: number;
+    inconclusiveLowTraffic: number;
+    stillDegraded: number;
+    timedOutClaims: number;
+    expiredGrants: number;
+}
+/**
+ * Post-Remediation Watchdog & Lease/Claim Timeout Evaluator (RFC 0013 § 5.B, § 6.B & P1 #3).
+ *
+ * Strictly separates:
+ *  - `recovery_status`: whether the service recovered under comparable traffic (`N >= minComparableRequests`)
+ *  - `causal_verification_status`: `"operationally_corroborated"` (never promoted to `"counterfactual_verified"`
+ *    by telemetry recovery alone!).
+ */
+declare function evaluateRemediationWatchdogs(db: SqlDb, options?: {
+    nowIso?: string;
+    minComparableRequests?: number;
+}): Promise<WatchdogEvaluationSummary>;
+
 /**
  * Storage seam for opaque blob payloads — replay rrweb chunks and
  * pprof profiles.
@@ -801,7 +1371,7 @@ declare class AlertsStore {
  *  - `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
+ * Replay chunks live under `replays/<project_id>/<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`).
@@ -976,6 +1546,10 @@ interface EvalRunCandidate {
     modelProvider: string | null;
     model: string | null;
     modelVersion: string | null;
+    environment?: string | null;
+    serviceVersion?: string | null;
+    commitSha?: string | null;
+    configDigest?: string | null;
 }
 interface EvalRunSourceCase {
     id: string;
@@ -997,6 +1571,12 @@ interface EvalRun {
     evalCaseId: string | null;
     status: EvalRunStatus;
     candidate: EvalRunCandidate;
+    environment?: string;
+    serviceVersion?: string | null;
+    commitSha?: string | null;
+    configDigest?: string | null;
+    inputPayloadHash?: string | null;
+    failureFingerprint?: string | null;
     startedAt: string | null;
     endedAt: string | null;
     totalCount: number;
@@ -1014,6 +1594,12 @@ interface EvalRunInput {
     evalCaseId?: string | null;
     status?: EvalRunStatus;
     candidate?: Partial<EvalRunCandidate>;
+    environment?: string | null;
+    serviceVersion?: string | null;
+    commitSha?: string | null;
+    configDigest?: string | null;
+    inputPayloadHash?: string | null;
+    failureFingerprint?: string | null;
     startedAt?: string | null;
     endedAt?: string | null;
     totalCount?: number;
@@ -1152,7 +1738,7 @@ declare class ProjectsStore {
     ensureDefaultProject(): Promise<void>;
     listKeys(projectId: string): Promise<IngestKey[]>;
     createKey(projectId: string, name: string): Promise<IngestKeyWithPlaintext>;
-    revokeKey(keyId: string): Promise<boolean>;
+    revokeKey(keyId: string, projectId: string): Promise<boolean>;
     findByKeyHash(keyHash: string): Promise<{
         projectId: string;
         keyId: string;
@@ -1184,6 +1770,23 @@ declare class PostgresAdapter implements SqlDb {
         };
     }>>;
 }
+/**
+ * Install `pg` result-type parsers so Postgres rows match the shape D1
+ * returns and the shared stores keep working unchanged:
+ *
+ *  - BOOLEAN  → 0 / 1       (D1 stores flags as INTEGER; stores compare `=== 1`)
+ *  - BIGINT   → number      (`COUNT(*)`, `SUM(bigint)` would otherwise be strings;
+ *                            integral values above MAX_SAFE_INTEGER throw)
+ *  - NUMERIC  → number      (`SUM`, `EXTRACT(EPOCH …)`; same overflow rule)
+ *  - JSON/JSONB → raw text  (stores `JSON.parse` the column themselves)
+ *
+ * Call once per process before issuing queries, e.g.
+ * `configurePostgresTypeParsers(pg.types)` in the Node entrypoint.
+ */
+interface PostgresTypeParserRegistry {
+    setTypeParser(oid: number, parser: (value: string) => unknown): void;
+}
+declare const configurePostgresTypeParsers: (types: PostgresTypeParserRegistry) => void;
 
 /** All built-in plugins in recommended registration order */
 declare const allPlugins: CollectorPlugin[];
@@ -1194,4 +1797,4 @@ 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 };
+export { type ActionGraphPurgeSummary, type ActionGraphRetentionOptions, type ActionRecord, ActionStore, type AgentRunRecord, AlertsStore, type AnalysesRunSummary, type ArtifactRecord, type BlobListOptions, type BlobListResult, type BlobObject, type BlobPutOptions, type BlobStore, BlobStoreToR2Adapter, type CollectorAuthConfig, type CollectorConfig, CollectorEnv, type CollectorPlugin, CollectorRouteContext, CollectorRuntime, CounterfactualVerificationError, D1Adapter, type DashboardAuthConfig, 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, type HostLookup, Logger, MetricsStore, PostgresAdapter, type PostgresAdapterOptions, type PostgresTypeParserRegistry, ProjectsStore, R2BlobStore, RemediationGateError, type RetentionCleanupSummary, type RetrievalEventRecord, S3BlobStore, type S3BlobStoreOptions, type ScheduledTaskHandler, type SpanProcessorPlugin, type SqlDb, type SqlDbFactory, type SqlStatement, type TailEvent, TailHub, type TailKind, type ToolCallRecord, type UsageEventProcessorPlugin, type WatchdogEvaluationSummary, acquireIncidentLease, actionRetentionCutoff, actionRoutesPlugin, aiReceiverPlugin, aiSpanPayloadsProcessorPlugin, alertsRoutesPlugin, allPlugins, analysesRoutesPlugin, approveRemediationProposal, askRoutesPlugin, autosreRoutesPlugin, botFilterPlugin, claimRemediationGrant, compareValue, completeRemediationProposal, computeChangeBlastRadius, computeTarjanScc, configurePostgresTypeParsers, connectedRoutesPlugin, createAlertEvaluatorHandler, createAnalysesRunHandler, createDashboardAuth, createDefaultCollectorApp, createRetentionCleanupHandler, createTelemetryCollectorApp, dashboardRoutesPlugin, _default as default, defaultSpanEnrichmentPlugin, dispatchIncidentWebhook, evalCasesRoutesPlugin, evaluateAllRules, evaluateRemediationWatchdogs, evidenceRetrievalRoutesPlugin, extractSpanLineageAndTopology, failRemediationProposal, findCrossTraceContention, genAiNormalizerPlugin, getChangeEvent, getIncidentInvestigation, getInvestigationFinding, getOntologyGraph, getRemediationProposal, identityReceiverPlugin, isEvalCaseSourceType, isEvalRunStatus, issueEnrichmentPlugin, issueInsightsPlugin, listChangeEvents, listIncidentInvestigations, listRemediationProposals, loadTraceFaultLocusFromDb, localizeTraceFaultLocus, logsReceiverPlugin, metricsReceiverPlugin, onboardingRoutesPlugin, openOrDeduplicateIncident, otlpReceiverPlugin, platformRoutesPlugin, profileRoutesPlugin, projectsRoutesPlugin, proposeRemediationAction, purgeExpiredActionGraph, queryRoutesPlugin, recordChangeEvent, recordInvestigationFinding, redactionProcessorPlugin, rejectRemediationProposal, replayQueryRoutesPlugin, replayReceiverPlugin, searchInvestigationFindings, tailRoutesPlugin, timelineRoutesPlugin, uaEnrichmentPlugin, upsertOntologyFromSpans, usageNormalizationPlugin, usagePrivacyPlugin, usageQueryRoutesPlugin, usageReceiverPlugin, usersQueryRoutesPlugin, utmEnrichmentPlugin, verifyPairedCounterfactualProof };