Eve library

OSHUN Studio Component Primitives Dependency and Data Contract Map

Spec

Revision 1

On this page

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.