# ADR-0033: OSHUN Studio Presence and Cursor Systems

**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

Studio collaboration relies on accurate participant presence and stable cursor
semantics. Current signals are partially implicit and not consistently modeled
across domains, causing operator confusion around who is active, where they are
working, and what replay point is authoritative.

Without a canonical presence/cursor system, OSHUN risks:

- stale participant indicators and misleading collaboration context
- replay/resume inconsistencies after reconnect or handoff
- duplicated or skipped windows in timeline and session recovery flows
- weak auditability for actor visibility and cursor movement decisions

## Decision Drivers

- **Clarity**: explicit participant presence and activity state.
- **Determinism**: stable cursor movement and replay semantics.
- **Resilience**: robust reconnect behavior and cursor continuity.
- **Security**: policy-aware presence exposure and redaction controls.
- **Interoperability**: shared contracts across Yemaya/Isis/Hathor/Aja/Bellona.

## Considered Options

### Option 1: Implicit Presence with Local Cursor State

Keep presence inferred client-side and cursor handling per-surface.

**Pros**:

- Minimal implementation effort.

**Cons**:

- High drift risk and inconsistent replay behavior.
- Weak cross-domain observability and governance.

### Option 2: Shared Presence Heartbeats with Flexible Cursor Contracts

Centralize heartbeats but allow ad hoc cursor schemas per domain.

**Pros**:

- Better visibility than local-only presence.

**Cons**:

- Cursor inconsistencies remain across workflows.
- Compatibility and recovery behavior become unpredictable.

### Option 3: Canonical Presence and Cursor Contracts (Chosen)

Adopt one policy-aware presence and cursor model with typed envelopes,
heartbeat/liveness semantics, deterministic cursor progression, and replay
guarantees.

**Pros**:

- Reliable operator awareness and deterministic resume/replay behavior.
- Strong compatibility and audit guarantees.
- Easier cross-domain coordination and incident reconstruction.

**Cons**:

- Higher coordination and governance overhead.

## Decision Outcome

**Chosen option**: Option 3.

Presence/cursor requirements:

1. **Canonical presence envelope** with actor/session/workspace attributes.
2. **Heartbeat and liveness contract** for active/idle/offline semantics.
3. **Cursor progression contract** for deterministic forward/backward movement.
4. **Replay/resume contract** for reconnect and handoff continuity.
5. **Security and governance contract** for visibility, redaction, and audits.

## Normative Rules

### Canonical Presence Envelope Contract

- Presence events must include `actorId`, `workspaceId`, `sessionId`,
  `presenceState`, and `occurredAt`.
- Domain-specific details must live under extension payloads.
- Invalid presence payloads must be rejected before distribution.

### Heartbeat and Liveness Contract

- Liveness is determined by heartbeat cadence and timeout windows.
- Transitions (`active`, `idle`, `offline`) must be explicit and auditable.
- Presence recovery after reconnect must avoid duplicate active sessions.

### Cursor Progression Contract

- Cursor values must be stable, monotonic within sequence boundaries, and
  replay-safe.
- Cursor movement must preserve causal ordering and prevent silent skips.
- Cursor rollback or reset must emit explicit state transition records.

### Replay and Resume Contract

- Resume operations must accept last acknowledged cursor and replay deltas.
- Replay must be idempotent and produce deterministic ordering.
- Replay failures must return explicit error states and recovery guidance.

### Security and Governance Contract

- Presence visibility must respect role and tenant policy boundaries.
- Sensitive cursor metadata must be redacted where policy requires.
- Presence/cursor lifecycle events must emit auditable telemetry records.

### Release Validity Contract

A presence/cursor release is valid only when all are true:

- envelope compatibility validation passes
- heartbeat/liveness transition tests pass
- cursor progression determinism tests pass
- replay/resume recovery tests pass
- telemetry/audit integrity checks pass
- rollback plan and owner handoff are documented

## Architecture Implications

- Studio surfaces consume shared presence and cursor streams.
- BFF manages heartbeat liveness and cursor continuity orchestration.
- Collaboration and activity feeds reuse canonical cursor primitives.
- Analytics pipelines monitor liveness health and replay reliability.

## Acceptance Criteria (OST-00161)

`OST-00161` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0039-oshun-studio-presence-and-cursor-systems.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines presence envelope, heartbeat/liveness, cursor progression,
   replay/resume, security/governance, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0032`, especially `ADR-0012`,
   `ADR-0032`, 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

- Clearer collaboration awareness and better handoff reliability.
- Stronger replay/reconnect predictability and incident reconstruction.
- Improved policy and compliance confidence for presence visibility.

### Negative

- Increased operational and contract governance complexity.
- Requires strict heartbeat/cursor adapter compliance.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0037-oshun-studio-activity-and-change-feeds.md`
- `docs/adr/ADR-0038-oshun-studio-real-time-collaboration-substrate.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`