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

The EvidenceReference is a Zod schema defined in packages/obs-types/src/types/evidence.ts.

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).
• 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

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

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

The JSON Schema definition is exported by @obsunified/types (EvidenceReferenceJsonSchema). Its $id is a stable identifier, not a hosted download URL:

{
  "$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" }
        }
      }
    }
  }
}