# OSHUN Studio Experimentation and Feature Flags Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Data/Analytics
Engineering + OSHUN Security  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0042-oshun-studio-experimentation-and-feature-flags.md`

## Purpose

Define dependencies and canonical contracts for Studio experimentation and
feature-flag capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project
Obsidian.

This document is the execution artifact for `OST-00234`.

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.md`
- `docs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.md`
- `docs/adr/ADR-0042-oshun-studio-experimentation-and-feature-flags.md`
- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/specs/studio-metrics-and-analytics-instrumentation-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-observability-and-operational-dashboards-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

- **Experimentation UI surfaces**: Studio experimentation modules in
  `apps/oshun/web/src/components/studio`.
- **Flag control-plane services**: BFF feature-toggle evaluation and assignment
  services.
- **Targeting and cohort services**: deterministic bucketing and eligibility
  evaluators.
- **Exposure/outcome analytics services**: event ingestion, KPI attribution, and
  statistical rollup pipelines.
- **Policy and approval services**: RBAC, permission-tier, and CAB governance
  controls.
- **Rollback/kill-switch services**: runtime override and emergency disable
  controls.

### 1.2 Domain Dependency Graph

- `Experimentation/Flags -> Yemaya`: release-flow UX experiments and rollout
  gating.
- `Experimentation/Flags -> Isis`: model pipeline UX variants and evaluation
  controls.
- `Experimentation/Flags -> Hathor`: narrative tooling experience experiments.
- `Experimentation/Flags -> Aja`: render/timeline workflow rollout controls.
- `Experimentation/Flags -> Bellona`: runtime safety and observability feature
  toggles.
- `Project Obsidian -> all`: cross-domain rollout orchestration and experiment
  governance.

## 2. Ownership and Contract Matrix

| Area                                  | Owner                    | Consumers                        | Artifact                   | Contract                                |
| ------------------------------------- | ------------------------ | -------------------------------- | -------------------------- | --------------------------------------- |
| Flag definition registry              | Platform Engineering     | Web + BFF + domain services      | Flag definition records    | `StudioFeatureFlagDefinition`           |
| Assignment and cohort evaluation      | BFF + Data Platform      | Runtime evaluators + analytics   | Assignment envelope        | `StudioExperimentAssignment`            |
| Exposure event capture                | Web + BFF                | Analytics + observability        | Exposure stream            | `StudioFeatureFlagExposureEvent`        |
| Outcome and KPI attribution           | Data/Analytics           | Product + program operations     | Outcome rollup stream      | `StudioExperimentOutcomeEvent`          |
| Policy and approval decisions         | Security + Compliance    | Operators + release managers     | Policy decision envelope   | `StudioFeatureFlagPolicyDecision`       |
| Rollback and kill-switch control path | Platform SRE + Security  | Incident responders + operations | Rollback execution records | `StudioFeatureFlagRollbackExecution`    |
| Governance audit evidence             | Security + Data Platform | Compliance + audit operations    | Governance audit stream    | `StudioFeatureFlagGovernanceAuditEvent` |

## 3. Canonical Contracts

### 3.1 StudioFeatureFlagDefinition

```ts
export interface StudioFeatureFlagDefinition {
  flagKey: string;
  owner: string;
  description: string;
  riskClass: 'low' | 'medium' | 'high' | 'critical';
  defaultState: boolean;
  expiresAt: string;
  createdAt: string;
  updatedAt: string;
}
```

### 3.2 StudioExperimentAssignment

```ts
export interface StudioExperimentAssignment {
  assignmentId: string;
  experimentKey: string;
  flagKey: string;
  actorId: string;
  workspaceId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  cohortId: string;
  variant: 'control' | 'treatment_a' | 'treatment_b';
  releaseChannel: 'preview' | 'staging' | 'production';
  assignedAt: string;
}
```

### 3.3 StudioFeatureFlagExposureEvent

```ts
export interface StudioFeatureFlagExposureEvent {
  eventId: string;
  experimentKey: string;
  flagKey: string;
  actorId: string;
  workspaceId: string;
  cohortId: string;
  variant: string;
  evaluatedState: boolean;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  occurredAt: string;
}
```

### 3.4 StudioExperimentOutcomeEvent

```ts
export interface StudioExperimentOutcomeEvent {
  eventId: string;
  experimentKey: string;
  metricId: string;
  cohortId: string;
  variant: string;
  outcome: 'success' | 'failure' | 'neutral';
  delta: number;
  confidenceScore: number;
  window: '1h' | '24h' | '7d';
  occurredAt: string;
}
```

### 3.5 StudioFeatureFlagPolicyDecision

```ts
export interface StudioFeatureFlagPolicyDecision {
  decisionId: string;
  flagKey: string;
  action: 'enable' | 'disable' | 'target_update' | 'rollback' | 'kill_switch';
  actorId: string;
  actorRole: string;
  permissionTier: 'baseline' | 'sensitive' | 'restricted';
  releaseChannel: 'preview' | 'staging' | 'production';
  approvalTicket?: string;
  outcome: 'allowed' | 'denied';
  reasonCode?: string;
  decidedAt: string;
}
```

### 3.6 StudioFeatureFlagRollbackExecution

```ts
export interface StudioFeatureFlagRollbackExecution {
  rollbackId: string;
  flagKey: string;
  experimentKey?: string;
  executionType: 'rollback' | 'kill_switch';
  actorId: string;
  initiatedByPolicyDecisionId: string;
  success: boolean;
  latencyMs: number;
  errorCode?: string;
  executedAt: string;
}
```

### 3.7 StudioFeatureFlagGovernanceAuditEvent

```ts
export interface StudioFeatureFlagGovernanceAuditEvent {
  eventId: string;
  action:
    | 'feature_flag.definition.created'
    | 'feature_flag.assignment.generated'
    | 'feature_flag.exposure.recorded'
    | 'feature_flag.outcome.computed'
    | 'feature_flag.policy.denied'
    | 'feature_flag.rollback.executed'
    | 'feature_flag.kill_switch.executed';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  flagKey?: string;
  experimentKey?: string;
  actorId?: string;
  actorRole?: string;
  reasonCode?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Flag definitions must have owner, risk class, and expiry metadata.
- Assignment envelopes must include deterministic cohort + variant fields.
- Exposure events must align with assignment identity and release channel.
- Outcome events must include deterministic window and confidence semantics.
- Policy decisions must enforce role/tier/approval constraints.
- Rollback/kill-switch executions must be idempotent and latency-instrumented.
- Governance audit events must capture definition, exposure, policy, and
  rollback actions end to end.

## 5. Acceptance Criteria (OST-00234)

`OST-00234` 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 flag definitions, assignment, exposure, outcomes, policy
   decisions, rollback execution, and governance audits are documented.
4. Ownership boundaries and validation rules are explicit.
