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.mdapps/oshun/bff/openapi/oshun-bff.openapi.yamlapps/oshun/bff/README.mdapps/iris/api/src/docs/index.tsapps/isis/cli/src/commands/generate.tsapps/lilith/svc-ai/src/integration-api/index.tslibs/nyx/client-python/README.mddocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/runbooks/on-call-runbook.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for contract source, SDK/doc artifacts, validation, publication decisions, and governance audits are documented.
- Ownership boundaries and validation rules are explicit.