# Unified Search Architecture

Unified Search is the cross-domain query and answer subsystem of Advisory AI. It lets operators and users who are unfamiliar with Stella Ops terminology find relevant results across every plane of the release control plane — findings, VEX, policy, graph, timeline, scanner, platform knowledge, and operational memory — through a single deterministic ranking and synthesis pipeline.

Audience: engineers building against the unified-search API and operators tuning its ranking and federation behavior. For the parent service see architecture.md; for operator configuration and examples see unified-search-operations.md and knowledge-search.md.

Goals

• Help operators and users unfamiliar with Stella Ops terminology find relevant results quickly.
• Merge platform knowledge, findings, VEX, policy, graph, timeline, scanner, and OpsMemory signals into one deterministic ranking stream.
• Keep the system offline-capable and tenant-safe.

Four-Layer Architecture

flowchart LR
  Q[Layer 1: Query Understanding]
  R[Layer 2: Federated Retrieval]
  F[Layer 3: Fusion and Entity Cards]
  S[Layer 4: Synthesis]

  Q --> R --> F --> S

Layer 1: Query Understanding

• Input: UnifiedSearchRequest (q, filters, ambient context, session id).
• Ambient context envelope from Web clients includes route/session continuity fields and optional last-action metadata (action, source, queryHint, domain, entityKey, route, occurredAt) for follow-up ranking/refinement.
• Components:
  • EntityExtractor
  • IntentClassifier
  • DomainWeightCalculator
  • AmbientContextProcessor
  • SearchSessionContextService
• Output: QueryPlan with intent, detected entities, domain weights, and context boosts.

Layer 2: Federated Retrieval

• Sources queried in parallel:
  • Primary universal index (IKnowledgeSearchStore FTS + vector candidates)
  • Optional federated backends via FederatedSearchDispatcher
• Ingestion adapters keep index coverage aligned across domains:
  • Findings, VEX, Policy (live + snapshot fallback)
  • Graph, Timeline, Scanner, OpsMemory snapshots
  • Platform catalog
• Tenant isolation is enforced in request filters and chunk identities.

Findings coverage

FindingsSearchAdapter reads the served-generation headers on every page of GET /api/findings/v1/security/findings: X-StellaOps-Match-State, X-StellaOps-Match-Incomplete-Versions, X-StellaOps-Source-State, X-StellaOps-Source-As-Of, and X-StellaOps-Corpus-Digest. The meaning of these headers is defined by the Findings API contract. An incomplete match means evaluable matches are present while unevaluated applicability remains unknown; missing findings and zero counts do not prove absence.

All chunks from one fetch carry the conservative combination of every page in their existing metadata: matchState, matchIncompleteVersions, sourceState, sourceAsOf, corpusDigest, and findingsTruncated. Any incomplete page makes match coverage incomplete; any stale page makes source freshness stale. Missing or invalid header values remain unknown. The incomplete-version count is the maximum tenant-wide count seen, not a sum across pages, and becomes unknown if a page omits it. The oldest source activation time is retained only when every page supplies it; a digest is retained only when all pages agree. Different generations cannot support a current-snapshot claim. Reaching the page cap is marked as a partial result set independently of match coverage. Snapshots have unknown served-generation coverage.

The indexer persists this metadata alongside each chunk and refreshes it even when only coverage changes. Search cards, facets, previews, and snippets retain the state; card merging combines Findings coverage even when a different domain supplies the primary card. Partial, stale, and unknown coverage produces an explicit Findings coverage: notice in snippets, deterministic summaries, LLM prompt context, and returned generated summaries. Grounded chat carries the notice into its evidence pack and reapplies it after model response validation. This makes coverage disclosure independent of model wording. Existing indexed rows without the metadata are treated as unknown until the next refresh.

Layer 3: Fusion and Entity Cards

• WeightedRrfFusion merges lexical + vector candidates with domain weights.
• Additional boosts:
  • Entity proximity
  • Ambient/session carry-forward
  • Graph gravity
  • Optional popularity and freshness controls
• Current-page scope is applied here as a ranking bias, not a hard filter. When outside-scope results remain materially stronger, or remain inside a narrow relative score band, the response surfaces them in bounded overflow metadata instead of hiding them.
• EntityCardAssembler groups facets into entity cards and resolves aliases.

Layer 4: Synthesis

• Deterministic synthesis is always available from top cards.
• Optional LLM tier (SearchSynthesisService) streams over SSE with:
  • quota enforcement
  • grounding score
  • action suggestions
• If LLM is unavailable or blocked by quota, deterministic output is still returned.
• Query responses may also include a deterministic contextAnswer envelope for answer-first search UX:
  • status: grounded | clarify | insufficient
  • code, summary, reason, evidence
  • bounded citations
  • bounded follow-up questions
