Eve library

OSHUN Studio Notification Center Dependency and Data Contract Map

Spec

Revision 1

On this page

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.