# OSHUN Studio Presence and Cursor Systems Journeys and Edge Cases

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.md`
- `docs/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

1. Presence visibility must be accurate, timely, and policy-aware.
2. Cursor progression must be deterministic and replay-safe.
3. Reconnect/resume behavior must preserve continuity without silent loss.
4. 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**:

1. Participant joins workspace session with actor/role context.
2. Presence envelope is validated and registered.
3. Heartbeat cadence is established and monitored.
4. Active presence badge appears for collaborators.
5. 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**:

1. Heartbeat slowdown or inactivity threshold is reached.
2. Presence transitions from `active` to `idle`.
3. Extended timeout transitions participant to `offline`.
4. UI and collaboration workflows reconcile presence state.
5. 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**:

1. Cursor is updated with next sequence checkpoint.
2. Cursor progression record is validated and emitted.
3. Peers receive updated cursor position in canonical order.
4. Cursor-linked views refresh with consistent sequence state.
5. 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**:

1. Reconnect request includes replay cursor context.
2. Missing deltas are replayed in causal order.
3. Local state is rehydrated to current canonical snapshot.
4. Presence state returns to active with continuity marker.
5. 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**:

1. Query presence/cursor audit logs for scoped window.
2. Validate visibility and redaction behavior against policy.
3. Verify cursor replay and transition outcomes.
4. Export review evidence package.
5. 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.started`
- `presence_cursor.journey.step.completed`
- `presence_cursor.journey.blocked`
- `presence_cursor.journey.recovered`
- `presence_cursor.journey.completed`

Required dimensions:

- `workspaceId`, `sessionId`, `actorId`, `actorRole`
- `journeyId`, `stepId`, `presenceState`, `cursor`, `sequence`
- `replayCursor`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00163)

`OST-00163` is complete only when:

1. At least five presence/cursor 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.
