ADR-0042: OSHUN Studio Experimentation and Feature Flags

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, OSHUN Data/Analytics Engineering
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design

Context and Problem Statement#

Studio now operates broad cross-domain workflows and requires safe progressive delivery. Without a canonical experimentation and feature-flag model, teams face release risk, inconsistent rollouts, and weak attribution for experiment outcomes.

Without unified experimentation and flag governance, OSHUN risks:

• uncontrolled or inconsistent feature activation across Studio domains
• weak confidence in experiment results due to poor exposure attribution
• elevated incident risk from all-at-once launches
• governance and compliance gaps for high-impact runtime toggles

Decision Drivers#

• Safety: support progressive rollout and fast rollback.
• Attribution: deterministic experiment exposure and outcome telemetry.
• Governance: policy-aware control of production-impacting flags.
• Consistency: one Studio-wide vocabulary and lifecycle model.
• Operability: rapid diagnosis of experiment and rollout regressions.

Considered Options#

Option 1: Domain-Local Feature Flags#

Allow each domain to define local flag lifecycles and exposure semantics.

Pros:

• Fast local implementation for individual teams.

Cons:

• Fragmented rollout behavior and inconsistent telemetry semantics.
• Harder cross-domain governance and incident handling.

Option 2: Release-Only Static Config#

Use only environment/static release config without dynamic flag controls.

Pros:

• Minimal runtime control-plane complexity.

Cons:

• Slow rollback and no safe progressive rollout path.
• No robust experimentation capability.

Option 3: Canonical Studio Experimentation + Flag Control Plane (Chosen)#

Adopt typed flag definitions, experiment assignment contracts, policy-aware targeting, and deterministic exposure/outcome telemetry.

Pros:

• Safer progressive delivery and rollback across all Studio domains.
• Strong experiment attribution and analytics confidence.
• Better policy/audit governance for production toggles.

Cons:

• Requires shared contract/version governance and operational discipline.

Decision Outcome#

Chosen option: Option 3.

Experimentation and flag requirements:

1. Canonical flag-definition contract for lifecycle, owner, and risk class.
2. Assignment and targeting contract for cohort routing and eligibility.
3. Exposure and outcome telemetry contract for experiment analytics.
4. Policy and approval contract for sensitive/production toggles.
5. Rollback and kill-switch contract for rapid containment.

Normative Rules#

Flag Definition Contract#

• Every flag must include flagKey, owner, description, riskClass, defaultState, and expiresAt.
• Flags without owner or expiry metadata are not production-eligible.
• Deprecated flags must be removed within defined cleanup windows.

Assignment and Targeting Contract#

• Assignment dimensions must include actorId, workspaceId, domain, releaseChannel, and cohortId.
• Cohort assignment must be deterministic and reproducible.
• Targeting predicates must reject ambiguous or conflicting conditions.

Exposure and Outcome Telemetry Contract#

• Every evaluated flag must emit exposure telemetry with assignment context.
• Experiment outcomes must include success/failure and key KPI deltas.
• Missing exposure or outcome telemetry is a release-blocking defect.

Policy and Approval Contract#

• Sensitive and production-impacting flags require role + permission-tier checks.
• High-risk production toggles require CAB/approval evidence.
• Policy denials must be auditable and queryable.

Rollback and Kill-Switch Contract#

• All high-risk flags must support instant disable/rollback.
• Rollback actions must be idempotent and telemetry-instrumented.
• Kill-switch activations must emit governance audit events.

Architecture Implications#

• Studio workspaces consume one shared flag and experiment contract model.
• Web/BFF/data pipelines align on exposure and outcome schema.
• Policy enforcement integrates with Studio RBAC and permission tiers.
• Observability dashboards can correlate rollout state with operational health.

Acceptance Criteria (OST-00233)#

OST-00233 is complete only when:

1. ADR exists at docs/adr/ADR-0048-oshun-studio-experimentation-and-feature-flags.md.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines flag definition, targeting, telemetry, policy/approval, and rollback/kill-switch contracts.
4. ADR aligns with ADR-0007 through ADR-0041, especially ADR-0012, ADR-0040, and ADR-0041.
5. ADR aligns with docs/releases/v1/design/ux-principles.md, libs/oshun/analytics, and libs/oshun/domain-registry.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

• Safer progressive delivery and higher release confidence.
• Better experiment insight with deterministic attribution.
• Stronger operational and compliance governance for runtime toggles.

Negative#

• Additional governance overhead for flag lifecycle maintenance.
• Requires strict discipline on exposure/outcome telemetry completeness.

Related Decisions#

• docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
• docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md
• docs/adr/ADR-0046-oshun-studio-metrics-and-analytics-instrumentation.md
• docs/adr/ADR-0047-oshun-studio-observability-and-operational-dashboards.md

References#

• libs/oshun/analytics/src/types.ts
• libs/oshun/domain-registry/src/index.ts
• 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