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.mddocs/releases/v1/specs/studio-notification-center-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio notification center governance.
This document is the execution artifact for OST-00139.
Personas#
- Program Operator
- Security Reviewer
- Domain Integrator
- Reliability Engineer
- Compliance Auditor
Journey Principles#
- Critical notifications must be visible, actionable, and escalatable.
- Notification state transitions must be deterministic and auditable.
- Deduplication must reduce noise without losing signal integrity.
- Triage workflows must preserve context and accountability.
1. Primary Journeys#
J1. Notification Feed Triage and Prioritization#
Goal: Triage incoming notifications by severity, domain, and recency.
Entry: Studio -> Notification Center
Steps:
- Load notification feed with priority ordering.
- Apply filters for severity/domain/state.
- Review summary + context links.
- Select highest-priority actionable items.
- Move items into acknowledgement/assignment workflows.
Success State:
- Operator can quickly identify and act on critical signals.
J2. Acknowledge and Assign Workflow#
Goal: Acknowledge ownership and assign notifications to responders.
Entry: Selected actionable notification
Steps:
- Acknowledge notification.
- Assign to responsible owner/role.
- Add handling notes/context.
- Confirm state transition to assigned.
- Emit workflow audit evidence.
Success State:
- Notification ownership is explicit and tracked.
J3. Resolve and Close Notification Loop#
Goal: Resolve notification once remediation is complete.
Entry: Assigned notification with remediation complete
Steps:
- Validate remediation evidence.
- Mark notification resolved.
- Attach closure rationale.
- Confirm no unresolved dependencies remain.
- Emit closure audit record.
Success State:
- Notification lifecycle is closed with traceable evidence.
J4. Escalation of Unresolved Critical Alerts#
Goal: Escalate unresolved critical notifications automatically or manually.
Entry: Critical notification timeout or Manual escalation
Steps:
- Detect escalation trigger.
- Route escalation to target channel/on-call.
- Record escalation metadata.
- Track acknowledgement status.
- Close escalation after incident handoff.
Success State:
- Critical alerts are escalated deterministically with ownership trace.
J5. Deduplication and Signal Integrity Review#
Goal: Validate deduplicated notifications preserve actionable context.
Entry: High-volume duplicate signal burst
Steps:
- Evaluate dedupe key and grouping policy.
- Collapse duplicate notifications.
- Preserve count and latest context.
- Verify grouped item remains actionable.
- Record dedupe decision evidence.
Success State:
- Noise is reduced while preserving operational signal integrity.
2. Critical Edge Cases#
E1. Missing Notification ID#
- Trigger: incoming payload missing
notificationId. - Required behavior: reject payload and emit ingestion error.
E2. Invalid Severity Classification#
- Trigger: payload severity outside supported enum.
- Required behavior: route to fallback class and flag schema error.
E3. Duplicate Deduplication Key Collision#
- Trigger: unrelated notifications share same dedupe key.
- Required behavior: prevent merge and escalate dedupe-rule review.
E4. Unauthorized Acknowledge Attempt#
- Trigger: actor lacks permission to acknowledge notification.
- Required behavior: deny action and preserve state.
E5. Unauthorized Assignment Attempt#
- Trigger: actor assigns notification without entitlement.
- Required behavior: deny action and surface policy guidance.
E6. Resolve Without Evidence#
- Trigger: resolve action submitted without remediation evidence.
- Required behavior: block resolve and require closure context.
E7. Escalation Channel Unavailable#
- Trigger: escalation target channel not reachable.
- Required behavior: retry and route to fallback escalation path.
E8. Escalation Looping#
- Trigger: same notification repeatedly escalated without state change.
- Required behavior: enforce escalation cooldown and manual review.
E9. Telemetry/Audit Emission Failure#
- Trigger: notification lifecycle events fail to emit.
- Required behavior: buffer/retry and surface degraded observability warning.
E10. Missing Rollback Reference for Notification Release#
- Trigger: notification-center release lacks rollback contract reference.
- Required behavior: block production promotion.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Notification Feed Triage and Prioritization | Notification Center | Domain emitters |
| J2 Acknowledge and Assign Workflow | Notification Center | Assignment services |
| J3 Resolve and Close Notification Loop | Notification Center | Governance workflows |
| J4 Escalation of Unresolved Critical Alerts | Notification Center | Incident response |
| J5 Deduplication and Signal Integrity Review | Notification Center | BFF dedupe engine |
4. Instrumentation Requirements#
Required events:
notification_center.journey.startednotification_center.journey.step.completednotification_center.journey.blockednotification_center.journey.recoverednotification_center.journey.completed
Required dimensions:
notificationId,actorId,actorRolejourneyId,stepId,severity,dedupeKeyoutcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00139)#
OST-00139 is complete only when:
- At least five notification-center journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.