• The answer envelope is additive and optional so older clients remain compatible.

Telemetry and gap surfacing

• Search analytics stays optional at the client layer; queries still work when analytics events are never emitted.
• AdvisoryAI:KnowledgeSearch:SearchTelemetryEnabled=false also disables backend analytics persistence, feedback persistence, popularity-map reads, and unified-search telemetry sink emission without disabling retrieval or history.
• When enabled, the self-serve lane records answer_frame, reformulation, and rescue_action with hashed query keys, hashed tenant-scoped session ids, and bounded answer metadata.
• Quality review surfaces:
  • GET /v1/advisory-ai/search/quality/metrics
  • GET /v1/advisory-ai/search/quality/alerts
• Current self-serve gap signals:
  • fallback answer rate
  • clarify rate
  • insufficient-evidence rate
  • reformulation count
  • rescue-action count
  • abandoned fallback count
  • fallback_loop and abandoned_fallback alerts

Data Flow

sequenceDiagram
  participant UI as Web UI / API Client
  participant API as UnifiedSearchEndpoints
  participant PLAN as QueryUnderstanding
  participant IDX as KnowledgeSearchStore
  participant FED as FederatedDispatcher
  participant FUS as WeightedRrfFusion
  participant CARDS as EntityCardAssembler
  participant SYN as SearchSynthesisService
  participant ANA as SearchAnalyticsService

  UI->>API: POST /v1/search/query
  API->>PLAN: Build QueryPlan
  PLAN-->>API: intent + entities + domain weights
  API->>IDX: SearchFtsAsync + LoadVectorCandidatesAsync
  API->>FED: DispatchAsync (optional)
  IDX-->>API: lexical + vector rows
  FED-->>API: federated rows + diagnostics
  API->>FUS: Fuse rankings
  FUS-->>API: ranked rows
  API->>CARDS: Assemble entity cards
  CARDS-->>API: entity cards
  API->>ANA: Record query/click/zero_result
  API-->>UI: UnifiedSearchResponse

  UI->>API: POST /v1/search/synthesize
  API->>SYN: ExecuteAsync
  SYN-->>UI: SSE deterministic-first + optional LLM chunks

Contracts and API Surface

• POST /v1/search/query
• POST /v1/search/suggestions/evaluate
• POST /v1/search/synthesize
• POST /v1/search/index/rebuild

POST /v1/search/query response notes:

• Entity cards remain the primary retrieval payload.
• contextAnswer is the preferred answer-first surface for Web self-serve UX when present.
• contextAnswer is query-driven rather than mode-driven: compare-like requests may blend close evidence clusters, while scoped troubleshoot requests prefer a single decisive answer when one result clearly leads.
• overflow is additive and bounded so FE can show “outside the current page, but likely relevant” results without reintroducing a scope toggle.
• overflow is intentionally narrow: it is suppressed when the current-scope winner has a clear lead, so FE can trust the primary section as the best local answer.
• coverage is additive and bounded so FE can suppress misleading suggestions when the active corpus has no sensible candidates for that domain.
• Live local verification currently covers the Doctor/knowledge path after the documented rebuild order:
  1. POST /v1/advisory-ai/index/rebuild
  2. POST /v1/search/index/rebuild One unified index run is admitted per host. A 409 Conflict answer names the startup, periodic or manual run that holds the host in running; retry after it finishes.

POST /v1/search/suggestions/evaluate response notes:

• Intended for proactive suggestion chips and page-owned prompts before the user commits a search.
• Returns per-query viability plus bounded domain coverage.
• Additive fields:
  • viabilityState: grounded | needs_clarification | no_match | scope_unready | corpus_unready
  • scopeReady: true when the current route scope has indexed corpus behind it
• viable=true is reserved for suggestions that already have grounded evidence; clarify-only suggestions are not considered executable.
• Does not require telemetry and does not record answer-frame analytics.

OpenAPI contract presence is validated by integration test:

• UnifiedSearchEndpointsIntegrationTests.OpenApi_Includes_UnifiedSearch_Contracts

Determinism Rules

• Stable ordering tie-breaks by kind then chunkId.
• Ranking benchmark includes a deterministic stability hash across top results.
• Session context is ephemeral and expires by inactivity timeout.

Configuration

Primary section: AdvisoryAI:UnifiedSearch

• Enabled
• BaseDomainWeights
• Weighting.* (domain/intent/entity/role boosts)
• Federation.*
• GravityBoost.*
• Synthesis.*
• Ingestion.*
• Session.*
• TenantFeatureFlags.<tenant>.{Enabled,FederationEnabled,SynthesisEnabled}

Detailed operator config and examples:

• docs/operations/unified-search-operations.md
• docs/modules/advisory-ai/knowledge-search.md