notarius/docs/integrations/evidence-context.md

Published Evidence Context

This contract defines the optional source/evidence-context artifact emitted by the production JSON output. Its configuration is owned by Configuration; its logical-file discovery is owned by Published JSON Output.

Identity And Discovery

When enabled, the JSON bundle contains evidence-context.json and an index.json evidence_context descriptor with the same six fields as other pipeline-wide artifact descriptors.

Property	Value
Artifact kind	source/evidence-context
Media type	application/json
Schema ID	notarius.source.evidence_context
Schema name	notarius_source_evidence_context_v1
Schema version	v1
Logical file	evidence-context.json

Consumers must discover the file from the descriptor, verify all six descriptor fields, and decode only a supported schema version. The descriptor is optional: its absence means evidence publication was not enabled for that bundle.

Payload

The v1 payload is a JSON object with required source_id, source_digest, window_units, selected_lanes, and contexts fields. selected_lanes and contexts are always arrays; an enabled configuration with no accepted direct evidence publishes contexts: [].

{
  "source_id": "session-alpha",
  "source_digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "window_units": 1,
  "selected_lanes": ["npcs", "spells"],
  "contexts": [
    {
      "context_ref": {
        "source_id": "session-alpha",
        "start_unit_id": 10,
        "end_unit_id": 20
      },
      "evidence_refs": [
        {
          "lane_id": "spells",
          "source_ref": {
            "source_id": "session-alpha",
            "start_unit_id": 10,
            "end_unit_id": 10
          }
        }
      ],
      "units": [
        {
          "id": 10,
          "kind": "transcript_segment",
          "text": "Aria casts Cure Wounds.",
          "ref": {
            "source_id": "session-alpha",
            "start_unit_id": 10,
            "end_unit_id": 10
          }
        },
        {
          "id": 20,
          "kind": "transcript_segment",
          "text": "The party regroups.",
          "ref": {
            "source_id": "session-alpha",
            "start_unit_id": 20,
            "end_unit_id": 20
          }
        }
      ]
    }
  ]
}

Each context requires a context_ref object and evidence_refs and units arrays. context_ref identifies the first and last included unit. Each evidence entry contains a selected lane_id and an original source_ref. A unit uses the existing source-unit shape: required id, kind, text, and self ref, plus optional JSON-object metadata. Fixed payload objects reject unknown fields; unit metadata may contain application-defined JSON values.

Citations And Context

evidence_refs are the authoritative citations. They identify the direct references emitted by accepted normalized artifacts. context_ref and the units collection include those cited units plus nearby source units selected by the configured window. They are explanatory context, not widened citations.

Only accepted outputs from the configured lane allowlist contribute. Rejected, failed, absent, and lane-filtered outputs do not contribute. The artifact never contains raw input bytes, prompts, model responses, auxiliary reference content, credentials, or filesystem paths.

Ordering And Compatibility

The selected lane allowlist is lexical. Contexts and units are in source document position order, not numeric unit-ID order. Direct evidence entries are deterministically ordered by lane and source reference. Overlapping or contiguous windows merge, and each source unit appears at most once in the resulting contexts.

The artifact is additive to the JSON bundle and is not a lane payload, normalized-output count, checkpoint, or generated reference. Consumers that do not need it must tolerate the absent optional descriptor. Consumers that do use it should preserve the artifact and its schema identity with the run provenance, and should treat its source text and metadata as sensitive durable content.