# OSHUN Studio SDK and Documentation Integration Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Developer
Experience + OSHUN Security + Platform SRE + OSHUN Data/Analytics Engineering  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0048-oshun-studio-sdk-and-documentation-integration.md`

## Purpose

Define dependencies and canonical contracts for Studio SDK and documentation
integration across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0048-oshun-studio-sdk-and-documentation-integration.md`
- `apps/oshun/bff/openapi/oshun-bff.openapi.yaml`
- `apps/oshun/bff/README.md`
- `apps/iris/api/src/docs/index.ts`
- `apps/isis/cli/src/commands/generate.ts`
- `apps/lilith/svc-ai/src/integration-api/index.ts`
- `libs/nyx/client-python/README.md`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`
- `docs/releases/v1/runbooks/on-call-runbook.md`
- `docs/domains/yemaya/features.md`
- `docs/domains/isis/features.md`
- `docs/domains/hathor/features.md`
- `docs/domains/aja/features.md`
- `docs/domains/bellona/features.md`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Contract authority surfaces**: OpenAPI/spec registries and schema version
  governance.
- **SDK generation surfaces**: typed client generation pipelines and packaging
  workflows.
- **Documentation assembly surfaces**: API reference, guides, and code samples
  publication workflows.
- **Validation surfaces**: example snippet validation and doc/sdk consistency
  checks.
- **Policy/approval surfaces**: role/tier/approval checks for sensitive
  publication and contract promotions.
- **Telemetry/audit surfaces**: generation/publication evidence and
  governance-event retention.

### 1.2 Domain Dependency Graph

- `SDK/Docs Integration -> Yemaya`: gameplay/release API contracts and SDK
  consumption.
- `SDK/Docs Integration -> Isis`: generation/inference contracts, CLI
  integrations, and SDK usage.
- `SDK/Docs Integration -> Hathor`: narrative/editorial automation contract
  surfaces.
- `SDK/Docs Integration -> Aja`: rendering/timeline and media pipeline contract
  surfaces.
- `SDK/Docs Integration -> Bellona`: runtime/release governance and integration
  contract surfaces.
- `Project Obsidian -> all`: unified cross-domain SDK/documentation governance,
  release, and operational ownership.

## 2. Ownership and Contract Matrix

| Area                                  | Owner                           | Consumers                                | Artifact                               | Contract                            |
| ------------------------------------- | ------------------------------- | ---------------------------------------- | -------------------------------------- | ----------------------------------- |
| Contract source registry              | OSHUN BFF + Studio Architecture | SDK generation + docs pipelines          | Source contract records                | `StudioSdkDocContractVersionRecord` |
| SDK generation and packaging workflow | Developer Experience + BFF      | Domain integrators + external developers | SDK artifact manifests                 | `StudioSdkArtifactDefinition`       |
| Documentation assembly and publishing | Developer Experience + Web      | Internal operators + external developers | Documentation release manifests        | `StudioDocumentationArtifact`       |
| Snippet/example validation            | Web QA + Developer Experience   | Docs authors + SDK maintainers           | Example validation reports             | `StudioSdkDocExampleValidation`     |
| Governance and policy controls        | Security + Compliance           | Release managers + program operations    | Approval decisions and evidence bundle | `StudioSdkDocPublicationDecision`   |
| Telemetry and audit continuity        | Data Platform + Security        | Compliance + incident responders         | Governance audit event stream          | `StudioSdkDocGovernanceAuditEvent`  |

## 3. Canonical Contracts

### 3.1 StudioSdkDocContractVersionRecord

```ts
export interface StudioSdkDocContractVersionRecord {
  contractId: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  service: string;
  version: string;
  digest: string;
  lifecycle: 'draft' | 'candidate' | 'active' | 'deprecated' | 'retired';
  publishedAt: string;
  publishedBy: string;
}
```

### 3.2 StudioSdkArtifactDefinition

```ts
export interface StudioSdkArtifactDefinition {
  artifactId: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  language: 'typescript' | 'python' | 'go' | 'java';
  packageName: string;
  packageVersion: string;
  sourceContractId: string;
  sourceContractVersion: string;
  generatedAt: string;
  changelogRef: string;
}
```

### 3.3 StudioDocumentationArtifact

```ts
export interface StudioDocumentationArtifact {
  artifactId: string;
  docVersion: string;
  sourceContractId: string;
  sourceContractVersion: string;
  sections: Array<
    'api_reference' | 'guides' | 'code_samples' | 'migration_notes'
  >;
  publishedChannel: 'preview' | 'staging' | 'production';
  publishedAt: string;
  publishedBy: string;
}
```

### 3.4 StudioSdkDocExampleValidation

```ts
export interface StudioSdkDocExampleValidation {
  validationId: string;
  artifactId: string;
  artifactType: 'sdk' | 'docs';
  sampleId: string;
  status: 'passed' | 'failed';
  contractVersion: string;
  runtime: string;
  latencyMs: number;
  errorCode?: string;
  validatedAt: string;
}
```

### 3.5 StudioSdkDocPublicationDecision

```ts
export interface StudioSdkDocPublicationDecision {
  decisionId: string;
  actorId: string;
  actorRole: string;
  permissionTier: 'baseline' | 'sensitive' | 'restricted';
  releaseChannel: 'preview' | 'staging' | 'production';
  approvalTicket?: string;
  action:
    | 'promote_contract'
    | 'publish_sdk'
    | 'publish_docs'
    | 'rollback_sdk'
    | 'rollback_docs';
  allowed: boolean;
  reasonCode?: string;
  decidedAt: string;
}
```

### 3.6 StudioSdkDocGovernanceAuditEvent

```ts
export interface StudioSdkDocGovernanceAuditEvent {
  eventId: string;
  action:
    | 'sdk_doc.contract.promoted'
    | 'sdk_doc.sdk.generated'
    | 'sdk_doc.docs.published'
    | 'sdk_doc.validation.failed'
    | 'sdk_doc.publication.denied'
    | 'sdk_doc.rollback.executed';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  contractId?: string;
  artifactId?: string;
  decisionId?: string;
  actorId?: string;
  actorRole?: string;
  reasonCode?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Contract version records must include domain, digest, lifecycle state, and
  publisher identity.
- SDK artifacts must trace to a source contract/version and generated timestamp.
- Documentation artifacts must bind to contract version and publication channel.
- Example validation records must include runtime status and deterministic error
  classification.
- Publication decisions must enforce role/tier/approval governance for
  production changes.
- Governance audit events must capture contract promotion, generation,
  publication, validation, and rollback lifecycle steps.

## 5. Acceptance Criteria (OST-00282)

`OST-00282` is complete only when:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Contracts for contract source, SDK/doc artifacts, validation, publication
   decisions, and governance audits are documented.
4. Ownership boundaries and validation rules are explicit.
