Eve library

OSHUN V1 Flows Event Taxonomy

Spec

Revision 1

On this page

Status: Canonical Date: 2026-04-26 Owners: OSHUN Trust & Safety, OSHUN Compliance, OSHUN Reliability, OSHUN Platform Engineering Tracks: V1-OBS-004 from OSHUN_V1_TODOS.md Spec source: libs/oshun/analytics/src/flows-taxonomy.ts

This document is the canonical, human-readable companion to the machine-readable V1 flows event taxonomy in @oshun/analytics.

The machine-readable taxonomy is the single source of truth. Any divergence between this document and flows-taxonomy.ts is a bug in this document — follow the code.


1. Scope#

This taxonomy defines every analytics event in the cross-cutting review, moderation, appeal, and incident flows — the customer-facing legs of those lifecycles, plus cross-workspace flow signals (SLA breach, handoff, status page) that V1-OBS-002 admin events do not cover on their own.

Pairs with:

  • the customer taxonomy (customer-taxonomy.ts, V1-OBS-001)
  • the admin taxonomy (admin-taxonomy.ts, V1-OBS-002)
  • the assistant taxonomy (assistant-taxonomy.ts, V1-OBS-003)

Out-of-scope:

  • admin-side review/moderation/incident operator events (V1-OBS-002)
  • customer-app surface events (V1-OBS-001)
  • assistant interactions (V1-OBS-003)
  • model intake/promotion/media release gates (V1-OBS-005)

Consistent with:

  • ADR-0006 — analytics taxonomy and event naming
  • ADR-0029 — review/approval workflows
  • libs/contracts/src/common/safety-appeals.ts — appeal state machine
  • libs/contracts/src/common/admin-moderation.ts — moderation decision kinds
  • libs/contracts/src/common/incident.ts — incident communications, SLAs, handoffs

2. Naming and envelope#

Names follow <namespace>.<entity>.<action> per ADR-0006. All events use the oshun.* namespace. Property names are snake_case. PII is never sent.

Tenant scoping is mandatory on every event (tenant_id).


3. Surfaces#

Surface Description
web_shell / mobile_shell / pwa_shell Customer shells.
web_profile / mobile_profile Customer profile/preferences surface.
web_activity / mobile_activity Activity surfaces (notifications cross there).
notification_handler Customer push/email/in-app handler.
background Customer background/service-worker.
flows_bff Flows BFF service emissions.
flows_background Flows background workers (delivery, expiry).
admin_review / admin_trust_safety / etc Admin workspaces participating in handoffs.
status_page Public status page surface.

4. Families#

Family Description
appeal Safety-appeal lifecycle per the contract.
moderation_delivery Customer-side delivery of moderation decisions.
review_delivery Customer-side delivery of review decisions.
incident_communication Incident communications routed to customers.
flow_sla SLA at-risk/breach/recovery/completion telemetry.
flow_handoff Cross-workspace handoffs between admin teams.
status_page Public status-page view and subscription events.

5. Appeal lifecycle#

The taxonomy mirrors the safety-appeal state machine (SAFETY_APPEAL_STATES = filed | in_review | granted | partially_granted | denied | withdrawn | expired).

Dedicated events:

  • oshun.appeal.filed
  • oshun.appeal.acknowledged
  • oshun.appeal.assigned
  • oshun.appeal.evidence_submitted
  • oshun.appeal.state_changed (covers any transition, including in_review)
  • oshun.appeal.decided (carries decision: granted/partially_granted/denied)
  • oshun.appeal.escalated
  • oshun.appeal.withdrawn
  • oshun.appeal.expired

Reviewer-tier and evidence-kind enums are mirrored verbatim from libs/contracts/src/common/safety-appeals.ts.


6. Moderation outcome delivery#

moderation_delivery events carry the moderation decision-kind enum from libs/contracts/src/common/admin-moderation.ts so customer-side delivery analytics align with the policy table.

The three customer-perceptible signals are:

  • oshun.moderation_outcome.delivered
  • oshun.moderation_outcome.acknowledged
  • oshun.moderation_outcome.appeal_invitation_shown

7. Review outcome delivery#

review_delivery events deliver review decisions per ADR-0029 (approved | rejected | changes_requested) to the customer subject of the review:

  • oshun.review_outcome.delivered
  • oshun.review_outcome.acknowledged

8. Incident communications#

incident_communication events emit at every customer-relevant stage of an incident communication, mirroring the IncidentCommunicationUpdate contract:

  • oshun.incident_communication.published
  • oshun.incident_communication.delivered
  • oshun.incident_communication.opened
  • oshun.incident_communication.subscribed
  • oshun.incident_communication.unsubscribed

The audience and channel enums are mirrored verbatim from libs/contracts/src/common/incident.ts.


9. Status page#

status_page.viewed and status_page.subscribed cover the public OSHUN status-page surface. These are opt-in events and are gated on analytics consent.


10. Flow SLA#

flow_sla events fire whenever an SLA clock crosses a threshold for any of the four flow kinds (review, moderation, appeal, incident):

  • oshun.flow_sla.at_risk
  • oshun.flow_sla.breached
  • oshun.flow_sla.recovered
  • oshun.flow_sla.completed

The sla_type enum extends the IncidentSlaType enum (acknowledgement, mitigation, resolution, next_update) with the cross-flow types first_response, first_decision, and final_decision for review, moderation, and appeal SLAs.


11. Flow handoff#

flow_handoff events fire whenever a flow item moves between admin workspaces:

  • oshun.flow_handoff.requested
  • oshun.flow_handoff.accepted
  • oshun.flow_handoff.declined

The from/to workspace enums correspond to the 13 admin workspaces that may participate in handoffs (excluding dashboard, which is a composed overview surface and not a handoff target).


  • Compliance-mandatory (NOT consent-gated): every event in appeal, moderation_delivery, review_delivery, flow_sla, flow_handoff, and the published, delivered, and opened events in incident_communication. These carry legal/operational obligations and are recorded regardless of analytics consent.
  • Consent-gated: incident_communication.subscribed, incident_communication.unsubscribed, status_page.viewed, status_page.subscribed — opt-in customer-engagement signals only.

Tests in flows-taxonomy.test.ts lock these partitions in.


13. Governance#

13.1 Amendments#

Adding, changing, or deprecating a flow event requires:

  1. updating flows-taxonomy.ts with the new or changed entry
  2. updating tests (lock-style tests fail closed if entries drift)
  3. updating this document if the change is structurally significant
  4. signoff from Trust & Safety (appeals/moderation), Reliability (incident), and Compliance (delivery semantics) leads, plus platform analytics

13.2 Versioning#

Same rules as the sibling taxonomies.

13.3 PII#

No PII appears in any flow-event property. Identifiers are stable (appeal ID, review ID, incident ID, communication ID, decision ID); free-form content (appeal narratives, communication summaries) never appears.


14. Out-of-scope#

  • admin operator-side review/moderation/incident events (V1-OBS-002)
  • customer surface events outside the flows scope (V1-OBS-001)
  • assistant interactions (V1-OBS-003)
  • model intake/promotion gates (V1-OBS-005)

15. Change log#

  • 2026-04-26 — Initial canonical V1 flows event taxonomy published alongside libs/oshun/analytics/src/flows-taxonomy.ts (V1-OBS-004).