Eve library

OSHUN Studio Navigation and Command Surfaces Dependency and Data Contract Map

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Product Design + OSHUN Web
Last Updated: 2026-02-23
Related: docs/adr/ADR-0020-oshun-studio-navigation-and-command-surfaces.md

Purpose#

Define dependencies and canonical contracts for Studio navigation and command surface governance across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for OST-00058.

Sources Used#

  • 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/domains/yemaya/service-catalog.md
  • docs/domains/isis/service-catalog.md
  • docs/domains/hathor/service-catalog.md
  • docs/domains/aja/service-catalog.md
  • docs/domains/bellona/service-catalog.md
  • docs/releases/v1/design/ux-principles.md
  • docs/releases/v1/design/ergonomics-requirements.md
  • libs/oshun/navigation
  • apps/oshun/web/src/navigation/routes.ts
  • libs/oshun/analytics

1. Dependency Overview#

1.1 Control Surfaces#

  • Route contracts: libs/oshun/navigation
  • Web route adapters: apps/oshun/web/src/navigation
  • Command surface UI: apps/oshun/web/src/components
  • Telemetry and audit: libs/oshun/analytics + Studio sinks

1.2 Domain Dependency Graph#

  • Navigation/Command Governance -> Yemaya: project and collaboration actions require predictable command scopes and return navigation.
  • Navigation/Command Governance -> Isis: generation workflows require clear command history and context restoration.
  • Navigation/Command Governance -> Hathor: narrative review flows require deterministic back-stack and command execution.
  • Navigation/Command Governance -> Aja: timeline and animation tools require rapid command invocation with guarded high-impact actions.
  • Navigation/Command Governance -> Bellona: build/runtime control surfaces require auditable command execution and fallback paths.
  • Project Obsidian -> all: program-level governance for command and routing reliability.

2. Ownership and Contract Matrix#

Area Owner Consumers Artifact Contract
Route contract schema Navigation Platform Web/mobile surfaces Route registry StudioRouteContract
Command catalog Product Design + Web Domain teams Command registry StudioCommandCatalog
Context restoration Platform Web Operators Context payload StudioNavigationContext
Command policy and approvals Security + Product Ops Engineering + QA Policy map CommandPolicyMatrix
Audit/telemetry stream Data Platform SRE + Governance Event stream NavigationCommandAuditEvent

3. Canonical Contracts#

3.1 StudioRouteContract#

ts
export interface StudioRouteContract {
  routeId: string;
  path: string;
  scope: 'global' | 'studio' | 'domain';
  requiredContextKeys: string[];
  supportsBackStack: boolean;
  fallbackRoute: string;
}

3.2 StudioCommandCatalog#

ts
export interface StudioCommandCatalog {
  catalogVersion: string;
  commands: Array<{
    commandId: string;
    label: string;
    scope: 'global' | 'workspace' | 'domain';
    category: 'navigation' | 'execution' | 'review' | 'administration';
    requiresConfirmation: boolean;
    policyKey: string;
  }>;
}

3.3 StudioNavigationContext#

ts
export interface StudioNavigationContext {
  contextId: string;
  programId: string;
  projectId: string;
  workspaceId: string;
  originRoute: string;
  backStack: string[];
  persistedAt: string;
}

3.4 CommandPolicyMatrix#

ts
export interface CommandPolicyMatrix {
  matrixId: string;
  version: string;
  policies: Array<{
    policyKey: string;
    allowedRoles: string[];
    restrictedScopes: string[];
    escalationPath: string;
  }>;
}

3.5 NavigationCommandAuditEvent#

ts
export interface NavigationCommandAuditEvent {
  eventId: string;
  action:
    | 'navigation.route.requested'
    | 'navigation.route.completed'
    | 'command.execute.requested'
    | 'command.execute.completed'
    | 'command.permission.denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  programId: string;
  projectId: string;
  workspaceId: string;
  routeId: string;
  commandId?: string;
  role: string;
  traceId: string;
  occurredAt: string;
  reason?: string;
}

4. Validation Rules#

  • Production release blocked unless route and context-restoration checks pass.
  • Production release blocked unless command policy matrix coverage is complete.
  • All command executions require complete context and policy authorization.
  • All allow/deny outcomes must emit NavigationCommandAuditEvent records.

5. Acceptance Criteria (OST-00058)#

OST-00058 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 routes, command catalog, context restoration, policy, and audit streams are documented.
  4. Ownership boundaries and validation rules are explicit.