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.mddocs/releases/v1/specs/studio-real-time-collaboration-substrate-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for the Studio real-time collaboration substrate.
This document is the execution artifact for OST-00155.
Personas#
- Program Operator
- Collaboration Producer
- Security Reviewer
- Domain Integrator
- Reliability Engineer
Journey Principles#
- Collaboration state must remain consistent across participants.
- Session joins/leaves and capability grants must be policy-aware.
- Concurrent changes must resolve deterministically.
- Disconnect/reconnect must recover state without hidden data loss.
1. Primary Journeys#
J1. Shared Session Join and Capability Handshake#
Goal: Join a workspace session and receive collaboration capabilities.
Entry: Studio -> Collaboration-enabled workspace
Steps:
- Request channel join with workspace + role context.
- Evaluate entitlement and role-policy grants.
- Establish live session with participant roster.
- Receive capabilities for edit/review/approve actions.
- Emit join audit signal.
Success State:
- Participant joins successfully with explicit capability scope.
J2. Live Multi-Actor Editing#
Goal: Apply changes from multiple participants with deterministic state.
Entry: Active collaboration session
Steps:
- Participant submits real-time change event.
- Substrate sequences and broadcasts event to subscribers.
- Peers apply event to local state in canonical order.
- Presence and context metadata update in-session.
- Event application is acknowledged and audited.
Success State:
- All participants observe the same ordered state transitions.
J3. Concurrent Edit Conflict Resolution#
Goal: Resolve conflicting writes without silent data loss.
Entry: Two or more overlapping edits on the same entity
Steps:
- Detect conflicting event set for entity scope.
- Apply configured strategy (
field-merge,last-write-wins, or manual). - Emit conflict decision metadata.
- Surface resolution summary to participants.
- Persist decision and audit trace.
Success State:
- Conflict is resolved deterministically and visibly.
J4. Disconnect and Replay Recovery#
Goal: Recover participant state after connection interruption.
Entry: Client reconnect after socket/network interruption
Steps:
- Re-authenticate session and capability context.
- Resume from last acknowledged collaboration cursor.
- Replay missed events in causal order.
- Rehydrate local state and participant roster.
- Confirm replay completion and latency metrics.
Success State:
- Reconnected client returns to consistent state without divergence.
J5. Governance and Audit Review of Collaboration Events#
Goal: Validate policy and audit integrity for collaboration actions.
Entry: Compliance/security review cycle
Steps:
- Query collaboration audit stream for scoped session window.
- Verify join/leave and capability actions against policy.
- Validate conflict decisions and replay outcomes.
- Export evidence package for governance archive.
- Record reviewer action and disposition.
Success State:
- Collaboration activity is reviewable, attributable, and policy-consistent.
2. Critical Edge Cases#
E1. Missing Workspace ID on Join#
- Trigger: join request omits
workspaceId. - Required behavior: reject join and emit policy/error audit event.
E2. Unauthorized Capability Request#
- Trigger: participant requests capability not granted by policy.
- Required behavior: deny capability grant and keep session in least-privilege mode.
E3. Duplicate Event ID Collision#
- Trigger: two distinct payloads share same
eventId. - Required behavior: quarantine duplicate and raise contract violation.
E4. Out-of-Order Event Sequence#
- Trigger: event sequence numbers regress or skip unexpectedly.
- Required behavior: pause apply, request replay window, and mark session degraded.
E5. Non-Deterministic Conflict Strategy Resolution#
- Trigger: same conflict input produces different resolution outputs.
- Required behavior: block release and raise determinism incident.
E6. Manual Conflict Resolution Timeout#
- Trigger: manual conflict remains unresolved past SLA window.
- Required behavior: escalate to designated owner and lock affected entity.
E7. Replay Cursor Expired or Invalid#
- Trigger: reconnect cursor is missing, expired, or malformed.
- Required behavior: fail over to full snapshot replay with explicit warning.
E8. Participant Presence Drift#
- Trigger: disconnected participant remains listed as active.
- Required behavior: enforce heartbeat timeout and reconcile roster state.
E9. Telemetry/Audit Emission Failure#
- Trigger: collaboration lifecycle events fail to emit.
- Required behavior: buffer/retry and surface degraded observability warning.
E10. Channel Partition Across Domains#
- Trigger: subset of domain participants cannot receive live updates.
- Required behavior: isolate partition, preserve backlog, and trigger failover routing.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Shared Session Join and Capability Handshake | Collaboration substrate | Entitlement and policy services |
| J2 Live Multi-Actor Editing | Collaboration substrate | Domain adapters + session fan-out |
| J3 Concurrent Edit Conflict Resolution | Collaboration substrate | Conflict resolution adapters |
| J4 Disconnect and Replay Recovery | Collaboration substrate | Replay/cursor services |
| J5 Governance and Audit Review | Collaboration substrate | Audit/compliance pipelines |
4. Instrumentation Requirements#
Required events:
collaboration_substrate.journey.startedcollaboration_substrate.journey.step.completedcollaboration_substrate.journey.blockedcollaboration_substrate.journey.recoveredcollaboration_substrate.journey.completed
Required dimensions:
workspaceId,sessionId,actorId,actorRolejourneyId,stepId,eventType,capability,conflictStrategyreplayCursor,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00155)#
OST-00155 is complete only when:
- At least five collaboration-substrate journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.