# OSHUN Studio Search and Global Discovery Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Product Design + OSHUN Web + OSHUN BFF  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0021-oshun-studio-search-and-global-discovery.md`

## Purpose

Define dependencies and canonical contracts for Studio search and global
discovery governance across Yemaya, Isis, Hathor, Aja, Bellona, and Project
Obsidian.

This document is the execution artifact for `OST-00066`.

## Sources Used

- `apps/oshun/bff/src/routes/search.ts`
- `apps/oshun/bff/src/search/ranking.ts`
- `apps/oshun/bff/src/__tests__/search-ranking.test.ts`
- `apps/oshun/web/src/components/UniversalSearchPanel.tsx`
- `apps/oshun/web/src/components/explore/ExploreDashboard.tsx`
- `apps/oshun/web/src/navigation/routes.ts`
- `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`
- `docs/releases/v1/specs/search-ranking-strategy.md`
- `docs/releases/v1/reports/metrics.md`
- `docs/releases/v1/design/ux-principles.md`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Ranking and query logic**: `apps/oshun/bff/src/search`
- **Search API contract**: `apps/oshun/bff/src/routes/search.ts`
- **Web discovery and query UI**:
  `apps/oshun/web/src/components/UniversalSearchPanel.tsx`
- **Explore aggregation UX**:
  `apps/oshun/web/src/components/explore/ExploreDashboard.tsx`
- **Route/context handoff**: `apps/oshun/web/src/navigation/routes.ts`
- **Telemetry and audit**: `libs/oshun/analytics` + BFF/web sinks

### 1.2 Domain Dependency Graph

- `Search Governance -> Yemaya`: asset and project search needs deterministic
  tagging and full-text discovery semantics.
- `Search Governance -> Isis`: workflow/model/prompt discovery requires clear
  filterable metadata and relevance behavior.
- `Search Governance -> Hathor`: lore/world/research discovery requires
  cross-entity and citation-aware result context.
- `Search Governance -> Aja`: reference/video and semantic search requires
  predictable ranking and scope filters.
- `Search Governance -> Bellona`: build/runtime diagnostics discovery requires
  low-noise, high-signal result ordering.
- `Project Obsidian -> all`: release governance, reliability targets, and
  evidence expectations for search behavior changes.

## 2. Ownership and Contract Matrix

| Area                               | Owner                  | Consumers                        | Artifact             | Contract                        |
| ---------------------------------- | ---------------------- | -------------------------------- | -------------------- | ------------------------------- |
| Query and ranking semantics        | OSHUN BFF              | Web/mobile discovery surfaces    | Ranking module       | `DiscoveryRankingSpec`          |
| Search API payloads                | OSHUN BFF              | Web search UI + Studio workflows | API response         | `SearchRoutePayloadContract`    |
| Result action routing              | OSHUN Web + Navigation | Domain surfaces                  | Route mapping        | `DiscoveryResultActionContract` |
| Domain status/degradation handling | BFF + Domain adapters  | SRE + Product Ops                | Domain status report | `SearchDomainStatusReport`      |
| Audit/telemetry evidence           | Data Platform          | Governance + SRE                 | Event stream         | `DiscoveryAuditEvent`           |

## 3. Canonical Contracts

### 3.1 DiscoveryRankingSpec

```ts
export interface DiscoveryRankingSpec {
  version: string;
  formula: 'lexical + kindBoost + domainIntentBoost';
  lexicalWeights: {
    titleExact: number;
    summaryExact: number;
    titleToken: number;
    summaryToken: number;
  };
  kindBoost: {
    continue: number;
    highlight: number;
  };
  domainIntent: {
    matchBoost: number;
    mismatchPenalty: number;
  };
  tieBreakOrder: Array<'score' | 'domain' | 'title'>;
}
```

### 3.2 SearchRoutePayloadContract

```ts
export interface SearchRoutePayloadContract {
  generatedAt: string;
  userId: string;
  query: string;
  domainFilter: 'all' | 'tara' | 'veritas' | 'nyx' | 'arete';
  authorizedDomains: string[];
  results: Array<{
    id: string;
    domain: 'tara' | 'veritas' | 'nyx' | 'arete';
    kind: 'continue' | 'highlight';
    title: string;
    summary: string;
    score: number;
  }>;
  pagination: {
    limit: number;
    offset: number;
    total: number;
    hasMore: boolean;
  };
  domainStatus: Record<
    'tara' | 'veritas' | 'nyx' | 'arete',
    'ok' | 'degraded' | 'forbidden'
  >;
  errors: Array<{
    domain: 'tara' | 'veritas' | 'nyx' | 'arete';
    stage: 'continue' | 'highlights';
    message: string;
  }>;
  partialFailure: boolean;
}
```

### 3.3 DiscoveryResultActionContract

```ts
export interface DiscoveryResultActionContract {
  actionId: string;
  resultId: string;
  domain: 'tara' | 'veritas' | 'nyx' | 'arete';
  routePath: string;
  requiredContext: {
    origin: string;
    stack?: string[];
    query?: string;
  };
  fallbackRoute: string;
}
```

### 3.4 SearchDomainStatusReport

```ts
export interface SearchDomainStatusReport {
  reportId: string;
  generatedAt: string;
  query: string;
  domainFilter: 'all' | 'tara' | 'veritas' | 'nyx' | 'arete';
  domains: Array<{
    domain: 'tara' | 'veritas' | 'nyx' | 'arete';
    status: 'ok' | 'degraded' | 'forbidden';
    stageFailures: Array<'continue' | 'highlights'>;
  }>;
  partialFailure: boolean;
}
```

### 3.5 DiscoveryAuditEvent

```ts
export interface DiscoveryAuditEvent {
  eventId: string;
  action:
    | 'discovery.query.executed'
    | 'discovery.results.returned'
    | 'discovery.result.opened'
    | 'discovery.permission.denied'
    | 'discovery.degraded';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  programId: string;
  projectId: string;
  workspaceId: string;
  query: string;
  domainFilter: 'all' | 'tara' | 'veritas' | 'nyx' | 'arete';
  resultCount?: number;
  role: string;
  traceId: string;
  occurredAt: string;
  reason?: string;
}
```

## 4. Validation Rules

- Production promotion is blocked unless ranking formula changes are documented
  and regression-tested.
- Production promotion is blocked unless query/filter/action route contracts are
  validated.
- Partial-failure handling must preserve deterministic domain status reporting.
- All allow/deny/degraded outcomes must emit `DiscoveryAuditEvent` records.

## 5. Acceptance Criteria (OST-00066)

`OST-00066` is complete only when:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Contracts for ranking spec, search route payloads, result actions, domain
   status, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
