Synonyms: Requirements and relevance contract

Versioned synonym sets declare one-way versus two-way expansion, allow tenant overrides, and must not expand a query into documents the searcher is not allowed to see.

Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.

Decision

Site search applies versioned synonym sets that are explicit about direction: two-way equivalence or one-way expansion. Tenants may overlay overrides that replace or add mappings without editing the global set in place. Query expansion runs after authorization filters are bound to the searcher; expansion must not retrieve or score documents the user cannot read, including via a synonym that only exists on hidden titles.

Scope

• Query-time synonym expansion, synonym-set versioning, one-way versus two-way maps, tenant overrides, and ACL-safe retrieval.
• Backend site search for authorized catalogs and knowledge collections.
• Evaluation of synonym-affected ranking on a labeled query set.

Outside this block

• Learning-to-rank model training and click analytics warehouses.
• Document chunking for RAG.

Contract

• Each published synonym set has a monotonic set_version and a list of mappings with direction of two-way or one-way.
• One-way mapping source -> target expands queries containing source to include target terms; it does not expand target to source unless a reverse mapping exists.
• Tenant overrides are stored as a higher-priority set and never mutate the parent set's bytes.
• Search execution applies document ACL (or equivalent visibility) before or with scoring so expanded terms cannot surface unauthorized hits.
• Hidden documents do not contribute synonym discovery: administrators must not harvest aliases from titles the searcher cannot see.
• Switching set_version is recorded on the query log so relevance comparisons are reproducible.

Implementation

• Normalize two-way mappings into deterministic equivalence classes. Keep one-way rules directional and bound recursive expansion by visited-term detection plus max_expansion_terms.
• Run expansion inside the same authorization-aware query as the user filter.

Failure handling

• Equivalent two-way cycles are collapsed into one canonical class. Directional cycles are either rejected by an engine profile that cannot represent them safely or compiled with deterministic visited-term detection so they cannot recurse without bound.
• Unknown set_version on a pinned query fails closed to the last good version or to no expansion, never to an unpublished draft.

Verification

• Query a one-way mapping and assert the reverse query does not match unless two-way is configured.
• Search as a user who cannot read a synonym-target document and assert zero hits.

The executable-looking examples in this package are fixtures and acceptance contracts. Run python tools/validate.py from the collection root to check package structure and metadata; then implement and execute the scenarios in the target repository.

Adoption assumptions

• Names and numeric values in example.yaml are an adoption profile, not universal defaults.
• The adopting team must map actors, data classes, error vocabulary, and ownership to its system.

References

• Analyzer-level synonym filters are a common search-engine feature; Elastic documents one approach at https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-synonym-tokenfilter.html. Direction, tenant overrides, and ACL-safe expansion remain a project decision.