Class SearchEngine

Access the cached provider metadata from SearchEngineBase

Resolver for a scope's declared Search Context dimensions. Overridable so a host can supply additional derivation sources (e.g. an external signal) without forking the engine.

Resolve the metadata provider via SearchEngineBase (which extends BaseEngine and tracks ProviderToUse).

Enforce a lane's RequiredMetadataKeys contract (Phase E).

The rendered filter must mention every key the author declared. This is the only guard that catches a filter which rendered partially — where an optional {% if %} clause disappeared because its dimension was absent or discarded, leaving a non-empty filter that passes every other check while restricting on strictly less than intended.

Fail a search CLOSED when a scope field that RESTRICTS was authored but did not render usably (see CheckRenderedTemplate).

Throwing rather than dropping the offending row is deliberate. Dropping it would empty the row collection, and buildScopeConstraints collapses an empty collection to undefined — which every provider reads as "unscoped", i.e. all entities / all indexes with no filter. So the surgical-looking fix is the one that widens; failing the search is the one that doesn't. A broken restricting template is a misconfiguration and should be loud and actionable, never silently degraded into a wider search.

Build a stable cache key for a search.

The key must include EVERY input that can change the result set, or the cache will serve one caller's results to another. Two of those inputs were previously missing and both are tenancy/authorization-relevant:

• SearchContext — carries PrimaryScopeRecordID (the TENANT) and the SecondaryScopes dimensions. Omitting it meant a user with access to two tenants could be served the other tenant's results for up to the cache TTL, and that two searches differing only by dimension (channel, skill, …) collided. This is the reason for the fix.
• ScopeIDs — determines which corpora are searched at all.

Also folded in: Mode, FusionWeightsOverride and PermissionOverfetchFactor (all change ranking or the candidate pool, so they change results) and AIAgentID (conservative: agent identity participates in scope resolution and per-agent overrides upstream; including it can only cost a miss, never leak).

ScopeIDs order is deliberately NOT sorted: it is behaviourally significant, because cross-scope reranker config and budget are taken from the first scope in the array that supplies one. Two different orderings can therefore produce different results and must not share a key.

The whole projection is emitted through stableStringify so key-order variation in SecondaryScopes doesn't fragment the cache. The user ID stays as a readable prefix for debuggability.

Note this runs AFTER scope resolution in searchInternal, so nothing here is circular. Entitlement is resolved by the CALLERS (__Scoped_Search, the GraphQL resolvers), which deny before reaching the engine; the engine therefore never caches across an allow/deny boundary.

Filter search results by entity-level and row-level security permissions.

This is a safety net. Providers are expected to do per-provider permission push-down (Section 3.6 of plans/search-scopes-rag-plus.md). If this filter is removing more than a handful of results in practice, the responsible provider's push-down is incomplete and should be fixed.

Groups results by entity for efficient permission checking:

1. Unknown entities are excluded (fail closed).
2. If the user lacks entity-level CanRead, all results for that entity are dropped.
3. If the user is exempt from RLS, all results pass through.
4. If RLS applies, a RunView validates which record IDs the user can read.

Build the principal set a dimension's expansion query may bind.

Exists so the real search path and the ExplainScope dry run cannot construct principals differently. They already did once: ExplainScope passed the agent and the search path passed nothing, so any scope deriving its bound from AgentID previewed one bound and searched with another. A single conversion site makes that class of drift unrepresentable rather than merely fixed.

Accepts anything carrying the two principal IDs, which both SearchParams and ExplainScopeInput do.

Deterministically serialize a value with object keys sorted, so that two logically-identical inputs always produce the same string.

JSON.stringify preserves insertion order, which means a caller that builds SecondaryScopes by spreading (a common pattern) can emit the same dimensions in different orders across calls. Left unsorted that causes avoidable cache misses; sorted, identity is stable. Array order is PRESERVED — see buildCacheKey for why ScopeIDs order is significant.