# OSHUN Studio Session and Device Management Runbook

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

- `docs/adr/ADR-0026-oshun-studio-session-and-device-management.md`
- `docs/releases/v1/specs/studio-session-and-device-management-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-session-and-device-management-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioSessionDeviceManagementWorkspace.tsx`
- `apps/oshun/web/src/analytics/studioSessionDeviceManagementTelemetry.ts`

## Purpose

Define operational ownership, SLOs, incident playbooks, and escalation paths for
Studio session and device management governance workflows.

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

## 1. Ownership Model

| Surface                                | Primary Owner                 | Backup Owner         | Dependencies                       |
| -------------------------------------- | ----------------------------- | -------------------- | ---------------------------------- |
| Session/device management route        | OSHUN Web                     | Platform Web         | route + analytics contracts        |
| Session inventory contracts            | Platform Identity             | BFF                  | session schema + identity services |
| Trusted-device challenge orchestration | Security + Platform Identity  | Security Engineering | challenge providers + risk policy  |
| Revocation execution and propagation   | OSHUN BFF + Platform Identity | Domain Integrators   | revoke APIs + domain adapters      |
| Telemetry and audit evidence           | Data Platform                 | SRE                  | event sinks + ingestion pipelines  |

## 2. Core SLOs

| Metric                              | Target             | Alert Threshold                  |
| ----------------------------------- | ------------------ | -------------------------------- |
| Session/device flow success rate    | >= 99.0%           | < 98.0% over 15 min              |
| Session inventory integrity         | 100% deterministic | any malformed inventory accepted |
| Revocation propagation completeness | >= 99.5%           | < 99.0% over 15 min              |
| Session/device flow p95 latency     | <= 2200ms          | > 3200ms over 15 min             |
| Session/device audit completeness   | >= 99.5%           | < 99.0% over 15 min              |

## 3. Operational Playbooks

### 3.1 Session Inventory Sync Failures

Trigger: repeated `SESSION_INVENTORY_SYNC_FAILED` outcomes.

Actions:

1. Validate identity/session service health and payload schema freshness.
2. Inspect inventory records for missing/duplicate session metadata.
3. Re-run sync in preview with schema diagnostics enabled.
4. Block privileged controls until inventory consistency is restored.

### 3.2 Trusted Device Enrollment Failures

Trigger: repeated `TRUSTED_DEVICE_ENROLLMENT_FAILED` outcomes.

Actions:

1. Validate challenge provider health and attestation contract versions.
2. Verify selected device eligibility and trust state.
3. Re-run challenge in controlled mode with trace correlation.
4. Keep device untrusted until deterministic enrollment succeeds.

### 3.3 Session Revocation Execution Failures

Trigger: repeated `SESSION_REVOCATION_EXECUTION_FAILED` outcomes.

Actions:

1. Validate revoke request scope and target resolution.
2. Inspect propagation status across enabled Studio domains.
3. Retry failed adapters and reconcile partial revocation outcomes.
4. Escalate unresolved targets with manual containment guidance.

### 3.4 Policy Denial Spike

Trigger: unexpected increase in `ROLE_POLICY_DENIED` outcomes.

Actions:

1. Compare flow policy map against active role entitlements.
2. Validate identity claims and role payload version alignment.
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 session/device telemetry events.

Actions:

1. Validate analytics sink health and 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/session-device-management` 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 Session and Device Management Incident
Detected: {timestamp}
Impact: {inventory | trust enrollment | revocation impact}
Suspected cause: {identity service issue | challenge provider issue | propagation drift}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio Session and Device Management Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {sessionInventorySync | trustedDeviceEnrollment | sessionRevocationExecution}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio Session and Device Management 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/session contracts         | `#oshun-identity`      | Identity architecture lead |
| Challenge and trust policy         | `#oshun-security`      | Security engineering lead  |
| Revocation propagation runtime     | `#oshun-bff`           | BFF architecture lead      |
| Telemetry pipeline and reliability | `#oshun-data-platform` | SRE lead                   |

## 7. Acceptance Criteria (OST-00112)

`OST-00112` is complete only when:

1. Ownership and decision authority are documented.
2. Session/device management 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.
