# OSHUN Studio Review and Approval Workflows Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Security  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0035-oshun-studio-review-and-approval-workflows.md`

## Purpose

Define dependencies and canonical contracts for Studio review and approval
workflows across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0035-oshun-studio-review-and-approval-workflows.md`
- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`
- `docs/releases/v1/design/ux-principles.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

- **Review and approval UI surfaces**: Studio workflow modules in
  `apps/oshun/web/src/components/studio`.
- **Stage and decision persistence services**: BFF workflow APIs.
- **Artifact/dependency binding adapters**: domain adapters for release,
  content, model, and runtime assets.
- **Policy and delegation services**: RBAC/approval policies and escalation
  controls.
- **Telemetry and governance evidence pipelines**: analytics + compliance
  retention/export systems.

### 1.2 Domain Dependency Graph

- `Review/Approval -> Yemaya`: release and production-readiness stage approvals.
- `Review/Approval -> Isis`: model promotion and validation sign-off.
- `Review/Approval -> Hathor`: narrative/content stage review decisions.
- `Review/Approval -> Aja`: timeline and sequence cut approvals.
- `Review/Approval -> Bellona`: runtime-risk waivers and incident closure
  approvals.
- `Project Obsidian -> all`: cross-domain portfolio-level approvals and
  escalations.

## 2. Ownership and Contract Matrix

| Area                              | Owner                    | Consumers                         | Artifact              | Contract                        |
| --------------------------------- | ------------------------ | --------------------------------- | --------------------- | ------------------------------- |
| Canonical review package envelope | BFF + Domain Integrators | Studio reviewers and approvers    | Review payload        | `StudioReviewApprovalPackage`   |
| Approval stage graph and routing  | BFF + Program Ops        | Review leads + approvers          | Stage payload         | `StudioApprovalStage`           |
| Decision lifecycle transitions    | Program Ops + Web        | Stakeholders + dependent services | Decision payload      | `StudioApprovalDecision`        |
| Delegation and escalation actions | Security + Compliance    | Leads + approvers                 | Delegation payload    | `StudioApprovalDelegationEvent` |
| Audit and governance evidence     | Data Platform + Security | Compliance + governance           | Telemetry/audit event | `StudioApprovalAuditEvent`      |

## 3. Canonical Contracts

### 3.1 StudioReviewApprovalPackage

```ts
export interface StudioReviewApprovalPackage {
  reviewId: string;
  artifactRef: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  ownerId: string;
  requestedBy: string;
  stageGraphId: string;
  blockingDependencies: string[];
  submittedAt: string;
}
```

### 3.2 StudioApprovalStage

```ts
export interface StudioApprovalStage {
  stageId: string;
  reviewId: string;
  stageType: 'review' | 'approval' | 'security' | 'compliance' | 'release_gate';
  state:
    | 'pending'
    | 'in_review'
    | 'approved'
    | 'rejected'
    | 'changes_requested';
  assignedRoles: string[];
  enteredAt: string;
  updatedAt: string;
}
```

### 3.3 StudioApprovalDecision

```ts
export interface StudioApprovalDecision {
  decisionId: string;
  reviewId: string;
  stageId: string;
  outcome: 'approved' | 'rejected' | 'changes_requested';
  decidedBy: string;
  decidedRole: string;
  rationale: string;
  decidedAt: string;
}
```

### 3.4 StudioApprovalDelegationEvent

```ts
export interface StudioApprovalDelegationEvent {
  delegationId: string;
  reviewId: string;
  stageId: string;
  action: 'delegate' | 'escalate' | 'reassign';
  actorId: string;
  fromRole: string;
  toRole: string;
  policyId: string;
  reason: string;
  occurredAt: string;
}
```

### 3.5 StudioApprovalAuditEvent

```ts
export interface StudioApprovalAuditEvent {
  eventId: string;
  action:
    | 'review.started'
    | 'review.stage_transitioned'
    | 'review.decision_recorded'
    | 'review.delegated'
    | 'review.escalated'
    | 'review.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  reviewId?: string;
  stageId?: string;
  decisionId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Review payloads missing artifact, owner, stage graph, or submitter context
  must be rejected.
- Stage transitions must follow deterministic graph edges and merge rules.
- Decision outcomes must include explicit actor attribution and rationale.
- Delegation and escalation events must reference authorized policy IDs.
- Audit events must capture lifecycle, delegation, and policy outcomes end to
  end.

## 5. Acceptance Criteria (OST-00178)

`OST-00178` 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 review package, approval stage, decision lifecycle,
   delegation/escalation, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
