references/implementation-contracts.md

# Implementation contracts
## Interfaces
`Document { source_id, version, canonical_uri, acl_scope, content, sections, updated_at }`
`Chunk { chunk_id, source_id, version, span, content, metadata, acl_scope }`
`QueryContext { request_id, user_id?, tenant_scope, query, filters, index_version }`
`RetrievedEvidence { source_id, chunk_id, version, content, score?, rank?, span?, acl_scope }`
`GroundedAnswer { answer, claims, citations[], abstained, trace_id }`
Use these as logical contracts, not forced language-specific SDK classes.

## Implementation boundaries
- Parsing and indexing deterministic and idempotent where possible.
- Trusted identity/ACL filters enforced before evidence is exposed.
- Ranking and context assembly keep stable source IDs; trace without leaking source contents.
- Generated text cannot trigger privileged tools solely because a retrieved document requests it.
- Retry transient network errors with limits, backoff and idempotency; never retry destructive writes blindly.
- Log and test source deletion, version updates, missing evidence, prompt injection and insufficient permissions.

## Acceptance
Tests show known-answer retrieval, no-answer abstention, cross-tenant isolation, citation support and failure recovery; record only actual executions.