# OSHUN Studio Notification Center Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Security  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0030-oshun-studio-notification-center.md`

## Purpose

Define dependencies and canonical contracts for Studio notification center
capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0030-oshun-studio-notification-center.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

- **Notification center UI**: Studio notification surfaces in
  `apps/oshun/web/src/components/studio`.
- **Notification ingestion and deduplication**: BFF notification services.
- **Domain signal emitters**: domain adapters producing canonical notifications.
- **Action workflow orchestration**: acknowledge/assign/resolve/escalate
  services.
- **Telemetry and audit**: analytics + compliance pipelines.

### 1.2 Domain Dependency Graph

- `Notification Center -> Yemaya`: content and collaboration events feed triage.
- `Notification Center -> Isis`: workflow/model signals drive review alerts.
- `Notification Center -> Hathor`: narrative publication and policy alerts feed
  center.
- `Notification Center -> Aja`: media timeline events require priority routing.
- `Notification Center -> Bellona`: build/runtime incidents require critical
  escalation.
- `Project Obsidian -> all`: central governance for signal policies and
  escalation.

## 2. Ownership and Contract Matrix

| Area                             | Owner                    | Consumers               | Artifact                  | Contract                             |
| -------------------------------- | ------------------------ | ----------------------- | ------------------------- | ------------------------------------ |
| Canonical notification payload   | BFF + Domain Integrators | Notification center UI  | Notification payload      | `StudioNotificationEnvelope`         |
| Priority and deduplication model | OSHUN BFF + Security     | Studio operators        | Priority payload          | `StudioNotificationPriorityDecision` |
| Notification action transitions  | Web + BFF                | Ops + Security          | Action transition payload | `StudioNotificationActionTransition` |
| Escalation workflow contract     | Security + Program Ops   | Incident response       | Escalation payload        | `StudioNotificationEscalationRecord` |
| Audit/compliance evidence        | Data Platform + Security | Compliance + Governance | Event stream              | `StudioNotificationAuditEvent`       |

## 3. Canonical Contracts

### 3.1 StudioNotificationEnvelope

```ts
export interface StudioNotificationEnvelope {
  notificationId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  category: string;
  severity: 'info' | 'warning' | 'critical';
  title: string;
  summary: string;
  contextRoute?: string;
  createdAt: string;
}
```

### 3.2 StudioNotificationPriorityDecision

```ts
export interface StudioNotificationPriorityDecision {
  notificationId: string;
  priorityScore: number;
  severity: 'info' | 'warning' | 'critical';
  dedupeKey?: string;
  dedupedCount: number;
  decidedAt: string;
}
```

### 3.3 StudioNotificationActionTransition

```ts
export interface StudioNotificationActionTransition {
  transitionId: string;
  notificationId: string;
  action: 'acknowledge' | 'assign' | 'resolve' | 'escalate';
  actorId: string;
  actorRole: string;
  fromState: 'new' | 'acknowledged' | 'assigned' | 'resolved' | 'escalated';
  toState: 'acknowledged' | 'assigned' | 'resolved' | 'escalated';
  occurredAt: string;
}
```

### 3.4 StudioNotificationEscalationRecord

```ts
export interface StudioNotificationEscalationRecord {
  escalationId: string;
  notificationId: string;
  trigger: 'critical_timeout' | 'manual' | 'policy_rule';
  targetChannel: string;
  escalatedBy: string;
  status: 'pending' | 'notified' | 'acknowledged' | 'closed';
  escalatedAt: string;
}
```

### 3.5 StudioNotificationAuditEvent

```ts
export interface StudioNotificationAuditEvent {
  eventId: string;
  action:
    | 'notification.received'
    | 'notification.deduplicated'
    | 'notification.acknowledged'
    | 'notification.assigned'
    | 'notification.resolved'
    | 'notification.escalated';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  notificationId: string;
  actorId?: string;
  actorRole?: string;
  severity: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Notification center must reject payloads missing canonical id/source/severity
  fields.
- Deduplication must preserve one active record with accurate deduped count.
- Action transitions must enforce valid state progression.
- Escalation triggers must be auditable and policy-consistent.

## 5. Acceptance Criteria (OST-00138)

`OST-00138` 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 notification envelope, priority decision, action transition,
   escalation record, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
