# OSHUN Studio Multi-Project Operations Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0024-oshun-studio-multi-project-operations.md`

## Purpose

Define dependencies and canonical contracts for multi-project operations across
Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `apps/oshun/web/src/navigation/routes.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

- **Operation planning and execution UI**: Studio multi-project operation
  surface (`apps/oshun/web/src/components/studio`).
- **Readiness and transition orchestration**: OSHUN BFF operation services.
- **Project metadata authority**: domain adapters + program governance metadata.
- **Context and route continuity**: `apps/oshun/web/src/navigation/routes.ts`.
- **Telemetry and audit**: `libs/oshun/analytics` + web/BFF pipelines.

### 1.2 Domain Dependency Graph

- `Multi-Project Operations -> Yemaya`: content/asset pipelines participate in
  cross-project sequencing and dependency gates.
- `Multi-Project Operations -> Isis`: workflow/model projects require staged
  promotion and rollback coordination.
- `Multi-Project Operations -> Hathor`: narrative/world projects require
  dependency-aware approval ordering.
- `Multi-Project Operations -> Aja`: media/timeline projects require readiness
  synchronization with upstream/downstream tasks.
- `Multi-Project Operations -> Bellona`: build/runtime projects require
  release-window alignment and rollback containment.
- `Project Obsidian -> all`: central governance for operation safety, approvals,
  and incident ownership.

## 2. Ownership and Contract Matrix

| Area                                   | Owner                                   | Consumers                   | Artifact           | Contract                          |
| -------------------------------------- | --------------------------------------- | --------------------------- | ------------------ | --------------------------------- |
| Multi-project operation envelope       | Studio Architecture                     | Web + BFF + Ops             | Operation schema   | `MultiProjectOperationEnvelope`   |
| Project dependency and readiness model | Program Operations + Domain Integrators | Release managers            | Readiness graph    | `ProjectReadinessGraph`           |
| Stage transition and execution model   | OSHUN BFF                               | Studio surfaces + SRE       | Transition payload | `MultiProjectExecutionTransition` |
| Rollback orchestration plan            | SRE + Program Ops                       | Incident response           | Recovery plan      | `MultiProjectRollbackPlan`        |
| Audit and compliance evidence          | Data Platform                           | Governance + Security + SRE | Event stream       | `MultiProjectOperationAuditEvent` |

## 3. Canonical Contracts

### 3.1 MultiProjectOperationEnvelope

```ts
export interface MultiProjectOperationEnvelope {
  operationId: string;
  programId: string;
  projectIds: string[];
  stage: 'planned' | 'running' | 'paused' | 'blocked' | 'completed' | 'aborted';
  releaseWindow?: string;
  dependencyGraphVersion: string;
  createdAt: string;
  updatedAt: string;
}
```

### 3.2 ProjectReadinessGraph

```ts
export interface ProjectReadinessGraph {
  operationId: string;
  nodes: Array<{
    projectId: string;
    readinessState: 'ready' | 'not_ready' | 'blocked';
    requiredGates: string[];
    failedGates?: string[];
  }>;
  edges: Array<{
    sourceProjectId: string;
    targetProjectId: string;
    relation: 'depends_on' | 'blocks' | 'ordered_before';
  }>;
  generatedAt: string;
}
```

### 3.3 MultiProjectExecutionTransition

```ts
export interface MultiProjectExecutionTransition {
  transitionId: string;
  operationId: string;
  fromStage: 'planned' | 'running' | 'paused' | 'blocked';
  toStage: 'running' | 'paused' | 'blocked' | 'completed' | 'aborted';
  actorId: string;
  actorRole: string;
  reason?: string;
  occurredAt: string;
}
```

### 3.4 MultiProjectRollbackPlan

```ts
export interface MultiProjectRollbackPlan {
  planId: string;
  operationId: string;
  checkpointId: string;
  rollbackOrder: string[];
  dependencyAware: boolean;
  fallbackActions: string[];
  validatedAt: string;
}
```

### 3.5 MultiProjectOperationAuditEvent

```ts
export interface MultiProjectOperationAuditEvent {
  eventId: string;
  action:
    | 'multi_project.operation.requested'
    | 'multi_project.operation.started'
    | 'multi_project.operation.paused'
    | 'multi_project.operation.blocked'
    | 'multi_project.operation.completed'
    | 'multi_project.operation.aborted'
    | 'multi_project.operation.rollback';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  operationId: string;
  programId: string;
  projectIds: string[];
  stage: string;
  role: string;
  traceId: string;
  occurredAt: string;
  reason?: string;
}
```

## 4. Validation Rules

- Production promotion is blocked unless operation envelope validation passes
  and contains at least two unique projects.
- Stage transition commit is blocked unless readiness gates pass for required
  projects.
- Rollback execution must use dependency-aware order and last confirmed
  checkpoint.
- All allow/deny/stage-transition/rollback outcomes must emit
  `MultiProjectOperationAuditEvent` records.

## 5. Acceptance Criteria (OST-00090)

`OST-00090` 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 operation envelope, readiness graph, transitions, rollback
   plan, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
