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 machinelibs/contracts/src/common/admin-moderation.ts— moderation decision kindslibs/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.filedoshun.appeal.acknowledgedoshun.appeal.assignedoshun.appeal.evidence_submittedoshun.appeal.state_changed(covers any transition, includingin_review)oshun.appeal.decided(carries decision: granted/partially_granted/denied)oshun.appeal.escalatedoshun.appeal.withdrawnoshun.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.deliveredoshun.moderation_outcome.acknowledgedoshun.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.deliveredoshun.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.publishedoshun.incident_communication.deliveredoshun.incident_communication.openedoshun.incident_communication.subscribedoshun.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_riskoshun.flow_sla.breachedoshun.flow_sla.recoveredoshun.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.requestedoshun.flow_handoff.acceptedoshun.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).
12. Consent vs compliance#
- Compliance-mandatory (NOT consent-gated): every event in
appeal,moderation_delivery,review_delivery,flow_sla,flow_handoff, and thepublished,delivered, andopenedevents inincident_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:
- updating
flows-taxonomy.tswith the new or changed entry - updating tests (lock-style tests fail closed if entries drift)
- updating this document if the change is structurally significant
- 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).