# OSHUN Studio RBAC and Permission Policy UX Runbook

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Security + Platform Identity + OSHUN
Web + OSHUN BFF  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0027-oshun-studio-rbac-and-permission-policy-ux.md`
- `docs/releases/v1/specs/studio-rbac-and-permission-policy-ux-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-rbac-and-permission-policy-ux-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioRbacPermissionPolicyUxWorkspace.tsx`
- `apps/oshun/web/src/analytics/studioRbacPermissionPolicyUxTelemetry.ts`

## Purpose

Define operational ownership, SLOs, incident playbooks, and escalation paths for
Studio RBAC and permission policy UX governance workflows.

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

## 1. Ownership Model

| Surface                                | Primary Owner                 | Backup Owner | Dependencies                          |
| -------------------------------------- | ----------------------------- | ------------ | ------------------------------------- |
| RBAC/policy UX route                   | OSHUN Web                     | Platform Web | route + analytics contracts           |
| Role catalog and entitlement contracts | Platform Identity + Security  | BFF          | role schemas + entitlement APIs       |
| Policy decision and reason codes       | Security + Program Governance | Identity     | policy engine + governance contracts  |
| Deny remediation UX content            | OSHUN Web + Security UX       | Program Ops  | reason mapping + escalation playbooks |
| Telemetry and audit evidence           | Data Platform                 | SRE          | event sinks + ingestion pipelines     |

## 2. Core SLOs

| Metric                           | Target                   | Alert Threshold      |
| -------------------------------- | ------------------------ | -------------------- |
| RBAC policy UX flow success rate | >= 99.0%                 | < 98.0% over 15 min  |
| Policy decision correctness      | 100% deterministic       | any false allow      |
| Deny-guidance coverage           | 100% mapped reason codes | any unmapped deny    |
| RBAC policy UX flow p95 latency  | <= 2200ms                | > 3200ms over 15 min |
| Permission audit completeness    | >= 99.5%                 | < 99.0% over 15 min  |

## 3. Operational Playbooks

### 3.1 Role Catalog Sync Failures

Trigger: repeated `RBAC_ROLE_CATALOG_SYNC_FAILED` outcomes.

Actions:

1. Validate role-catalog service health and schema versions.
2. Inspect missing/invalid role mappings and entitlement bundles.
3. Re-run sync in preview with schema diagnostics enabled.
4. Block policy UX promotion until role consistency is restored.

### 3.2 Permission Decision Simulation Failures

Trigger: repeated `RBAC_PERMISSION_DECISION_SIMULATION_FAILED` outcomes.

Actions:

1. Validate policy bundle versions and decision engine availability.
2. Verify entitlement-to-action mapping integrity.
3. Re-run simulation with trace correlation enabled.
4. Block production promotion until deterministic outcomes pass.

### 3.3 Deny Guidance Publish Failures

Trigger: repeated `RBAC_DENY_GUIDANCE_PUBLISH_FAILED` outcomes.

Actions:

1. Validate deny reason-code registry completeness.
2. Inspect remediation content contract and escalation mappings.
3. Republish guidance bundle after contract correction.
4. Verify all active deny outcomes resolve to guidance entries.

### 3.4 Policy Denial Spike

Trigger: unexpected increase in `ROLE_POLICY_DENIED` outcomes.

Actions:

1. Compare active policy allowlists to entitlement contracts.
2. Validate recent role/entitlement payload changes.
3. Apply policy hotfix or rollback entitlement drift.
4. Confirm deny-rate normalization after mitigation.

### 3.5 Telemetry and Audit Degradation

Trigger: missing or delayed RBAC/policy UX telemetry events.

Actions:

1. Validate analytics sink health and ingestion queue depth.
2. Enable degraded-observability warning in workspace.
3. Reconcile missed events from buffered traces.
4. Confirm event completeness and SLO recovery.

## 4. Release Checklist

- [ ] Validate `/studio/rbac-permission-policy` renders and executes required
      flows.
- [ ] Validate optimistic, error, and retry behavior for each flow.
- [ ] Validate role-policy allow/deny behavior.
- [ ] Validate telemetry/audit emissions and SLO panel updates.
- [ ] Validate integration/e2e/accessibility evidence artifacts.

## 5. Incident Communication Templates

### Incident Start

```
[P{severity}] Studio RBAC and Permission Policy UX Incident
Detected: {timestamp}
Impact: {role catalog | permission decision | deny guidance impact}
Suspected cause: {identity drift | policy engine issue | guidance mapping regression}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio RBAC and Permission Policy UX Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {roleCatalogSync | permissionDecisionSimulation | denyGuidancePublish}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio RBAC and Permission Policy UX Incident Resolved
Resolved: {timestamp}
Root cause: {description}
Fix: {release/hotfix id}
Validation: {tests + telemetry checks}
Postmortem: {link}
```

## 6. Escalation Paths

| Area                               | Primary Channel        | Escalate To                |
| ---------------------------------- | ---------------------- | -------------------------- |
| Web runtime and workspace          | `#oshun-web`           | Platform on-call           |
| Identity and role contracts        | `#oshun-identity`      | Identity architecture lead |
| Policy decisions and governance    | `#oshun-security`      | Security lead              |
| Deny-guidance UX and content       | `#oshun-product`       | Studio design lead         |
| Telemetry pipeline and reliability | `#oshun-data-platform` | SRE lead                   |

## 7. Acceptance Criteria (OST-00120)

`OST-00120` is complete only when:

1. Ownership and decision authority are documented.
2. RBAC/policy UX SLOs and alert thresholds are documented.
3. At least five playbooks are documented for major failure modes.
4. Release checklist, communication templates, and escalation paths exist.
