Eve library

OSHUN Studio Search and Global Discovery Journeys and Edge Cases

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Product Design + Web Engineering + OSHUN BFF
Last Updated: 2026-02-23
Related:

  • docs/adr/ADR-0021-oshun-studio-search-and-global-discovery.md
  • docs/releases/v1/specs/studio-search-and-global-discovery-dependency-and-data-contract-map.md

Purpose#

Define primary journeys and deterministic edge-case behavior for Studio search and global discovery governance.

This document is the execution artifact for OST-00067.

Personas#

  • Program Operator
  • Domain Specialist
  • Discovery Analyst
  • Security Reviewer
  • Accessibility Lead

Journey Principles#

  1. Discovery queries must produce deterministic and explainable results.
  2. Domain context must be preserved from search to action.
  3. Partial failures must degrade gracefully with explicit domain status.
  4. Search surfaces must be keyboard and screen-reader accessible.

1. Primary Journeys#

J1. Global Query and Cross-Domain Result Discovery#

Goal: Execute one query and discover relevant results across multiple domains.

Entry: Studio -> Search and Discovery -> Global Query

Steps:

  1. Enter query and optional domain filter.
  2. Execute query against global search contract.
  3. Inspect blended and domain-grouped results.
  4. Review ranking metadata and domain labels.
  5. Select result and continue into domain workflow.

Success State:

  • Relevant, ranked cross-domain results are returned and actionable.

J2. Filtered Discovery for Domain-Specific Work#

Goal: Scope discovery to one domain while preserving global context.

Entry: Studio -> Search and Discovery -> Domain Filter

Steps:

  1. Select a specific domain filter.
  2. Execute scoped query.
  3. Validate result relevance and domain status.
  4. Open result action route.
  5. Return to discovery with query/filter state intact.

Success State:

  • Scoped results are deterministic and context is preserved after roundtrip.

J3. Query-to-Action Handoff with Context Preservation#

Goal: Move from discovery result to execution surface without losing origin context.

Entry: Result action in search panel

Steps:

  1. Select result action from list.
  2. Navigate to mapped route with origin/stack/query context.
  3. Execute target workflow action.
  4. Return using preserved back path.
  5. Confirm restored query state and recent-search continuity.

Success State:

  • Action completes and user is returned to correct discovery state.

J4. Partial-Failure Discovery Recovery#

Goal: Continue meaningful discovery when one or more domain sources are degraded.

Entry: Search execution with degraded domain adapters

Steps:

  1. Execute global query.
  2. Detect per-domain degraded statuses and errors.
  3. Show partial-failure signal and domain-level diagnostics.
  4. Continue exploring healthy-domain results.
  5. Retry query once degraded domains recover.

Success State:

  • Discovery remains usable with clear degraded-domain visibility.

J5. Search Governance Promotion and Rollback#

Goal: Promote search changes safely and recover from regressions.

Entry: Review & Approvals or Observability alert

Steps:

  1. Review ranking/query/action contract evidence.
  2. Approve and promote discovery release.
  3. Monitor quality and latency indicators.
  4. If regression occurs, rollback to certified release.
  5. Publish incident summary and remediation tasks.

Success State:

  • Discovery release is either stable or safely rolled back with full evidence.

2. Critical Edge Cases#

E1. Empty Query State#

  • Trigger: query is blank.
  • Required behavior: show deterministic curated defaults (recent/trending).

E2. Invalid Domain Filter#

  • Trigger: domain filter is outside supported enum.
  • Required behavior: reject request and present clear validation error.

E3. Unauthorized Domain Scope#

  • Trigger: user lacks scope for one or more domains.
  • Required behavior: mark domains forbidden, suppress unauthorized results.

E4. Ranking Drift Regression#

  • Trigger: ranking order deviates from documented formula.
  • Required behavior: fail validation and block release.

E5. Query-to-Route Mapping Missing#

  • Trigger: result lacks valid action path.
  • Required behavior: disable action, show fallback guidance, emit audit error.

E6. Context Loss on Return Path#

  • Trigger: user cannot return to original query/filter context.
  • Required behavior: restore from persisted context or safe fallback route.

E7. Partial Domain Outage#

  • Trigger: one or more domain adapters fail during query.
  • Required behavior: return partial results + explicit domain status and errors.

E8. Search Telemetry Sink Failure#

  • Trigger: discovery telemetry or audit emission fails.
  • Required behavior: retry, mark degraded observability, reconcile buffered events.

E9. Excessive Search Latency#

  • Trigger: search response exceeds defined SLO window.
  • Required behavior: alert operators, capture diagnostics, expose user-safe feedback.

E10. Missing Rollback Reference#

  • Trigger: discovery release package lacks rollback target.
  • Required behavior: block production promotion.

3. Journey-to-Surface Mapping#

Journey Primary Surface Supporting Surfaces
J1 Global Query and Cross-Domain Result Discovery Search and Discovery Explore
J2 Filtered Discovery for Domain-Specific Work Search and Discovery Domain surfaces
J3 Query-to-Action Handoff with Context Preservation Search and Discovery Navigation, Domain routes
J4 Partial-Failure Discovery Recovery Search and Discovery Observability
J5 Search Governance Promotion and Rollback Review & Approvals Observability, Governance

4. Instrumentation Requirements#

Required events:

  • search_discovery.journey.started
  • search_discovery.journey.step.completed
  • search_discovery.journey.blocked
  • search_discovery.journey.recovered
  • search_discovery.journey.completed

Required dimensions:

  • programId, projectId, workspaceId
  • journeyId, stepId, query, domainFilter
  • actorRole, outcome, latencyMs, errorCode

5. Acceptance Criteria (OST-00067)#

OST-00067 is complete only when:

  1. At least five search/discovery journeys are documented.
  2. At least ten deterministic edge cases are documented.
  3. Journey-to-surface mapping is explicit.
  4. Instrumentation requirements and dimensions are documented.