Disciplines · Decisions (ADRs)

ADR-0031: OSHUN Studio Activity and Change Feeds

Studio operators need a canonical timeline of material changes across projects, assets, workflows, policy decisions, and incident handling.

Accepted · 2026-02-23
10sections3 minread
Markdown source
On this page

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.
  • 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