# Evidence reference (/docs/evidence-reference) When AI agents query the telemetry graph or when human SREs view automated alerts and analyses, obs-unified provides structured, machine-readable evidence packages. These packages let agents traverse the causal graph programmatically without parsing narrative prose. The canonical schema is written in TypeScript and matches the published JSON Schema version `obs-unified.evidence-reference.v1`. ## EvidenceReference schema [#evidencereference-schema] The `EvidenceReference` is a Zod schema defined in [`packages/obs-types/src/types/evidence.ts`](https://github.com/dev-sawan-ruparel/obs-unified/blob/main/packages/obs-types/src/types/evidence.ts). ### Fields [#fields] * **`evidenceId`** (string): A unique identifier for this specific evidence entry. * **`entityKind`** (EvidenceEntityKind): The type of entity being referenced. Must be one of: * `"analysis"` (automated analysis results/notebooks) * `"alert"` (firing system/business alert rules) * `"agent_run"` (causal workflow run of an AI agent) * `"action"` (specific step or LLM execution in the Agent Action Graph) * `"trace"` (OpenTelemetry distributed trace) * `"span"` (individual OpenTelemetry span) * `"tool_call"` (MCP or GenAI tool execution record) * `"ai_call"` (individual LLM/GenAI call record) * `"eval"` (automated model evaluation run or case) * `"profile"` (pprof CPU or off-CPU profile blob) * `"replay"` (rrweb session replay stream) * `"service"` (logical service/system node) * `"log"` (individual log line record) * `"docs"` (documentation page or reference file) * `"change"` (deployment, rollback, feature-flag flip, config change, or prompt release in `change_events`) * `"finding"` (persisted `InvestigationFinding` in incident memory) * `"incident"` (durable `IncidentInvestigation` coordination record) * **`entityId`** (string): The stable database key or identifier of the referenced entity. * **`route`** (string): The dashboard deep-link path for the entity (e.g. `"/dashboard/traces/trace-123"`). * **`source`** (string): Description of the engine or rule that generated this evidence (e.g. `"collector.analyses.self_time"`). * **`confidence`** (number): A float strictly bounded between `0.0` (no confidence) and `1.0` (absolute certainty/explicit propagation). * **`relationshipCertainty`** (optional, `"exact" | "inferred" | "heuristic"`): How the graph link was constructed (`"exact"` for shared trace/span IDs or exact file-path match; `"inferred"` for statistical cohort isolation; `"heuristic"` for temporal window proximity). * **`causalProofTier`** (optional, `"counterfactual_verified" | "cohort_rate_isolated" | "corroborated_candidate" | "unverified_locus"`): How strongly causality has been proven for root-cause attribution and remediation gating (see [AutoSRE causal ontology](/docs/autosre)). * **`predicate`** (optional, `"triggered_by_interaction" | "caused_by_action" | "executed_in_agent_run" | "mutated_external_state" | "originated_fault_in_span" | "failed_due_to_child_span" | "contended_on_shared_resource" | "induced_shared_resource_contention" | "blackout_on_dependency" | "sampled_hot_frame" | "uninstrumented_self_time_gap" | "exemplifies_metric_spike" | "degraded_after_change" | "isolated_to_version_cohort" | "touched_same_code_path" | "mitigated_by_change" | "violated_eval" | "verified_by_counterfactual" | "remediated_by_agent_run" | "matches_prior_finding"`): Typed causal relation between the anchor entity and this evidence node (represented as `evidencePredicate` on `ConnectedLink` items, while `EvidenceBundle` and `ConnectedLink` also carry the canonical `environment` scope). * **`reason`** (string): Human-readable summary explaining why this evidence is relevant. * **`citations`** (array of citations): Supporting files, traces, or documentation that support this evidence. * **`suggestedNextPivots`** (array of pivots): Recommended exploration routes to help investigate from this anchor. ### Citations structure [#citations-structure] Each item in the `citations` array contains: * `label` (string): Text describing the cited reference. * `entityKind` (EvidenceEntityKind): Kind of cited entity. * `entityId` (string): Stable identifier. * `route` (string, nullable/optional): Deep-link route. ### Suggested next pivots structure [#suggested-next-pivots-structure] Each item in the `suggestedNextPivots` array contains: * `label` (string): Text describing the suggested action (e.g., `"Inspect CPU profile for checkout-service"`). * `entityKind` (EvidenceEntityKind): Kind of target entity. * `entityId` (string): Stable identifier. * `route` (string): Deep-link target route. * `reason` (string, optional): Context explaining why this pivot is suggested. *** ## JSON schema definition [#json-schema-definition] The JSON Schema definition is exported by `@obsunified/types` (`EvidenceReferenceJsonSchema`). Its `$id` is a stable identifier, not a hosted download URL: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://obs-unified.dev/schemas/obs-unified.evidence-reference.v1.json", "title": "EvidenceReference", "type": "object", "additionalProperties": false, "required": [ "evidenceId", "entityKind", "entityId", "route", "source", "confidence", "reason", "citations", "suggestedNextPivots" ], "properties": { "evidenceId": { "type": "string" }, "entityKind": { "type": "string", "enum": [ "analysis", "alert", "agent_run", "action", "trace", "span", "tool_call", "ai_call", "eval", "profile", "replay", "service", "log", "docs", "change", "finding", "incident" ] }, "entityId": { "type": "string" }, "route": { "type": "string" }, "source": { "type": "string" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "relationshipCertainty": { "type": "string", "enum": ["exact", "inferred", "heuristic"] }, "causalProofTier": { "type": "string", "enum": [ "counterfactual_verified", "cohort_rate_isolated", "corroborated_candidate", "unverified_locus" ] }, "predicate": { "type": "string", "enum": [ "triggered_by_interaction", "caused_by_action", "executed_in_agent_run", "mutated_external_state", "originated_fault_in_span", "failed_due_to_child_span", "contended_on_shared_resource", "induced_shared_resource_contention", "blackout_on_dependency", "sampled_hot_frame", "uninstrumented_self_time_gap", "exemplifies_metric_spike", "degraded_after_change", "isolated_to_version_cohort", "touched_same_code_path", "mitigated_by_change", "violated_eval", "verified_by_counterfactual", "remediated_by_agent_run", "matches_prior_finding" ] }, "reason": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["label", "entityKind", "entityId"], "properties": { "label": { "type": "string" }, "entityKind": { "type": "string", "enum": [ "analysis", "alert", "agent_run", "action", "trace", "span", "tool_call", "ai_call", "eval", "profile", "replay", "service", "log", "docs", "change", "finding", "incident" ] }, "entityId": { "type": "string" }, "route": { "type": ["string", "null"] } } } }, "suggestedNextPivots": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["label", "entityKind", "entityId", "route"], "properties": { "label": { "type": "string" }, "entityKind": { "type": "string", "enum": [ "analysis", "alert", "agent_run", "action", "trace", "span", "tool_call", "ai_call", "eval", "profile", "replay", "service", "log", "docs", "change", "finding", "incident" ] }, "entityId": { "type": "string" }, "route": { "type": "string" }, "reason": { "type": "string" } } } } } } ```