# OSHUN Studio Accessibility Governance Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Data/Analytics
Engineering + OSHUN Security + Compliance  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0044-oshun-studio-accessibility-governance.md`

## Purpose

Define dependencies and canonical contracts for Studio accessibility governance
across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0018-oshun-studio-component-primitives-and-composition-contracts.md`
- `docs/adr/ADR-0040-oshun-studio-metrics-and-analytics-instrumentation.md`
- `docs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.md`
- `docs/adr/ADR-0044-oshun-studio-accessibility-governance.md`
- `apps/oshun/web/src/components/__tests__/accessibility-axe.test.tsx`
- `apps/oshun/web/src/components/__tests__/accessibility-keyboard.test.tsx`
- `apps/oshun/web/src/components/__tests__/accessibility-screen-reader.test.tsx`
- `apps/oshun/web/src/components/__tests__/StudioPerformanceBudgetsWorkspace.validation.test.tsx`
- `apps/oshun/web/src/components/__tests__/StudioExperimentationFeatureFlagsWorkspace.validation.test.tsx`
- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `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`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Accessibility governance UI surfaces**: Studio accessibility governance
  modules in `apps/oshun/web/src/components/studio`.
- **Validation services**: CI accessibility suites (axe, keyboard, screen-reader
  semantics).
- **Runtime accessibility monitors**: production accessibility posture checks
  and diagnostics.
- **Policy and waiver services**: role/tier-aware accessibility waiver and
  release governance.
- **Remediation services**: accessibility issue triage, remediation execution,
  and closure workflows.
- **Audit and evidence services**: telemetry and governance event retention.

### 1.2 Domain Dependency Graph

- `Accessibility Governance -> Yemaya`: release flow navigation and semantic
  control checks.
- `Accessibility Governance -> Isis`: model-workbench operability and keyboard
  flow controls.
- `Accessibility Governance -> Hathor`: narrative editing accessibility and
  screen-reader posture.
- `Accessibility Governance -> Aja`: timeline/render accessibility semantics and
  focus continuity.
- `Accessibility Governance -> Bellona`: safety-control operability under
  assistive technologies.
- `Project Obsidian -> all`: cross-domain accessibility release governance and
  compliance orchestration.

## 2. Ownership and Contract Matrix

| Area                               | Owner                    | Consumers                            | Artifact                    | Contract                                  |
| ---------------------------------- | ------------------------ | ------------------------------------ | --------------------------- | ----------------------------------------- |
| Accessibility contract definition  | Design Systems + Web     | Domain teams + release operations    | Contract definition records | `StudioAccessibilityContractDefinition`   |
| Accessibility validation execution | Platform SRE + Web QA    | CI/release pipelines + operators     | Validation result stream    | `StudioAccessibilityValidationEvent`      |
| Accessibility issue tracking       | Web + Program Operations | Security + compliance + domain leads | Issue records               | `StudioAccessibilityIssueRecord`          |
| Policy and waiver decisions        | Security + Compliance    | Operators + release managers         | Policy decision envelope    | `StudioAccessibilityPolicyDecision`       |
| Remediation execution and closure  | Web + Platform SRE       | Incident responders + domain teams   | Remediation execution logs  | `StudioAccessibilityRemediationExecution` |
| Governance audit evidence          | Security + Data Platform | Compliance + audit operations        | Audit event stream          | `StudioAccessibilityAuditEvent`           |

## 3. Canonical Contracts

### 3.1 StudioAccessibilityContractDefinition

```ts
export interface StudioAccessibilityContractDefinition {
  contractId: string;
  contractKey: string;
  owner: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  workflowRef: string;
  scope: 'keyboard' | 'screen_reader' | 'semantic' | 'motion' | 'contrast';
  severity: 'low' | 'medium' | 'high' | 'critical';
  releaseChannelScope: 'preview' | 'staging' | 'production' | 'all';
  expiresAt: string;
  createdAt: string;
  updatedAt: string;
}
```

### 3.2 StudioAccessibilityValidationEvent

```ts
export interface StudioAccessibilityValidationEvent {
  eventId: string;
  contractId: string;
  validationSource:
    | 'ci_axe'
    | 'ci_keyboard'
    | 'ci_screen_reader'
    | 'runtime_probe';
  status: 'pass' | 'warning' | 'fail';
  violationCount: number;
  criticalViolationCount: number;
  artifactRef?: string;
  occurredAt: string;
}
```

### 3.3 StudioAccessibilityIssueRecord

```ts
export interface StudioAccessibilityIssueRecord {
  issueId: string;
  contractId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  severity: 'warning' | 'high' | 'critical';
  category: 'keyboard' | 'screen_reader' | 'semantic' | 'motion' | 'contrast';
  summary: string;
  state: 'new' | 'investigating' | 'mitigated' | 'resolved';
  releaseBlocked: boolean;
  createdAt: string;
  updatedAt: string;
}
```

### 3.4 StudioAccessibilityPolicyDecision

```ts
export interface StudioAccessibilityPolicyDecision {
  decisionId: string;
  contractId: string;
  action:
    | 'waiver_create'
    | 'waiver_extend'
    | 'waiver_revoke'
    | 'release_block'
    | 'release_allow';
  actorId: string;
  actorRole: string;
  permissionTier: 'baseline' | 'sensitive' | 'restricted';
  releaseChannel: 'preview' | 'staging' | 'production';
  approvalTicket?: string;
  outcome: 'allowed' | 'denied';
  reasonCode?: string;
  decidedAt: string;
}
```

### 3.5 StudioAccessibilityRemediationExecution

```ts
export interface StudioAccessibilityRemediationExecution {
  remediationId: string;
  issueId: string;
  contractId: string;
  action: 'fix_forward' | 'rollback' | 'feature_disable' | 'fallback_mode';
  actorId: string;
  success: boolean;
  validationRecheckPassed: boolean;
  latencyMs: number;
  errorCode?: string;
  executedAt: string;
}
```

### 3.6 StudioAccessibilityAuditEvent

```ts
export interface StudioAccessibilityAuditEvent {
  eventId: string;
  action:
    | 'accessibility.contract.created'
    | 'accessibility.validation.failed'
    | 'accessibility.issue.opened'
    | 'accessibility.policy.denied'
    | 'accessibility.remediation.executed'
    | 'accessibility.issue.closed';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  contractId?: string;
  issueId?: string;
  actorId?: string;
  actorRole?: string;
  reasonCode?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Accessibility contracts must include owner, domain attribution, scope,
  severity, and expiry.
- Validation events must record source suite, status, and violation counts.
- Issue records must include severity, category, release-block flag, and
  deterministic state.
- Policy decisions must enforce role/tier/approval constraints by channel.
- Remediation executions must include success and post-fix validation outcomes.
- Audit events must capture contract, validation, issue, policy, and remediation
  lifecycle actions end to end.

## 5. Acceptance Criteria (OST-00250)

`OST-00250` 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 contract definitions, validation, issue tracking, policy
   decisions, remediation, and governance audits are documented.
4. Ownership boundaries and validation rules are explicit.
