# ADR-0030: OSHUN Studio Notification Center

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, OSHUN
Security  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio workflows generate high volumes of system, policy, review, and incident
signals. Existing notification patterns are distributed across surfaces and do
not provide one authoritative center for triage, prioritization, and action.

Without a first-class Studio notification center, OSHUN risks:

- missed high-priority governance alerts
- inconsistent triage and acknowledgement workflows
- duplicate/fragmented notification handling across domains
- weak auditability of notification response actions

## Decision Drivers

- **Operational responsiveness**: faster triage and action on critical alerts.
- **Consistency**: unified notification model across Studio domains.
- **Signal quality**: deduplicated, prioritized, actionable notification feed.
- **Traceability**: auditable acknowledgement and response actions.
- **Interoperability**: align with Yemaya/Isis/Hathor/Aja/Bellona + Project
  Obsidian.

## Considered Options

### Option 1: Keep Notifications Embedded in Each Surface

Continue handling notification cues in individual Studio pages only.

**Pros**:

- Minimal near-term implementation effort.

**Cons**:

- Fragmented signal handling and higher miss risk.
- No unified triage workflow.

### Option 2: Basic Unified Feed Without Workflow Semantics

Aggregate notifications in one list but without priorities/escalation states.

**Pros**:

- Better visibility than fragmented model.

**Cons**:

- Limited actionability for governance-critical signals.
- Weak workflow and compliance traceability.

### Option 3: Unified Notification Center with Priority + Action Contracts (Chosen)

Adopt one Studio notification center contract with canonical payloads,
prioritization, deduplication, acknowledgement semantics, and escalation flows.

**Pros**:

- Deterministic triage and response behavior.
- Better incident and governance responsiveness.
- Stronger audit/compliance traceability for notification handling.

**Cons**:

- Additional schema/governance complexity.

## Decision Outcome

**Chosen option**: Option 3.

Notification center requirements:

1. **Notification payload contract** for canonical
   actor/source/severity/context.
2. **Priority and deduplication contract** for ordering and signal collapse.
3. **Action workflow contract** for acknowledge, assign, resolve, escalate.
4. **Compatibility contract** for schema/version and routing evolution.
5. **Release governance** with validation, approval, telemetry/audit, and
   rollback.

## Normative Rules

### Notification Payload Contract

- Notifications must include stable id, source, severity, summary, and context.
- Every actionable notification must link to target workflow context.
- Invalid payloads must be rejected from production feed rendering.

### Priority and Deduplication Contract

- Notifications must use deterministic severity/priority classification.
- Duplicate signals for same incident context must collapse with counters.
- Critical notifications must surface above lower-severity items.

### Action Workflow Contract

- Notification actions must support acknowledge, assign, resolve, and escalate.
- Action state transitions must be deterministic and auditable.
- Unresolved critical notifications must trigger escalation workflows.

### Compatibility Contract

- Payload schema changes require compatibility checks.
- Breaking changes require migration guidance and rollback references.
- Domain routing metadata must remain backward compatible.

### Release Validity Contract

A notification-center release is valid only when all are true:

- payload validation checks pass
- priority/deduplication behavior passes deterministic tests
- action workflow transitions pass integrity checks
- telemetry/audit records are complete
- rollback strategy is documented

## Architecture Implications

- Studio web surfaces expose centralized notification center workflows.
- BFF orchestrates notification ingestion, deduplication, and state transitions.
- Domain adapters emit canonical notification payloads into shared pipelines.
- Analytics pipelines capture notification triage and response outcomes.

## Acceptance Criteria (OST-00137)

`OST-00137` is complete only when:

1. ADR exists at `docs/adr/ADR-0036-oshun-studio-notification-center.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines notification payload, priority/deduplication, action workflow,
   compatibility, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0029`, especially `ADR-0012`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/analytics`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Faster and more reliable response to governance-critical signals.
- Consistent notification handling across all Studio domains.
- Improved audit/compliance evidence for alert lifecycle handling.

### Negative

- Increased schema and deduplication governance complexity.
- Requires strict notification routing and payload quality controls.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0035-oshun-studio-audit-and-compliance-surfaces.md`

## References

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `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`