# OSHUN Studio Component Primitives Journeys and Edge Cases

Status: Active  
Owner: OSHUN Studio Product Design + Web Engineering  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0018-oshun-studio-component-primitives-and-composition-contracts.md`
- `docs/releases/v1/specs/studio-component-primitives-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and edge-case behavior for Studio component-primitives
governance.

This document is the execution artifact for `OST-00043`.

## Personas

- Design System Lead
- UX Architect
- Accessibility Lead
- Frontend Technical Director
- Program Reviewer

## Journey Principles

1. Primitive changes must be reviewable, reversible, and auditable.
2. Composition behavior must remain deterministic across all governed surfaces.
3. Accessibility semantics are release gates, not optional checks.
4. Every governance action preserves Studio execution context and traceability.

## 1. Primary Journeys

### J1. Primitive Catalog Draft and Publish

**Goal**: Publish a new component-primitives bundle to preview.

**Entry**: `Studio -> Component Primitives -> Bundle Pipeline`

**Steps**:

1. Clone current primitive catalog as draft.
2. Add/update primitive variants and state contracts.
3. Run schema + token dependency checks.
4. Publish bundle to preview channel.
5. Record telemetry/audit and rollback reference.

**Success State**:

- Immutable primitive bundle version is published and preview-ready.

### J2. Composition Contract Validation

**Goal**: Validate template composition behavior for command-heavy workflows.

**Entry**: `Studio -> Component Primitives -> Composition Validation`

**Steps**:

1. Select bundle and composition template set.
2. Execute composition integrity checks.
3. Execute focus, keyboard, and state-transition checks.
4. Review violations and remediation hints.
5. Re-run until validation passes.

**Success State**:

- Validation report status is `pass` with no critical violations.

### J3. Domain Primitive Parity Sync

**Goal**: Ensure Yemaya/Isis/Hathor/Aja/Bellona consume the canonical primitive
bundle.

**Entry**: `Studio -> Component Primitives -> Domain Parity`

**Steps**:

1. Generate parity drift report by domain and surface.
2. Apply canonical primitive bundle references.
3. Re-run parity checks.
4. Confirm parity pass state.
5. Attach parity report to release package.

**Success State**:

- Domain parity status is `pass` across all target domains.

### J4. Program Approval and Production Promotion

**Goal**: Promote validated primitive bundle to production.

**Entry**: `Review & Approvals`

**Steps**:

1. Review primitive diff and validation/parity evidence.
2. Verify role-policy and approver matrix.
3. Approve/reject with rationale.
4. Promote to production if approved.
5. Confirm deployment and audit-event completeness.

**Success State**:

- Production promotion completes with signed approval and full evidence chain.

### J5. Primitive Regression Incident Rollback

**Goal**: Recover from primitive-level regression in production.

**Entry**: `Observability` alert or escalation.

**Steps**:

1. Identify failing primitive bundle and impacted surfaces.
2. Roll back to last certified bundle.
3. Validate interaction and accessibility recovery.
4. Freeze problematic bundle and open remediation task.
5. Publish incident analysis and prevention actions.

**Success State**:

- Stable primitive behavior restored with incident evidence captured.

## 2. Critical Edge Cases

### E1. Incomplete Studio Context

- Trigger: missing program/project/workspace identifiers.
- Required behavior: block action, request context repair, emit audit error.

### E2. Unauthorized Publish Attempt

- Trigger: role lacks permission to publish primitives bundle.
- Required behavior: deny with explicit policy reason and escalation guidance.

### E3. Primitive State Contract Violation

- Trigger: missing required state variant (`loading`, `error`, `disabled`).
- Required behavior: fail validation with primitive-level diagnostics.

### E4. Keyboard Contract Regression

- Trigger: composed flow breaks required keyboard traversal behavior.
- Required behavior: block release and attach focus-path diagnostics.

### E5. Aria Semantics Drift

- Trigger: primitives missing or conflicting aria roles/states.
- Required behavior: fail accessibility validation and require remediation.

### E6. Composition Template Mismatch

- Trigger: governed surface uses forbidden composition pattern.
- Required behavior: block promotion and identify violating template.

### E7. Persistent Domain Parity Drift

- Trigger: parity still fails after sync operation.
- Required behavior: keep release blocked and surface domain-specific drift
  details.

### E8. Telemetry Sink Degradation

- Trigger: telemetry/audit events cannot be emitted.
- Required behavior: retry, mark degraded observability, reconcile buffered
  events.

### E9. Approval Deadlock

- Trigger: approver conflict, absence, or stale decision window.
- Required behavior: delegated approval path with SLA escalation.

### E10. Missing Rollback Reference

- Trigger: release package does not include rollback bundle metadata.
- Required behavior: block production promotion.

## 3. Journey-to-Surface Mapping

| Journey                                      | Primary Surface      | Supporting Surfaces              |
| -------------------------------------------- | -------------------- | -------------------------------- |
| J1 Primitive Catalog Draft and Publish       | Component Primitives | Observability                    |
| J2 Composition Contract Validation           | Component Primitives | Governance                       |
| J3 Domain Primitive Parity Sync              | Component Primitives | Programs, Projects               |
| J4 Program Approval and Production Promotion | Review & Approvals   | Governance                       |
| J5 Primitive Regression Incident Rollback    | Observability        | Component Primitives, Governance |

## 4. Instrumentation Requirements

Required events:

- `primitives.journey.started`
- `primitives.journey.step.completed`
- `primitives.journey.blocked`
- `primitives.journey.recovered`
- `primitives.journey.completed`

Required dimensions:

- `programId`, `projectId`, `workspaceId`
- `journeyId`, `stepId`, `bundleVersion`
- `actorRole`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00043)

`OST-00043` is complete only when:

1. At least five component-primitives journeys are documented.
2. At least ten component-primitives edge cases are documented with
   deterministic behavior.
3. Journey-to-surface mapping is explicit.
4. Instrumentation requirements and dimensions are documented.
