#ADR 0002: Optional Rebuildable Vector Search

• Status: accepted for an opt-in reference implementation; production semantic provider and live SLO approval remain pending
• Date: 2026-08-20

#Context

k0smos already has canonical SQL/domain repositories, lexical SQL search, and optional modern text-search providers. Vector retrieval can improve discovery, but it must not become a second source of truth, weaken tenant isolation, index sensitive content by default, or silently turn a chat profile into an embedding model.

#Decision

SQL and module repositories remain canonical. A vector index is a disposable, versioned projection that can be disabled or rebuilt without affecting page rendering, writes, or lexical search.

Provider-neutral contracts under Domain/Search/Vector carry tenant, module, entity type/id, locale, source version, SHA-256 checksum, embedding provider, model/version/dimension, scalar metadata, privacy class, and deletion state. The application boundary owns an explicit source allowlist and permits only public content by default.

Qdrant is the first reference store. The adapter:

• creates a cosine collection only for an explicitly enabled configuration;
• creates payload indexes for tenant, module, entity type, locale, embedding identity, and deletion state;
• injects tenant, embedding-identity, and deleted=false predicates itself;
• never accepts a tenant filter from caller metadata and rejects a foreign tenant returned by the provider;
• uses stable UUID point identities and upserts deletion tombstones;
• exposes health without making an unavailable provider fatal to canonical search.

The only bundled embedding implementation is the explicit feature_hash lexical-vector reference. It is deterministic and useful for offline adapter/relevance tests, but is not described as a semantic model. Chat profiles are never selected. A future embedding model must implement the embedding contract and declare its own provider/model/version/dimension.

Documentation is the first allowlisted source because it is reviewed, public, versioned, and contains no tenant records. Active modules contribute sources through VectorProjectionProviderModuleInterface; inactive modules contribute nothing. search:vector:rebuild performs bounded bulk projection. Typed queue messages contain identity/checksum only, re-read canonical content at handling time, ignore superseded revisions, and create tenant-scoped tombstones.

Documentation search negotiates vector availability at runtime, merges vector and lexical hits, and falls back to its existing lexical implementation on any missing/unhealthy provider or projection error.

#Consequences

#Source-policy extension — 2026-09-13

The Discovery navigator is an accepted bounded consumer of public product, editorial and Page projections plus selectively approved document evidence. Its implementation does not activate these sources in an existing index. The five-query Documentation proof satisfies the contract gate only; the expanded 50-query relevance, canonical-publication and tenant/privacy gates in doc/public/en/architecture/vector-search.md govern product activation. Private documents, admin chat and raw connector payloads remain excluded.

#Operational consequences

• The application behaves normally with no Qdrant service.
• A shared collection remains tenant-safe through adapter-owned payload predicates; a dedicated collection remains a future operational option.
• The reference proves contracts, request shapes, isolation, rebuild, and fallback. It does not approve a production semantic model or Qdrant SLO.
• Production activation is gated on the live evaluation in doc/public/en/architecture/vector-search.md.
• pgvector is not enabled by this decision. It may be evaluated only on explicit PostgreSQL tenants with the extension provisioned and the same contracts.