Eve library

OSHUN Studio Experimentation and Feature Flags Dependency and Data Contract Map

Spec

Revision 1

On this page

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.