[gkennos]

Summary

Normalised search compares against a computed expression, so ordinary indexes on concept_name do not help.

Measured on a 1.7M-concept CDM:

Call	Time
unconstrained	40s
domain='Drug'	25s
vocabulary_id='MedDRA'	0.4s

search_normalized now requires vocabulary_id or parent_ids (a domain filter is not selective enough) and raises INVALID_INPUT otherwise.

allow_unindexed_scan=True accepts the scan if it's really requires (exposed on MCP tool)

concept_candidate_bundle degrades instead of failing (the same way an absent full-text sidecar is handled)

Share one normalisation contract between Python and SQL

Adds NormalizationProfile (StrEnum: verbatim / aggressive / drug_name) and moves the SQL expression builder to base/sql.py as normalization_expression(), replacing the private _normalized_sql_expr in the vocab service. The three profiles were previously bare strings validated on only one of the two paths; an unknown profile is now rejected by both.

Expose a read-only MappingContext to plugins

Plugins can reuse the host's configured mapping and grounding services (candidate bundles, sync and async, concept context, grounding), instead of constructing a second omop-graph or vocabulary adapter from context.cdm_engine. All operations are query-only --> the underlying service objects are deliberately not exposed. The application wires one shared instance into every plugin.

Checklist

• Applied exactly one label (breaking, feature, fix, dependencies, or chore)
• Tests pass locally (uv run pytest -q)
• Lint passes (uv run ruff check .)