Documentation
¶
Overview ¶
Package conformance provides the shared VectorIndex conformance suite (REQ-VEC-002, ADR-05, W8.4).
Every domain.VectorIndex adapter (sqlite_blob, qdrant, pgvector) MUST pass this suite against IDENTICAL fixtures. The suite verifies:
- Capabilities declares the full mandated field set.
- Upsert + Search round-trip returns the eligible candidate set.
- Dimension-mismatch vectors are REJECTED fail-closed (REQ-VEC-001 corruption pin).
- Delete removes vectors from subsequent search results (idempotent).
- Batch chunking respects declared MaxBatchSize when BatchUpsert is true.
- Health is reported explicitly (healthy/degraded/unhealthy).
- Score threshold filters candidates client-side.
The suite is PARAMETERIZED: a Factory closure constructs a fresh, isolated VectorIndex for each test case. Each adapter's integration test file calls RunSuite with a factory that builds a real adapter (Docker-backed for external providers, or in-memory for sqlite_blob under cortex_vectors).
The suite uses 64-dimensional fixtures (DefaultFixtures), the minimum dimension accepted by sqlite_blob's enabled store (MinEmbeddingDimension). External adapters (qdrant, pgvector) accept arbitrary dimensions, so all three adapters share the SAME fixtures — the parity assertion is real.
LOCAL-TRACK BOUNDARY: this package imports ONLY internal/domain. It never imports any concrete adapter, so it compiles in the zero-CGO local build. Adapters import THIS package (not the other way around), preserving the dependency direction mandated by REQ-FOUND-001.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunSuite ¶
RunSuite executes the full shared conformance suite against the adapter produced by factory. Each sub-test constructs a FRESH adapter via factory so tests are isolated and order-independent.
Call this from each adapter's integration test file:
func TestIntegration_Conformance(t *testing.T) {
conformance.RunSuite(t, func(t *testing.T, dim int, m domain.ModelInfo) (domain.VectorIndex, error) {
return qdrant.New(ctx, qdrant.AdapterConfig{Dimension: dim, ...})
})
}
Types ¶
type Factory ¶
Factory constructs a fresh, isolated domain.VectorIndex for one test case. The returned adapter MUST be empty (no prior fixtures). The caller is responsible for Close; the suite registers t.Cleanup to invoke it.
dim and model are the dimension/model the adapter is constructed with (used for namespace enforcement and collection creation). They match Fixtures.
type Fixtures ¶
type Fixtures struct {
// Dimension is the vector dimension every fixture point carries. All
// adapters are constructed with this same dimension.
Dimension int
// Model is the ModelInfo stamped on every fixture point (namespace
// enforcement).
Model domain.ModelInfo
// Points is the set of vectors to Upsert before each search test.
Points []domain.VectorPoint
}
Fixtures is the identical dataset every adapter is tested against. The candidate set produced by SearchForID must be deterministic given these fixtures, modulo declared capability differences (filter strategy, score rounding). Using a shared fixture set is what makes the suite a PARITY assertion, not just a smoke test (REQ-VEC-002 happy path).
func DefaultFixtures ¶
func DefaultFixtures() Fixtures
DefaultFixtures returns a deterministic 64-dimensional fixture set suitable for ALL adapters including sqlite_blob. 64 is the MinEmbeddingDimension accepted by the enabled sqlite_blob store (internal/store/sqlite); external adapters (qdrant, pgvector) accept arbitrary dimensions. Using the SAME dimension across all adapters is what makes the parity assertion real.
The cosine similarity structure is identical to a 4-dim set (points differ only in the first few axes; the rest are zero), so the rankings are non-degenerate and deterministic across all adapters.
Source Files