# OSHUN Studio Activity and Change Feeds Journeys and Edge Cases

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`
- `docs/releases/v1/specs/studio-activity-and-change-feeds-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio activity
and change-feed governance.

This document is the execution artifact for `OST-00147`.

## Personas

- Program Operator
- Security Reviewer
- Domain Integrator
- Reliability Engineer
- Compliance Auditor

## Journey Principles

1. Cross-domain changes must be visible with deterministic ordering.
2. Every material change must be attributable to actor + target context.
3. Replay behavior must be cursor-safe and idempotent.
4. Actionable changes must route operators to follow-up workflows quickly.

## 1. Primary Journeys

### J1. Unified Timeline Triage

**Goal**: Triage the latest changes across all Studio domains.

**Entry**: `Studio -> Activity and Change Feeds`

**Steps**:

1. Load canonical timeline ordered by severity + recency.
2. Filter by domain, change type, and actor role.
3. Inspect summary and affected entity context.
4. Select high-impact changes for immediate follow-up.
5. Route to linked workflows.

**Success State**:

- Operator identifies and prioritizes critical changes quickly.

### J2. Actor Attribution Verification

**Goal**: Verify who executed a change and why.

**Entry**: `Selected change event`

**Steps**:

1. Expand actor and target metadata.
2. Inspect role, policy context, and timestamp.
3. Confirm attribution record integrity.
4. Compare against policy expectations.
5. Export attribution evidence for governance review.

**Success State**:

- Actor accountability is explicit and verifiable.

### J3. Cursor Replay for Incident Reconstruction

**Goal**: Replay change timelines for incident/postmortem analysis.

**Entry**: `Incident investigation workflow`

**Steps**:

1. Select replay time window and cursor start.
2. Replay events in deterministic order.
3. Compare observed sequence with incident timeline.
4. Flag missing/late events.
5. Persist replay evidence.

**Success State**:

- Teams reconstruct incident sequence without ambiguity.

### J4. Follow-Up Routing from Change Events

**Goal**: Open remediation or review workflows from feed entries.

**Entry**: `Actionable activity item`

**Steps**:

1. Detect event with follow-up action metadata.
2. Open linked remediation/review route.
3. Assign owner and due-time guidance.
4. Confirm action ownership state.
5. Track follow-up completion in feed context.

**Success State**:

- Actionable changes transition into owned workflows immediately.

### J5. Compliance Review and Export

**Goal**: Export governed change history for compliance audits.

**Entry**: `Compliance review cycle`

**Steps**:

1. Filter feed by policy-relevant change categories.
2. Validate attribution and policy outcomes.
3. Export signed audit evidence package.
4. Record export metadata and reviewer identity.
5. Archive package with retention tags.

**Success State**:

- Compliance receives complete, policy-consistent change evidence.

## 2. Critical Edge Cases

### E1. Missing `changeId`

- Trigger: ingested event lacks canonical `changeId`.
- Required behavior: reject event and emit ingestion error.

### E2. Invalid `occurredAt` Timestamp

- Trigger: event timestamp is malformed or out-of-range.
- Required behavior: quarantine event and flag ordering integrity check.

### E3. Non-Deterministic Ordering for Same Filter

- Trigger: same query returns different order across retries.
- Required behavior: block feed release and raise ordering incident.

### E4. Cursor Replay Skips Events

- Trigger: replay cursor pagination omits expected change IDs.
- Required behavior: retry cursor window and flag replay integrity failure.

### E5. Duplicate `changeId` Collision

- Trigger: unrelated events share same `changeId`.
- Required behavior: isolate payloads and raise schema contract violation.

### E6. Missing Actor Attribution

- Trigger: event lacks actorId/role metadata.
- Required behavior: suppress event from production feed and log policy error.

### E7. Unauthorized Feed Export Attempt

- Trigger: actor without export entitlement triggers compliance export.
- Required behavior: deny request and emit policy-denied audit event.

### E8. Follow-Up Route Missing

- Trigger: actionable event references invalid route.
- Required behavior: render fallback guidance and open incident for route
  repair.

### E9. Telemetry/Audit Emission Failure

- Trigger: feed lifecycle events fail to emit.
- Required behavior: buffer/retry and surface degraded observability warning.

### E10. Feed Retention Tag Missing

- Trigger: exported feed package lacks retention classification.
- Required behavior: block export completion and require retention metadata.

## 3. Journey-to-Surface Mapping

| Journey                                      | Primary Surface           | Supporting Surfaces        |
| -------------------------------------------- | ------------------------- | -------------------------- |
| J1 Unified Timeline Triage                   | Activity and Change Feeds | Domain event emitters      |
| J2 Actor Attribution Verification            | Activity and Change Feeds | Identity + policy services |
| J3 Cursor Replay for Incident Reconstruction | Activity and Change Feeds | Replay/cursor services     |
| J4 Follow-Up Routing from Change Events      | Activity and Change Feeds | Workflow orchestration     |
| J5 Compliance Review and Export              | Activity and Change Feeds | Compliance export services |

## 4. Instrumentation Requirements

Required events:

- `activity_change_feed.journey.started`
- `activity_change_feed.journey.step.completed`
- `activity_change_feed.journey.blocked`
- `activity_change_feed.journey.recovered`
- `activity_change_feed.journey.completed`

Required dimensions:

- `changeId`, `actorId`, `actorRole`
- `journeyId`, `stepId`, `sourceDomain`, `changeType`
- `cursor`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00147)

`OST-00147` is complete only when:

1. At least five activity/change-feed journeys are documented.
2. At least ten deterministic edge cases are documented.
3. Journey-to-surface mapping is explicit.
4. Instrumentation requirements and dimensions are documented.
