108 lines
4.5 KiB
Markdown
108 lines
4.5 KiB
Markdown
# 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](../config.md#module-bindings-and-validators), and 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 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 `[]`.
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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.
|