# OSHUN Studio Real-Time Collaboration Substrate 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-0032-oshun-studio-real-time-collaboration-substrate.md`

## Purpose

Define dependencies and canonical contracts for Studio real-time collaboration
substrate capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project
Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0032-oshun-studio-real-time-collaboration-substrate.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

- **Collaboration UI surfaces**: Studio collaborative workspaces in
  `apps/oshun/web/src/components/studio`.
- **Session topology and fan-out**: BFF collaboration session services.
- **Conflict-resolution adapters**: domain-level merge and resolution logic.
- **Replay and reconnect services**: cursor sequencing and state rehydration.
- **Telemetry and audit**: analytics + compliance evidence pipelines.

### 1.2 Domain Dependency Graph

- `Real-Time Collaboration -> Yemaya`: co-authoring and workspace operations.
- `Real-Time Collaboration -> Isis`: workflow, generation, and review pipelines.
- `Real-Time Collaboration -> Hathor`: narrative/world state editing sessions.
- `Real-Time Collaboration -> Aja`: timeline/media collaboration and routing.
- `Real-Time Collaboration -> Bellona`: runtime/build incident coordination.
- `Project Obsidian -> all`: cross-domain collaboration policy and governance.

## 2. Ownership and Contract Matrix

| Area                                | Owner                    | Consumers                      | Artifact               | Contract                              |
| ----------------------------------- | ------------------------ | ------------------------------ | ---------------------- | ------------------------------------- |
| Canonical collaboration envelope    | BFF + Domain Integrators | Studio collaboration UI        | Event payload          | `StudioCollaborationEventEnvelope`    |
| Session membership and capabilities | BFF + Security           | Operators + Program Ops        | Session payload        | `StudioCollaborationSessionTopology`  |
| Concurrent change resolution        | Domain Integrators       | Editors + reviewers            | Resolution payload     | `StudioCollaborationConflictDecision` |
| Replay and reconnect behavior       | BFF + Data Platform      | Web clients + incident tooling | Replay cursor payload  | `StudioCollaborationReplayCursor`     |
| Collaboration audit evidence        | Data Platform + Security | Compliance + governance        | Telemetry/audit stream | `StudioCollaborationAuditEvent`       |

## 3. Canonical Contracts

### 3.1 StudioCollaborationEventEnvelope

```ts
export interface StudioCollaborationEventEnvelope {
  eventId: string;
  workspaceId: string;
  actorId: string;
  actorRole: string;
  sessionId: string;
  eventType: string;
  entityId: string;
  entityType: string;
  payload: Record<string, unknown>;
  occurredAt: string;
}
```

### 3.2 StudioCollaborationSessionTopology

```ts
export interface StudioCollaborationSessionTopology {
  sessionId: string;
  workspaceId: string;
  channelId: string;
  participants: Array<{
    actorId: string;
    role: string;
    capabilities: string[];
  }>;
  updatedAt: string;
}
```

### 3.3 StudioCollaborationConflictDecision

```ts
export interface StudioCollaborationConflictDecision {
  decisionId: string;
  workspaceId: string;
  entityId: string;
  strategy: 'last-write-wins' | 'field-merge' | 'manual-resolution';
  winningEventId?: string;
  requiresManualResolution: boolean;
  resolvedBy?: string;
  resolvedAt: string;
}
```

### 3.4 StudioCollaborationReplayCursor

```ts
export interface StudioCollaborationReplayCursor {
  workspaceId: string;
  sessionId: string;
  cursor: string;
  sequence: number;
  replayMode: 'delta' | 'full-snapshot';
  replaySafe: boolean;
  generatedAt: string;
}
```

### 3.5 StudioCollaborationAuditEvent

```ts
export interface StudioCollaborationAuditEvent {
  eventId: string;
  action:
    | 'collaboration.session_joined'
    | 'collaboration.session_left'
    | 'collaboration.event_applied'
    | 'collaboration.conflict_resolved'
    | 'collaboration.replay_executed'
    | 'collaboration.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  workspaceId: string;
  sessionId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Collaboration events missing workspace/session/actor context must be rejected.
- Session joins must enforce entitlement and role-policy checks.
- Conflict resolution outcomes must be deterministic and explicitly observable.
- Replay must be idempotent and preserve causal ordering guarantees.
- Audit events must map join/leave/resolve/replay/policy outcomes.

## 5. Acceptance Criteria (OST-00154)

`OST-00154` 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 collaboration envelope, session topology, conflict decision,
   replay cursor, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
