# OSHUN Studio Cross-Domain Entity Model Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0022-oshun-studio-cross-domain-entity-model.md`

## Purpose

Define dependencies and canonical contracts for cross-domain entity modeling
across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `libs/oshun/domain-registry/src/index.ts`
- `apps/oshun/web/src/navigation/routes.ts`
- `apps/oshun/bff/src/routes/search.ts`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.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`
- `docs/releases/v1/design/ux-principles.md`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Domain metadata authority**: `libs/oshun/domain-registry`
- **Cross-domain aggregation and normalization**: OSHUN BFF routes
- **Route and action resolution**: `libs/oshun/navigation` +
  `apps/oshun/web/src/navigation`
- **Studio governance UX**: `apps/oshun/web/src/components/studio`
- **Telemetry and audit**: `libs/oshun/analytics` + domain pipelines

### 1.2 Domain Dependency Graph

- `Entity Model Governance -> Yemaya`: assets, projects, collaboration items
  require stable cross-domain references.
- `Entity Model Governance -> Isis`: workflow runs, model artifacts, and prompts
  require consistent IDs across discovery and execution.
- `Entity Model Governance -> Hathor`: world entities, lore artifacts, and
  research links require typed relationship contracts.
- `Entity Model Governance -> Aja`: media timelines, reference videos, and
  annotations require deterministic entity mapping.
- `Entity Model Governance -> Bellona`: builds, runtime artifacts, and incident
  entities require auditable lineage.
- `Project Obsidian -> all`: program governance for entity identity,
  compatibility, and change control.

## 2. Ownership and Contract Matrix

| Area                               | Owner                       | Consumers                     | Artifact        | Contract                          |
| ---------------------------------- | --------------------------- | ----------------------------- | --------------- | --------------------------------- |
| Canonical entity envelope          | Studio Architecture         | Web + BFF + Domain adapters   | Entity schema   | `CrossDomainEntityEnvelope`       |
| Entity relation graph              | Domain leads + Architecture | Search, feeds, workflows      | Relation graph  | `CrossDomainEntityRelation`       |
| Entity route/action resolution     | Navigation Platform         | Web surfaces + command layers | Resolution spec | `EntityResolutionContract`        |
| Compatibility and migration policy | Platform Architecture       | Engineering + Ops             | Version policy  | `EntitySchemaCompatibilityPolicy` |
| Audit and lineage evidence         | Data Platform               | Governance + SRE              | Event stream    | `EntityAuditEvent`                |

## 3. Canonical Contracts

### 3.1 CrossDomainEntityEnvelope

```ts
export interface CrossDomainEntityEnvelope {
  entityId: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona';
  entityType: string;
  schemaVersion: string;
  title: string;
  summary?: string;
  status?: string;
  ownerId?: string;
  createdAt: string;
  updatedAt: string;
  extensions?: Record<string, unknown>;
}
```

### 3.2 CrossDomainEntityRelation

```ts
export interface CrossDomainEntityRelation {
  relationId: string;
  sourceEntityId: string;
  targetEntityId: string;
  relationType:
    | 'references'
    | 'depends_on'
    | 'derived_from'
    | 'blocks'
    | 'linked_to'
    | string;
  createdAt: string;
  metadata?: Record<string, unknown>;
}
```

### 3.3 EntityResolutionContract

```ts
export interface EntityResolutionContract {
  contractId: string;
  entityType: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona';
  routeTemplate: string;
  requiredContext: Array<'programId' | 'projectId' | 'workspaceId'>;
  fallbackRoute: string;
  actionCapabilities: string[];
}
```

### 3.4 EntitySchemaCompatibilityPolicy

```ts
export interface EntitySchemaCompatibilityPolicy {
  policyId: string;
  schemaVersion: string;
  backwardCompatibleWith: string[];
  forwardCompatibleWith: string[];
  breakingChanges: string[];
  migrationStrategy: string;
  rollbackVersion: string;
}
```

### 3.5 EntityAuditEvent

```ts
export interface EntityAuditEvent {
  eventId: string;
  action:
    | 'entity.created'
    | 'entity.updated'
    | 'entity.resolved'
    | 'entity.relation.updated'
    | 'entity.validation.failed'
    | 'entity.permission.denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  entityId: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona';
  entityType: string;
  programId: string;
  projectId: string;
  workspaceId: string;
  role: string;
  traceId: string;
  occurredAt: string;
  reason?: string;
}
```

## 4. Validation Rules

- Production promotion is blocked unless entity envelope validation passes for
  identity immutability and required fields.
- Production promotion is blocked unless route/action resolution coverage is
  complete for all governed entity types.
- Breaking schema changes require compatibility policy and migration plan.
- All allow/deny/validation-failure outcomes must emit `EntityAuditEvent`
  records.

## 5. Acceptance Criteria (OST-00074)

`OST-00074` 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 entity envelope, relations, resolution, compatibility policy,
   and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
