Eve library

OSHUN Studio Presence and Cursor Systems Dependency and Data Contract Map

Spec

Revision 1

On this page

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.