Eve library

OSHUN Studio Activity and Change Feeds 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-0031-oshun-studio-activity-and-change-feeds.md

Purpose#

Define dependencies and canonical contracts for Studio activity and change-feed capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for OST-00146.

Sources Used#

  • docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0031-oshun-studio-activity-and-change-feeds.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#

  • Activity/change feed UI: Studio feed surfaces in apps/oshun/web/src/components/studio.
  • Feed ingestion and normalization: BFF aggregation + canonical mapper.
  • Domain signal emitters: domain adapters publishing change events.
  • Replay and cursor services: deterministic pagination and replay APIs.
  • Telemetry and audit: analytics + compliance pipelines.

1.2 Domain Dependency Graph#

  • Activity/Change Feeds -> Yemaya: collaboration and governance changes.
  • Activity/Change Feeds -> Isis: model lifecycle and pipeline changes.
  • Activity/Change Feeds -> Hathor: narrative/world state updates.
  • Activity/Change Feeds -> Aja: media processing and timeline events.
  • Activity/Change Feeds -> Bellona: build/runtime and incident changes.
  • Project Obsidian -> all: unified franchise-level operational timeline.

2. Ownership and Contract Matrix#

Area Owner Consumers Artifact Contract
Canonical change envelope BFF + Domain Integrators Activity feed UI Change event payload StudioActivityChangeEnvelope
Timeline ordering and cursoring BFF + Data Platform Studio operators Timeline/replay payload StudioActivityTimelineCursor
Actionability and follow-up routing Web + Program Ops Ops + Security Action routing payload StudioActivityFollowUpAction
Change attribution and governance Security + Compliance Auditors + leads Attribution payload StudioActivityAttributionRecord
Audit/telemetry evidence stream Data Platform + Security Compliance + Governance Event stream StudioActivityFeedAuditEvent

3. Canonical Contracts#

3.1 StudioActivityChangeEnvelope#

ts
export interface StudioActivityChangeEnvelope {
  changeId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  changeType: string;
  actorId: string;
  actorRole: string;
  targetEntityId: string;
  targetEntityType: string;
  summary: string;
  metadata?: Record<string, unknown>;
  occurredAt: string;
}

3.2 StudioActivityTimelineCursor#

ts
export interface StudioActivityTimelineCursor {
  cursor: string;
  direction: 'forward' | 'backward';
  pageSize: number;
  orderedBy: 'occurredAt' | 'ingestedAt';
  replaySafe: boolean;
}

3.3 StudioActivityFollowUpAction#

ts
export interface StudioActivityFollowUpAction {
  actionId: string;
  changeId: string;
  route: string;
  ownerRole: string;
  priority: 'low' | 'medium' | 'high' | 'critical';
  dueAt?: string;
  createdAt: string;
}

3.4 StudioActivityAttributionRecord#

ts
export interface StudioActivityAttributionRecord {
  attributionId: string;
  changeId: string;
  actorId: string;
  actorRole: string;
  tenantId?: string;
  policyContext: string;
  verifiedAt: string;
}

3.5 StudioActivityFeedAuditEvent#

ts
export interface StudioActivityFeedAuditEvent {
  eventId: string;
  action:
    | 'activity.change_ingested'
    | 'activity.timeline_rendered'
    | 'activity.replayed'
    | 'activity.follow_up_routed'
    | 'activity.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  changeId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}

4. Validation Rules#

  • Feed ingestion must reject events missing canonical IDs/actor/target fields.
  • Timeline ordering must remain deterministic for identical query parameters.
  • Cursor replay must be idempotent and pagination-safe.
  • Follow-up actions must include route and owner role context.
  • Attribution records must meet policy and audit traceability requirements.

5. Acceptance Criteria (OST-00146)#

OST-00146 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 envelope, timeline cursor, follow-up action, attribution record, and audit event are documented.
  4. Ownership boundaries and validation rules are explicit.