# OSHUN V1 Flows Event Taxonomy

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).

---

## 12. Consent vs compliance

- **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).
