# OSHUN Studio Cross-Domain Entity Model Runbook

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

- `docs/adr/ADR-0022-oshun-studio-cross-domain-entity-model.md`
- `docs/releases/v1/specs/studio-cross-domain-entity-model-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-cross-domain-entity-model-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioCrossDomainEntityModelWorkspace.tsx`
- `apps/oshun/web/src/analytics/studioCrossDomainEntityModelTelemetry.ts`

## Purpose

Define operational ownership, SLOs, incident playbooks, and escalation paths for
Studio cross-domain entity model governance workflows.

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

## 1. Ownership Model

| Surface                               | Primary Owner                      | Backup Owner       | Dependencies                              |
| ------------------------------------- | ---------------------------------- | ------------------ | ----------------------------------------- |
| Entity model workspace route          | OSHUN Web                          | Platform Web       | route + analytics contracts               |
| Canonical entity schema governance    | OSHUN Studio Architecture          | Domain Integrators | schema contracts + compatibility policies |
| Entity resolution contract validation | Navigation Platform                | Domain Integrators | route/action contracts                    |
| Relation graph integrity and lineage  | Domain Integrators + Data Platform | SRE                | graph sync + lineage pipelines            |
| Telemetry and audit pipeline          | Data Platform                      | SRE                | analytics sinks + ingestion pipelines     |

## 2. Core SLOs

| Metric                          | Target                      | Alert Threshold              |
| ------------------------------- | --------------------------- | ---------------------------- |
| Entity-model flow success rate  | >= 99.0%                    | < 98.0% over 15 min          |
| Envelope validation integrity   | 100% deterministic          | any false pass               |
| Resolution-contract coverage    | 100% governed types covered | any missing required mapping |
| Entity-model flow p95 latency   | <= 2200ms                   | > 3200ms over 15 min         |
| Entity-model audit completeness | >= 99.5%                    | < 99.0% over 15 min          |

## 3. Operational Playbooks

### 3.1 Canonical Envelope Publish Failures

Trigger: repeated `ENTITY_ENVELOPE_VALIDATION_FAILED` outcomes.

Actions:

1. Inspect envelope diagnostics for required fields and immutable identity
   constraints.
2. Validate schema versioning and extension namespace contracts.
3. Re-run publish in preview with validation logging enabled.
4. Roll back to the last certified schema bundle if needed.

### 3.2 Entity Resolution Contract Failures

Trigger: repeated `ENTITY_RESOLUTION_CONTRACTS_FAILED` outcomes.

Actions:

1. Identify entity types missing route/action mappings.
2. Validate required context contracts (`programId`, `projectId`,
   `workspaceId`).
3. Patch missing fallback routes and deterministic action capabilities.
4. Re-run validation and block promotion until all mappings pass.

### 3.3 Relation Graph Integrity Failures

Trigger: repeated `ENTITY_RELATION_GRAPH_INTEGRITY_FAILED` outcomes.

Actions:

1. Generate relation diagnostics for cycles and orphaned targets.
2. Quarantine invalid edges and restore authoritative references.
3. Re-run lineage continuity checks across all governed domains.
4. Freeze promotion until relation graph integrity is restored.

### 3.4 Policy Denial Spike

Trigger: unexpected increase in `ROLE_POLICY_DENIED` outcomes.

Actions:

1. Compare workspace flow policy map against entitlement contracts.
2. Verify recent identity payload/version 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 cross-domain entity-model 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/cross-domain-entity-model` 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 Cross-Domain Entity Model Incident
Detected: {timestamp}
Impact: {envelope/resolution/relation integrity impact}
Suspected cause: {schema regression | contract drift | lineage failure | policy drift}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio Cross-Domain Entity Model Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {canonicalEnvelopePublish | entityResolutionValidation | relationGraphSync}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio Cross-Domain Entity Model 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             |
| Schema governance and compatibility | `#oshun-architecture`  | Architecture council         |
| Route/action resolution contracts   | `#oshun-navigation`    | Navigation architecture lead |
| Policy and permissions              | `#oshun-security`      | Security lead                |
| Telemetry pipeline and reliability  | `#oshun-data-platform` | SRE lead                     |

## 7. Acceptance Criteria (OST-00080)

`OST-00080` is complete only when:

1. Ownership and decision authority are documented.
2. Cross-domain entity-model 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.
