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.tsapps/oshun/bff/src/search/ranking.tsapps/oshun/bff/src/__tests__/search-ranking.test.tsapps/oshun/web/src/components/UniversalSearchPanel.tsxapps/oshun/web/src/components/explore/ExploreDashboard.tsxapps/oshun/web/src/navigation/routes.tsdocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/domains/bellona/features.mddocs/releases/v1/specs/search-ranking-strategy.mddocs/releases/v1/reports/metrics.mddocs/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
DiscoveryAuditEventrecords.
5. Acceptance Criteria (OST-00066)#
OST-00066 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for ranking spec, search route payloads, result actions, domain status, and audit events are documented.
- Ownership boundaries and validation rules are explicit.