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.mddocs/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#
- Cross-domain changes must be visible with deterministic ordering.
- Every material change must be attributable to actor + target context.
- Replay behavior must be cursor-safe and idempotent.
- 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:
- Load canonical timeline ordered by severity + recency.
- Filter by domain, change type, and actor role.
- Inspect summary and affected entity context.
- Select high-impact changes for immediate follow-up.
- 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:
- Expand actor and target metadata.
- Inspect role, policy context, and timestamp.
- Confirm attribution record integrity.
- Compare against policy expectations.
- 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:
- Select replay time window and cursor start.
- Replay events in deterministic order.
- Compare observed sequence with incident timeline.
- Flag missing/late events.
- 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:
- Detect event with follow-up action metadata.
- Open linked remediation/review route.
- Assign owner and due-time guidance.
- Confirm action ownership state.
- 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:
- Filter feed by policy-relevant change categories.
- Validate attribution and policy outcomes.
- Export signed audit evidence package.
- Record export metadata and reviewer identity.
- 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.startedactivity_change_feed.journey.step.completedactivity_change_feed.journey.blockedactivity_change_feed.journey.recoveredactivity_change_feed.journey.completed
Required dimensions:
changeId,actorId,actorRolejourneyId,stepId,sourceDomain,changeTypecursor,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00147)#
OST-00147 is complete only when:
- At least five activity/change-feed journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.