117 lines
4.2 KiB
Markdown
117 lines
4.2 KiB
Markdown
# Published Evidence Context
|
|
|
|
This contract defines the optional `source/evidence-context` artifact emitted
|
|
by the production JSON output. Its configuration is owned by
|
|
[Configuration](../config.md#module-bindings-and-validators); its logical-file
|
|
discovery is owned by [Published JSON Output](json-output.md).
|
|
|
|
## 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: []`.
|
|
|
|
```json
|
|
{
|
|
"source_id": "session-alpha",
|
|
"source_digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
|
"window_units": 1,
|
|
"selected_lanes": ["npc_registry", "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.
|