Eve library

OSHUN Studio Multi-Project Operations 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-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.