# OSHUN Studio Component Primitives Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Design Systems + OSHUN Web  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0018-oshun-studio-component-primitives-and-composition-contracts.md`

## Purpose

Define dependencies and canonical contracts required to govern Studio component
primitives across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `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`
- `docs/domains/yemaya/service-catalog.md`
- `docs/domains/isis/service-catalog.md`
- `docs/domains/hathor/service-catalog.md`
- `docs/domains/aja/service-catalog.md`
- `docs/domains/bellona/service-catalog.md`
- `docs/releases/v1/design/ux-principles.md`
- `docs/releases/v1/design/ergonomics-requirements.md`
- `libs/oshun/ui`
- `libs/oshun/design-tokens/src/tokens.ts`
- `apps/oshun/web/src/design-system/tokens.ts`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Primitive source of truth**: `libs/oshun/ui`
- **Web composition layer**: `apps/oshun/web/src/design-system`
- **Studio governance UX**: `apps/oshun/web/src/components/studio`
- **Telemetry and audit**: `libs/oshun/analytics` + Studio event sinks

### 1.2 Domain Dependency Graph

- `Component Primitive Governance -> Yemaya`: project and collaboration surfaces
  require consistent card, table, and action-strip primitives.
- `Component Primitive Governance -> Isis`: workflow builders and job logs rely
  on deterministic field, modal, and status-pattern primitives.
- `Component Primitive Governance -> Hathor`: long-form authoring and review
  flows require reliable text-input, panel, and approval primitives.
- `Component Primitive Governance -> Aja`: timeline and motion pipeline tooling
  requires stable command, scrubber, and diagnostics primitives.
- `Component Primitive Governance -> Bellona`: build/runtime orchestration needs
  high-density operational controls with consistent error/disabled states.
- `Project Obsidian -> all`: program-level compliance for primitive contracts
  and release evidence.

## 2. Ownership and Contract Matrix

| Area                           | Owner                            | Consumers        | Artifact          | Contract                      |
| ------------------------------ | -------------------------------- | ---------------- | ----------------- | ----------------------------- |
| Primitive catalog spec         | Design Systems + Web Platform    | Studio surfaces  | Primitive bundle  | `PrimitiveCatalogBundle`      |
| Composition templates          | Design Systems + UX Architecture | Domain teams     | Composition spec  | `PrimitiveCompositionSpec`    |
| Accessibility/state validation | Accessibility QA + Web           | Release managers | Validation report | `PrimitiveValidationReport`   |
| Domain primitive parity        | Domain adapters + QA             | Product + Ops    | Parity report     | `DomainPrimitiveParityReport` |
| Audit/telemetry stream         | Data Platform                    | SRE + Governance | Event stream      | `PrimitiveAuditEvent`         |

## 3. Canonical Contracts

### 3.1 PrimitiveCatalogBundle

```ts
export interface PrimitiveCatalogBundle {
  bundleId: string;
  version: string;
  scope: 'studio-component-primitives';
  generatedAt: string;
  generatedBy: string;
  primitives: Array<{
    primitiveId: string;
    category:
      | 'input'
      | 'navigation'
      | 'feedback'
      | 'overlay'
      | 'data'
      | 'layout';
    variants: string[];
    states: Array<'idle' | 'loading' | 'error' | 'disabled' | 'success'>;
    tokenDependencies: string[];
    accessibilityContractId: string;
  }>;
}
```

### 3.2 PrimitiveCompositionSpec

```ts
export interface PrimitiveCompositionSpec {
  specId: string;
  bundleVersion: string;
  templates: Array<{
    templateId: string;
    name: string;
    useCase:
      | 'list_detail'
      | 'command_bar'
      | 'approval_workspace'
      | 'dashboard_panel_grid'
      | 'diagnostics_console';
    requiredPrimitives: string[];
    forbiddenPatterns: string[];
    interactionContracts: string[];
  }>;
}
```

### 3.3 PrimitiveValidationReport

```ts
export interface PrimitiveValidationReport {
  reportId: string;
  bundleVersion: string;
  checkedAt: string;
  checkedBy: string;
  checks: {
    keyboardContractPass: boolean;
    focusOrderPass: boolean;
    ariaStateSemanticsPass: boolean;
    compositionTemplatePass: boolean;
    tokenContractParityPass: boolean;
  };
  violations: Array<{
    primitiveId: string;
    issue: string;
    severity: 'low' | 'medium' | 'high' | 'critical';
  }>;
  status: 'pass' | 'fail';
}
```

### 3.4 DomainPrimitiveParityReport

```ts
export interface DomainPrimitiveParityReport {
  reportId: string;
  bundleVersion: string;
  domains: Array<'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona'>;
  generatedAt: string;
  driftFindings: Array<{
    domain: string;
    surface: string;
    primitiveId: string;
    expectedVersion: string;
    actualVersion: string;
  }>;
  parityStatus: 'pass' | 'fail';
}
```

### 3.5 PrimitiveAuditEvent

```ts
export interface PrimitiveAuditEvent {
  eventId: string;
  action:
    | 'primitives.bundle.publish.requested'
    | 'primitives.bundle.publish.completed'
    | 'primitives.validation.requested'
    | 'primitives.validation.completed'
    | 'primitives.parity.sync.requested'
    | 'primitives.parity.sync.completed'
    | 'primitives.permission.denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  programId: string;
  projectId: string;
  workspaceId: string;
  role: string;
  traceId: string;
  occurredAt: string;
  reason?: string;
}
```

## 4. Validation Rules

- Production promotion is blocked unless
  `PrimitiveValidationReport.status = 'pass'`.
- Production promotion is blocked unless
  `DomainPrimitiveParityReport.parityStatus = 'pass'`.
- All publish/validate/sync flows require complete context and policy
  authorization.
- All allow/deny outcomes must emit `PrimitiveAuditEvent` records.

## 5. Acceptance Criteria (OST-00042)

`OST-00042` is complete only when:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Contracts for primitive catalog, composition templates, validation, parity,
   and audit streams are documented.
4. Ownership boundaries and validation rules are explicit.
