# ADR-0032: OSHUN Studio Real-Time Collaboration Substrate

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, OSHUN
Security  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

OSHUN Studio needs shared, low-latency collaboration across narrative, asset,
pipeline, and governance surfaces. Current collaboration behavior is mostly
surface-local and asynchronous, which creates state drift between operators and
slows incident response and production coordination.

Without a first-class real-time collaboration substrate, OSHUN risks:

- conflicting edits and reduced trust in current workspace state
- delayed handoffs for approvals, reviews, and production actions
- inconsistent operational awareness across domains and time zones
- weak recovery behavior during network partitions and reconnects

## Decision Drivers

- **Consistency**: deterministic shared-state behavior for multi-user sessions.
- **Latency**: predictable sub-second propagation for collaboration updates.
- **Resilience**: reconnect/replay behavior that preserves causal ordering.
- **Security**: policy-aware collaboration actions and auditability.
- **Interoperability**: shared protocol for Yemaya/Isis/Hathor/Aja/Bellona.

## Considered Options

### Option 1: Polling + Optimistic Local Merges

Retain asynchronous API polling and local optimistic merges per surface.

**Pros**:

- Lower initial implementation complexity.

**Cons**:

- High drift risk and stale collaboration context.
- Inefficient at scale for active Studio sessions.

### Option 2: Real-Time Channel with Loose Event Semantics

Use websocket channels but allow mostly ad hoc payload schemas.

**Pros**:

- Faster delivery of near-real-time updates.

**Cons**:

- Hard to maintain compatibility and deterministic conflict handling.
- Fragmented observability and policy-governance semantics.

### Option 3: Canonical Collaboration Substrate with Typed Contracts (Chosen)

Adopt one policy-aware collaboration substrate with typed envelopes, conflict
resolution strategy, replay/reconnect semantics, and observability contracts.

**Pros**:

- Deterministic cross-domain collaboration behavior.
- Strong compatibility and auditability guarantees.
- Better failure handling under reconnect and partition scenarios.

**Cons**:

- Higher rollout coordination and schema governance overhead.

## Decision Outcome

**Chosen option**: Option 3.

Real-time collaboration substrate requirements:

1. **Canonical collaboration envelope** with actor/session/workspace context.
2. **Session topology contract** for channel membership and capability grants.
3. **Conflict resolution contract** for concurrent edit/application behavior.
4. **Replay and reconnect contract** for deterministic recovery after
   disconnect.
5. **Security and governance contract** for policy checks and auditable trails.

## Normative Rules

### Canonical Collaboration Envelope Contract

- Every collaboration event must include `eventId`, `workspaceId`, `actorId`,
  `sessionId`, `eventType`, and `occurredAt`.
- Domain-specific fields must be nested under typed extension payloads.
- Events missing required context must be rejected before fan-out.

### Session Topology and Membership Contract

- Channel joins must verify workspace entitlement and active role policy.
- Session membership changes must emit deterministic join/leave signals.
- Capability grants must be explicit and revocable without reconnect churn.

### Conflict Resolution Contract

- Concurrent writes must apply deterministic ordering semantics.
- Domain adapters must declare merge strategy per collaboration entity type.
- Non-mergeable conflicts must yield explicit resolution states, not silent
  overwrite.

### Replay and Reconnect Contract

- Reconnect must support cursor-based replay of missed collaboration events.
- Replay must be idempotent and preserve causal event ordering.
- Partial replay failure must surface explicit operator-visible error state.

### Security and Governance Contract

- Collaboration actions must be policy-evaluated at execution time.
- Sensitive collaboration events must be redacted per role/privacy policy.
- Collaboration telemetry and audit events must meet retention requirements.

### Release Validity Contract

A collaboration substrate release is valid only when all are true:

- envelope compatibility validation passes
- join/leave/capability policy tests pass
- conflict-resolution determinism tests pass
- reconnect/replay recovery tests pass
- telemetry/audit integrity checks pass
- rollback plan and owner handoff are documented

## Architecture Implications

- Studio collaboration flows share one typed event transport and envelope model.
- BFF hosts collaboration session topology and fan-out orchestration.
- Web workspace surfaces consume collaboration streams with explicit recovery
  states.
- Analytics pipelines track collaboration health, policy denials, and recovery
  latencies.

## Acceptance Criteria (OST-00153)

`OST-00153` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0038-oshun-studio-real-time-collaboration-substrate.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines collaboration envelope, session topology, conflict resolution,
   replay/reconnect, security/governance, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0031`, especially `ADR-0012`,
   `ADR-0023`, and `ADR-0031`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/analytics`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Faster cross-domain collaboration with stronger consistency guarantees.
- Better incident and production coordination in shared workspace contexts.
- More reliable recovery behavior under disconnect and partition conditions.

### Negative

- Increased complexity in channel orchestration and schema governance.
- Requires strict adapter compliance and continuous compatibility testing.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0029-oshun-studio-workspace-context-switching.md`
- `docs/adr/ADR-0037-oshun-studio-activity-and-change-feeds.md`

## References

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `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`