Eve library

OSHUN Studio Commenting and Annotation System 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-0034-oshun-studio-commenting-and-annotation-system.md
  • docs/releases/v1/specs/studio-commenting-and-annotation-system-dependency-and-data-contract-map.md

Purpose#

Define primary journeys and deterministic edge-case behavior for Studio commenting and annotation workflows.

This document is the execution artifact for OST-00171.

Personas#

  • Collaboration Lead
  • Program Operator
  • Domain Integrator
  • Security Reviewer
  • Compliance Auditor

Journey Principles#

  1. Every annotation must be anchored to explicit target context.
  2. Thread lifecycle transitions must be deterministic and auditable.
  3. Moderation and visibility controls must be policy-aware.
  4. Resolved decisions must preserve traceability and reopen history.

1. Primary Journeys#

J1. Create Context-Bound Annotation#

Goal: Capture actionable feedback on a specific target scope.

Entry: Studio asset/timeline/entity review surface

Steps:

  1. Select target anchor (entity, frame, token range, or coordinate).
  2. Enter annotation content and visibility scope.
  3. Submit annotation envelope with actor metadata.
  4. Persist annotation and render in thread list.
  5. Emit creation audit event.

Success State:

  • Annotation is visible in context with complete actor/target metadata.

J2. Reply and Thread Expansion#

Goal: Continue conversation with deterministic thread structure.

Entry: Open annotation thread

Steps:

  1. Open existing thread with ordered replies.
  2. Submit reply bound to parent annotation.
  3. Update thread reply count and state metadata.
  4. Re-render participants with latest activity markers.
  5. Emit reply lifecycle event.

Success State:

  • Thread maintains consistent ordering and relationship integrity.

J3. Acknowledge and Resolve Annotation#

Goal: Transition annotation thread to resolved state with ownership.

Entry: Actionable annotation with remediation complete

Steps:

  1. Assign owner and acknowledge pending annotation.
  2. Add resolution rationale and evidence references.
  3. Transition state to resolved.
  4. Notify thread participants of closure.
  5. Emit resolution lifecycle and audit events.

Success State:

  • Resolution is explicit, attributable, and traceable.

J4. Reopen Resolved Annotation#

Goal: Reopen previously resolved thread when issues regress.

Entry: Resolved annotation with newly discovered impact

Steps:

  1. Trigger reopen action with reason code.
  2. Restore thread state to open.
  3. Preserve prior resolution evidence and timestamps.
  4. Notify owners and participants.
  5. Emit reopen lifecycle event.

Success State:

  • Thread history remains intact while new action cycle begins.

J5. Moderation and Governance Review#

Goal: Enforce visibility policy and moderation controls on annotation content.

Entry: Moderation/security review cycle

Steps:

  1. Query annotation stream by moderation policy filters.
  2. Evaluate visibility and policy scope compliance.
  3. Apply moderation action (allow/hide/redact/lock) if required.
  4. Export governance evidence package.
  5. Record reviewer disposition and handoff.

Success State:

  • Annotation workflows satisfy policy and compliance requirements.

2. Critical Edge Cases#

E1. Missing Target Anchor#

  • Trigger: annotation submitted without target reference.
  • Required behavior: reject annotation and emit validation error.

E2. Empty Annotation Content#

  • Trigger: submission payload contains empty or whitespace-only content.
  • Required behavior: block submission and require actionable content.

E3. Invalid Parent Annotation Reference#

  • Trigger: reply references missing or deleted parent annotation.
  • Required behavior: reject reply and preserve thread consistency.

E4. Duplicate Annotation ID Collision#

  • Trigger: two payloads share same annotationId.
  • Required behavior: quarantine duplicate and raise contract violation.

E5. Non-Deterministic Thread Ordering#

  • Trigger: identical query returns different reply ordering.
  • Required behavior: block release and raise ordering integrity incident.

E6. Resolve Without Owner Attribution#

  • Trigger: resolution action submitted without owner metadata.
  • Required behavior: block transition and request owner assignment.

E7. Reopen Without Resolution History#

  • Trigger: reopen action references missing prior resolution evidence.
  • Required behavior: deny reopen and flag lifecycle integrity issue.

E8. Unauthorized Visibility Scope Expansion#

  • Trigger: actor tries to expand annotation visibility beyond policy scope.
  • Required behavior: deny request and emit policy-denied audit event.

E9. Moderation Action Without Policy ID#

  • Trigger: moderation decision submitted without policy reference.
  • Required behavior: reject moderation action and require policy metadata.

E10. Annotation Audit Emission Failure#

  • Trigger: lifecycle/moderation events fail to emit.
  • Required behavior: buffer/retry and surface degraded observability warning.

3. Journey-to-Surface Mapping#

Journey Primary Surface Supporting Surfaces
J1 Create Context-Bound Annotation Commenting/Annotation system Domain target adapters
J2 Reply and Thread Expansion Commenting/Annotation system Thread persistence services
J3 Acknowledge and Resolve Annotation Commenting/Annotation system Workflow ownership systems
J4 Reopen Resolved Annotation Commenting/Annotation system Lifecycle state orchestration
J5 Moderation and Governance Review Commenting/Annotation system Security/compliance pipelines

4. Instrumentation Requirements#

Required events:

  • annotation_system.journey.started
  • annotation_system.journey.step.completed
  • annotation_system.journey.blocked
  • annotation_system.journey.recovered
  • annotation_system.journey.completed

Required dimensions:

  • annotationId, threadId, targetRef, actorId, actorRole
  • journeyId, stepId, visibilityScope, lifecycleState, moderationAction
  • outcome, latencyMs, errorCode

5. Acceptance Criteria (OST-00171)#

OST-00171 is complete only when:

  1. At least five commenting/annotation 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.