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.mddocs/adr/ADR-0031-oshun-studio-activity-and-change-feeds.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#
- 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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for envelope, timeline cursor, follow-up action, attribution record, and audit event are documented.
- Ownership boundaries and validation rules are explicit.