Semantic search feels like finding the thought

Semantic search follows the shape of an idea rather than its exact words. That is the useful part. The production work is everything around the vector.

Meaning is not permission. A nearest neighbor should not be visible before access filtering. Keep scope with the retrieval record:

{
  "tenantId": "acme",
  "visibility": "team",
  "allowedGroups": ["engineering", "security"],
  "sourceType": "incident_doc",
  "deleted": false
}

Metadata also controls ranking, citation, freshness, and expiry. Keep owner, source system, timestamps, version, tenant, project, access groups, language, confidence, deletion state, and retention policy where the system can use them.

Deleting the source is not enough. Chunks, embeddings, summaries, extracted entities, rerank features, and copied index entries must have a deletion path:

which entries came from this source?
when were they generated?
which model made them?
where do they live?
how do we delete or rebuild them?

Results should carry enough evidence to inspect:

type SearchHit = {
  sourceId: string
  chunkId: string
  title: string
  score: number
  sourceUpdatedAt: string
  accessReason: "owner" | "group" | "public"
  matchedTextPreview: string
}

Production search is usually hybrid. Exact matching handles IDs, error codes, SKUs, function names, and version numbers. Embeddings handle paraphrase. Metadata scopes the result. A reranker combines the evidence.

Evals need relevance and permission cases: paraphrases, old terminology, exact identifiers, stale documents, inaccessible sources, deleted records, changed visibility, and tenant boundaries. The worst failure is a correct answer from a source the user should not know exists.

Indexes drift when content, permissions, chunking, models, or metadata change. Track reindex reasons and make pending, failed, and old-index traffic visible.

Semantic search can find thought-shaped things. It becomes trustworthy when meaning, scope, freshness, and deletion are first-class behavior.