# OSHUN Studio Performance Budgets 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-0043-oshun-studio-performance-budgets.md`

## Purpose

Define dependencies and canonical contracts for Studio performance-budget
governance across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## 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`
- `docs/adr/ADR-0042-oshun-studio-experimentation-and-feature-flags.md`
- `docs/adr/ADR-0043-oshun-studio-performance-budgets.md`
- `apps/oshun/web/src/lib/hooks/use-web-vitals.ts`
- `apps/oshun/web/src/observability/performance-telemetry.ts`
- `apps/oshun/web/src/__tests__/performance-web-vitals.test.ts`
- `apps/oshun/web/src/__tests__/performance-bundle.test.ts`
- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `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

- **Performance budget workspace UI surfaces**: Studio performance modules in
  `apps/oshun/web/src/components/studio`.
- **Telemetry collection services**: web-vitals and runtime performance emitters
  in web shell runtime.
- **Budget policy services**: role/tier-aware budget enforcement and waiver
  controls.
- **Validation services**: CI tests and release gates for budget assertions.
- **Observability services**: dashboards for budget breach detection and
  remediation tracking.
- **Governance services**: audit evidence and exception approval workflows.

### 1.2 Domain Dependency Graph

- `Performance Budgets -> Yemaya`: release/workspace publish latency budgets.
- `Performance Budgets -> Isis`: model interaction and inference flow budgets.
- `Performance Budgets -> Hathor`: narrative editing and composition latency
  budgets.
- `Performance Budgets -> Aja`: timeline/render orchestration budgets.
- `Performance Budgets -> Bellona`: runtime safety and kill-switch interaction
  budgets.
- `Project Obsidian -> all`: cross-domain release gate and budget-governance
  orchestration.

## 2. Ownership and Contract Matrix

| Area                                   | Owner                    | Consumers                          | Artifact                  | Contract                                 |
| -------------------------------------- | ------------------------ | ---------------------------------- | ------------------------- | ---------------------------------------- |
| Budget definition registry             | Platform Engineering     | Web + BFF + domain operators       | Budget definition records | `StudioPerformanceBudgetDefinition`      |
| Budget measurement and attribution     | Web + Data Platform      | Observability + release governance | Measurement events        | `StudioPerformanceBudgetMeasurement`     |
| Budget policy and waiver decisions     | Security + Compliance    | Operators + release managers       | Policy decision envelope  | `StudioPerformanceBudgetPolicyDecision`  |
| Budget validation and release gate     | Platform SRE + Program   | CI/release orchestrators           | Validation result stream  | `StudioPerformanceBudgetValidationEvent` |
| Budget breach incident and remediation | Platform SRE + Security  | Incident responders + domain teams | Breach/remediation events | `StudioPerformanceBudgetBreachEvent`     |
| Governance audit evidence              | Security + Data Platform | Compliance + audit operations      | Audit event stream        | `StudioPerformanceBudgetAuditEvent`      |

## 3. Canonical Contracts

### 3.1 StudioPerformanceBudgetDefinition

```ts
export interface StudioPerformanceBudgetDefinition {
  budgetId: string;
  budgetKey: string;
  owner: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  workflowRef: string;
  budgetTier: 'tier_1_critical' | 'tier_2_operational' | 'tier_3_supporting';
  metric: 'lcp_ms' | 'inp_ms' | 'cls_score' | 'tti_ms' | 'flow_p95_ms';
  threshold: number;
  releaseChannelScope: 'preview' | 'staging' | 'production' | 'all';
  expiresAt: string;
  createdAt: string;
  updatedAt: string;
}
```

### 3.2 StudioPerformanceBudgetMeasurement

```ts
export interface StudioPerformanceBudgetMeasurement {
  eventId: string;
  budgetId: string;
  budgetKey: string;
  workspaceId: string;
  actorId?: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  releaseChannel: 'preview' | 'staging' | 'production';
  metric: 'lcp_ms' | 'inp_ms' | 'cls_score' | 'tti_ms' | 'flow_p95_ms';
  measuredValue: number;
  withinBudget: boolean;
  window: '1m' | '5m' | '15m' | '1h';
  occurredAt: string;
}
```

### 3.3 StudioPerformanceBudgetPolicyDecision

```ts
export interface StudioPerformanceBudgetPolicyDecision {
  decisionId: string;
  budgetId: string;
  action:
    | 'waiver_create'
    | 'waiver_extend'
    | 'waiver_revoke'
    | 'release_block'
    | 'release_allow';
  actorId: string;
  actorRole: string;
  permissionTier: 'baseline' | 'sensitive' | 'restricted';
  releaseChannel: 'preview' | 'staging' | 'production';
  approvalTicket?: string;
  outcome: 'allowed' | 'denied';
  reasonCode?: string;
  decidedAt: string;
}
```

### 3.4 StudioPerformanceBudgetValidationEvent

```ts
export interface StudioPerformanceBudgetValidationEvent {
  eventId: string;
  budgetId: string;
  validationSource: 'ci' | 'runtime' | 'release_gate';
  status: 'pass' | 'warning' | 'fail';
  failingMetrics: string[];
  testArtifactRef?: string;
  releaseCandidateRef?: string;
  occurredAt: string;
}
```

### 3.5 StudioPerformanceBudgetBreachEvent

```ts
export interface StudioPerformanceBudgetBreachEvent {
  eventId: string;
  budgetId: string;
  breachSeverity: 'warning' | 'high' | 'critical';
  metric: 'lcp_ms' | 'inp_ms' | 'cls_score' | 'tti_ms' | 'flow_p95_ms';
  measuredValue: number;
  threshold: number;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  incidentId?: string;
  remediationAction?: string;
  occurredAt: string;
}
```

### 3.6 StudioPerformanceBudgetAuditEvent

```ts
export interface StudioPerformanceBudgetAuditEvent {
  eventId: string;
  action:
    | 'performance_budget.definition.created'
    | 'performance_budget.measurement.recorded'
    | 'performance_budget.policy.denied'
    | 'performance_budget.validation.failed'
    | 'performance_budget.breach.detected'
    | 'performance_budget.remediation.executed';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  budgetId?: string;
  actorId?: string;
  actorRole?: string;
  reasonCode?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Budget definitions must include owner, tier, metric, threshold, and expiry.
- Measurements must include budget identity, metric context, and within-budget
  verdict.
- Policy decisions must enforce role/tier/approval constraints by channel/tier.
- Validation events must record source (`ci`, `runtime`, `release_gate`) and
  deterministic status.
- Breach events must link measured values, thresholds, domain attribution, and
  incident/remediation references.
- Audit events must capture definition, measurement, policy, validation, and
  remediation actions end to end.

## 5. Acceptance Criteria (OST-00242)

`OST-00242` 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 budget definitions, measurements, policy decisions, validation,
   breach/remediation, and governance audits are documented.
4. Ownership boundaries and validation rules are explicit.
