Eve library

OSHUN Studio Search and Global Discovery Dependency and Data Contract Map

Spec

Revision 1

On this page

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.