Eve library

OSHUN Studio Commenting and Annotation System Dependency and Data Contract Map

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

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.md
  • docs/adr/ADR-0034-oshun-studio-commenting-and-annotation-system.md
  • libs/oshun/analytics/src/types.ts
  • libs/oshun/domain-registry/src/index.ts
  • docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md
  • 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

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:

  1. This dependency and contract map exists.
  2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
  3. Contracts for annotation envelope, thread, lifecycle event, moderation decision, and audit events are documented.
  4. Ownership boundaries and validation rules are explicit.