# OSHUN Studio Navigation and Command Surfaces Dependency and Data Contract Map

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.
