# OSHUN Studio Audit and Compliance Surfaces Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Security + Compliance + OSHUN Web +
OSHUN BFF  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0029-oshun-studio-audit-and-compliance-surfaces.md`

## Purpose

Define dependencies and canonical contracts for Studio audit and compliance
surfaces across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0029-oshun-studio-audit-and-compliance-surfaces.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

- **Audit/compliance UX surfaces**: Studio audit and compliance workspaces in
  `apps/oshun/web/src/components/studio`.
- **Evidence ingestion and query authority**: analytics/event pipelines + BFF
  evidence services.
- **Policy/compliance governance**: security and compliance policy engines.
- **Cross-domain evidence correlation**: domain adapters + trace linkage
  services.
- **Retention and archival**: data platform retention controls and storage
  tiers.

### 1.2 Domain Dependency Graph

- `Audit & Compliance Surfaces -> Yemaya`: asset/content governance requires
  actor/action traceability and review evidence.
- `Audit & Compliance Surfaces -> Isis`: workflow/model governance requires
  deterministic decision lineage.
- `Audit & Compliance Surfaces -> Hathor`: narrative/publishing operations
  require compliance attestation and closure evidence.
- `Audit & Compliance Surfaces -> Aja`: media/timeline actions require
  cross-surface trace correlation.
- `Audit & Compliance Surfaces -> Bellona`: build/runtime governance requires
  high-fidelity incident and compliance traceability.
- `Project Obsidian -> all`: central governance for evidence standards,
  exception workflows, and retention policies.

## 2. Ownership and Contract Matrix

| Area                                | Owner                      | Consumers                 | Artifact                 | Contract                          |
| ----------------------------------- | -------------------------- | ------------------------- | ------------------------ | --------------------------------- |
| Canonical audit evidence model      | Data Platform + Security   | Web + BFF + Compliance    | Evidence payload         | `StudioAuditEvidenceRecord`       |
| Evidence query and correlation APIs | OSHUN BFF + Data Platform  | Audit/compliance surfaces | Query payload            | `StudioAuditQueryRequest`         |
| Compliance review workflow          | Compliance + Security      | Program governance        | Review payload           | `StudioComplianceReviewRecord`    |
| Exception and attestation actions   | Compliance + Security      | Operators + auditors      | Exception payload        | `StudioComplianceExceptionRecord` |
| Retention and archival policy model | Data Platform + Compliance | Security + Legal          | Retention policy payload | `StudioAuditRetentionPolicy`      |

## 3. Canonical Contracts

### 3.1 StudioAuditEvidenceRecord

```ts
export interface StudioAuditEvidenceRecord {
  evidenceId: string;
  traceId: string;
  actorId: string;
  actorRole: string;
  action: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  reasonCode?: string;
  occurredAt: string;
}
```

### 3.2 StudioAuditQueryRequest

```ts
export interface StudioAuditQueryRequest {
  requestId: string;
  filters: {
    actorId?: string;
    action?: string;
    domain?: string;
    outcome?: string;
    from?: string;
    to?: string;
    traceId?: string;
  };
  page: number;
  pageSize: number;
  requestedAt: string;
}
```

### 3.3 StudioComplianceReviewRecord

```ts
export interface StudioComplianceReviewRecord {
  reviewId: string;
  evidenceIds: string[];
  reviewerId: string;
  reviewerRole: string;
  status: 'open' | 'in_review' | 'approved' | 'denied' | 'closed';
  notes?: string;
  updatedAt: string;
}
```

### 3.4 StudioComplianceExceptionRecord

```ts
export interface StudioComplianceExceptionRecord {
  exceptionId: string;
  policyId: string;
  requestedBy: string;
  justification: string;
  status: 'pending' | 'approved' | 'denied' | 'expired';
  approverId?: string;
  decisionReason?: string;
  decidedAt?: string;
}
```

### 3.5 StudioAuditRetentionPolicy

```ts
export interface StudioAuditRetentionPolicy {
  policyId: string;
  evidenceCategory: string;
  retentionDays: number;
  archivalTier: 'hot' | 'warm' | 'cold';
  legalHoldSupported: boolean;
  version: string;
}
```

## 4. Validation Rules

- Evidence ingestion must reject records missing canonical actor/action/outcome
  lineage fields.
- Audit query responses must preserve event ordering for a trace.
- Compliance review closures must reference valid evidence sets.
- Retention policy updates must preserve required compliance/legal constraints.

## 5. Acceptance Criteria (OST-00130)

`OST-00130` 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 audit evidence, query request, compliance review, compliance
   exception, and retention policy are documented.
4. Ownership boundaries and validation rules are explicit.
