Eve library

OSHUN Studio Real-Time Collaboration Substrate 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-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.