# ADR-0021: OSHUN Studio Search and Global Discovery

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Product Design, OSHUN Web Engineering  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio already contains cross-domain explore and search capabilities, plus a
deterministic ranking strategy in the BFF. However, advanced Studio workflows
need a governed global discovery model that unifies search intent, contextual
relevance, and actionability across domains.

Without an explicit search/discovery decision, Studio risks:

- inconsistent search semantics across domains and surfaces
- fragmented relevance behavior between ranking and UI presentation
- weak context preservation when moving from discovery to execution
- reduced trust in global results for high-stakes production workflows

## Decision Drivers

- **Relevance determinism**: ranking behavior must be predictable and auditable.
- **Cross-domain discoverability**: one query should support multi-domain
  outcomes with clear source context.
- **Actionability**: results should transition users directly into workflows.
- **Context continuity**: discovery-to-workflow handoff must preserve context.
- **Operational governance**: search surfaces require policy, telemetry, and
  rollback-safe releases.

## Considered Options

### Option 1: Domain-Specific Search Experiences

Each domain maintains independent search and discovery behavior.

**Pros**:

- Local optimization for domain-specific semantics.

**Cons**:

- Cross-domain inconsistency and high operator context-switch cost.
- Duplicate ranking and UX governance burden.

### Option 2: Shared Endpoint, Ungoverned Discovery UX

Use one backend search path while allowing ungoverned frontend discovery
patterns.

**Pros**:

- Faster UI iteration in the short term.

**Cons**:

- Inconsistent result interpretation and action flows.
- Weak guarantees for accessibility and policy-sensitive discovery actions.

### Option 3: Unified Global Discovery System with Governed Search Semantics (Chosen)

Adopt one global search and discovery model with deterministic ranking,
context-preserving handoff, policy-aware action controls, and auditable release
governance.

**Pros**:

- Consistent, trustworthy discovery across all Studio domains.
- Better operator efficiency and lower error rate in result-to-action paths.
- Clear observability and governance for search quality.

**Cons**:

- Increased governance overhead for discovery-surface changes.

## Decision Outcome

**Chosen option**: Option 3.

Search/discovery requirements:

1. **Canonical query contract**: shared query semantics and filter behavior.
2. **Deterministic ranking model**: explainable ordering and tie-break rules.
3. **Contextual result actions**: each result maps to clear execution
   entrypoint.
4. **Cross-domain grouping**: preserve domain identity while enabling blended
   discovery.
5. **Release governance**: validate -> approve -> publish with telemetry/audit
   and rollback coverage.

## Normative Rules

### Query Contract

- Governed discovery surfaces must support consistent query/filter semantics.
- Empty-state discovery behavior must be deterministic and intentionally
  curated.

### Ranking Contract

- Ranking formula and tie-break behavior must be documented and versioned.
- Ranking changes must include before/after evidence and rollback strategy.

### Result Action Contract

- Every result item must expose an explicit action path and preserved context.
- Cross-domain actions must include deterministic return paths.

### Accessibility Contract

- Search input, filters, and result actions must be keyboard-accessible.
- Result grouping and metadata must be screen-reader interpretable.

### Release Validity Contract

A search/discovery release is valid only when all are true:

- query and ranking behavior validations pass
- action-path and context-preservation checks pass
- accessibility checks pass
- role-authorized approval exists
- telemetry/audit records are complete
- rollback reference is defined

## Architecture Implications

- Global ranking strategy remains implemented and governed via BFF search
  contracts (`apps/oshun/bff/src/search`).
- Discovery surfaces in `apps/oshun/web` must align to shared ranking and route
  contracts.
- Route/context contracts remain aligned with `libs/oshun/navigation`.
- Search/discovery observability remains centralized in `libs/oshun/analytics`.

## Acceptance Criteria (OST-00065)

`OST-00065` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0027-oshun-studio-search-and-global-discovery.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines query, ranking, result-action, accessibility, and
   release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0020`.
5. ADR aligns with `docs/releases/v1/specs/search-ranking-strategy.md`,
   `docs/releases/v1/design/ux-principles.md`, and `libs/oshun/navigation`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Higher trust and consistency in Studio discovery behavior.
- Stronger cross-domain query-to-action workflow continuity.
- Better quality governance for ranking and discovery changes.

### Negative

- Additional validation overhead for search/discovery releases.
- Requires coordinated ownership across BFF, Web, and Product Design.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0014-oshun-web-and-pwa-strategy.md`
- `docs/adr/ADR-0015-deep-linking-and-cross-domain-routing.md`
- `docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md`
- `docs/adr/ADR-0017-offline-caching-and-sync-strategy.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0019-oshun-studio-information-architecture.md`
- `docs/adr/ADR-0020-oshun-studio-design-language-and-visual-identity.md`
- `docs/adr/ADR-0021-oshun-studio-typography-system.md`
- `docs/adr/ADR-0022-oshun-studio-color-system-and-token-governance.md`
- `docs/adr/ADR-0023-oshun-studio-spacing-and-layout-grid.md`
- `docs/adr/ADR-0024-oshun-studio-component-primitives-and-composition-contracts.md`
- `docs/adr/ADR-0025-oshun-studio-complex-interaction-patterns-and-state-orchestration.md`
- `docs/adr/ADR-0026-oshun-studio-navigation-and-command-surfaces.md`

## References

- `docs/releases/v1/specs/search-ranking-strategy.md`
- `docs/releases/v1/reports/metrics.md`
- `docs/releases/v1/design/ux-principles.md`
- `docs/domains/yemaya/features.md`
- `docs/domains/isis/features.md`
- `docs/domains/hathor/features.md`
- `docs/domains/aja/features.md`
- `docs/domains/bellona/features.md`
- `apps/oshun/web/src/components/UniversalSearchPanel.tsx`
- `apps/oshun/web/src/components/explore/ExploreDashboard.tsx`
- `apps/oshun/bff/src/search/ranking.ts`