Disciplines · Decisions (ADRs)

ADR-0032: OSHUN Studio Real-Time Collaboration Substrate

OSHUN Studio needs shared, low-latency collaboration across narrative, asset, pipeline, and governance surfaces.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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.
  • 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