Disciplines · Decisions (ADRs)

ADR-0043: OSHUN Studio Performance Budgets

Studio now spans cross-domain workflows with increasingly complex UI, telemetry, and orchestration behavior.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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.
  • 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