# OSHUN Studio Observability and Operational Dashboards Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + Platform SRE + OSHUN
Data/Analytics Engineering + OSHUN Security  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.md`

## Purpose

Define dependencies and canonical contracts for Studio observability and
operational dashboard capabilities across Yemaya, Isis, Hathor, Aja, Bellona,
and Project Obsidian.

This document is the execution artifact for `OST-00226`.

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.md`
- `docs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.md`
- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/specs/studio-metrics-and-analytics-instrumentation-dependency-and-data-contract-map.md`
- `docs/releases/v1/design/ux-principles.md`
- `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`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Dashboard UI surfaces**: Studio observability modules in
  `apps/oshun/web/src/components/studio`.
- **Signal aggregation services**: BFF + metrics pipelines producing SLI/SLO and
  alert envelopes.
- **Dependency drill-down services**: workflow/dependency graph and context
  lookup services.
- **Policy and remediation services**: RBAC + permission-tier + CAB approval
  policy providers.
- **Audit and evidence services**: event ingestion + history replay + retention
  exports.

### 1.2 Domain Dependency Graph

- `Observability Dashboards -> Yemaya`: release and publication pipeline SLI/SLO
  rollups.
- `Observability Dashboards -> Isis`: model training/inference reliability and
  quality signals.
- `Observability Dashboards -> Hathor`: narrative/content synthesis health and
  policy metrics.
- `Observability Dashboards -> Aja`: timeline/render queue latency and
  throughput signals.
- `Observability Dashboards -> Bellona`: runtime incident, denial, and
  recovery-operability signals.
- `Project Obsidian -> all`: cross-domain rollups, alert prioritization, and
  operational readiness gating.

## 2. Ownership and Contract Matrix

| Area                                | Owner                    | Consumers                           | Artifact                    | Contract                                  |
| ----------------------------------- | ------------------------ | ----------------------------------- | --------------------------- | ----------------------------------------- |
| Dashboard signal card ingestion     | Data Platform + SRE      | Program operators + domain leads    | Signal card stream          | `StudioDashboardSignalCard`               |
| Alert lifecycle and triage actions  | Platform SRE + Security  | On-call + compliance                | Alert-state stream          | `StudioDashboardAlertRecord`              |
| Domain/workflow drill-down context  | BFF + Domain services    | Operators + incident responders     | Drill-down descriptor       | `StudioDashboardDrilldownDescriptor`      |
| Remediation action policy decisions | Security + Compliance    | Operators + release managers        | Policy decision envelope    | `StudioDashboardRemediationPolicy`        |
| SLO rollups and release readiness   | Data Platform + SRE      | Program/release management          | SLO snapshot stream         | `StudioDashboardSloRollupSnapshot`        |
| Dashboard governance evidence       | Security + Data Platform | Compliance + audit operations       | Dashboard audit event log   | `StudioDashboardGovernanceAuditEvent`     |
| Domain metadata and topology lookup | Domain Registry          | Dashboard cards + drill-down panels | Domain topology descriptors | `StudioDashboardDomainTopologyDescriptor` |

## 3. Canonical Contracts

### 3.1 StudioDashboardSignalCard

```ts
export interface StudioDashboardSignalCard {
  signalId: string;
  signalType: 'sli' | 'slo' | 'alert' | 'dependency' | 'quality';
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  workflowRef: string;
  status: 'healthy' | 'warning' | 'degraded' | 'critical';
  window: '5m' | '15m' | '1h' | '24h';
  currentValue: number;
  targetValue: number;
  updatedAt: string;
}
```

### 3.2 StudioDashboardAlertRecord

```ts
export interface StudioDashboardAlertRecord {
  alertId: string;
  signalId: string;
  severity: 'info' | 'warning' | 'high' | 'critical';
  state: 'new' | 'acknowledged' | 'investigating' | 'resolved' | 'closed';
  assignee?: string;
  summary: string;
  createdAt: string;
  updatedAt: string;
}
```

### 3.3 StudioDashboardDrilldownDescriptor

```ts
export interface StudioDashboardDrilldownDescriptor {
  drilldownId: string;
  signalId: string;
  actorId: string;
  workspaceId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  workflowId: string;
  dependencyRefs: string[];
  traceIds: string[];
  openedAt: string;
}
```

### 3.4 StudioDashboardRemediationPolicy

```ts
export interface StudioDashboardRemediationPolicy {
  decisionId: string;
  actionId: string;
  actorId: string;
  actorRole: string;
  permissionTier: 'baseline' | 'sensitive' | 'restricted';
  releaseChannel: 'preview' | 'staging' | 'production';
  approvalTicket?: string;
  outcome: 'allowed' | 'denied';
  reasonCode?: string;
  decidedAt: string;
}
```

### 3.5 StudioDashboardSloRollupSnapshot

```ts
export interface StudioDashboardSloRollupSnapshot {
  snapshotId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  successRate: number;
  p95LatencyMs: number;
  denialRate: number;
  availabilityRate: number;
  telemetryCompletenessRate: number;
  capturedAt: string;
}
```

### 3.6 StudioDashboardGovernanceAuditEvent

```ts
export interface StudioDashboardGovernanceAuditEvent {
  eventId: string;
  action:
    | 'dashboard.signal.ingested'
    | 'dashboard.alert.transitioned'
    | 'dashboard.drilldown.opened'
    | 'dashboard.remediation.executed'
    | 'dashboard.release_gate.evaluated'
    | 'dashboard.policy.denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  alertId?: string;
  signalId?: string;
  actorId?: string;
  actorRole?: string;
  reasonCode?: string;
  occurredAt: string;
}
```

### 3.7 StudioDashboardDomainTopologyDescriptor

```ts
export interface StudioDashboardDomainTopologyDescriptor {
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  upstreamDependencies: string[];
  downstreamConsumers: string[];
  criticalWorkflows: string[];
  onCallChannel: string;
  escalationOwner: string;
}
```

## 4. Validation Rules

- Dashboard signal cards must maintain freshness and target metadata.
- Alert lifecycle transitions must enforce state-machine integrity.
- Drill-down descriptors must preserve actor/workspace and dependency lineage.
- Remediation policy decisions must include role/tier/release context.
- SLO rollups must remain deterministic and window-consistent.
- Governance audit events must cover ingest, triage, remediation, and
  release-gate actions.

## 5. Acceptance Criteria (OST-00226)

`OST-00226` 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 signal cards, alerts, drill-down descriptors, remediation
   policy, SLO rollups, governance audits, and topology descriptors are
   documented.
4. Ownership boundaries and validation rules are explicit.
