Eve library

OSHUN Studio Real-Time Collaboration Substrate Journeys and Edge Cases

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
  • docs/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#

  1. Collaboration state must remain consistent across participants.
  2. Session joins/leaves and capability grants must be policy-aware.
  3. Concurrent changes must resolve deterministically.
  4. 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:

  1. Request channel join with workspace + role context.
  2. Evaluate entitlement and role-policy grants.
  3. Establish live session with participant roster.
  4. Receive capabilities for edit/review/approve actions.
  5. 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:

  1. Participant submits real-time change event.
  2. Substrate sequences and broadcasts event to subscribers.
  3. Peers apply event to local state in canonical order.
  4. Presence and context metadata update in-session.
  5. 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:

  1. Detect conflicting event set for entity scope.
  2. Apply configured strategy (field-merge, last-write-wins, or manual).
  3. Emit conflict decision metadata.
  4. Surface resolution summary to participants.
  5. 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:

  1. Re-authenticate session and capability context.
  2. Resume from last acknowledged collaboration cursor.
  3. Replay missed events in causal order.
  4. Rehydrate local state and participant roster.
  5. 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:

  1. Query collaboration audit stream for scoped session window.
  2. Verify join/leave and capability actions against policy.
  3. Validate conflict decisions and replay outcomes.
  4. Export evidence package for governance archive.
  5. 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.started
  • collaboration_substrate.journey.step.completed
  • collaboration_substrate.journey.blocked
  • collaboration_substrate.journey.recovered
  • collaboration_substrate.journey.completed

Required dimensions:

  • workspaceId, sessionId, actorId, actorRole
  • journeyId, stepId, eventType, capability, conflictStrategy
  • replayCursor, outcome, latencyMs, errorCode

5. Acceptance Criteria (OST-00155)#

OST-00155 is complete only when:

  1. At least five collaboration-substrate journeys are documented.
  2. At least ten deterministic edge cases are documented.
  3. Journey-to-surface mapping is explicit.
  4. Instrumentation requirements and dimensions are documented.