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.mddocs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.mddocs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.mddocs/adr/ADR-0042-oshun-studio-experimentation-and-feature-flags.mdlibs/oshun/analytics/src/types.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-metrics-and-analytics-instrumentation-dependency-and-data-contract-map.mddocs/releases/v1/specs/studio-observability-and-operational-dashboards-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#
- 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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for flag definitions, assignment, exposure, outcomes, policy decisions, rollback execution, and governance audits are documented.
- Ownership boundaries and validation rules are explicit.