# OSHUN Studio Metrics and Analytics Instrumentation Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Data/Analytics
Engineering  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.md`

## Purpose

Define dependencies and canonical contracts for Studio metrics and analytics
instrumentation capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and
Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.md`
- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/specs/studio-domain-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

- **Metrics/instrumentation UI surfaces**: Studio metrics modules in
  `apps/oshun/web/src/components/studio`.
- **Telemetry ingestion and normalization services**: BFF + analytics sink
  gateways for canonical event contracts.
- **KPI aggregation services**: rate/latency/reliability computation pipelines.
- **Audit-linkage services**: policy and governance event correlation pipelines.
- **Quality and governance controls**: schema validation, null-rate monitoring,
  and release-gate checks.

### 1.2 Domain Dependency Graph

- `Metrics/Instrumentation -> Yemaya`: release telemetry, publish-flow KPIs.
- `Metrics/Instrumentation -> Isis`: model workflow telemetry and reliability
  KPIs.
- `Metrics/Instrumentation -> Hathor`: narrative pipeline telemetry and quality
  KPIs.
- `Metrics/Instrumentation -> Aja`: timeline/render telemetry and latency KPIs.
- `Metrics/Instrumentation -> Bellona`: runtime/incident telemetry and recovery
  KPIs.
- `Project Obsidian -> all`: cross-domain KPI governance, comparability, and
  alerts.

## 2. Ownership and Contract Matrix

| Area                           | Owner                    | Consumers                     | Artifact               | Contract                            |
| ------------------------------ | ------------------------ | ----------------------------- | ---------------------- | ----------------------------------- |
| Canonical metric definitions   | Data/Analytics + Studio  | Product + operations          | Metric definition      | `StudioMetricDefinition`            |
| Flow-span instrumentation      | Web + BFF Engineering    | Observability + analytics     | Flow-span payload      | `StudioFlowTelemetrySpan`           |
| Audit-to-analytics linkage     | Security + Data Platform | Compliance + operations       | Linkage record         | `StudioAuditAnalyticsLinkage`       |
| KPI composition and thresholds | Data/Analytics           | Leadership + on-call          | KPI spec               | `StudioKpiCompositionSpec`          |
| Telemetry quality governance   | Platform SRE + Analytics | Release managers + on-call    | Quality snapshot       | `StudioTelemetryQualitySnapshot`    |
| Governance evidence export     | Data Platform + Security | Compliance + audit operations | Telemetry/audit export | `StudioMetricsGovernanceAuditEvent` |

## 3. Canonical Contracts

### 3.1 StudioMetricDefinition

```ts
export interface StudioMetricDefinition {
  metricId: string;
  metricName: string;
  metricType: 'counter' | 'gauge' | 'rate' | 'histogram';
  unit: 'count' | 'ms' | 'percent' | 'ratio';
  owner: string;
  aggregationWindow: '1m' | '5m' | '15m' | '1h' | '1d';
  alertThreshold?: number;
  updatedAt: string;
}
```

### 3.2 StudioFlowTelemetrySpan

```ts
export interface StudioFlowTelemetrySpan {
  spanId: string;
  flow: string;
  actorId: string;
  role: string;
  workspaceId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  startedAt: string;
  completedAt?: string;
  success?: boolean;
  latencyMs?: number;
  errorCode?: string;
}
```

### 3.3 StudioAuditAnalyticsLinkage

```ts
export interface StudioAuditAnalyticsLinkage {
  linkageId: string;
  auditEventId: string;
  analyticsEventName: string;
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  actorId: string;
  workspaceId: string;
  occurredAt: string;
}
```

### 3.4 StudioKpiCompositionSpec

```ts
export interface StudioKpiCompositionSpec {
  kpiId: string;
  kpiName: string;
  numeratorMetricId: string;
  denominatorMetricId?: string;
  calculation: 'sum' | 'avg' | 'ratio' | 'p95' | 'p99';
  targetValue: number;
  warningThreshold: number;
  criticalThreshold: number;
  updatedAt: string;
}
```

### 3.5 StudioTelemetryQualitySnapshot

```ts
export interface StudioTelemetryQualitySnapshot {
  snapshotId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  completenessRate: number;
  nullDimensionRate: number;
  duplicateSpanRate: number;
  schemaViolationRate: number;
  capturedAt: string;
}
```

### 3.6 StudioMetricsGovernanceAuditEvent

```ts
export interface StudioMetricsGovernanceAuditEvent {
  eventId: string;
  action:
    | 'metrics.definition.updated'
    | 'metrics.flow_span.completed'
    | 'metrics.audit_linkage.recorded'
    | 'metrics.kpi.threshold_breached'
    | 'metrics.quality.degraded'
    | 'metrics.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  metricId?: string;
  spanId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Metric definitions must include owner, unit, and threshold metadata.
- Flow spans must emit requested/completed lifecycle with stable IDs.
- Audit-linkage records must map to canonical analytics event names.
- KPI specs must include deterministic threshold and calculation semantics.
- Telemetry quality snapshots must enforce completeness and schema-violation
  checks.
- Governance audit events must capture definition, linkage, threshold, and
  quality outcomes end to end.

## 5. Acceptance Criteria (OST-00218)

`OST-00218` 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 metric definitions, flow spans, audit-linkage, KPI composition,
   quality snapshots, and governance audit events are documented.
4. Ownership boundaries and validation rules are explicit.
