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
Purpose#
Define dependencies and canonical contracts for Studio commenting and annotation capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
This document is the execution artifact for OST-00170.
Sources Used#
docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.mddocs/adr/ADR-0034-oshun-studio-commenting-and-annotation-system.mdlibs/oshun/analytics/src/types.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/design/ux-principles.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/domains/bellona/features.md
1. Dependency Overview#
1.1 Control Surfaces#
- Annotation UI surfaces: Studio commenting and annotation modules in
apps/oshun/web/src/components/studio. - Thread persistence and lifecycle services: BFF annotation APIs.
- Target binding adapters: domain adapters for entity/frame/token anchors.
- Moderation and policy services: visibility, redaction, and abuse controls.
- Telemetry and audit: analytics + compliance evidence pipelines.
1.2 Domain Dependency Graph#
Commenting/Annotation -> Yemaya: program coordination and release feedback.Commenting/Annotation -> Isis: model review and generation quality notes.Commenting/Annotation -> Hathor: narrative and worldbuilding annotations.Commenting/Annotation -> Aja: timeline and media-sequence notes.Commenting/Annotation -> Bellona: runtime/build incident annotations.Project Obsidian -> all: franchise-wide review, moderation, and governance.
2. Ownership and Contract Matrix#
| Area | Owner | Consumers | Artifact | Contract |
|---|---|---|---|---|
| Canonical annotation envelope | BFF + Domain Integrators | Studio reviewers and operators | Annotation payload | StudioAnnotationEnvelope |
| Threading and reply structure | BFF + Web | Collaboration participants | Thread payload | StudioAnnotationThread |
| Annotation lifecycle transitions | Program Ops + Web | Owners + moderators | Lifecycle payload | StudioAnnotationLifecycleEvent |
| Moderation and visibility controls | Security + Compliance | Moderators + governance | Moderation payload | StudioAnnotationModerationDecision |
| Annotation audit evidence | Data Platform + Security | Compliance + governance | Telemetry/audit event | StudioAnnotationAuditEvent |
3. Canonical Contracts#
3.1 StudioAnnotationEnvelope#
ts
export interface StudioAnnotationEnvelope {
annotationId: string;
threadId: string;
targetRef: string;
sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
actorId: string;
actorRole: string;
content: string;
visibilityScope: 'workspace' | 'project' | 'domain';
occurredAt: string;
}
3.2 StudioAnnotationThread#
ts
export interface StudioAnnotationThread {
threadId: string;
rootAnnotationId: string;
targetRef: string;
replyCount: number;
state: 'open' | 'acknowledged' | 'resolved' | 'locked';
updatedAt: string;
}
3.3 StudioAnnotationLifecycleEvent#
ts
export interface StudioAnnotationLifecycleEvent {
lifecycleId: string;
annotationId: string;
threadId: string;
action: 'create' | 'reply' | 'acknowledge' | 'resolve' | 'reopen';
actorId: string;
actorRole: string;
reason?: string;
occurredAt: string;
}
3.4 StudioAnnotationModerationDecision#
ts
export interface StudioAnnotationModerationDecision {
decisionId: string;
annotationId: string;
action: 'allow' | 'hide' | 'redact' | 'lock';
moderatorId: string;
policyId: string;
reason: string;
decidedAt: string;
}
3.5 StudioAnnotationAuditEvent#
ts
export interface StudioAnnotationAuditEvent {
eventId: string;
action:
| 'annotation.created'
| 'annotation.replied'
| 'annotation.resolved'
| 'annotation.reopened'
| 'annotation.moderated'
| 'annotation.policy_denied';
outcome: 'allowed' | 'denied' | 'success' | 'error';
annotationId?: string;
threadId?: string;
actorId?: string;
actorRole?: string;
traceId?: string;
occurredAt: string;
}
4. Validation Rules#
- Annotation payloads missing thread/target/actor context must be rejected.
- Thread ordering must remain deterministic for identical query parameters.
- Lifecycle transitions must follow explicit state transition contracts.
- Moderation decisions must reference active policy IDs and rationale.
- Audit events must capture lifecycle and moderation outcomes end-to-end.
5. Acceptance Criteria (OST-00170)#
OST-00170 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for annotation envelope, thread, lifecycle event, moderation decision, and audit events are documented.
- Ownership boundaries and validation rules are explicit.