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.mddocs/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#
- Every annotation must be anchored to explicit target context.
- Thread lifecycle transitions must be deterministic and auditable.
- Moderation and visibility controls must be policy-aware.
- 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:
- Select target anchor (entity, frame, token range, or coordinate).
- Enter annotation content and visibility scope.
- Submit annotation envelope with actor metadata.
- Persist annotation and render in thread list.
- 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:
- Open existing thread with ordered replies.
- Submit reply bound to parent annotation.
- Update thread reply count and state metadata.
- Re-render participants with latest activity markers.
- 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:
- Assign owner and acknowledge pending annotation.
- Add resolution rationale and evidence references.
- Transition state to resolved.
- Notify thread participants of closure.
- 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:
- Trigger reopen action with reason code.
- Restore thread state to open.
- Preserve prior resolution evidence and timestamps.
- Notify owners and participants.
- 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:
- Query annotation stream by moderation policy filters.
- Evaluate visibility and policy scope compliance.
- Apply moderation action (allow/hide/redact/lock) if required.
- Export governance evidence package.
- 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.startedannotation_system.journey.step.completedannotation_system.journey.blockedannotation_system.journey.recoveredannotation_system.journey.completed
Required dimensions:
annotationId,threadId,targetRef,actorId,actorRolejourneyId,stepId,visibilityScope,lifecycleState,moderationActionoutcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00171)#
OST-00171 is complete only when:
- At least five commenting/annotation journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.