Retrieval evidence and reproducible citations

Relata DB 3.0
This page describes Relata DB 3.0, the current release. Paths use the new /v1 prefix; see the route restructure.

Retrieval evidence (relata.evidence/v1) records what a retrieval was based on, so a later reader can check an answer against the exact source versions it cited, even after the sources changed. Nothing changes for callers who do not ask for it.

Recording

Send X-Relata-Record-Evidence: true on POST /v1/query, POST /v1/search or POST /v1/graphql. For MCP tools/call, send the header or set "_relata_record_evidence": true in the request body. The normal response is returned unchanged plus an evidence summary (id, citations, uncited, complete, expires_at_ns); GraphQL carries it under extensions.evidence.

X-Relata-Evidence-Retention-Days (1 to 365, default 30) sets retention. A malformed header is a 400 evidence-request-invalid.

GET /v1/evidence lists your unexpired records and GET /v1/evidence/{id} returns one.

What a record holds

  • retrieval: the door, the query text, and the parameters with credential-like keys (authorization, token, secret, password, api_key) removed.
  • configuration: the versions in force when the retrieval ran. The embedding and reranker model tags and versions, the vector model tags of the cited rows, the producer and producer version of cited media child rows (the OpenETL run that made them), and a SHA-256 fingerprint of every retrieval-affecting setting. Endpoint URLs and API keys are never recorded. A stored record keeps the versions it was made with. ranking_reproducible is false: ranking is not recomputed.
  • citations, in rank order: the type and id, the cited version (valid_from, system_from), content_sha256, an optional score, a chunk id where the result is a chunk, an ontology definition stamp where the type has a published definition, and a locator. The locator carries the row's own location columns (page, character offsets, start and end times where the type has them) and text ranges from search highlights as UTF-8 byte offsets found in the cited version's own field value.
  • completeness: complete is false, with reasons, whenever a returned row could not be cited (no resolvable type and id, or not readable by the caller).

The hash is over the caller-visible content of the version (masking applied, system-managed fields such as embeddings excluded), so a background embedding write-back does not change it. A record stores hashes and identifiers only, never copies of source content, so erasing a source also removes what the evidence could reveal about it.

Media offsets are OpenETL's
Relata extracts nothing from media. Audio and video offsets are exactly the values on the media-segment rows that OpenETL delivered. A citation proves which stored row answered, not the extractor's timing quality.

Replay

POST /v1/evidence/{id}/replay (optionally {"include_content": true}) re-reads every cited version under the caller's current authorization:

OutcomeMeaning
verifiedthe cited version exists, is readable and its hash matches; superseded says whether a newer version exists
hash_mismatchreadable, but the content differs (for example the masking policy changed); no content is returned
missingthe version is no longer retained (history compacted or erased)
deniedthe caller can no longer read the source; nothing is returned
deletedthe source was deleted; it is never resurrected

Replay is mode: recorded_context. It verifies the recorded citations and does not re-run the query or recompute ranking. Approximate nearest-neighbour search, rerankers and model calls are not deterministic, so only the cited source versions are re-verified.

Operations

  • Profile: single machine. Records are ordinary governed records of the reserved EvidenceRecord type in the caller's tenant, written to the WAL, replayed on restart and included in backups.
  • Retention: chosen per request. A record past expires_at_ns answers 410 and is not listed; its rows are not yet physically purged.
  • Size: a record cites at most 500 results; more mark it complete: false.
  • Who can read a record: private to the principal (token) that recorded it, within its tenant. A different token of the same tenant, or another tenant, gets a 404 (never a 403). After a restart read it with the same token.
  • Backup and restore: records survive. A restored deployment re-evaluates current authorization on replay.

Evidence status

No performance or throughput guarantee is made for evidence recording. One Linux run of the repository's live script (release binary, arm64 container, six synthetic rows, default CPU embedder) passed its checks: recording on query and search, no evidence without the header, retention validation, replay verified, superseded and deleted outcomes, 404 for another tenant or principal, and survival of a clean restart. Not covered: backup and restore of records, the GraphQL and MCP doors, media offsets, and cluster.

Limits

  • Row identifiers are process-local, so a version is identified by type, id, its two timestamps and the content hash.
  • Page and media offsets are cited only where the row has locator columns. Text ranges are matched by term, ASCII case-insensitively; a stemmed or fuzzy match whose surface form is absent gets no range.