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.tsapps/oshun/web/src/navigation/routes.tsapps/oshun/bff/src/routes/search.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/domains/bellona/features.mddocs/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
EntityAuditEventrecords.
5. Acceptance Criteria (OST-00074)#
OST-00074 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for entity envelope, relations, resolution, compatibility policy, and audit events are documented.
- Ownership boundaries and validation rules are explicit.