notarius/docs/integrations/evidence-context.md

Published Evidence Context

This contract defines the optional source/evidence-context artifact emitted by the production JSON output. It is a selected source-unit excerpt for convenient reading alongside normalized lane artifacts; it is not a second citation or provenance model. Its configuration is owned by Configuration, and 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 top-level JSON array of generic source units. There is no wrapper, source-level metadata, context grouping, lane identifier, or evidence reference in the payload. An enabled configuration with no contributing accepted evidence publishes [].

[
  {
    "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 source unit has required id, kind, text, and self ref fields. ref contains source_id, start_unit_id, and end_unit_id, and both unit endpoints identify that unit's id. A unit may also contain source-owned metadata, an open-ended JSON object. Fixed unit and reference fields are strict: consumers must reject unknown fixed fields, malformed units, invalid self-references, units whose source_id differs from other units in the same excerpt, and a payload that is not the array described here.

The excerpt preserves each selected unit exactly as represented by the validated generic source document. It does not add evidence-context-specific annotations or reshape source-owned metadata.

Selection And Citations

The framework obtains direct source references only through typed evidence projections of accepted normalized artifacts in the configured lane allowlist. It validates each reference against the current source document, expands its range by window_units source-unit positions on each side, clamps at document boundaries, and takes the union of all expanded ranges. The output contains each selected source unit once in source-document position order, regardless of numeric unit IDs. Repeated references, overlapping windows, and citations from multiple lanes do not duplicate a unit. Rejected, failed, absent, inactive, and unselected lanes contribute nothing.

Normalized lane artifacts remain authoritative for citations and for which lane cited a range. The excerpt has no lane attribution and must not be used to reconstruct it. Its included nearby units provide reading context only; they do not widen any citation in a lane artifact.

The excerpt contains at most every generic source unit once. It can therefore equal the complete generic source document when coverage is broad or the window is large. No byte-, token-, or compression-size guarantee is made, and the framework does not truncate the excerpt to meet an arbitrary size limit.

Consumer Responsibilities And Data Handling

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 an absent descriptor. Consumers that do use it should validate the descriptor and payload before use, retain the artifact with its schema identity when needed for a run record, and read citations from the corresponding normalized lane artifacts.

The excerpt contains source-unit text and source-owned metadata and is durable output. Treat it as sensitive source content, apply appropriate access controls and retention, and do not assume its selected form is materially smaller or less sensitive than the original input.