Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Security
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0033-oshun-studio-presence-and-cursor-systems.mddocs/releases/v1/specs/studio-presence-and-cursor-systems-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio presence and cursor systems.
This document is the execution artifact for OST-00163.
Personas#
- Collaboration Lead
- Program Operator
- Domain Integrator
- Security Reviewer
- Reliability Engineer
Journey Principles#
- Presence visibility must be accurate, timely, and policy-aware.
- Cursor progression must be deterministic and replay-safe.
- Reconnect/resume behavior must preserve continuity without silent loss.
- Presence/cursor lifecycle transitions must be auditable end-to-end.
1. Primary Journeys#
J1. Participant Presence Join and Liveness Start#
Goal: Register participant presence with active heartbeat liveness.
Entry: Studio collaborative workspace session start
Steps:
- Participant joins workspace session with actor/role context.
- Presence envelope is validated and registered.
- Heartbeat cadence is established and monitored.
- Active presence badge appears for collaborators.
- Join/liveness audit events are emitted.
Success State:
- Participant appears with accurate active status and policy-compliant metadata.
J2. Presence Transition Active to Idle to Offline#
Goal: Represent participant activity transitions accurately.
Entry: In-session activity changes or disconnect timeout
Steps:
- Heartbeat slowdown or inactivity threshold is reached.
- Presence transitions from
activetoidle. - Extended timeout transitions participant to
offline. - UI and collaboration workflows reconcile presence state.
- Transition events are persisted for audit.
Success State:
- Presence transitions are deterministic and visible to collaborators.
J3. Cursor Progression During Collaborative Work#
Goal: Progress cursors deterministically across live collaboration updates.
Entry: Participant performs ordered collaboration actions
Steps:
- Cursor is updated with next sequence checkpoint.
- Cursor progression record is validated and emitted.
- Peers receive updated cursor position in canonical order.
- Cursor-linked views refresh with consistent sequence state.
- Cursor progression audit event is emitted.
Success State:
- Every participant sees stable, ordered cursor progression.
J4. Replay and Resume After Reconnect#
Goal: Recover participant context after connection interruption.
Entry: Participant reconnect with last acknowledged cursor
Steps:
- Reconnect request includes replay cursor context.
- Missing deltas are replayed in causal order.
- Local state is rehydrated to current canonical snapshot.
- Presence state returns to active with continuity marker.
- Replay completion is recorded in audit telemetry.
Success State:
- Reconnected participant resumes without duplicated or missing state.
J5. Presence/Cursor Governance Review#
Goal: Validate policy and operational integrity of presence/cursor events.
Entry: Security/compliance review cycle
Steps:
- Query presence/cursor audit logs for scoped window.
- Validate visibility and redaction behavior against policy.
- Verify cursor replay and transition outcomes.
- Export review evidence package.
- Record reviewer decision and follow-up actions.
Success State:
- Governance teams can verify presence/cursor integrity and policy compliance.
2. Critical Edge Cases#
E1. Missing Presence Actor ID#
- Trigger: presence envelope missing
actorId. - Required behavior: reject payload and emit validation error.
E2. Duplicate Active Presence for Same Session#
- Trigger: same actor/session emits duplicate active join events.
- Required behavior: deduplicate and reconcile to one active record.
E3. Heartbeat Jitter Beyond Threshold#
- Trigger: heartbeat intervals exceed liveness threshold unexpectedly.
- Required behavior: transition to degraded liveness and surface warning.
E4. False Offline Transition During Network Spike#
- Trigger: temporary packet loss triggers offline state incorrectly.
- Required behavior: apply grace window and retry before final offline change.
E5. Cursor Regression#
- Trigger: incoming cursor sequence is lower than current acknowledged sequence.
- Required behavior: reject regression and request fresh replay baseline.
E6. Cursor Skip with Missing Delta#
- Trigger: sequence jumps without intermediate cursor events.
- Required behavior: pause progression and force replay reconciliation.
E7. Replay Cursor Expired#
- Trigger: reconnect cursor points to expired retention window.
- Required behavior: fall back to full snapshot recovery with warning.
E8. Policy-Denied Presence Visibility#
- Trigger: actor requests visibility outside authorized scope.
- Required behavior: deny view and emit policy-denied audit event.
E9. Presence/Cursor Audit Emission Failure#
- Trigger: lifecycle events fail to emit to audit pipeline.
- Required behavior: buffer/retry and expose degraded observability state.
E10. Handoff Cursor Mismatch#
- Trigger: ownership handoff references stale cursor baseline.
- Required behavior: require handoff reconciliation before workflow transfer.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Presence Join and Liveness Start | Presence/Cursor systems | Session topology services |
| J2 Active/Idle/Offline Transition | Presence/Cursor systems | Heartbeat/liveness monitor |
| J3 Cursor Progression During Collaboration | Presence/Cursor systems | Collaboration event sequencing |
| J4 Replay and Resume After Reconnect | Presence/Cursor systems | Replay/cursor services |
| J5 Presence/Cursor Governance Review | Presence/Cursor systems | Audit/compliance pipelines |
4. Instrumentation Requirements#
Required events:
presence_cursor.journey.startedpresence_cursor.journey.step.completedpresence_cursor.journey.blockedpresence_cursor.journey.recoveredpresence_cursor.journey.completed
Required dimensions:
workspaceId,sessionId,actorId,actorRolejourneyId,stepId,presenceState,cursor,sequencereplayCursor,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00163)#
OST-00163 is complete only when:
- At least five presence/cursor journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.