Eve library

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

Spec

Revision 1

On this page

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.