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.mddocs/adr/ADR-0032-oshun-studio-real-time-collaboration-substrate.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#
- 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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for collaboration envelope, session topology, conflict decision, replay cursor, and audit events are documented.
- Ownership boundaries and validation rules are explicit.