Retrieval Classes

Release binding: v0.1.0-enterprise-ready · AMI ami-010806d4d3445660e · 2026-05-19

This page is the operator's view of the retrieval surface: the six retrieval classes served by the governor and the EXACT path, the per-class contracts, the metrics that expose runtime state, and the alerts and runbook entries that turn each alert into a fix.

Class table

Five classes are governor-derived from per-query gate measurements; the sixth, EXACT, is a caller-requested contract and is never inferred.

Class	Governor posture	Compression	Rerank	R@100% contract	p95 alert threshold
A_ELITE	Rank versus recovery	Aggressive	On	No (recall floor enforced)	50 ms
A_ELITE_FAST	Rank versus recovery	Aggressive	Off	No (recall floor enforced)	Below A_ELITE; promoted once the floor is cleared with margin
B_TWO_TIER	Rank versus recovery	Moderate	On	No (recall floor enforced)	50 ms
D_SENSITIVE	Cautious	Conservative	On	No	100 ms
E_DEGENERATE	Rank versus recall	None	Off	No	Rank-bound, budget-driven
EXACT	Brute force	None	Not applicable	Yes	Bounded by corpus size and VRAM

The latency values in this table are operational alert thresholds, not performance claims; measured performance lives on the Performance Evidence page.

Invariants, enforced by release-gating tests:

• Every class has an entry in every dispatch table.
• EXACT is never returned by classification; it must be opted into through the API.
• Promotion to A_ELITE_FAST is monotone: once the floor is cleared with the configured margin, the governor does not demote back to A_ELITE except through a full recertification.

How the governor picks a class

The governor measures two quantities per workload: the rerank utility (how much the rerank stage recovers) and the damage propagation ratio (how much compression damage survives rerank).

• Low rerank utility with high damage propagation classifies as E_DEGENERATE; with low propagation, D_SENSITIVE.
• High rerank utility with very low propagation and small compression damage classifies as A_ELITE, promoted to A_ELITE_FAST once the floor is cleared with margin; larger damage classifies as B_TWO_TIER.
• Moderate propagation classifies as B_TWO_TIER; high propagation as D_SENSITIVE.

A stricter variant of the classifier runs when only compressed-path measurements are available; it never promotes past A_ELITE_FAST without the full gate values.

The EXACT path and PQC attestation

EXACT is the R@100% contract surfaced through POST /v1/query/exact:

• Brute-force top-K against the raw, uncompressed corpus.
• ML-DSA-65 (FIPS 204) signed receipt of the exact result set.
• Self-verified before the response is returned.
• Independently verifiable through POST /v1/attestation/verify.

Operational requirements:

1. A raw corpus must be registered per namespace (see the corpus registry). A missing corpus returns 409.
2. The signing keys must be present in the appliance signing directory. Missing keys or a missing PQC backend returns 503.
3. Key rotation is manual: rotate the signing and verifying keys together and re-run the exact-path stress check to reset the latency budget.

The receipt is canonical JSON carrying the schema identifier, retrieval class, NIST standard, UTC timestamp, score digests, and extras. The shipped clients carry byte-for-byte parity with the receipt schema.

Metrics

Scraped at /metrics:

Metric	Type	Labels	Meaning
holonomix_query_total	counter	namespace,retrieval_class,metric_type	Every served query
holonomix_query_duration_seconds	histogram	namespace,retrieval_class,metric_type	End-to-end latency
holonomix_query_class_transitions_total	counter	namespace,from_class,to_class	Governor transitions
holonomix_receipt_verifications_total	counter	result	ML-DSA-65 verify outcomes
holonomix_vram_budget_exceeded_total	counter	tag	Preflight allocation rejections
holonomix_sign_duration_seconds	histogram	none	Signing latency
holonomix_verify_duration_seconds	histogram	result	Verify latency
holonomix_put_duration_seconds	histogram	namespace	Ingest latency
holonomix_passthrough_on_error_total	counter	namespace	Fail-closed bypass fires
holonomix_auth_failures_total	counter	reason	Auth middleware rejections

Alerts and runbook

All thresholds below are operational alert settings.

Recall floor breach. Trigger: p95 latency of A_ELITE, A_ELITE_FAST, or B_TWO_TIER exceeds 50 ms for 10 minutes. Likely cause: the governor demoted off A_ELITE_FAST, or hot-path rerank is enabled when it should not be. Runbook: check holonomix_query_class_transitions_total; a sustained A_ELITE_FAST outflow means recertify the namespace, otherwise inspect the rerank multiplier and rerank latency.

EXACT path slow. Trigger: EXACT p95 above 2 s for 10 minutes. Likely cause: the raw corpus does not fit the configured chunk size, or the reduction kernel is saturating. Runbook: lower chunk_rows, or shard the raw corpus across namespaces and re-register each shard's corpus.

Receipt verify failures. Trigger: any non-zero rate of rejected verifications for 2 minutes. Severity: critical; this is an integrity event. Runbook: freeze the signing key, snapshot the offending receipts, and check for key rotation skew, clock drift, or tamper on the wire. No receipt should ever verify-reject under normal operation.

Degenerate class sustained. Trigger: sustained E_DEGENERATE classifications above 1 query per second for 15 minutes. Likely cause: corpus drift; rerank is no longer a rescue stage. Runbook: trigger a recertification run; until it lands, E-class callers are latency rank-bound.

VRAM budget exceeded. Trigger: a sustained non-zero holonomix_vram_budget_exceeded_total rate. Likely cause: the host is under-provisioned for the current workload, or the VRAM safety margin is set too aggressively. Runbook: adjust the VRAM safety margin, lower chunk_rows, or move the hot path to a larger host.

Console

The Model Certification, Telemetry, and Receipt Inspector screens surface class membership, per-class telemetry, and receipt verification in the appliance UI. See Console.