# ADR-0043: OSHUN Studio Performance Budgets

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

## Context and Problem Statement

Studio now spans cross-domain workflows with increasingly complex UI, telemetry,
and orchestration behavior. Without explicit performance budgets and enforcement
policy, latency and runtime regressions can silently degrade operator
productivity, release safety, and cross-domain reliability.

Without canonical Studio performance budgets, OSHUN risks:

- inconsistent latency expectations across Studio workspaces and domains
- uncaught regressions in Core Web Vitals and interaction latency
- weak release gating for performance-sensitive production workflows
- poor correlation between performance degradation and policy/operational risk

## Decision Drivers

- **Predictability**: deterministic performance expectations for all Studio
  surfaces.
- **Safety**: prevent release of performance regressions in critical workflows.
- **Operability**: correlate UX latency with telemetry, policy, and incident
  signals.
- **Consistency**: one budget vocabulary across Yemaya, Isis, Hathor, Aja,
  Bellona, and Project Obsidian.
- **Governance**: performance SLOs become first-class release criteria.

## Considered Options

### Option 1: Advisory-Only Budgets Per Team

Allow each domain/workspace to define non-binding local performance targets.

**Pros**:

- Minimal implementation overhead.

**Cons**:

- No deterministic release guardrails.
- Hard to compare or aggregate performance posture across domains.

### Option 2: Global Static Thresholds Only

Apply one global threshold set to all Studio flows without contextual budgets.

**Pros**:

- Simple implementation and straightforward rule set.

**Cons**:

- Overly coarse and prone to false positives/negatives.
- Ignores domain/workflow criticality and operational context.

### Option 3: Tiered Canonical Performance Budget Framework (Chosen)

Define canonical budget tiers and enforce them via CI/runtime telemetry/release
gates with role-aware exception handling.

**Pros**:

- Deterministic release enforcement and faster regression detection.
- Strong alignment with observability, experimentation, and policy surfaces.
- Supports domain-specific nuance while preserving shared governance.

**Cons**:

- Requires disciplined contract/version maintenance and ongoing tuning.

## Decision Outcome

**Chosen option**: Option 3.

Performance-budget requirements:

1. **Canonical budget contracts** for web vitals, interaction latency, and flow
   completion SLOs.
2. **Tiered budget policy** aligned to workflow criticality and risk class.
3. **Enforcement model** across CI validation, runtime telemetry, and release
   gates.
4. **Policy exception contract** for temporary waivers with owner + expiry.
5. **Cross-domain attribution contract** for budget violations and remediation
   ownership.

## Normative Rules

### Budget Contract Model

- Every Studio flow must define budget metrics and target thresholds.
- Required dimensions: `workspaceId`, `flow`, `sourceDomain`, `releaseChannel`,
  and `budgetTier`.
- Budget definitions without owner and expiry metadata are invalid.

### Tiered Budget Policy

- `tier_1_critical` budgets apply to Bellona safety controls and Project
  Obsidian release-gate checkpoints.
- `tier_2_operational` budgets apply to operational decision and triage flows
  across Yemaya, Isis, Hathor, and Aja.
- `tier_3_supporting` budgets apply to non-blocking support/diagnostic flows.

### Enforcement Model

- CI checks must fail when contractual budget assertions regress past threshold.
- Runtime telemetry must emit budget pass/fail events for every governed flow.
- Production release gates must block on unresolved `tier_1_critical` and
  sustained `tier_2_operational` violations.

### Exception and Waiver Policy

- Budget waivers require explicit owner, rationale, scope, and expiry.
- Waivers for `tier_1_critical` budgets require Compliance + Security approval.
- Expired waivers auto-fail release gates until renewed or remediated.

### Attribution and Incident Policy

- Budget violations must resolve to owning domain/workflow and responsible team.
- Persistent budget violations trigger incident playbooks and escalation.
- Remediation outcomes must be auditable and linked to budget-violation events.

## Architecture Implications

- Studio workspaces expose budget posture and enforcement status as first-class
  signals.
- Existing web-vitals and performance telemetry hooks provide baseline
  measurement contracts.
- Metrics and observability dashboards consume budget events for release and
  operations decisions.
- Experimentation and rollout workflows can gate feature promotion on budget
  conformance.

## Acceptance Criteria (OST-00241)

`OST-00241` is complete only when:

1. ADR exists at `docs/adr/ADR-0049-oshun-studio-performance-budgets.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines budget contracts, tiers, enforcement, waivers, and attribution
   rules.
4. ADR aligns with `ADR-0007` through `ADR-0042`, especially `ADR-0012`,
   `ADR-0040`, `ADR-0041`, and `ADR-0042`.
5. ADR aligns with existing web-vitals and performance budget test surfaces in
   `apps/oshun/web/src`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Consistent and enforceable Studio performance expectations.
- Faster regression detection and safer release decisions.
- Stronger cross-domain accountability for performance posture.

### Negative

- Additional maintenance overhead for budget evolution and waiver governance.
- Requires strict coordination across web, BFF, SRE, and domain teams.

## 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`
- `docs/adr/ADR-0048-oshun-studio-experimentation-and-feature-flags.md`

## References

- `apps/oshun/web/src/lib/hooks/use-web-vitals.ts`
- `apps/oshun/web/src/__tests__/performance-web-vitals.test.ts`
- `apps/oshun/web/src/__tests__/performance-bundle.test.ts`
- `apps/oshun/web/src/observability/performance-telemetry.ts`
- `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`