Disciplines · Decisions (ADRs)

ADR-0033: OSHUN Studio Presence and Cursor Systems

Studio collaboration relies on accurate participant presence and stable cursor semantics.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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.
  • 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