# OSHUN Studio Commenting and Annotation System Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Security  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0034-oshun-studio-commenting-and-annotation-system.md`

## Purpose

Define dependencies and canonical contracts for Studio commenting and annotation
capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0034-oshun-studio-commenting-and-annotation-system.md`
- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`
- `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`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Annotation UI surfaces**: Studio commenting and annotation modules in
  `apps/oshun/web/src/components/studio`.
- **Thread persistence and lifecycle services**: BFF annotation APIs.
- **Target binding adapters**: domain adapters for entity/frame/token anchors.
- **Moderation and policy services**: visibility, redaction, and abuse controls.
- **Telemetry and audit**: analytics + compliance evidence pipelines.

### 1.2 Domain Dependency Graph

- `Commenting/Annotation -> Yemaya`: program coordination and release feedback.
- `Commenting/Annotation -> Isis`: model review and generation quality notes.
- `Commenting/Annotation -> Hathor`: narrative and worldbuilding annotations.
- `Commenting/Annotation -> Aja`: timeline and media-sequence notes.
- `Commenting/Annotation -> Bellona`: runtime/build incident annotations.
- `Project Obsidian -> all`: franchise-wide review, moderation, and governance.

## 2. Ownership and Contract Matrix

| Area                               | Owner                    | Consumers                      | Artifact              | Contract                             |
| ---------------------------------- | ------------------------ | ------------------------------ | --------------------- | ------------------------------------ |
| Canonical annotation envelope      | BFF + Domain Integrators | Studio reviewers and operators | Annotation payload    | `StudioAnnotationEnvelope`           |
| Threading and reply structure      | BFF + Web                | Collaboration participants     | Thread payload        | `StudioAnnotationThread`             |
| Annotation lifecycle transitions   | Program Ops + Web        | Owners + moderators            | Lifecycle payload     | `StudioAnnotationLifecycleEvent`     |
| Moderation and visibility controls | Security + Compliance    | Moderators + governance        | Moderation payload    | `StudioAnnotationModerationDecision` |
| Annotation audit evidence          | Data Platform + Security | Compliance + governance        | Telemetry/audit event | `StudioAnnotationAuditEvent`         |

## 3. Canonical Contracts

### 3.1 StudioAnnotationEnvelope

```ts
export interface StudioAnnotationEnvelope {
  annotationId: string;
  threadId: string;
  targetRef: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  actorId: string;
  actorRole: string;
  content: string;
  visibilityScope: 'workspace' | 'project' | 'domain';
  occurredAt: string;
}
```

### 3.2 StudioAnnotationThread

```ts
export interface StudioAnnotationThread {
  threadId: string;
  rootAnnotationId: string;
  targetRef: string;
  replyCount: number;
  state: 'open' | 'acknowledged' | 'resolved' | 'locked';
  updatedAt: string;
}
```

### 3.3 StudioAnnotationLifecycleEvent

```ts
export interface StudioAnnotationLifecycleEvent {
  lifecycleId: string;
  annotationId: string;
  threadId: string;
  action: 'create' | 'reply' | 'acknowledge' | 'resolve' | 'reopen';
  actorId: string;
  actorRole: string;
  reason?: string;
  occurredAt: string;
}
```

### 3.4 StudioAnnotationModerationDecision

```ts
export interface StudioAnnotationModerationDecision {
  decisionId: string;
  annotationId: string;
  action: 'allow' | 'hide' | 'redact' | 'lock';
  moderatorId: string;
  policyId: string;
  reason: string;
  decidedAt: string;
}
```

### 3.5 StudioAnnotationAuditEvent

```ts
export interface StudioAnnotationAuditEvent {
  eventId: string;
  action:
    | 'annotation.created'
    | 'annotation.replied'
    | 'annotation.resolved'
    | 'annotation.reopened'
    | 'annotation.moderated'
    | 'annotation.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  annotationId?: string;
  threadId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Annotation payloads missing thread/target/actor context must be rejected.
- Thread ordering must remain deterministic for identical query parameters.
- Lifecycle transitions must follow explicit state transition contracts.
- Moderation decisions must reference active policy IDs and rationale.
- Audit events must capture lifecycle and moderation outcomes end-to-end.

## 5. Acceptance Criteria (OST-00170)

`OST-00170` 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 annotation envelope, thread, lifecycle event, moderation
   decision, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
