# OSHUN Studio Activity and Change Feeds 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-0031-oshun-studio-activity-and-change-feeds.md`

## Purpose

Define dependencies and canonical contracts for Studio activity and change-feed
capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0031-oshun-studio-activity-and-change-feeds.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

- **Activity/change feed UI**: Studio feed surfaces in
  `apps/oshun/web/src/components/studio`.
- **Feed ingestion and normalization**: BFF aggregation + canonical mapper.
- **Domain signal emitters**: domain adapters publishing change events.
- **Replay and cursor services**: deterministic pagination and replay APIs.
- **Telemetry and audit**: analytics + compliance pipelines.

### 1.2 Domain Dependency Graph

- `Activity/Change Feeds -> Yemaya`: collaboration and governance changes.
- `Activity/Change Feeds -> Isis`: model lifecycle and pipeline changes.
- `Activity/Change Feeds -> Hathor`: narrative/world state updates.
- `Activity/Change Feeds -> Aja`: media processing and timeline events.
- `Activity/Change Feeds -> Bellona`: build/runtime and incident changes.
- `Project Obsidian -> all`: unified franchise-level operational timeline.

## 2. Ownership and Contract Matrix

| Area                                | Owner                    | Consumers               | Artifact                | Contract                          |
| ----------------------------------- | ------------------------ | ----------------------- | ----------------------- | --------------------------------- |
| Canonical change envelope           | BFF + Domain Integrators | Activity feed UI        | Change event payload    | `StudioActivityChangeEnvelope`    |
| Timeline ordering and cursoring     | BFF + Data Platform      | Studio operators        | Timeline/replay payload | `StudioActivityTimelineCursor`    |
| Actionability and follow-up routing | Web + Program Ops        | Ops + Security          | Action routing payload  | `StudioActivityFollowUpAction`    |
| Change attribution and governance   | Security + Compliance    | Auditors + leads        | Attribution payload     | `StudioActivityAttributionRecord` |
| Audit/telemetry evidence stream     | Data Platform + Security | Compliance + Governance | Event stream            | `StudioActivityFeedAuditEvent`    |

## 3. Canonical Contracts

### 3.1 StudioActivityChangeEnvelope

```ts
export interface StudioActivityChangeEnvelope {
  changeId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  changeType: string;
  actorId: string;
  actorRole: string;
  targetEntityId: string;
  targetEntityType: string;
  summary: string;
  metadata?: Record<string, unknown>;
  occurredAt: string;
}
```

### 3.2 StudioActivityTimelineCursor

```ts
export interface StudioActivityTimelineCursor {
  cursor: string;
  direction: 'forward' | 'backward';
  pageSize: number;
  orderedBy: 'occurredAt' | 'ingestedAt';
  replaySafe: boolean;
}
```

### 3.3 StudioActivityFollowUpAction

```ts
export interface StudioActivityFollowUpAction {
  actionId: string;
  changeId: string;
  route: string;
  ownerRole: string;
  priority: 'low' | 'medium' | 'high' | 'critical';
  dueAt?: string;
  createdAt: string;
}
```

### 3.4 StudioActivityAttributionRecord

```ts
export interface StudioActivityAttributionRecord {
  attributionId: string;
  changeId: string;
  actorId: string;
  actorRole: string;
  tenantId?: string;
  policyContext: string;
  verifiedAt: string;
}
```

### 3.5 StudioActivityFeedAuditEvent

```ts
export interface StudioActivityFeedAuditEvent {
  eventId: string;
  action:
    | 'activity.change_ingested'
    | 'activity.timeline_rendered'
    | 'activity.replayed'
    | 'activity.follow_up_routed'
    | 'activity.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  changeId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Feed ingestion must reject events missing canonical IDs/actor/target fields.
- Timeline ordering must remain deterministic for identical query parameters.
- Cursor replay must be idempotent and pagination-safe.
- Follow-up actions must include route and owner role context.
- Attribution records must meet policy and audit traceability requirements.

## 5. Acceptance Criteria (OST-00146)

`OST-00146` 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 envelope, timeline cursor, follow-up action, attribution
   record, and audit event are documented.
4. Ownership boundaries and validation rules are explicit.
