# OSHUN Studio SDK and Documentation Integration Runbook

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Developer
Experience + OSHUN Security + Platform SRE + OSHUN Data/Analytics Engineering +
Program Operations  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0048-oshun-studio-sdk-and-documentation-integration.md`
- `docs/releases/v1/specs/studio-sdk-and-documentation-integration-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-sdk-and-documentation-integration-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioSdkDocumentationIntegrationWorkspace.tsx`
- `apps/oshun/web/src/analytics/studioSdkDocumentationIntegrationTelemetry.ts`

## Purpose

Define operational ownership, SLOs, incident playbooks, and escalation paths for
Studio SDK and documentation integration workflows.

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

## 1. Ownership Model

| Surface                                        | Primary Owner                   | Backup Owner       | Dependencies                                              |
| ---------------------------------------------- | ------------------------------- | ------------------ | --------------------------------------------------------- |
| SDK/docs integration workspace route           | OSHUN Web                       | Platform Web       | workflow UX orchestration + release visibility            |
| Contract source registry and lifecycle         | OSHUN BFF + Studio Architecture | Platform SRE       | contract schemas + digest/version governance              |
| SDK generation and package publication         | Developer Experience            | BFF platform       | codegen pipelines + artifact registries                   |
| Documentation assembly and publication         | Developer Experience + Web      | Program Operations | API reference/guides/samples + publication channels       |
| Policy/approval controls for sensitive actions | Security + Compliance           | Program Operations | role/tier governance + CAB evidence                       |
| Telemetry and governance audit continuity      | Data Platform + Security        | Platform SRE       | analytics sinks + retention/export controls + replay path |

## 2. Core SLOs

| Metric                                    | Target    | Alert Threshold      |
| ----------------------------------------- | --------- | -------------------- |
| SDK/docs integration flow success rate    | >= 99.0%  | < 98.0% over 15 min  |
| Contract-to-artifact consistency          | >= 99.5%  | < 99.0% over 15 min  |
| Generation/publication/recovery flow p95  | <= 2500ms | > 3500ms over 15 min |
| Sample-validation pass continuity         | >= 99.5%  | < 99.0% over 15 min  |
| Policy-tier/CAB enforcement correctness   | >= 99.5%  | < 99.0% over 15 min  |
| Drift incident closure determinism        | >= 99.5%  | < 99.0% over 15 min  |
| Telemetry/audit event delivery continuity | >= 99.5%  | < 99.0% over 15 min  |

## 3. Operational Playbooks

### 3.1 Contract Promotion Failures

Trigger: repeated `SDK_DOCS_CONTRACT_PROMOTION_FAILED` outcomes.

Actions:

1. Validate contract identity (`contractId`, `version`, `digest`, lifecycle).
2. Inspect compatibility checks and migration guidance artifacts.
3. Re-run promotion in preview with diagnostics enabled.
4. Block downstream SDK/docs publication until contract integrity recovers.

### 3.2 SDK Generation or Publication Failures

Trigger: repeated `SDK_DOCS_SDK_GENERATION_FAILED` outcomes.

Actions:

1. Validate codegen input contract and target language profile.
2. Inspect compile/type-test failures and package metadata drift.
3. Re-run generation against known-good toolchain baseline.
4. Escalate to Developer Experience on sustained generation regressions.

### 3.3 Documentation Publication Failures

Trigger: repeated `SDK_DOCS_DOCUMENTATION_PUBLISH_FAILED` outcomes.

Actions:

1. Validate reference/guides/sample bundle completeness.
2. Inspect publish-channel health and release metadata integrity.
3. Re-run publication after dependency verification.
4. Preserve release hold until documentation integrity is restored.

### 3.4 Sample Validation Drift

Trigger: repeated `SDK_DOCS_SAMPLE_VALIDATION_FAILED` outcomes.

Actions:

1. Validate sample bindings against active contract and SDK versions.
2. Inspect runtime fixture drift and stale snippet dependencies.
3. Re-run sample validation across target language/runtime profiles.
4. Block promotion to production until sample parity recovers.

### 3.5 Sensitive Publish/Rollback Policy Failures

Trigger: repeated `SDK_DOCS_POLICY_DECISION_FAILED` outcomes.

Actions:

1. Validate role/tier/CAB prerequisites and reason codes.
2. Inspect policy bundle drift and deny-path anomalies.
3. Re-run decision with compliance-auditor oversight.
4. Freeze production publish/rollback path while policy integrity is degraded.

### 3.6 SDK/Docs Consistency Recovery Failures

Trigger: repeated `SDK_DOCS_CONSISTENCY_RECOVERY_FAILED` outcomes.

Actions:

1. Validate incident-state and remediation-action preconditions.
2. Verify post-remediation SDK/docs/contract alignment checks.
3. Re-run recovery flow under incident command oversight.
4. Prevent incident closure until deterministic revalidation is complete.

### 3.7 Telemetry and Audit Degradation

Trigger: missing or delayed `studio_sdk_documentation_integration_*` telemetry
events.

Actions:

1. Validate analytics sink health and ingestion backlog.
2. Enable degraded-observability notice in SDK/docs workspace.
3. Replay buffered events where replay semantics are supported.
4. Confirm SLO panel and audit-evidence continuity after recovery.

## 4. Release Checklist

- [ ] Validate `/studio/sdk-documentation-integration` renders and executes
      required flows.
- [ ] Validate optimistic, error, and retry behavior across all SDK/docs
      integration flows.
- [ ] Validate permission-tier and production CAB policy enforcement.
- [ ] Validate telemetry/audit emissions and SLO panel updates.
- [ ] Validate integration/e2e/accessibility/performance evidence artifacts.

## 5. Incident Communication Templates

### Incident Start

```text
[P{severity}] Studio SDK/Docs Integration Incident
Detected: {timestamp}
Impact: {contract-promotion | sdk-generation | docs-publication | policy-decision | consistency-recovery}
Suspected cause: {contract drift | toolchain regression | policy drift | sample validation drift | telemetry degradation}
Owner: {on-call}
```

### Incident Update

```text
[P{severity}] Studio SDK/Docs Integration Update
Time: {timestamp}
Mitigation: {rollback | hotfix | policy patch | republish | release hold}
Affected flows: {promoteContractVersion | generateSdkArtifact | publishDocumentationRelease | decideSensitivePublishRollback | recoverSdkDocsConsistency}
ETA: {time}
```

### Incident Resolved

```text
[P{severity}] Studio SDK/Docs Integration 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           |
| ---------------------------------------- | ---------------------- | --------------------- |
| SDK/docs integration workspace UX        | `#oshun-web`           | Platform on-call      |
| Contract registry and codegen APIs       | `#oshun-bff`           | BFF lead              |
| SDK generation and package publication   | `#oshun-developer-exp` | DX lead               |
| Policy-tier/CAB governance controls      | `#oshun-security`      | Security + Compliance |
| Telemetry and audit reporting continuity | `#oshun-data-platform` | Data platform lead    |

## 7. Acceptance Criteria (OST-00288)

`OST-00288` is complete only when:

1. Ownership and decision authority are documented.
2. SDK/docs integration 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.
