Eve library

OSHUN Studio Activity and Change Feeds Journeys and Edge Cases

Spec

Revision 1

On this page

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.