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.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/design/ux-principles.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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
MultiProjectOperationAuditEventrecords.
5. Acceptance Criteria (OST-00090)#
OST-00090 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for operation envelope, readiness graph, transitions, rollback plan, and audit events are documented.
- Ownership boundaries and validation rules are explicit.