Invariants
Rules that cannot be broken by any PR, feature request, or version release. Relaxing an invariant is a breaking change — major version bump required.I1 — Chunk Provenance Is Mandatory
AChunk that does not know its parent Document, its position within that document,
and its embedding model ID does not exist in rag-axis.
I2 — No Silent Truncation
If context is dropped due to budget constraints, aContextTruncationEvent is emitted with
the reason, tokens dropped, and stage responsible. Silent truncation is a contract violation.
I3 — Every RetrievalResult Has a Confidence Signal
Acceptable values: a calibrated score, or the literal typeConfidenceUnknown.
Returning results without confidence metadata is a contract violation.
I4 — Adapters Must Type Their Errors
No adapter may suppress a provider error into a genericException.
Every error must be typed: RateLimitError, ContextLengthError, ProviderSchemaError, TransportError.
I5 — Core Has Zero Provider Dependencies
rag_axis.core must have zero mandatory runtime dependencies on any specific LLM provider,
vector database, or evaluation framework.
All integration is through the adapter Protocol boundary.
I6 — Dependency Direction Is One-Way
rag_axis.bench may depend on rag_axis.core.
rag_axis.core must never depend on rag_axis.bench.
Circular imports are an invariant violation. No exceptions.