DIP/docs/embedding/NV3_3_OPTION_A_HARDENING_NOTES.md

Option A semantic search hardening

This patch hardens the multi-model semantic search implementation in three places:

1. Semantic repository

• requires a positive model dimension
• requires a configured distance metric
• uses metric-aware SQL expressions:
  • cosine -> 1 - distance
  • inner product -> -1 * negative_inner_product
  • euclidean -> 1 / (1 + distance)

2. Semantic engine

• resolves one explicit model per request
• validates:
  • model active
  • dimensions > 0
  • distance metric configured
  • query embedding mode supported

3. Database

• check constraint for positive dimensions
• unique constraint on (representation_id, model_id)
• comments documenting the per-model partial ANN index strategy

Why this matters

With Option A, multiple vector lengths live in one DOC.doc_embedding.embedding_vector column. That is safe only if:

• every semantic query resolves exactly one model
• the query vector uses that same model
• the repository filters by model_id
• the vector cast uses the correct model dimension
• ANN indexes are created per active model