# OSHUN Studio Presence and Cursor Systems 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-0033-oshun-studio-presence-and-cursor-systems.md`

## Purpose

Define dependencies and canonical contracts for Studio presence and cursor
systems across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0033-oshun-studio-presence-and-cursor-systems.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

- **Presence UI surfaces**: Studio collaboration/presence indicators in
  `apps/oshun/web/src/components/studio`.
- **Heartbeat and liveness services**: BFF session heartbeat orchestration.
- **Cursor sequencing services**: canonical cursor issuance and progression.
- **Replay/resume services**: reconnect and handoff continuity APIs.
- **Telemetry and audit**: analytics + compliance evidence pipelines.

### 1.2 Domain Dependency Graph

- `Presence/Cursor -> Yemaya`: collaboration presence and release workflows.
- `Presence/Cursor -> Isis`: generation pipeline session continuity.
- `Presence/Cursor -> Hathor`: narrative world-state co-authoring sessions.
- `Presence/Cursor -> Aja`: timeline collaboration and retargeting flows.
- `Presence/Cursor -> Bellona`: runtime/build incident command sessions.
- `Project Obsidian -> all`: shared franchise-level presence policy governance.

## 2. Ownership and Contract Matrix

| Area                               | Owner                    | Consumers                     | Artifact              | Contract                         |
| ---------------------------------- | ------------------------ | ----------------------------- | --------------------- | -------------------------------- |
| Canonical presence envelope        | BFF + Domain Integrators | Studio collaboration surfaces | Presence payload      | `StudioPresenceEnvelope`         |
| Heartbeat and liveness transitions | BFF + Platform SRE       | Operators + reliability teams | Liveness payload      | `StudioPresenceHeartbeatRecord`  |
| Cursor progression semantics       | BFF + Data Platform      | Replay/resume clients         | Cursor payload        | `StudioCursorProgressionRecord`  |
| Replay and handoff continuity      | BFF + Web                | Reconnecting participants     | Replay payload        | `StudioPresenceReplayCursor`     |
| Presence/cursor audit evidence     | Data Platform + Security | Compliance + governance       | Telemetry/audit event | `StudioPresenceCursorAuditEvent` |

## 3. Canonical Contracts

### 3.1 StudioPresenceEnvelope

```ts
export interface StudioPresenceEnvelope {
  presenceId: string;
  workspaceId: string;
  sessionId: string;
  actorId: string;
  actorRole: string;
  presenceState: 'active' | 'idle' | 'offline';
  domainScope: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  occurredAt: string;
}
```

### 3.2 StudioPresenceHeartbeatRecord

```ts
export interface StudioPresenceHeartbeatRecord {
  heartbeatId: string;
  sessionId: string;
  actorId: string;
  sequence: number;
  heartbeatMs: number;
  timeoutMs: number;
  livenessState: 'healthy' | 'degraded' | 'expired';
  measuredAt: string;
}
```

### 3.3 StudioCursorProgressionRecord

```ts
export interface StudioCursorProgressionRecord {
  cursorId: string;
  workspaceId: string;
  sessionId: string;
  actorId: string;
  cursor: string;
  direction: 'forward' | 'backward';
  sequence: number;
  replaySafe: boolean;
  occurredAt: string;
}
```

### 3.4 StudioPresenceReplayCursor

```ts
export interface StudioPresenceReplayCursor {
  workspaceId: string;
  sessionId: string;
  actorId: string;
  replayCursor: string;
  replayMode: 'delta' | 'snapshot';
  continuityState: 'consistent' | 'recovered' | 'degraded';
  generatedAt: string;
}
```

### 3.5 StudioPresenceCursorAuditEvent

```ts
export interface StudioPresenceCursorAuditEvent {
  eventId: string;
  action:
    | 'presence.joined'
    | 'presence.left'
    | 'presence.heartbeat_processed'
    | 'cursor.progressed'
    | 'cursor.replay_executed'
    | 'presence_cursor.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  workspaceId: string;
  sessionId?: string;
  actorId?: string;
  actorRole?: string;
  cursor?: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Presence payloads missing actor/workspace/session context must be rejected.
- Liveness transitions must be driven by deterministic heartbeat thresholds.
- Cursor progression must be monotonic within sequence constraints.
- Replay cursors must be idempotent and causally ordered.
- Presence/cursor audit events must map join/leave/heartbeat/progression/replay
  lifecycle outcomes.

## 5. Acceptance Criteria (OST-00162)

`OST-00162` 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 presence envelope, heartbeat record, cursor progression, replay
   cursor, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
