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.mddocs/adr/ADR-0033-oshun-studio-presence-and-cursor-systems.mdlibs/oshun/analytics/src/types.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/design/ux-principles.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for presence envelope, heartbeat record, cursor progression, replay cursor, and audit events are documented.
- Ownership boundaries and validation rules are explicit.