Semantic product search
The tenant search facade is implemented, but its owner contract remains draft.
Call POST /api/v1/catalog/search/query from a tenant-owned backend. The response is retrieval candidates, not an AI answer. Use GET /capabilities to learn enabled/effective lanes, limits, readiness, and semantic-index state.
Hybrid retrieval can combine exact, structured, lexical, and semantic lanes. Structured constraints such as price/category/stock must be sent as filters when known; semantic similarity is not a substitute for enforcing a hard bound.
Descriptions improve semantic retrieval because canonical embedding text includes title, taxonomy, description, tags, scalar attributes, and variant options. Use truthful, customer-oriented descriptions rather than keyword stuffing.
Treat degraded: true and degraded_reasons as actionable state. Exact/lexical results may still be useful while semantic warming is incomplete. Keep tenant identity server-side and never merge result ids across tenants.