Eve library

OSHUN Studio Review and Approval Workflows Dependency and Data Contract Map

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Security
Last Updated: 2026-02-23
Related: docs/adr/ADR-0035-oshun-studio-review-and-approval-workflows.md

Purpose#

Define dependencies and canonical contracts for Studio review and approval workflows across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for OST-00178.

Sources Used#

  • docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0035-oshun-studio-review-and-approval-workflows.md
  • libs/oshun/analytics/src/types.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#

  • Review and approval UI surfaces: Studio workflow modules in apps/oshun/web/src/components/studio.
  • Stage and decision persistence services: BFF workflow APIs.
  • Artifact/dependency binding adapters: domain adapters for release, content, model, and runtime assets.
  • Policy and delegation services: RBAC/approval policies and escalation controls.
  • Telemetry and governance evidence pipelines: analytics + compliance retention/export systems.

1.2 Domain Dependency Graph#

  • Review/Approval -> Yemaya: release and production-readiness stage approvals.
  • Review/Approval -> Isis: model promotion and validation sign-off.
  • Review/Approval -> Hathor: narrative/content stage review decisions.
  • Review/Approval -> Aja: timeline and sequence cut approvals.
  • Review/Approval -> Bellona: runtime-risk waivers and incident closure approvals.
  • Project Obsidian -> all: cross-domain portfolio-level approvals and escalations.

2. Ownership and Contract Matrix#

Area Owner Consumers Artifact Contract
Canonical review package envelope BFF + Domain Integrators Studio reviewers and approvers Review payload StudioReviewApprovalPackage
Approval stage graph and routing BFF + Program Ops Review leads + approvers Stage payload StudioApprovalStage
Decision lifecycle transitions Program Ops + Web Stakeholders + dependent services Decision payload StudioApprovalDecision
Delegation and escalation actions Security + Compliance Leads + approvers Delegation payload StudioApprovalDelegationEvent
Audit and governance evidence Data Platform + Security Compliance + governance Telemetry/audit event StudioApprovalAuditEvent

3. Canonical Contracts#

3.1 StudioReviewApprovalPackage#

ts
export interface StudioReviewApprovalPackage {
  reviewId: string;
  artifactRef: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  ownerId: string;
  requestedBy: string;
  stageGraphId: string;
  blockingDependencies: string[];
  submittedAt: string;
}

3.2 StudioApprovalStage#

ts
export interface StudioApprovalStage {
  stageId: string;
  reviewId: string;
  stageType: 'review' | 'approval' | 'security' | 'compliance' | 'release_gate';
  state:
    | 'pending'
    | 'in_review'
    | 'approved'
    | 'rejected'
    | 'changes_requested';
  assignedRoles: string[];
  enteredAt: string;
  updatedAt: string;
}

3.3 StudioApprovalDecision#

ts
export interface StudioApprovalDecision {
  decisionId: string;
  reviewId: string;
  stageId: string;
  outcome: 'approved' | 'rejected' | 'changes_requested';
  decidedBy: string;
  decidedRole: string;
  rationale: string;
  decidedAt: string;
}

3.4 StudioApprovalDelegationEvent#

ts
export interface StudioApprovalDelegationEvent {
  delegationId: string;
  reviewId: string;
  stageId: string;
  action: 'delegate' | 'escalate' | 'reassign';
  actorId: string;
  fromRole: string;
  toRole: string;
  policyId: string;
  reason: string;
  occurredAt: string;
}

3.5 StudioApprovalAuditEvent#

ts
export interface StudioApprovalAuditEvent {
  eventId: string;
  action:
    | 'review.started'
    | 'review.stage_transitioned'
    | 'review.decision_recorded'
    | 'review.delegated'
    | 'review.escalated'
    | 'review.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  reviewId?: string;
  stageId?: string;
  decisionId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}

4. Validation Rules#

  • Review payloads missing artifact, owner, stage graph, or submitter context must be rejected.
  • Stage transitions must follow deterministic graph edges and merge rules.
  • Decision outcomes must include explicit actor attribution and rationale.
  • Delegation and escalation events must reference authorized policy IDs.
  • Audit events must capture lifecycle, delegation, and policy outcomes end to end.

5. Acceptance Criteria (OST-00178)#

OST-00178 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 review package, approval stage, decision lifecycle, delegation/escalation, and audit events are documented.
  4. Ownership boundaries and validation rules are explicit.