# ADR-0031: OSHUN Studio Activity and Change Feeds

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, OSHUN
Security  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio operators need a canonical timeline of material changes across projects,
assets, workflows, policy decisions, and incident handling. Existing activity
signals are fragmented across domains and lack deterministic sequencing,
attribution, and replay semantics.

Without a first-class activity and change feed, OSHUN risks:

- inconsistent operational understanding across teams
- missed high-impact changes and delayed response actions
- weak accountability for actor-level change attribution
- poor auditability for release and governance reviews

## Decision Drivers

- **Operational clarity**: one timeline for critical Studio changes.
- **Determinism**: stable ordering and replay semantics for feed consumers.
- **Attribution**: explicit actor/target/action context for each change.
- **Interoperability**: shared model across Yemaya/Isis/Hathor/Aja/Bellona.
- **Governance**: auditable retention and compliance-ready change evidence.

## Considered Options

### Option 1: Keep Domain-Specific Change Feeds Only

Retain independent activity views in each domain without unified Studio model.

**Pros**:

- Minimal implementation effort.

**Cons**:

- Fragmented visibility and inconsistent ordering semantics.
- Difficult cross-domain triage and governance review.

### Option 2: Unified Feed with Loose Event Schema

Aggregate domain events but allow permissive/optional event fields.

**Pros**:

- Faster unification than strict contracts.

**Cons**:

- Inconsistent payload quality and poor comparability.
- Higher long-term migration and support costs.

### Option 3: Canonical Activity + Change Feed with Deterministic Contracts (Chosen)

Adopt one canonical activity/change feed contract with strict envelope,
ordering/replay behavior, actor attribution, and governance controls.

**Pros**:

- Deterministic cross-domain visibility and triage behavior.
- Strong change attribution and compliance evidence quality.
- Predictable compatibility and migration patterns.

**Cons**:

- Higher schema governance and rollout coordination effort.

## Decision Outcome

**Chosen option**: Option 3.

Activity/change feed requirements:

1. **Canonical change envelope** with stable IDs and actor/target metadata.
2. **Timeline ordering + replay contract** for deterministic consumption.
3. **Attribution/actionability contract** for ownership and follow-up routing.
4. **Compatibility contract** for versioning and non-breaking evolution.
5. **Release governance contract** for validation, telemetry, and rollback.

## Normative Rules

### Canonical Change Envelope Contract

- Every feed event must include `changeId`, `changeType`, `actor`, `target`, and
  `occurredAt`.
- Domain-specific metadata must be nested under canonical extension fields.
- Invalid or incomplete events must not appear in production feeds.

### Timeline Ordering and Replay Contract

- Feed ordering must be deterministic for identical filters.
- Replay requests must use stable cursors and idempotent pagination behavior.
- Late-arriving events must preserve causal metadata and replay safety.

### Attribution and Actionability Contract

- Each change event must identify actor role and affected entity scope.
- Actionable events must include routing references to follow-up workflows.
- Sensitive actor fields must respect RBAC/privacy policy boundaries.

### Compatibility Contract

- Schema changes require compatibility verification against current feed
  consumers.
- Breaking changes require migration tooling and rollback references.
- Event naming and dimensions must align with analytics taxonomy decisions.

### Release Validity Contract

An activity/change feed release is valid only when all are true:

- envelope validation checks pass
- timeline ordering and replay tests pass
- attribution and actionability checks pass
- telemetry/audit event integrity checks pass
- rollback plan and ownership handoff are documented

## Architecture Implications

- Studio web surfaces expose a unified activity/change timeline workspace.
- BFF aggregates domain events into canonical feed envelopes.
- Domain adapters emit structured change signals into shared ingestion paths.
- Analytics pipelines track change-feed consumption and incident follow-up.

## Acceptance Criteria (OST-00145)

`OST-00145` is complete only when:

1. ADR exists at `docs/adr/ADR-0037-oshun-studio-activity-and-change-feeds.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines envelope, ordering/replay, attribution/actionability,
   compatibility, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0030`, especially `ADR-0012` and
   `ADR-0030`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/analytics`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Faster and more reliable cross-domain operational awareness.
- Stronger governance and incident evidence quality.
- Clear ownership for actor-attributed change actions.

### Negative

- Increased schema governance overhead.
- Requires strict domain adapter compliance and rollout discipline.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0036-oshun-studio-notification-center.md`

## References

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `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`